@frontdesk-africa/store-js 0.1.0

package/dist/index.js

@@ -0,0 +1,177 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StoreApiError: () => StoreApiError,
+  createStoreClient: () => createStoreClient,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+var StoreApiError = class extends Error {
+  static {
+    __name(this, "StoreApiError");
+  }
+  code;
+  status;
+  retryable;
+  requestId;
+  details;
+  constructor(status, body) {
+    const e = body?.error ?? {};
+    super(typeof e.message === "string" ? e.message : `Request failed (${status})`);
+    this.name = "StoreApiError";
+    this.status = status;
+    this.code = typeof e.code === "string" ? e.code : "INTERNAL";
+    this.retryable = e.retryable === true;
+    this.requestId = typeof e.requestId === "string" ? e.requestId : null;
+    this.details = e.details;
+  }
+};
+function createStoreClient(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  async function request(path, init) {
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${opts.key}`,
+      ...init?.headers ?? {}
+    };
+    if (init?.body) headers["Content-Type"] = "application/json";
+    if (init?.idempotencyKey) headers["Idempotency-Key"] = init.idempotencyKey;
+    const res = await doFetch(`${base}${path}`, {
+      ...init,
+      headers
+    });
+    const text = await res.text();
+    const body = text ? JSON.parse(text) : null;
+    if (!res.ok) throw new StoreApiError(res.status, body);
+    return body;
+  }
+  __name(request, "request");
+  const enc = encodeURIComponent;
+  return {
+    /** Escape hatch for anything not yet wrapped. Same auth, same error handling. */
+    request,
+    // ------------------------------------------------------------- read (fd_pk_)
+    storefront: /* @__PURE__ */ __name(() => request("/store/storefront"), "storefront"),
+    products: /* @__PURE__ */ __name(() => request("/store/products"), "products"),
+    product: /* @__PURE__ */ __name((slug) => request(`/store/products/${enc(slug)}`), "product"),
+    productSlots: /* @__PURE__ */ __name((slug, opts2) => request(`/store/products/${enc(slug)}/slots?variantRef=${enc(opts2.variantRef)}&date=${enc(opts2.date)}`), "productSlots"),
+    collections: /* @__PURE__ */ __name(() => request("/store/collections"), "collections"),
+    collection: /* @__PURE__ */ __name((slug) => request(`/store/collections/${enc(slug)}`), "collection"),
+    events: /* @__PURE__ */ __name(() => request("/store/events"), "events"),
+    event: /* @__PURE__ */ __name((slug) => request(`/store/events/${enc(slug)}`), "event"),
+    form: /* @__PURE__ */ __name((slug) => request(`/store/forms/${enc(slug)}`), "form"),
+    table: /* @__PURE__ */ __name((slug) => request(`/store/tables/${enc(slug)}`), "table"),
+    catalog: /* @__PURE__ */ __name((slug) => request(`/store/catalogs/${enc(slug)}`), "catalog"),
+    files: /* @__PURE__ */ __name((slug) => request(`/store/files/${enc(slug)}`), "files"),
+    note: /* @__PURE__ */ __name((slug) => request(`/store/notes/${enc(slug)}`), "note"),
+    deliveryZones: /* @__PURE__ */ __name(() => request("/store/delivery-zones"), "deliveryZones"),
+    /**
+    * Live stock for the variants a cart already holds — a cart is localStorage, so its lines can be
+    * days old. A ref missing from the response map is no longer purchasable: drop that line. Refs in
+    * `preorderable` are still buyable at 0 stock; cap those on `preorderRemaining` instead.
+    */
+    availability: /* @__PURE__ */ __name((variantRefs) => request(`/store/availability?variantRefs=${enc(variantRefs.join(","))}`), "availability"),
+    /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
+    paymentMethods: /* @__PURE__ */ __name((currency) => request(`/store/payment-methods${currency ? `?currency=${enc(currency)}` : ""}`), "paymentMethods"),
+    // --------------------------------------------------- checkout (fd_sk_, server)
+    /**
+    * Open a hosted checkout. SERVER ONLY — needs a secret key.
+    *
+    * `idempotencyKey` is required by the API, not optional politeness: reuse the same value on a
+    * retry and you get the SAME checkout back instead of charging a buyer twice. Derive it from
+    * something stable in your own system (your cart id), never a random value per attempt.
+    */
+    createCheckout: /* @__PURE__ */ __name((input, idempotencyKey) => request("/store/checkouts", {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createCheckout"),
+    /**
+    * Open a hosted checkout for event tickets. SERVER ONLY — needs a secret key.
+    *
+    * `GET /store/events/:slug` tells you what to collect first: each tier carries formFields,
+    * requiresAttendeeDetails, groupSize and min/max per order; the event carries minAge and dobMode.
+    * Everything is re-validated server-side, so prices and availability are never yours to decide.
+    */
+    createEventCheckout: /* @__PURE__ */ __name((slug, input, idempotencyKey) => request(`/store/events/${enc(slug)}/checkout`, {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createEventCheckout"),
+    /**
+    * Open a ticket checkout you render yourself, including the payment step. SERVER ONLY, and the
+    * workspace must have headless switched on. Name ONE provider from `paymentMethods()`; branch on
+    * the provider you asked for, never on which payment field came back filled in.
+    */
+    createHeadlessCheckout: /* @__PURE__ */ __name((slug, input, idempotencyKey) => request(`/store/events/${enc(slug)}/checkout/headless`, {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createHeadlessCheckout"),
+    /**
+    * The state of a checkout. THIS is how you confirm a purchase — the return redirect is a browser
+    * navigation and can be lost, replayed or forged, so never fulfil on it alone. Safe to poll while
+    * a buyer is paying: an open session is verified against the provider before we answer.
+    */
+    getCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}`), "getCheckout"),
+    /**
+    * Cancel an open checkout and release the seats it was holding, instead of leaving them out of
+    * stock until the session lapses. Cancelling an already-paid checkout returns 409.
+    */
+    cancelCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}/cancel`, {
+      method: "POST"
+    }), "cancelCheckout")
+  };
+}
+__name(createStoreClient, "createStoreClient");
+async function verifyWebhook(opts) {
+  const { createHmac, timingSafeEqual } = await import("crypto");
+  const ts = String(opts.timestampHeader ?? "");
+  const got = String(opts.signatureHeader ?? "").replace(/^sha256=/, "");
+  if (!ts || !got) return false;
+  const tolerance = opts.toleranceSec ?? 300;
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - Number(ts));
+  if (!Number.isFinite(age) || age > tolerance) return false;
+  const want = createHmac("sha256", opts.secret).update(`${ts}.${opts.rawBody}`).digest("hex");
+  const a = Buffer.from(got, "utf8");
+  const b = Buffer.from(want, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+__name(verifyWebhook, "verifyWebhook");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StoreApiError,
+  createStoreClient,
+  verifyWebhook
+});

package/dist/index.mjs

@@ -0,0 +1,142 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+var StoreApiError = class extends Error {
+  static {
+    __name(this, "StoreApiError");
+  }
+  code;
+  status;
+  retryable;
+  requestId;
+  details;
+  constructor(status, body) {
+    const e = body?.error ?? {};
+    super(typeof e.message === "string" ? e.message : `Request failed (${status})`);
+    this.name = "StoreApiError";
+    this.status = status;
+    this.code = typeof e.code === "string" ? e.code : "INTERNAL";
+    this.retryable = e.retryable === true;
+    this.requestId = typeof e.requestId === "string" ? e.requestId : null;
+    this.details = e.details;
+  }
+};
+function createStoreClient(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  async function request(path, init) {
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${opts.key}`,
+      ...init?.headers ?? {}
+    };
+    if (init?.body) headers["Content-Type"] = "application/json";
+    if (init?.idempotencyKey) headers["Idempotency-Key"] = init.idempotencyKey;
+    const res = await doFetch(`${base}${path}`, {
+      ...init,
+      headers
+    });
+    const text = await res.text();
+    const body = text ? JSON.parse(text) : null;
+    if (!res.ok) throw new StoreApiError(res.status, body);
+    return body;
+  }
+  __name(request, "request");
+  const enc = encodeURIComponent;
+  return {
+    /** Escape hatch for anything not yet wrapped. Same auth, same error handling. */
+    request,
+    // ------------------------------------------------------------- read (fd_pk_)
+    storefront: /* @__PURE__ */ __name(() => request("/store/storefront"), "storefront"),
+    products: /* @__PURE__ */ __name(() => request("/store/products"), "products"),
+    product: /* @__PURE__ */ __name((slug) => request(`/store/products/${enc(slug)}`), "product"),
+    productSlots: /* @__PURE__ */ __name((slug, opts2) => request(`/store/products/${enc(slug)}/slots?variantRef=${enc(opts2.variantRef)}&date=${enc(opts2.date)}`), "productSlots"),
+    collections: /* @__PURE__ */ __name(() => request("/store/collections"), "collections"),
+    collection: /* @__PURE__ */ __name((slug) => request(`/store/collections/${enc(slug)}`), "collection"),
+    events: /* @__PURE__ */ __name(() => request("/store/events"), "events"),
+    event: /* @__PURE__ */ __name((slug) => request(`/store/events/${enc(slug)}`), "event"),
+    form: /* @__PURE__ */ __name((slug) => request(`/store/forms/${enc(slug)}`), "form"),
+    table: /* @__PURE__ */ __name((slug) => request(`/store/tables/${enc(slug)}`), "table"),
+    catalog: /* @__PURE__ */ __name((slug) => request(`/store/catalogs/${enc(slug)}`), "catalog"),
+    files: /* @__PURE__ */ __name((slug) => request(`/store/files/${enc(slug)}`), "files"),
+    note: /* @__PURE__ */ __name((slug) => request(`/store/notes/${enc(slug)}`), "note"),
+    deliveryZones: /* @__PURE__ */ __name(() => request("/store/delivery-zones"), "deliveryZones"),
+    /**
+    * Live stock for the variants a cart already holds — a cart is localStorage, so its lines can be
+    * days old. A ref missing from the response map is no longer purchasable: drop that line. Refs in
+    * `preorderable` are still buyable at 0 stock; cap those on `preorderRemaining` instead.
+    */
+    availability: /* @__PURE__ */ __name((variantRefs) => request(`/store/availability?variantRefs=${enc(variantRefs.join(","))}`), "availability"),
+    /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
+    paymentMethods: /* @__PURE__ */ __name((currency) => request(`/store/payment-methods${currency ? `?currency=${enc(currency)}` : ""}`), "paymentMethods"),
+    // --------------------------------------------------- checkout (fd_sk_, server)
+    /**
+    * Open a hosted checkout. SERVER ONLY — needs a secret key.
+    *
+    * `idempotencyKey` is required by the API, not optional politeness: reuse the same value on a
+    * retry and you get the SAME checkout back instead of charging a buyer twice. Derive it from
+    * something stable in your own system (your cart id), never a random value per attempt.
+    */
+    createCheckout: /* @__PURE__ */ __name((input, idempotencyKey) => request("/store/checkouts", {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createCheckout"),
+    /**
+    * Open a hosted checkout for event tickets. SERVER ONLY — needs a secret key.
+    *
+    * `GET /store/events/:slug` tells you what to collect first: each tier carries formFields,
+    * requiresAttendeeDetails, groupSize and min/max per order; the event carries minAge and dobMode.
+    * Everything is re-validated server-side, so prices and availability are never yours to decide.
+    */
+    createEventCheckout: /* @__PURE__ */ __name((slug, input, idempotencyKey) => request(`/store/events/${enc(slug)}/checkout`, {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createEventCheckout"),
+    /**
+    * Open a ticket checkout you render yourself, including the payment step. SERVER ONLY, and the
+    * workspace must have headless switched on. Name ONE provider from `paymentMethods()`; branch on
+    * the provider you asked for, never on which payment field came back filled in.
+    */
+    createHeadlessCheckout: /* @__PURE__ */ __name((slug, input, idempotencyKey) => request(`/store/events/${enc(slug)}/checkout/headless`, {
+      method: "POST",
+      body: JSON.stringify(input),
+      idempotencyKey
+    }), "createHeadlessCheckout"),
+    /**
+    * The state of a checkout. THIS is how you confirm a purchase — the return redirect is a browser
+    * navigation and can be lost, replayed or forged, so never fulfil on it alone. Safe to poll while
+    * a buyer is paying: an open session is verified against the provider before we answer.
+    */
+    getCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}`), "getCheckout"),
+    /**
+    * Cancel an open checkout and release the seats it was holding, instead of leaving them out of
+    * stock until the session lapses. Cancelling an already-paid checkout returns 409.
+    */
+    cancelCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}/cancel`, {
+      method: "POST"
+    }), "cancelCheckout")
+  };
+}
+__name(createStoreClient, "createStoreClient");
+async function verifyWebhook(opts) {
+  const { createHmac, timingSafeEqual } = await import("crypto");
+  const ts = String(opts.timestampHeader ?? "");
+  const got = String(opts.signatureHeader ?? "").replace(/^sha256=/, "");
+  if (!ts || !got) return false;
+  const tolerance = opts.toleranceSec ?? 300;
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - Number(ts));
+  if (!Number.isFinite(age) || age > tolerance) return false;
+  const want = createHmac("sha256", opts.secret).update(`${ts}.${opts.rawBody}`).digest("hex");
+  const a = Buffer.from(got, "utf8");
+  const b = Buffer.from(want, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+__name(verifyWebhook, "verifyWebhook");
+export {
+  StoreApiError,
+  createStoreClient,
+  verifyWebhook
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@frontdesk-africa/store-js",
+  "version": "0.1.0",
+  "description": "Typed client for the FrontDesk Storefront API: catalogue, events, forms, hosted checkout and signed webhooks.",
+  "license": "MIT",
+  "homepage": "https://api.frontdesk.africa/v1/store/docs",
+  "keywords": [
+    "frontdesk",
+    "storefront",
+    "ecommerce",
+    "checkout",
+    "webhooks",
+    "api-client"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "release:check": "pnpm build && npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@frontdesk/shared": "workspace:*",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0"
+  }
+}