@frontdesk-africa/store-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Live Capital, Inc.
+
+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

@@ -0,0 +1,242 @@
+# @frontdesk-africa/store-js
+
+Typed client for the FrontDesk Storefront API. Build your own website or app on a merchant's
+catalogue, events, forms and checkout.
+
+It is deliberately thin: a fetch wrapper with the response types attached and the error envelope
+turned into a real `Error`. It does not cache, retry or reshape anything, because a client that does
+becomes a second implementation of the API's semantics.
+
+Full reference for agents: `GET /v1/store/llms.txt`. OpenAPI: `GET /v1/store/openapi.json`.
+MCP: `POST /v1/store/mcp`.
+
+---
+
+## The two keys
+
+| Key | Where it goes | What it does |
+|---|---|---|
+| `fd_pk_…` | your **page**, safe to ship | read-only, and only from origins the merchant registered |
+| `fd_sk_…` | your **server**, never a page | opens checkouts |
+
+A publishable key is designed to be public. It is locked to exact origins, and an empty origin list
+refuses everything — that is deliberate, not a misconfiguration. A secret key in browser code lets
+anyone viewing source take payments as that merchant.
+
+`fd_pk_test_…` / `fd_sk_test_…` work against staging; `live` against production. A key from the
+wrong environment is refused.
+
+## Install
+
+```bash
+pnpm add @frontdesk-africa/store-js
+```
+
+## Read (browser)
+
+```ts
+import { createStoreClient } from '@frontdesk-africa/store-js'
+
+const store = createStoreClient({
+  baseUrl: 'https://api.frontdesk.africa/v1',
+  key: process.env.NEXT_PUBLIC_FRONTDESK_PK!, // fd_pk_…
+})
+
+const site = await store.storefront()   // brand, theme, sections, pages, embedded lists
+const products = await store.products()
+const item = await store.product('blue-mug')
+```
+
+You never choose the workspace: the key does. Any workspace ref you send is ignored.
+
+## Checkout (server)
+
+You never handle card details and you never price a cart. The buyer pays on a FrontDesk-hosted page
+on the merchant's own domain, so their branding does not change mid-payment.
+
+```ts
+// server only — fd_sk_…
+const checkout = await store.createCheckout(
+  {
+    items: [{ variantRef: variant.ref, quantity: 2 }],
+    returnUrl: 'https://yourbrand.com/thanks',
+  },
+  `cart_${cart.id}`, // idempotency key: stable per cart, NOT random per attempt
+)
+
+redirect(checkout.hostedUrl)
+```
+
+Then, when the buyer comes back:
+
+```ts
+const done = await store.getCheckout(ref)
+if (done.status === 'completed') fulfil(done.orderRef)
+```
+
+**Do not fulfil on the redirect itself.** It is a browser navigation: it can be lost, replayed or
+forged. `getCheckout` or the `checkout.completed` webhook are the only proof.
+
+Event tickets work the same way, with the event telling you what to collect first:
+
+```ts
+const event = await store.event('gala-night') // tiers carry formFields, requiresAttendeeDetails, min/max
+const checkout = await store.createEventCheckout(
+  'gala-night',
+  {
+    tickets: [{ ticketTypeRef: tier.ref, quantity: 2 }],
+    contact: { name, email },
+    returnUrl: 'https://yourbrand.com/thanks',
+  },
+  `evtcart_${cart.id}`,
+)
+redirect(checkout.hostedUrl)
+```
+
+If the buyer walks away, `cancelCheckout(ref)` releases the seats straight away instead of holding
+them until the session lapses. For carts that live in the buyer's storage, `availability(variantRefs)`
+tells you which lines are still purchasable before you reopen a days-old cart.
+
+`createHeadlessCheckout` (you render the payment step yourself) needs headless switched on for the
+workspace, and one `provider` from `paymentMethods()` — see the API docs for the per-rail flow.
+
+Prices from the read endpoints are for **display**. The order is priced when the buyer pays, so a
+price that moved in between is resolved there, not by you.
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from '@frontdesk-africa/store-js'
+
+export async function POST(req: Request) {
+  const raw = await req.text() // RAW body — verify before parsing
+  const ok = await verifyWebhook({
+    rawBody: raw,
+    signatureHeader: req.headers.get('x-fd-signature'),
+    timestampHeader: req.headers.get('x-fd-timestamp'),
+    secret: process.env.FRONTDESK_WEBHOOK_SECRET!,
+  })
+  if (!ok) return new Response('bad signature', { status: 400 })
+
+  const event = JSON.parse(raw)
+  // Return 2xx fast and do the work asynchronously; we retry with backoff for 24h.
+  queue(event)
+  return new Response('ok')
+}
+```
+
+Pass the **raw** body. `JSON.parse` then `JSON.stringify` will not reproduce the bytes we signed, and
+the check will fail in a way that looks like a key mismatch.
+
+Payloads are thin — refs only. Re-fetch through the API for detail, so a replayed delivery can never
+present stale figures as current.
+
+## Test mode
+
+A `fd_sk_test_…` key opens a test checkout. The hosted page shows a test banner and a
+**Simulate a successful payment** button, so you can build the whole loop with no bank account and no
+spend.
+
+A simulated payment completes the session, sets a synthetic `test_ord_…` ref, and fires
+`checkout.completed` with `"test": true`. It creates **no order**, credits nobody and posts no ledger
+entry — so do not try to fetch that order ref. Test mode proves your integration, not fulfilment.
+
+---
+
+## Starters
+
+### Lovable / Replit prompt
+
+Paste this, with your key:
+
+> Build a storefront on the FrontDesk Storefront API.
+>
+> Read the full API reference first: https://api.frontdesk.africa/v1/store/llms.txt
+>
+> Use publishable key `fd_pk_live_…` for all reads, in the browser. Base URL
+> `https://api.frontdesk.africa/v1`, `Authorization: Bearer <key>`.
+>
+> Pages: home rendering `GET /v1/store/storefront`, a product list from `GET /v1/store/products`, and
+> a product page from `GET /v1/store/products/{slug}`.
+>
+> For checkout, call `POST /v1/store/checkouts` **from a server route, never the browser**, using the
+> secret key, with an `Idempotency-Key` header derived from the cart id. Redirect the buyer to the
+> `hostedUrl` you get back. Do not build a payment form and do not ask for card details.
+>
+> After the buyer returns, confirm with `GET /v1/store/checkouts/{ref}` server-side before showing a
+> success page. Never trust the redirect alone.
+
+The origin your app is served from must be registered on the publishable key, in the merchant's
+FrontDesk portal under Settings → Website → Developers. Until it is, every call is refused.
+
+### Next.js (App Router)
+
+```ts
+// lib/store.ts — browser-safe reads
+import { createStoreClient } from '@frontdesk-africa/store-js'
+export const store = createStoreClient({
+  baseUrl: process.env.NEXT_PUBLIC_FRONTDESK_API!,
+  key: process.env.NEXT_PUBLIC_FRONTDESK_PK!,
+})
+
+// lib/store.server.ts — server only, never imported by a client component
+import 'server-only'
+import { createStoreClient } from '@frontdesk-africa/store-js'
+export const storeServer = createStoreClient({
+  baseUrl: process.env.FRONTDESK_API!,
+  key: process.env.FRONTDESK_SK!,
+})
+```
+
+```ts
+// app/api/checkout/route.ts
+import { storeServer } from '@/lib/store.server'
+
+export async function POST(req: Request) {
+  const { items, cartId } = await req.json()
+  const checkout = await storeServer.createCheckout(
+    { items, returnUrl: `${process.env.SITE_URL}/thanks` },
+    `cart_${cartId}`,
+  )
+  return Response.json({ hostedUrl: checkout.hostedUrl })
+}
+```
+
+The `server-only` import is the guard that matters: it turns "I accidentally imported the secret key
+into a client component" from a silent production leak into a build error.
+
+### Expo / React Native
+
+```ts
+const store = createStoreClient({
+  baseUrl: process.env.EXPO_PUBLIC_FRONTDESK_API!,
+  key: process.env.EXPO_PUBLIC_FRONTDESK_PK!,
+})
+```
+
+A native app has no browser `Origin`, so the origin lock does not apply the same way — treat the
+publishable key as public (it is), keep the secret key on your own server, and open checkouts there.
+Send the buyer to `hostedUrl` in a system browser or web view, then confirm server-side on return.
+
+## Errors
+
+```ts
+import { StoreApiError } from '@frontdesk-africa/store-js'
+
+try {
+  await store.product('nope')
+} catch (e) {
+  if (e instanceof StoreApiError) {
+    e.code       // 'NOT_FOUND' | 'ORIGIN_NOT_ALLOWED' | 'INSUFFICIENT_SCOPE' | 'RATE_LIMITED' | …
+    e.retryable  // honour Retry-After on RATE_LIMITED
+    e.requestId  // quote this when asking us for help
+  }
+}
+```
+
+`ORIGIN_NOT_ALLOWED` almost always means the origin is not on the key, or the key has no origins at
+all. `INSUFFICIENT_SCOPE` means a publishable key tried something only a secret key can do.
+
+`STORE_API_SECRET_DISABLED` means your workspace is not cleared for server-side (`fd_sk_`) calls yet —
+ask us to switch it on. Publishable reads are not affected and keep working. `STORE_API_DISABLED` is
+different: it means the whole workspace is switched off, and both kinds of key stop.