@zappie/sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zappie/sdk
 
+## 0.5.0
+
+### Minor Changes
+
+- a5bd08f: `@zappie/sdk/account` reads the signed-in shopper's account through the same endpoint and session as `createCustomer`. `createAccount()` returns `wallets()`, `cards()`, `removeCard(id)`, `payments({ limit, cursor })` and `payment(id)`. A call the shopper's sign-in doesn't cover rejects with `ScopeRequiredError`, which names the scope, and a card or payment that isn't theirs rejects with `NotFoundError`. Both are a `CustomerError`. `accountsUrl(path, environment, { returnTo })` builds a link to a page on the Zappie accounts portal, `/account`, `/account/profile`, `/account/payouts`, `/account/withdraw` or `/account/activity`, with the page to come back to. It refuses a path the way `checkoutUrl` does. `@zappie/sdk/testing` adds `mockAccountFetch()` and `accountFixtures`, which answer the account endpoints as the API does, including a removed card and a missing scope.
+
+  `@zappie/foundations/account` adds headless account parts that load only on account pages: `Wallets`, `Cards`, `RemoveCard` (a confirmation before a card is removed), `Payments`, `Receipt` and `ScopeMissing`, which offers to sign in again. `SignInOptions.scopes` accepts `wallet`, `cards` and `payments:read`.
+
+  `no-offsite-navigation` trusts the staging accounts portal and `accountsUrl` from `@zappie/sdk/account`, and `no-direct-api` points a written-out accounts address to `accountsUrl`.
+
+## 0.4.0
+
+### Minor Changes
+
+- b884697: `zappieSupportUrl(context)` in `@zappie/foundations` builds a WhatsApp link to Zappie support for a shopper with a problem such as a payment. Its message starts with "Hi Zappie support," and names the store, the branch when the store has more than one, the order and the page, as the classic storefront does. `ZAPPIE_SUPPORT_WHATSAPP` in `@zappie/sdk/services` is the number it opens.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -50,21 +50,22 @@ Prices always come from Zappie. The cart shows a local estimate while it waits,
 
 ## Entry points
 
-| Import                                       | For                                                                                      |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `@zappie/sdk`                                | The client, the cart, money formatting and errors                                        |
-| `@zappie/sdk/react`                          | `ZappieProvider` and hooks such as `useStore`, `useMenu` and `useCart`                   |
-| `@zappie/sdk/checkout`                       | Opening Zappie's hosted checkout and checking it completed                               |
-| `@zappie/sdk/checkout-defaults`              | The phone, address, region and time a signed-in checkout starts from                     |
-| `@zappie/sdk/customer` and `/customer/react` | Signed-in customers, their orders and saved addresses                                    |
-| `@zappie/sdk/integrations`                   | Public integration IDs and browser keys                                                  |
-| `@zappie/sdk/places`                         | Address search and delivery-zone checks                                                  |
-| `@zappie/sdk/pricing`                        | An item's starting price and whether to show it as "From"                                |
-| `@zappie/sdk/server`                         | Server-side reads, storefront URLs, `verifyWebhook()`, menu snapshots and sign-in crypto |
-| `@zappie/sdk/template` and `/template/react` | Template settings and responsive images for template authors                             |
-| `@zappie/sdk/testing`                        | A mock client for your tests                                                             |
-| `@zappie/sdk/url`                            | Storefront URL parsing and canonical redirects                                           |
-| `@zappie/sdk/redirect`                       | Same-origin validation for untrusted redirect targets                                    |
+| Import                                       | For                                                                                        |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `@zappie/sdk`                                | The client, the cart, money formatting and errors                                          |
+| `@zappie/sdk/react`                          | `ZappieProvider` and hooks such as `useStore`, `useMenu` and `useCart`                     |
+| `@zappie/sdk/checkout`                       | Opening Zappie's hosted checkout and checking it completed                                 |
+| `@zappie/sdk/checkout-defaults`              | The phone, address, region and time a signed-in checkout starts from                       |
+| `@zappie/sdk/customer` and `/customer/react` | Signed-in customers, their orders and saved addresses                                      |
+| `@zappie/sdk/account`                        | The shopper's wallet, saved cards, payments and receipts, and links to the accounts portal |
+| `@zappie/sdk/integrations`                   | Public integration IDs and browser keys                                                    |
+| `@zappie/sdk/places`                         | Address search and delivery-zone checks                                                    |
+| `@zappie/sdk/pricing`                        | An item's starting price and whether to show it as "From"                                  |
+| `@zappie/sdk/server`                         | Server-side reads, storefront URLs, `verifyWebhook()`, menu snapshots and sign-in crypto   |
+| `@zappie/sdk/template` and `/template/react` | Template settings and responsive images for template authors                               |
+| `@zappie/sdk/testing`                        | A mock client and mock account endpoints for your tests                                    |
+| `@zappie/sdk/url`                            | Storefront URL parsing and canonical redirects                                             |
+| `@zappie/sdk/redirect`                       | Same-origin validation for untrusted redirect targets                                      |
 
 Customer sign-in runs through Zappie's site host, so `@zappie/sdk/customer` works on sites Zappie hosts. Sign-in for a site you host yourself isn't available yet.
 

