@swift-food-services/catering-widget 0.1.0-beta.2 → 0.1.0-beta.20

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnav Vaish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,13 +10,15 @@ npm install @swift-food-services/catering-widget
 
 ```tsx
 import { CateringWidget } from "@swift-food-services/catering-widget";
-import "@swift-food-services/catering-widget/dist/styles.css";
 
 export default function CateringPage() {
   return (
     <CateringWidget
       publishableKey="pk_live_..."
+      googleMapsApiKey="AIzaSy..."
       onOrderComplete={({ orderId }) => {
+        // Fires after the success-screen countdown (default 15s,
+        // configurable via `onOrderCompleteDelaySeconds`).
         window.location.href = `/thanks?order=${orderId}`;
       }}
     />
@@ -30,18 +32,20 @@ Defaults: Swift-hosted backend, `localStorage` persistence, neutral theme.
 
 - React 18+ and React-DOM 18+ as peer dependencies
 - A publishable key from Swift (see [Getting a publishable key](#getting-a-publishable-key))
-- At least one origin registered with Swift where the widget will load
 
 ## Props
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
-| `publishableKey` | `string` | yes | Your `pk_live_...` or `pk_test_...` key from Swift. |
+| `publishableKey` | `string` | yes | Your `pk_live_...` key from Swift. |
+| `googleMapsApiKey` | `string` | yes | Google Maps JavaScript API key with the Places library enabled. Used by the address-autocomplete field. |
 | `theme` | `Theme` | no | Primary color, border radius, and font overrides. |
-| `initialData` | `InitialData` | no | Pre-populate event, address, and contact fields. Applied only on first mount. |
+| `initialData` | `InitialData` | no | Pre-populate event window, address, and contact fields. Re-applied when its fingerprint changes between mounts; preserved on reload. See [Pre-filling known event details](#pre-filling-known-event-details). |
+| `allowedCateringTimes` | `AllowedCateringTimes` | no | Partner-level catering availability window (`{ start: "HH:MM", end: "HH:MM" }`). Restricts the session delivery-time picker to slots within this range. |
 | `stickyTopOffset` | `number` | no | Pixels to offset the widget's internal sticky date/session nav from the top of the viewport. Set this to the height of any sticky/fixed navbar in your host layout so the widget's nav doesn't slide underneath it. Defaults to `0`. |
 | `onReady` | `() => void` | no | Fires when the widget has initialized. |
-| `onOrderComplete` | `(result: OrderCompleteResult) => void` | no | Fires after a successful order submission. |
+| `onOrderComplete` | `(result: OrderCompleteResult) => void` | no | Fires after a successful order submission. See [`onOrderComplete` behaviour](#onordercompleteresult) for the timing. |
+| `onOrderCompleteDelaySeconds` | `number` | no | Seconds to keep the success screen visible before firing `onOrderComplete`. Defaults to `15`. Ignored if `onOrderComplete` is not provided. |
 | `onError` | `(error: WidgetError) => void` | no | Fires on unrecoverable errors (bad key, network, submit failure). |
 
 ## Examples
@@ -51,14 +55,14 @@ Defaults: Swift-hosted backend, `localStorage` persistence, neutral theme.
 ```tsx
 "use client";
 import { CateringWidget } from "@swift-food-services/catering-widget";
