@bookr-cl/widget

Shared booking-flow logic (typed API client, auth helpers, and React hooks) used by Bookr client widgets (ko-pilates, magnolia, and future clients — including third-party integrators). Each site keeps its own JSX/Tailwind presentation layer — this package only owns the parts that cause bugs when duplicated: API calls, validation, state machines, and auth/token handling.

Install

Published on the public npm registry — no auth or custom .npmrc needed:

npm install @bookr-cl/widget

Requires React 19+ (see peerDependencies).

What's exported

• api.ts — thin typed functions for every Bookr endpoint the widgets call (listLocations, createBooking, sendMagicLink, etc.), each taking an explicit { apiBase, apiKey } config.
• clientAuth.ts — getClientToken/setClientToken/clearClientToken/fetchMe.
• dateUtils.ts — week/date helpers and the default provider-color palette used by class-schedule UIs.
• hooks/useBookingFlow — locations→services→providers→slots fetch chain, validation, submit with 409 handling. Anonymous submissions are resolved server-side by contact fields (rut/email); a caller-supplied client_id is only honored alongside a client or staff auth token.
• hooks/useClassSchedule — weekly group-class schedule fetch/submit logic, same anonymous-booking contract as useBookingFlow.
• hooks/useMagicLinkAuth — passwordless (magic-link) auth; also accepts optional profile fields (firstName/lastName/phone/rut) for signup-style forms, linked server-side by rut first, then email.
• hooks/usePasswordLoginAuth: email/password client login, additive alongside magic link. Also drives the forgot-password flow, which doubles as first-time password setup since there's no separate "set password" step.
• hooks/useClientAccount, useSessionSummary — the client account/auth pages' remaining logic and session-summary display.
• hooks/useShareableProfile — profile + stats ("member since", sessions completed) for shareable profile cards, tenant-agnostic.
• clientAccountApi.ts, giftCards.ts, payments.ts, leadsApi.ts — typed client-account, gift-card, checkout (Webpay/Mercado Pago), and lead-submission (submitLead, contact forms) functions, same pattern as api.ts.
• warmup.ts — warmupApi(config), fire-and-forget ping to /health to warm up Lambda/DB before the user reaches the booking flow.
• generated/schema.ts — TS types generated from the real openapi.json (api/) via openapi-typescript. Not hand-edited.

Publishing a new version

Publishing happens under the bookr-cl npm account (a service account for the product, not any individual's personal npm login). CI (.github/workflows/publish.yml) publishes automatically when a vX.Y.Z tag is pushed — this is the only supported path now, so npm and git can't drift apart again (see bookr-cl/widget#5):

npm version patch   # or minor/major — also updates package-lock.json
git push && git push --tags

Update CHANGELOG.md with what changed before tagging. A manual npm publish from a laptop should only ever be used if CI itself is broken — if so, still commit the version bump and push a matching tag afterward so git stays the source of truth.

CI authenticates to npm via Trusted Publishing — OIDC straight from GitHub Actions to the npm registry, no token or secret involved at all. Configured on npmjs.com under the @bookr-cl/widget package's Settings → Trusted Publisher, pointing at this repo, publish.yml, and the widget environment.