package/dist/account/client.js

@@ -0,0 +1,68 @@
+// src/account/client.ts
+import { CustomerError } from "../customer/error.js";
+import { createCustomerRequest } from "../customer/request.js";
+import { NotFoundError, ScopeRequiredError } from "./errors.js";
+function createAccount(options = {}) {
+  const base = (options.customerBase ?? "/_zappie/api").replace(/\/+$/, "");
+  const request = createCustomerRequest(
+    base,
+    options.fetch ?? globalThis.fetch,
+    () => {
+      void options.customer?.session().catch(() => void 0);
+    }
+  );
+  const call = async (scope, path, method = "GET") => {
+    try {
+      return await request(path, { method });
+    } catch (error) {
+      if (error instanceof CustomerError) {
+        if (error.apiCode === "scope_required") {
+          throw new ScopeRequiredError(scope, error.message);
+        }
+        if (error.status === 404) {
+          throw new NotFoundError(error.message);
+        }
+      }
+      throw error;
+    }
+  };
+  return {
+    /** The shopper's Zappie wallet, one balance per currency, naira first. Needs the `wallet` scope. */
+    async wallets() {
+      return (await call("wallet", "/me/wallets")).wallets;
+    },
+    /** The cards the shopper saved when they paid. Needs the `cards` scope. */
+    async cards() {
+      return (await call("cards", "/me/cards")).cards;
+    },
+    /** Remove one of the shopper's saved cards. Needs the `cards` scope. */
+    removeCard: (id) => call("cards", `/me/cards/${encodeURIComponent(id)}`, "DELETE"),
+    /**
+     * One page of the shopper's payments at this business, newest first. Needs the `payments:read` scope.
+     *
+     * @param page - Up to 50 payments a page, 20 by default, and the next_cursor of the previous page.
+     */
+    payments(page = {}) {
+      const query = new URLSearchParams();
+      if (page.limit !== void 0) {
+        query.set("limit", String(page.limit));
+      }
+      if (page.cursor !== void 0) {
+        query.set("cursor", page.cursor);
+      }
+      return call(
+        "payments:read",
+        `/me/payments${query.size > 0 ? `?${query}` : ""}`
+      );
+    },
+    /** One payment with what its receipt shows. Needs the `payments:read` scope. */
+    payment: (id) => call(
+      "payments:read",
+      `/me/payments/${encodeURIComponent(id)}`
+    )
+  };
+}
+export {
+  createAccount
+};
+//# sourceMappingURL=client.js.map

package/dist/account/client.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/account/client.ts"],
+  "mappings": ";AAAA,SAAS,qBAAqB;AAC9B,SAAS,6BAA6B;AACtC,SAAS,eAAe,0BAA0B;AAmB3C,SAAS,cAAc,UAAgC,CAAC,GAAG;AAChE,QAAM,QAAQ,QAAQ,gBAAgB,gBAAgB,QAAQ,QAAQ,EAAE;AACxE,QAAM,UAAU;AAAA,IACd;AAAA,IACA,QAAQ,SAAS,WAAW;AAAA,IAC5B,MAAM;AACJ,WAAK,QAAQ,UAAU,QAAQ,EAAE,MAAM,MAAM,MAAS;AAAA,IACxD;AAAA,EACF;AACA,QAAM,OAAO,OACX,OACA,MACA,SAAS,UACM;AACf,QAAI;AACF,aAAO,MAAM,QAAW,MAAM,EAAE,OAAO,CAAC;AAAA,IAC1C,SAAS,OAAO;AACd,UAAI,iBAAiB,eAAe;AAClC,YAAI,MAAM,YAAY,kBAAkB;AACtC,gBAAM,IAAI,mBAAmB,OAAO,MAAM,OAAO;AAAA,QACnD;AACA,YAAI,MAAM,WAAW,KAAK;AACxB,gBAAM,IAAI,cAAc,MAAM,OAAO;AAAA,QACvC;AAAA,MACF;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACA,SAAO;AAAA;AAAA,IAEL,MAAM,UAA6B;AACjC,cAAQ,MAAM,KAA4B,UAAU,aAAa,GAC9D;AAAA,IACL;AAAA;AAAA,IAEA,MAAM,QAA8B;AAClC,cAAQ,MAAM,KAA6B,SAAS,WAAW,GAAG;AAAA,IACpE;AAAA;AAAA,IAEA,YAAY,CAAC,OACX,KAAK,SAAS,aAAa,mBAAmB,EAAE,CAAC,IAAI,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAM/D,SAAS,OAA4C,CAAC,GAAG;AACvD,YAAM,QAAQ,IAAI,gBAAgB;AAClC,UAAI,KAAK,UAAU,QAAW;AAC5B,cAAM,IAAI,SAAS,OAAO,KAAK,KAAK,CAAC;AAAA,MACvC;AACA,UAAI,KAAK,WAAW,QAAW;AAC7B,cAAM,IAAI,UAAU,KAAK,MAAM;AAAA,MACjC;AACA,aAAO;AAAA,QACL;AAAA,QACA,eAAe,MAAM,OAAO,IAAI,IAAI,KAAK,KAAK,EAAE;AAAA,MAClD;AAAA,IACF;AAAA;AAAA,IAEA,SAAS,CAAC,OACR;AAAA,MACE;AAAA,MACA,gBAAgB,mBAAmB,EAAE,CAAC;AAAA,IACxC;AAAA,EACJ;AACF;",
+  "names": []
+}

