# Holidoit Browser JS Library

Booking embed and widgets for partner websites. See [widget installation](WIDGETS_INSTALLATION.md) and [embed integration](EMBED_INTEGRATION.md).

## Local development

Configure `.env`, then run `yarn install` and `yarn dev`.
Playground: http://localhost:3001. `yarn build` creates a local production build.

### Google Places for invoice addresses

The optional browser key is configured locally in `.env`:

```dotenv
NEXT_PUBLIC_MAPS_API_KEY=your_browser_key
```

Restart `yarn dev` after changing it. Builds read `.env` and environment variables;
changing a deployed key requires a new build. To disable address search locally,
set `NEXT_PUBLIC_MAPS_API_KEY=` in `.env`. Without a key, manual invoice address
entry remains available. Address search loads only while an eligible invoice form
is visible in the customer step. Suggestions fill the existing editable address
fields; foreign postal codes remain excluded from the invoice payload.

For deployment, configure repository secrets `DEV_NEXT_PUBLIC_MAPS_API_KEY` and
`PROD_NEXT_PUBLIC_MAPS_API_KEY`. Production never falls back to the development
key. An absent key does not fail the build; verify the appropriate secret before
releasing address search.

Use a dedicated browser key with billing enabled and **Maps JavaScript API** and
**Places API (New)** enabled. Restrict the key to these two APIs and authorized
websites. For iframe checkout, authorize the domain serving the iframe, using the
actual DEV/PROD `CDN_DOMAIN` values (default embed URL: `https://cdn.holidoit.com/`).
For local testing authorize `http://localhost:3001/*`; authorize any custom host
or direct integration domain separately.

The key is visible in the browser bundle and Google requests, even when supplied
through GitHub Secrets. Do not commit its value or print it in logs. Configure
quotas and usage monitoring; budget alerts alone do not cap spending. Keys in the
same Google project share project quotas, including any PayByLink usage. Real
Google requests can be billed even when checkout payments are simulated.

See [Google API security guidance](https://developers.google.com/maps/api-security-best-practices)
and [dynamic library loading](https://developers.google.com/maps/documentation/javascript/load-maps-js-api).

## PayPal with Stripe Connect

The full embed checkout supports cards and PayPal for connected partners. PayPal
uses Holidoit as the merchant and transfers funds to the partner after platform
fees. Inline widget checkouts currently support cards only.

## Deploy and rollback

**Actions → Deploy embed and widgets → Run workflow**:

- `operation=deploy`: build and publish a new versioned release.
- `operation=rollback`: restore an existing release without rebuilding. Set `rollback_run_id` to the number in the previous successful deployment's `/actions/runs/ID` URL, using the same environment. Its artifact must still be available (30 days).

Pushes to `develop` automatically deploy to development. Production deploys and rollbacks are manual and restricted to the default branch. Both operations share the same deployment lock.

Partner snippets stay unchanged. Release files are kept under `holidoit-js-releases/<id>/`; do not delete old releases. Rollback updates public URLs and invalidates their CDN cache without overwriting release files.

### GitHub configuration

Use repository **Settings → Secrets and variables → Actions**, with `DEV_` and `PROD_` prefixes; no GitHub Environments are needed.

| Location | Names (add the environment prefix) |
| --- | --- |
| Variables | `AWS_S3_BUCKET`, `CDN_DOMAIN`, `AWS_CLOUDFRONT_DISTRIBUTION_ID` |
| Variables (optional) | `AWS_REGION` (default: `eu-south-1`) |
| Secrets | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `BASE_API_URL`, `NEXT_PUBLIC_STRIPE_CLIENT_ID` |
| Secrets (optional) | `NEXT_PUBLIC_PAYPAL_CLIENT_ID`, `NEXT_PUBLIC_MAPS_API_KEY` |

`CDN_DOMAIN` is a hostname, without `https://`. AWS credentials need S3 upload and CloudFront invalidation permissions; CloudFront must be allowed to read release files. Public URLs must allow revalidation (CloudFront minimum TTL: 0).