-import "@swift-food-services/catering-widget/dist/styles.css";
 import { useRouter } from "next/navigation";
 
 export default function Page() {
   const router = useRouter();
   return (
     <CateringWidget
-      publishableKey={process.env.NEXT_PUBLIC_SWIFT_KEY!}
+      publishableKey={process.env.NEXT_PUBLIC_SWIFT_PUBLISHABLE_KEY!}
+      googleMapsApiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}
       onOrderComplete={({ orderId, accessToken }) => {
         router.push(`/orders/${orderId}?token=${accessToken}`);
       }}
@@ -87,13 +91,17 @@ export default function Page() {
   publishableKey="pk_live_..."
   initialData={{
     eventName: "Alice's Birthday",
-    eventDate: "2026-07-12",
-    eventTime: "19:00",
+    eventStartDate: "2026-07-12",
+    eventStartTime: "18:00",
+    eventEndDate: "2026-07-12",
+    eventEndTime: "22:00",
     guestCount: 40,
     deliveryAddress: {
       line1: "1 Example Lane",
       city: "London",
       postcode: "E1 6AN",
+      lat: 51.5074,
+      lng: -0.1278,
     },
     contact: { name: "Alice", email: "alice@example.com" },
   }}
@@ -101,7 +109,32 @@ export default function Page() {
 />
 ```
 
-Every field in `initialData` is optional. Fields remain editable after pre-fill. `initialData` is only applied on first mount — if the user has a half-finished order in progress (persisted in `localStorage`), the persisted state wins.
+Every field in `initialData` is optional. Fields remain editable after pre-fill.
+
+**How `initialData` interacts with persisted in-progress orders:** the widget fingerprints the supplied `initialData` (event window, guest count, address, and contact fields) and stores the fingerprint alongside the order. On every mount it compares the incoming fingerprint to the stored one:
+
+- **Match** (e.g. page reload) → the in-progress order is preserved; `initialData` is _not_ re-applied.
+- **Differ** (e.g. customer navigated back to your booking page, edited details, then returned) → the stored order is cleared and `initialData` is applied fresh.
+- **No fingerprint stored yet** (first visit) → `initialData` is applied and the fingerprint is recorded.
+
+For this to behave predictably, make sure the values you pass for the same booking are stable across renders — avoid recomputing dynamic values like `new Date()` inline in render.
+
+The event window is a start–end pair (`eventStartDate` + `eventStartTime` to `eventEndDate` + `eventEndTime`). When set, the session editor restricts session dates to that range and filters the delivery-time picker so it stays within the window on the boundary days.
+
+**Address requires `lat` and `lng`.** Delivery pricing depends on coordinates, so if you pass a `deliveryAddress` without both `lat` and `lng`, the widget ignores the entire address (no fields are pre-filled) and the guest is asked to pick one via the address-autocomplete field instead. The other `initialData` fields (event window, guest count, contact) still apply.
+
+### Restricting catering hours (`allowedCateringTimes`)
+
+Pass a partner-level catering availability window to restrict the session delivery-time picker to a subset of the day. Times are 24-hour `"HH:MM"` strings.
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  allowedCateringTimes={{ start: "09:00", end: "19:00" }}
+/>
+```
+
+Each slot is a 30-minute window. A slot is shown only if it fits entirely within `[start, end]` — its start must be ≥ `start` and its end must be ≤ `end`. With `end: "19:00"`, for example, the latest visible slot is 6:30 PM – 7:00 PM. If `initialData` also defines an event window, the two filters compose: the partner window is the outer bound, and the event start/end further narrow the picker on boundary days.
 
 ### Offsetting below a host navbar
 
@@ -124,6 +157,7 @@ import {
   type CateringWidgetProps,
   type Theme,
   type InitialData,
+  type AllowedCateringTimes,
   type OrderCompleteResult,
   type OrderSummary,
   type MealSession,
@@ -138,12 +172,29 @@ See the generated `dist/index.d.ts` for the full shapes — your IDE picks them
 
 ### `onOrderComplete(result)`
 
-Fires when an order has been successfully submitted. `result` contains:
+Fires after a successful order submission. `result` contains:
 
 - `orderId: string` — Swift's order ID.
 - `accessToken: string` — a token the customer can use to view the order on Swift's hosted view page.
 - `summary: OrderSummary` — structured breakdown of the submitted order.
 
+**Timing.** When `onOrderComplete` is wired, the widget shows its built-in success screen with a "Continuing in N seconds…" countdown for `onOrderCompleteDelaySeconds` seconds (default `15`), then fires the callback. This gives the guest a moment to read the confirmation before the host navigates away. A "Continue now" button under the countdown lets the guest skip the wait — clicking it cancels the timer and fires `onOrderComplete` immediately.
+
+If `onOrderComplete` is **not** wired, the success screen stays up indefinitely. The success screen shows the event, customer, and pricing summary, and any navigation is the host's responsibility (do it from `onOrderComplete`).
+
+**Heads up:** the widget does not navigate on its own. If your `onOrderComplete` runs without triggering a navigation (e.g. you only fire analytics or close a modal), the guest will stay on the widget's order-confirmation page even after the callback fires. To send them elsewhere, do it from inside `onOrderComplete` — `router.push(...)`, `window.location.href = ...`, hide the widget from your layout, etc.
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  googleMapsApiKey="AIzaSy..."
+  onOrderCompleteDelaySeconds={5}
+  onOrderComplete={({ orderId, accessToken }) => {
+    router.push(`/orders/${orderId}?token=${accessToken}`);
+  }}
+/>
+```
+
 ### `onError(error)`
 
 Fires on errors the widget can't recover from. `error.code` is one of:
@@ -160,14 +211,14 @@ Fires on errors the widget can't recover from. `error.code` is one of:
 - Multi-session meal building
 - Contact details and delivery address
 - Promo codes and pricing preview
-- Google Maps address autocomplete
+- Google Maps address autocomplete (requires the `googleMapsApiKey` you provide)
 - Order submission to Swift's API
 - State persistence in `localStorage` (namespaced)
 
 ## What you're responsible for
 
 - Getting a publishable key from Swift.
-- Registering your site's origin(s) with Swift.
+- Providing a Google Maps JavaScript API key (with the Places library enabled) via the `googleMapsApiKey` prop. Restrict the key to your own domain(s) in the Google Cloud Console.
 - Rendering `<CateringWidget>` wherever you want the flow to live.
 - Navigating after `onOrderComplete`.
 - Page chrome around the widget.
@@ -175,36 +226,25 @@ Fires on errors the widget can't recover from. `error.code` is one of:
 ## What you're **not** responsible for
 
 - Payment. Swift sends a payment link by email after reviewing the order.
-- Loading Google Maps — the widget handles this internally.
+- Loading the Google Maps script — the widget injects the script using the key you provide.
 - Making API calls to Swift.
 - Session or auth management.
 
-## Build-time configuration
-
-Set `SWIFT_WIDGET_GOOGLE_MAPS_KEY` before building the library so the Maps script loads with the correct key. CI publishes with the production key; local development can use a restricted dev key.
-
 ## Getting a publishable key
 
-Contact Swift at [partners@swiftfood.uk](mailto:partners@swiftfood.uk) with:
+Contact Swift at [swiftfooduk@gmail.com](mailto:swiftfooduk@gmail.com) with:
 
 1. Your company name.
-2. The origin(s) where the widget will be embedded.
-3. A technical contact for integration support.
+2. A technical contact for integration support.
 
-Swift provisions a partner record and returns a publishable key (format: `pk_live_...` or `pk_test_...`) out of band.
+Swift provisions a partner record and returns a publishable key (format: `pk_live_...`) out of band.
 
-The key is public (it ships in the browser bundle). Swift's backend validates the key against the request's origin, so a stolen key cannot be used from a non-allowlisted domain.
+The key is public — it ships in the browser bundle.
 
 ## Troubleshooting
 
-**Widget doesn't render / screen is blank**
-Check that you've imported the stylesheet: `import "@swift-food-services/catering-widget/dist/styles.css";`.
-
 **Errors mentioning `invalid_publishable_key` or `session_failed`**
-Either the key is wrong, the key is inactive, or your current origin isn't in the allowlist.
-
-**Widget works on `localhost` but not in production**
-Your production origin isn't registered. Ask Swift to add it.
+Either the key is wrong or the key is inactive. Contact Swift if you need a new one.
 
 **TypeScript errors importing types**
 Ensure your `tsconfig.json` has `"moduleResolution": "bundler"` or `"node16"`/`"nodenext"`.
@@ -219,7 +259,7 @@ Modern evergreen browsers (Chrome, Firefox, Safari, Edge) on desktop and mobile.
 
 ## Support
 
-- Integration questions: [partners@swiftfood.uk](mailto:partners@swiftfood.uk)
+- Integration questions: [swiftfooduk@gmail.com](mailto:swiftfooduk@gmail.com)
 - Bug reports: include your publishable key prefix (first 8 chars), the browser, and a reproducible example.
 
 ## License