package/dist/account/errors.js

@@ -0,0 +1,20 @@
+// src/account/errors.ts
+import { CustomerError } from "../customer/error.js";
+var ScopeRequiredError = class extends CustomerError {
+  constructor(scope, message) {
+    super(403, "scope_required", message);
+    this.scope = scope;
+    this.name = "ScopeRequiredError";
+  }
+};
+var NotFoundError = class extends CustomerError {
+  constructor(message) {
+    super(404, "not_found", message);
+    this.name = "NotFoundError";
+  }
+};
+export {
+  NotFoundError,
+  ScopeRequiredError
+};
+//# sourceMappingURL=errors.js.map

package/dist/account/errors.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/account/errors.ts"],
+  "mappings": ";AAAA,SAAS,qBAAqB;AAOvB,IAAM,qBAAN,cAAiC,cAAc;AAAA,EACpD,YAEW,OACT,SACA;AACA,UAAM,KAAK,kBAAkB,OAAO;AAH3B;AAIT,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,gBAAN,cAA4B,cAAc;AAAA,EAC/C,YAAY,SAAiB;AAC3B,UAAM,KAAK,aAAa,OAAO;AAC/B,SAAK,OAAO;AAAA,EACd;AACF;",
+  "names": []
+}

package/dist/account/index.d.ts

@@ -0,0 +1,150 @@
+import { ZappieError } from '@zappie/sdk';
+
+/**
+ * A customer API amount in minor currency units, paired with its currency code.
+ */
+type Money = {
+    amount_minor: number;
+    currency: string;
+};
+
+/** A scope the account calls need. A token without it gets `scope_required`. */
+type AccountScope = "wallet" | "cards" | "payments:read";
+/** One balance in the shopper's Zappie wallet, which is the same at every business. */
+type Wallet = {
+    currency: string;
+    balance: Money;
+};
+/** A card the shopper saved when they paid. It never carries the full card number. */
+type SavedCard = {
+    id: string;
+    /** The card scheme in lower case, such as `mastercard`. */
+    brand: string;
+    last4: string;
+    exp_month: number;
+    exp_year: number;
+};
+/** A payment the shopper made at this business. */
+type CustomerPayment = {
+    id: string;
+    status: "successful" | "failed" | "refunded";
+    /** What the payment was for. */
+    amount: Money;
+    /** What the shopper paid, fees included. */
+    paid: Money;
+    reference: string;
+    branch_id: string;
+    /** The order the payment paid for, or null when it wasn't a delivery or pickup order. */
+    order_id: string | null;
+    created_at: string;
+    paid_at: string | null;
+};
+/** A page of payments and the cursor for the next page, or null at the end. */
+type PaymentsPage = {
+    payments: CustomerPayment[];
+    next_cursor: string | null;
+};
+/** How the shopper paid. A card shows its brand and last four digits, a bank transfer its bank and account name. */
+type PaymentMethodDetails = {
+    type: "card" | "card_terminal" | "bank_transfer" | "wallet" | "apple_pay" | "google_pay" | "store_credit" | "loyalty_points" | "mobile_money" | "other";
+    card_brand?: string;
+    card_last4?: string;
+    bank_name?: string;
+    account_name?: string;
+};
+/** A payment with what its receipt shows: the branch's name and how the shopper paid. */
+type PaymentReceipt = CustomerPayment & {
+    branch_name: string;
+    method: PaymentMethodDetails;
+};
+/**
+ * Where the account calls go and how. They share the customer client's defaults, so a site that
+ * changed `customerBase` or `fetch` for createCustomer passes the same values here.
+ */
+type AccountClientOptions = {
+    customerBase?: string;
+    fetch?: typeof fetch;
+    /** The site's customer client. A call the session no longer allows re-checks it, so the site sees the shopper signed out. */
+    customer?: {
+        session(): Promise<unknown>;
+    };
+};
+
+/**
+ * Create a client for the shopper's wallet, saved cards and payments at this business, through the
+ * same endpoint and session as createCustomer. Load it only on account pages.
+ * A call the shopper's sign-in doesn't allow rejects with ScopeRequiredError. A card or payment that
+ * isn't theirs rejects with NotFoundError. Any other failure is a CustomerError.
+ *
+ * @param options - Endpoint and fetch overrides, and the site's customer client.
+ * @returns The account calls.
+ */
+declare function createAccount(options?: AccountClientOptions): {
+    /** The shopper's Zappie wallet, one balance per currency, naira first. Needs the `wallet` scope. */
+    wallets(): Promise<Wallet[]>;
+    /** The cards the shopper saved when they paid. Needs the `cards` scope. */
+    cards(): Promise<SavedCard[]>;
+    /** Remove one of the shopper's saved cards. Needs the `cards` scope. */
+    removeCard: (id: string) => Promise<void>;
+    /**
+     * One page of the shopper's payments at this business, newest first. Needs the `payments:read` scope.
+     *
+     * @param page - Up to 50 payments a page, 20 by default, and the next_cursor of the previous page.
+     */
+    payments(page?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<PaymentsPage>;
+    /** One payment with what its receipt shows. Needs the `payments:read` scope. */
+    payment: (id: string) => Promise<PaymentReceipt>;
+};
+/** The wallet, card and payment calls returned by createAccount. */
+type AccountClient = ReturnType<typeof createAccount>;
+
+/**
+ * A customer API failure with its HTTP status, API code and optional validation issues.
+ * Statuses 429 and 5xx are marked retryable.
+ */
+declare class CustomerError extends ZappieError {
+    readonly apiCode: string;
+    readonly issues?: unknown;
+    constructor(status: number, apiCode: string, message: string, param?: string, issues?: unknown);
+}
+
+/**
+ * The shopper's sign-in doesn't include the scope this call needs, usually because they signed in
+ * before the site asked for it. Offer to sign in again. It doesn't sign the shopper out.
+ */
+declare class ScopeRequiredError extends CustomerError {
+    /** The scope the call needs. */
+    readonly scope: AccountScope;
+    constructor(
+    /** The scope the call needs. */
+    scope: AccountScope, message: string);
+}
+/** The card or payment isn't the shopper's, or isn't at this business. */
+declare class NotFoundError extends CustomerError {
+    constructor(message: string);
+}
+
+/** The Zappie environment a service URL points at. */
+type ZappieEnvironment = "production" | "staging";
+
+/** A page on the Zappie accounts portal. */
+type AccountsPage = "/account" | "/account/profile" | "/account/payouts" | "/account/withdraw" | "/account/activity";
+/**
+ * Build a link to a page on the Zappie accounts portal, where the shopper changes their name or
+ * email, adds a payout account, withdraws from their wallet or sees all their activity. The portal
+ * links back to `returnTo` when it is a page on a site registered with Zappie.
+ *
+ * @param path - The portal page, such as `/account/withdraw`.
+ * @param environment - `staging` for a test host. Defaults to `production`.
+ * @param options - `returnTo`, the page to come back to. A path resolves against the current page.
+ * @returns The absolute portal URL. A path that could leave the portal, or a `returnTo` that isn't an http or https page, throws a TypeError.
+ */
+declare function accountsUrl(path: AccountsPage, environment?: ZappieEnvironment, options?: {
+    returnTo?: string | URL;
+}): string;
+
+export { NotFoundError, ScopeRequiredError, accountsUrl, createAccount };
+export type { AccountClient, AccountClientOptions, AccountScope, AccountsPage, CustomerPayment, PaymentMethodDetails, PaymentReceipt, PaymentsPage, SavedCard, Wallet };

package/dist/account/index.js

@@ -0,0 +1,11 @@
+// src/account/index.ts
+import { createAccount } from "./client.js";
+import { NotFoundError, ScopeRequiredError } from "./errors.js";
+import { accountsUrl } from "./url.js";
+export {
+  NotFoundError,
+  ScopeRequiredError,
+  accountsUrl,
+  createAccount
+};
+//# sourceMappingURL=index.js.map

package/dist/account/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/account/index.ts"],
+  "mappings": ";AAAA,SAAS,qBAAqB;AAE9B,SAAS,eAAe,0BAA0B;AAElD,SAAS,mBAAmB;",
+  "names": []
+}

package/dist/account/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/account/types.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": [],
+  "mappings": "",
+  "names": []
+}

package/dist/account/url.js

@@ -0,0 +1,24 @@
+// src/account/url.ts
+import { serviceUrl } from "../internal/service-url.js";
+var ACCOUNTS = {
+  production: "https://accounts.zappie.ai",
+  staging: "https://accounts.stg.zappie.ai"
+};
+function accountsUrl(path, environment = "production", options = {}) {
+  const url = new URL(serviceUrl(ACCOUNTS, path, environment));
+  if (options.returnTo !== void 0) {
+    const back = new URL(
+      options.returnTo,
+      typeof location === "undefined" ? void 0 : location.href
+    );
+    if (back.protocol !== "https:" && back.protocol !== "http:") {
+      throw new TypeError("Pass an http or https page to return to");
+    }
+    url.searchParams.set("return", back.href);
+  }
+  return url.href;
+}
+export {
+  accountsUrl
+};
+//# sourceMappingURL=url.js.map

package/dist/account/url.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/account/url.ts"],
+  "mappings": ";AAAA,SAAS,kBAA0C;AAEnD,IAAM,WAAW;AAAA,EACf,YAAY;AAAA,EACZ,SAAS;AACX;AAoBO,SAAS,YACd,MACA,cAAiC,cACjC,UAAuC,CAAC,GAChC;AACR,QAAM,MAAM,IAAI,IAAI,WAAW,UAAU,MAAM,WAAW,CAAC;AAC3D,MAAI,QAAQ,aAAa,QAAW;AAClC,UAAM,OAAO,IAAI;AAAA,MACf,QAAQ;AAAA,MACR,OAAO,aAAa,cAAc,SAAY,SAAS;AAAA,IACzD;AACA,QAAI,KAAK,aAAa,YAAY,KAAK,aAAa,SAAS;AAC3D,YAAM,IAAI,UAAU,yCAAyC;AAAA,IAC/D;AACA,QAAI,aAAa,IAAI,UAAU,KAAK,IAAI;AAAA,EAC1C;AACA,SAAO,IAAI;AACb;",
+  "names": []
+}

package/dist/debug.js

@@ -1,5 +1,5 @@
 // src/debug.ts
-var VERSION = true ? "0.3.0" : "0.0.0-development";
+var VERSION = true ? "0.5.0" : "0.0.0-development";
 function installDebug(client) {
   if (typeof window === "undefined" || client.mode !== "test") {
     return;

package/dist/index.js

@@ -10,7 +10,7 @@ import { ZappieError, isZappieError } from "./errors.js";
 export * from "./models.js";
 import { format, money } from "./money.js";
 import { RestTransport } from "./transport/rest.js";
-var VERSION = true ? "0.3.0" : "0.0.0-development";
+var VERSION = true ? "0.5.0" : "0.0.0-development";
 export {
   API_VERSION,
   RestTransport,

package/dist/internal/service-url.js

@@ -0,0 +1,11 @@
+// src/internal/service-url.ts
+var serviceUrl = (origins, path, environment) => {
+  if (environment !== "production" && environment !== "staging" || !/^\/(?!\/)[^\u0000- \u007f\\]*$/u.test(path)) {
+    throw new TypeError("Pass a path that starts with one slash");
+  }
+  return origins[environment] + path;
+};
+export {
+  serviceUrl
+};
+//# sourceMappingURL=service-url.js.map

package/dist/internal/service-url.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/internal/service-url.ts"],
+  "mappings": ";AAIO,IAAM,aAAa,CACxB,SACA,MACA,gBACW;AACX,MACG,gBAAgB,gBAAgB,gBAAgB,aACjD,CAAC,kCAAkC,KAAK,IAAI,GAC5C;AACA,UAAM,IAAI,UAAU,wCAAwC;AAAA,EAC9D;AACA,SAAO,QAAQ,WAAW,IAAI;AAChC;",
+  "names": []
+}

package/dist/services/index.d.ts

@@ -1,5 +1,6 @@
 /** The Zappie environment a service URL points at. */
 type ZappieEnvironment = "production" | "staging";
+
 /**
  * Build a URL on Zappie's checkout, such as an old payment link's new home.
  *
@@ -16,6 +17,8 @@ declare const checkoutUrl: (path: string, environment?: ZappieEnvironment) => st
  * @returns The absolute app URL. A path that could leave the app throws a TypeError.
  */
 declare const appUrl: (path: string, environment?: ZappieEnvironment) => string;
+/** Zappie's support WhatsApp number, the same one the classic storefront opens. */
+declare const ZAPPIE_SUPPORT_WHATSAPP = "15558956471";
 
-export { appUrl, checkoutUrl };
+export { ZAPPIE_SUPPORT_WHATSAPP, appUrl, checkoutUrl };
 export type { ZappieEnvironment };

package/dist/services/index.js

@@ -1,23 +1,18 @@
 // src/services/index.ts
-var ORIGINS = {
-  checkout: {
-    production: "https://checkout.zappie.ai",
-    staging: "https://checkout.stg.zappie.ai"
-  },
-  app: {
-    production: "https://app.zappie.ai",
-    staging: "https://app.stg.zappie.ai"
-  }
+import { serviceUrl } from "../internal/service-url.js";
+var CHECKOUT = {
+  production: "https://checkout.zappie.ai",
+  staging: "https://checkout.stg.zappie.ai"
 };
-var serviceUrl = (service, path, environment) => {
-  if (environment !== "production" && environment !== "staging" || !/^\/(?!\/)[^\u0000- \u007f\\]*$/u.test(path)) {
-    throw new TypeError("Pass a path that starts with one slash");
-  }
-  return ORIGINS[service][environment] + path;
+var APP = {
+  production: "https://app.zappie.ai",
+  staging: "https://app.stg.zappie.ai"
 };
-var checkoutUrl = (path, environment = "production") => serviceUrl("checkout", path, environment);
-var appUrl = (path, environment = "production") => serviceUrl("app", path, environment);
+var checkoutUrl = (path, environment = "production") => serviceUrl(CHECKOUT, path, environment);
+var appUrl = (path, environment = "production") => serviceUrl(APP, path, environment);
+var ZAPPIE_SUPPORT_WHATSAPP = "15558956471";
 export {
+  ZAPPIE_SUPPORT_WHATSAPP,
   appUrl,
   checkoutUrl
 };

package/dist/services/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/services/index.ts"],
-  "mappings": ";AAIA,IAAM,UAAU;AAAA,EACd,UAAU;AAAA,IACR,YAAY;AAAA,IACZ,SAAS;AAAA,EACX;AAAA,EACA,KAAK;AAAA,IACH,YAAY;AAAA,IACZ,SAAS;AAAA,EACX;AACF;AAGA,IAAM,aAAa,CACjB,SACA,MACA,gBACW;AACX,MACG,gBAAgB,gBAAgB,gBAAgB,aACjD,CAAC,kCAAkC,KAAK,IAAI,GAC5C;AACA,UAAM,IAAI,UAAU,wCAAwC;AAAA,EAC9D;AACA,SAAO,QAAQ,OAAO,EAAE,WAAW,IAAI;AACzC;AASO,IAAM,cAAc,CACzB,MACA,cAAiC,iBACtB,WAAW,YAAY,MAAM,WAAW;AAS9C,IAAM,SAAS,CACpB,MACA,cAAiC,iBACtB,WAAW,OAAO,MAAM,WAAW;",
+  "mappings": ";AAAA,SAAS,kBAA0C;AAKnD,IAAM,WAAW;AAAA,EACf,YAAY;AAAA,EACZ,SAAS;AACX;AACA,IAAM,MAAM;AAAA,EACV,YAAY;AAAA,EACZ,SAAS;AACX;AASO,IAAM,cAAc,CACzB,MACA,cAAiC,iBACtB,WAAW,UAAU,MAAM,WAAW;AAS5C,IAAM,SAAS,CACpB,MACA,cAAiC,iBACtB,WAAW,KAAK,MAAM,WAAW;AAGvC,IAAM,0BAA0B;",
   "names": []
 }

package/dist/testing/account.js

@@ -0,0 +1,126 @@
+// src/testing/account.ts
+var ngn = (amount_minor) => ({ amount_minor, currency: "NGN" });
+var receipt = (id, status, amount, at, method) => ({
+  id,
+  status,
+  amount: ngn(amount),
+  paid: ngn(amount),
+  reference: `PAY_${id.slice(4).toUpperCase()}`,
+  branch_id: "br_fixture",
+  branch_name: "Main",
+  order_id: status === "failed" ? null : `ord_${id.slice(4)}`,
+  created_at: at,
+  paid_at: status === "failed" ? null : at,
+  method
+});
+var accountFixtures = {
+  wallets: [
+    { currency: "NGN", balance: ngn(25e5) },
+    { currency: "USD", balance: { amount_minor: 1250, currency: "USD" } }
+  ],
+  cards: [
+    {
+      id: "card_fixture1",
+      brand: "mastercard",
+      last4: "4321",
+      exp_month: 4,
+      exp_year: 2029
+    },
+    {
+      id: "card_fixture2",
+      brand: "visa",
+      last4: "1881",
+      exp_month: 11,
+      exp_year: 2027
+    }
+  ],
+  payments: [
+    receipt("pay_fixture3", "successful", 105e4, "2026-10-12T12:00:00Z", {
+      type: "card",
+      card_brand: "mastercard",
+      card_last4: "4321"
+    }),
+    receipt("pay_fixture2", "refunded", 45e4, "2026-10-11T09:30:00Z", {
+      type: "bank_transfer",
+      bank_name: "Example Bank",
+      account_name: "Ada Obi"
+    }),
+    receipt("pay_fixture1", "failed", 2e5, "2026-10-10T18:15:00Z", {
+      type: "wallet"
+    })
+  ]
+};
+var SCOPES = ["wallet", "cards", "payments:read"];
+function mockAccountFetch(fixtures = accountFixtures, options = {}) {
+  const data = structuredClone(fixtures);
+  const granted = options.scopes ?? SCOPES;
+  const error = (status, code, message) => Response.json({ error: { code, message } }, { status });
+  return async (input, init) => {
+    const request = new Request(
+      new URL(String(input), "http://mock.test"),
+      init
+    );
+    const url = new URL(request.url);
+    const [, resource, id, extra] = /\/me\/(wallets|cards|payments)(?:\/([^/]+))?(\/.*)?$/.exec(
+      url.pathname
+    ) ?? [];
+    if (!resource || extra !== void 0) {
+      return error(404, "not_found", "No such endpoint.");
+    }
+    const scope = resource === "wallets" ? "wallet" : resource === "cards" ? "cards" : "payments:read";
+    if (!granted.includes(scope)) {
+      return error(
+        403,
+        "scope_required",
+        `The customer did not grant the ${scope} scope.`
+      );
+    }
+    const method = request.method;
+    if (resource === "wallets" && id === void 0 && method === "GET") {
+      return Response.json({ wallets: data.wallets });
+    }
+    if (resource === "cards" && id === void 0 && method === "GET") {
+      return Response.json({ cards: data.cards });
+    }
+    if (resource === "cards" && id !== void 0 && method === "DELETE") {
+      const cardId = decodeURIComponent(id);
+      if (!/^card_\w+$/.test(cardId)) {
+        return error(400, "invalid_id", "That isn't a card ID.");
+      }
+      const index = data.cards.findIndex((card) => card.id === cardId);
+      if (index < 0) {
+        return error(404, "not_found", "No such card.");
+      }
+      data.cards.splice(index, 1);
+      return new Response(null, { status: 204 });
+    }
+    if (resource === "payments" && method === "GET") {
+      if (id !== void 0) {
+        const found = data.payments.find(
+          (payment) => payment.id === decodeURIComponent(id)
+        );
+        return found ? Response.json(found) : error(404, "not_found", "No such payment.");
+      }
+      const limit = Number(url.searchParams.get("limit") ?? 20);
+      const cursor = url.searchParams.get("cursor");
+      const start = cursor === null ? 0 : data.payments.findIndex((payment) => payment.id === cursor);
+      if (!Number.isInteger(limit) || limit < 1 || start < 0) {
+        return error(400, "parameter_invalid", "Check limit and cursor.");
+      }
+      const page = data.payments.slice(start, start + Math.min(limit, 50));
+      const next = data.payments[start + page.length];
+      return Response.json({
+        payments: page.map(
+          ({ branch_name: _name, method: _method, ...payment }) => payment
+        ),
+        next_cursor: next?.id ?? null
+      });
+    }
+    return error(405, "method_not_allowed", "Method not allowed.");
+  };
+}
+export {
+  accountFixtures,
+  mockAccountFetch
+};
+//# sourceMappingURL=account.js.map

package/dist/testing/account.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/testing/account.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/testing/index.d.ts

@@ -4,6 +4,85 @@ import { Store, Menu, Formatters } from '../index.js';
 export { VERSION } from '../index.js';
 import { CartModule, CartLineInput } from '../index.js';
 
+/**
+ * A customer API amount in minor currency units, paired with its currency code.
+ */
+type Money = {
+    amount_minor: number;
+    currency: string;
+};
+
+/** A scope the account calls need. A token without it gets `scope_required`. */
+type AccountScope = "wallet" | "cards" | "payments:read";
+/** One balance in the shopper's Zappie wallet, which is the same at every business. */
+type Wallet = {
+    currency: string;
+    balance: Money;
+};
+/** A card the shopper saved when they paid. It never carries the full card number. */
+type SavedCard = {
+    id: string;
+    /** The card scheme in lower case, such as `mastercard`. */
+    brand: string;
+    last4: string;
+    exp_month: number;
+    exp_year: number;
+};
+/** A payment the shopper made at this business. */
+type CustomerPayment = {
+    id: string;
+    status: "successful" | "failed" | "refunded";
+    /** What the payment was for. */
+    amount: Money;
+    /** What the shopper paid, fees included. */
+    paid: Money;
+    reference: string;
+    branch_id: string;
+    /** The order the payment paid for, or null when it wasn't a delivery or pickup order. */
+    order_id: string | null;
+    created_at: string;
+    paid_at: string | null;
+};
+/** How the shopper paid. A card shows its brand and last four digits, a bank transfer its bank and account name. */
+type PaymentMethodDetails = {
+    type: "card" | "card_terminal" | "bank_transfer" | "wallet" | "apple_pay" | "google_pay" | "store_credit" | "loyalty_points" | "mobile_money" | "other";
+    card_brand?: string;
+    card_last4?: string;
+    bank_name?: string;
+    account_name?: string;
+};
+/** A payment with what its receipt shows: the branch's name and how the shopper paid. */
+type PaymentReceipt = CustomerPayment & {
+    branch_name: string;
+    method: PaymentMethodDetails;
+};
+
+/** The wallets, saved cards and payment receipts the mock account endpoints answer with. */
+type MockAccountFixtures = {
+    wallets: Wallet[];
+    cards: SavedCard[];
+    /** Newest first, as the API lists them. */
+    payments: PaymentReceipt[];
+};
+/** The scopes the mock shopper granted. Leave it out to grant all three. */
+type MockAccountOptions = {
+    scopes?: AccountScope[];
+};
+/** Sample account data with no real cards or people: two balances, two cards and three payments. */
+declare const accountFixtures: MockAccountFixtures;
+/**
+ * A fetch that answers the account endpoints `/me/wallets`, `/me/cards`, `/me/cards/{card_id}`,
+ * `/me/payments` and `/me/payments/{payment_id}` as the API does, from fixtures and in memory.
+ * Pass it as `fetch` to createAccount, or call it from a mock API server. A removed card stays
+ * removed for this fetch. A scope left out of `scopes` answers 403 `scope_required`. Any other
+ * path answers 404.
+ *
+ * @param fixtures - The account data. Defaults to accountFixtures.
+ * @param options - The scopes the shopper granted.
+ * @returns A fetch implementation for the account endpoints.
+ */
+declare function mockAccountFetch(fixtures?: MockAccountFixtures, options?: MockAccountOptions): typeof fetch;
+
 /** Store and branch menus supplied to the deterministic mock transport. */
 type MockFixtures = {
     store: Store;
@@ -64,5 +143,5 @@ declare const fixtures: {
     };
 };
 
-export { createMockZappie, fixtures };
-export type { MockFixtures, MockOptions };
+export { accountFixtures, createMockZappie, fixtures, mockAccountFetch };
+export type { MockAccountFixtures, MockAccountOptions, MockFixtures, MockOptions };

package/dist/testing/index.js

@@ -7,6 +7,7 @@ import { delay, throwIfAborted } from "../internal/abort.js";
 import { multiplyMoney } from "../internal/money-math.js";
 import { money } from "../money.js";
 import { VERSION } from "../index.js";
+import { accountFixtures, mockAccountFetch } from "./account.js";
 function createMockZappie(input, opts = {}) {
   const fixtures2 = structuredClone(input);
   const before = async (method, ctx) => {
@@ -452,6 +453,8 @@ var fixtures = {
 };
 export {
   VERSION,
+  accountFixtures,
   createMockZappie,
-  fixtures
+  fixtures,
+  mockAccountFetch
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zappie/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Typed, framework-agnostic client for Zappie menus, carts, checkout, auth and events.",
   "type": "module",
   "sideEffects": false,
@@ -73,6 +73,10 @@
       "types": "./dist/customer/react.d.ts",
       "import": "./dist/customer/react.js"
     },
+    "./account": {
+      "types": "./dist/account/index.d.ts",
+      "import": "./dist/account/index.js"
+    },
     "./places": {
       "types": "./dist/places/index.d.ts",
       "import": "./dist/places/index.js"
@@ -148,7 +152,7 @@
     "vite": "8.3.5"
   },
   "scripts": {
-    "build": "tsup && tsup --config tsup.checkout.config.ts && tsup --config tsup.checkout-defaults.config.ts && tsup --config tsup.customer.config.ts && tsup --config tsup.places.config.ts && tsup --config tsup.url.config.ts && tsup --config tsup.redirect.config.ts && tsup --config tsup.services.config.ts && tsup --config tsup.visits.config.ts && tsup --config tsup.pricing.config.ts && tsup --config tsup.site-config.config.ts && tsup --config tsup.template.config.ts && node ../../scripts/release-packages/build-modules.mjs --no-sources-content --unmapped=studio/index.js --unmapped=testing/index.js --unmapped=vite/index.js",
+    "build": "tsup && tsup --config tsup.checkout.config.ts && tsup --config tsup.checkout-defaults.config.ts && tsup --config tsup.customer.config.ts && tsup --config tsup.account.config.ts && tsup --config tsup.places.config.ts && tsup --config tsup.url.config.ts && tsup --config tsup.redirect.config.ts && tsup --config tsup.services.config.ts && tsup --config tsup.visits.config.ts && tsup --config tsup.pricing.config.ts && tsup --config tsup.site-config.config.ts && tsup --config tsup.template.config.ts && node ../../scripts/release-packages/build-modules.mjs --no-sources-content --unmapped=studio/index.js --unmapped=testing/index.js --unmapped=vite/index.js",
     "test": "vitest run --root ../.. packages/sdk/test",
     "size": "node ../../scripts/release-packages/size-sdk.mjs && size-limit"
   }