@asstio-dev/storefront 0.27.0 → 0.31.0

package/README.md

@@ -260,6 +260,36 @@ export async function generateMetadata(): Promise<Metadata> {
 
 Titles come out as `{ absolute }` on purpose, so a layout's `title.template` does not apply a second time.
 
+**Sitemap.** `sitemapEntries` reads every sitemap URL of one market: `GET /v1/site` once, then for each type
+(`product`, `collection`, `brand`; default all three) a cursor walk of `GET /v1/sitemap` from `cursor=start` along
+`nextCursor`, with no 10 000-row ceiling. `toNextSitemap` turns the result into Next.js's `app/sitemap.ts` shape:
+
+```ts
+import type { MetadataRoute } from "next";
+
+export const dynamic = "force-dynamic";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const market = process.env.STOREFRONT_MARKET!;            // the same market the client sends as X-Market
+  const api = createStorefrontClient({ baseUrl: API_URL, siteKey: SITE_KEY, market });
+  const result = await sitemapEntries(api, { market });
+  if (!result.complete) console.warn("Sitemap: Storefront API unavailable; serving a partial sitemap.");
+  return toNextSitemap(result);
+}
+```
+
+- `market` is required and must be the client's market. It is matched case-insensitively against the site's markets;
+  an unknown one throws `SeoError` before any page is read. Never pass the site's default instead of the request's.
+- hreflang tags are `language-COUNTRY` (`sv-SE`, never the market code `se`), each entry lists itself, and `x-default`
+  appears only when the site's default market has the page. Two markets with the same tag and different URLs drop that
+  entry's alternates; the URL stays listed.
+- `lastModified` is left out when the API reports the Unix epoch (collections carry no timestamp of their own).
+- `complete: false`: a transport failure, a 5xx, `INDEX_UNAVAILABLE` or `SITE_REGISTRY_WARMING` stopped the walk; the
+  entries read so far are returned. Any other problem (a 400 such as `INVALID_CURSOR`) throws.
+- An API older than cursor paging throws "the Storefront API does not support sitemap cursors; deploy the API first"
+  rather than ending the walk after one page.
+- A walk is an eventually consistent crawl, not a snapshot: a product added mid-walk may wait for the next render.
+
 **Errors.** `SeoError` means a caller or configuration error: `redirectTo` is set (answer 301 instead), an unknown
 market, a bad `variesBy` value, a variant URL (`v.url` or the optional `variantUrl` hook) that is missing, not an absolute http(s) URL or repeated for two variants, or
 two markets with the same `language-COUNTRY` and different URLs. Catch it at your SEO boundary and fix the market
@@ -602,6 +632,84 @@ mountCheckout(el, widget, {
   visible.
 - The SDK owns the provider's shipping events while `onShipping` is set; do not bind them yourself.
 
+### Accounts: sign-in, sessions and saved carts
+
+Shopper accounts are a **server-only** module, `@asstio-dev/storefront/account`, with a Next.js (15+) adapter,
+`@asstio-dev/storefront/account/next`, and one browser helper, `@asstio-dev/storefront/account/browser`. Every account call
+needs the site's **server key** (`sfk_srv_…`) and runs on your server; the session token travels in `X-Shopper-Session`, which
+the API refuses from a browser (`SESSION_FROM_BROWSER`) and which no CORS preflight allows. A site without accounts answers
+every account route `404 ACCOUNTS_DISABLED`, and `GET /v1/site` has `accounts: null` — render no sign-in then.
+
+**Sign-in.** `startSignInAction(config, email, returnPath?)` mails an 8-digit code and a link (the `202` is the same whether
+or not the address may sign in) and keeps the start's binding in the HttpOnly `__Host-sf_signin` cookie for 10 minutes.
+`verifySignInAction(config, { code })` or `{ link }` mints the session into the `__Host-sf_session` cookie. On the link's
+page, read the token with `readLinkFragment()` in the browser (it removes it from the URL) and hand it to a server action.
+A link opened in another browser has no binding: the answer is `409 SIGN_IN_CONFIRM_REQUIRED` with `maskedEmail` and
+`siteName` — ask "Sign in on this device?" and call again with `confirm: true`. Any other failure is one code,
+`SIGN_IN_INVALID`: start a new sign-in. Redirect to the view's `returnPath` (or your default) yourself.
+
+**Sessions.** Build a client per request, never a module singleton: `shopperClient(config)` reads the session cookie
+(`createShopperClient({ baseUrl, serverKey, market, session, shopperIp })` outside Next.js). `getSession`, `getMe` and
+`getMyCompany` read who is signed in; `switchPrincipalAction(config, principal)` acts as another principal (`"consumer"` or a
+membership id), rotates the session and points your cart cookie at the new principal's saved cart, or clears it when that
+principal has none; `signOutAction(config, { everywhere? })` clears the session, sign-in, cart and
+browser-cart cookies whatever the API answers. A session that no longer validates is `401 SESSION_INVALID` on **every**
+route, never a silent signed-out answer: render signed-out, and let the next action clear the cookie.
+
+**Saved carts.** With a session, `POST /v1/cart` returns the principal's saved cart (or creates one) and `GET /v1/me/cart`
+reads it; the cart routes work on it with its token **and** the session. A saved cart's token without its owner's session —
+another device signed out, another principal, another account — is `404 NOT_FOUND`, exactly an unknown token; a principal
+that may not change the cart (a company viewer) is `403 PERMISSION_DENIED` with `permission: "cart.edit"`. Sign-in never
+merges carts: when the shopper had a browser cart A and a saved cart B, verify points your cart cookie
+(`config.cartCookie`) at B and keeps A in `__Host-sf_browser_cart` for 30 minutes; with no saved cart, the cookie stays on A
+(adopted, or still anonymous) and is cleared when the API names neither cart (the cookie held no usable cart). Offer "Add to saved cart" and call
+`copyBrowserCartAction(config)`: each line of A is an ordinary `POST /v1/cart/lines` on B with
+`Idempotency-Key: copy:{A}:{lineId}`, so a retry never doubles a line. The result lists line ids as `copied`, `skipped`
+(the product is gone or cannot be sold) and `failed` (retry); the browser-cart cookie is cleared once nothing failed, at
+sign-out and at its expiry.
+
+**Checkout with a session.** Pass the shopper client as `{ shopper }` to `startCheckout`, `syncCheckout`,
+`completeCheckout`, `getCheckoutStatus`, `liveShippingFor` and `getOrder`: the call goes through it, so a saved cart checks
+out under its owner and the order records the consumer. Signed out, leave it out — the call is exactly today's. A company
+principal cannot check out yet (`409 COMPANY_CHECKOUT_UNAVAILABLE`). The confirmation and order pages of a consumer's
+checkout still open by the cart token and the order token alone, so a payment that returns to a signed-out tab completes.
+
+```ts
+import { getMe } from "@asstio-dev/storefront/account";
+import { copyBrowserCartAction, shopperClient, signOutAction, startSignInAction, verifySignInAction, type AccountActionConfig } from "@asstio-dev/storefront/account/next";
+
+// process.env.STOREFRONT_SERVER_KEY: the server key never reaches a browser bundle.
+declare const STOREFRONT_SERVER_KEY: string;
+
+const accounts: AccountActionConfig = {
+  baseUrl: "https://api.storefront.asstio.com",
+  serverKey: STOREFRONT_SERVER_KEY,
+  market: "se",
+  origin: "https://shop.example",   // decides Secure and the __Host- prefix (dropped on http://localhost)
+  trustedHops: 1,                    // proxies in front of this server, for the shopper IP the sign-in limits use
+  cartCookie: "cart",                // your cart cookie: sent at verify, pointed at the saved cart, read by the copy
+};
+
+// Your "use server" actions.
+export async function startSignInForm(email: string) { return startSignInAction(accounts, email, "/account"); }
+export async function verifyCode(code: string) { return verifySignInAction(accounts, { code }); }
+export async function verifyLink(link: string, confirm = false) { return verifySignInAction(accounts, { link, confirm }); }
+export async function addToSavedCart() { return copyBrowserCartAction(accounts); }
+export async function signOutEverywhere() { return signOutAction(accounts, { everywhere: true }); }
+
+// A server component: who is signed in. Signed out, or a session that no longer validates, renders signed-out.
+export async function accountHeader() {
+  const me = await getMe(await shopperClient(accounts));
+  return me.ok ? me.data.email : null;
+}
+
+// Checkout under the session: the saved cart checks out under its owner, and the order records the principal.
+export async function beginSignedInCheckout(savedCart: string) {
+  const shopper = await shopperClient(accounts);
+  return startCheckout(storefront, savedCart, { returnOrigin: "https://shop.example", shopper });
+}
+```
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.
@@ -641,7 +749,7 @@ Every operation documents `400`, `401`, `403`, `404`, `429` and `503`; the entit
 
 Codes you will meet: `SITE_KEY_MISSING`, `SITE_KEY_INVALID`, `SITE_INACTIVE`, `SECRET_KEY_FROM_BROWSER`,
 `SITE_REGISTRY_WARMING`, `MARKET_UNKNOWN`, `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
-header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`,
+header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`, `INVALID_CURSOR`,
 `INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`, `INVALID_QUERY`,
 `FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`,
 and, from the checkout ([above](#checkout)): `CART_EMPTY`, `CHECKOUT_CART_CHANGED`, `CHECKOUT_PREVIEW_KEY`,
@@ -677,8 +785,10 @@ A range is `min-max`: either bound may be left out and either may be negative
 −10), `--2` (at most −2) — and a leading dash with nothing before it keeps its meaning, `-500` is "at most 500". A
 range whose lower bound is above its upper bound is ignored with a warning.
 
-`/v1/sitemap` takes `type` (`product` | `collection`), `since` (ISO-8601, inclusive), `page` and `pageSize`
-(max 1000, default 500).
+`/v1/sitemap` takes `type` (`product` | `collection` | `brand`), `since` (ISO-8601, inclusive), `pageSize` (max 1000,
+default 500) and either `page` (page mode, `page × pageSize` at most 10 000) or `cursor` (cursor mode: `start`, then
+each response's `nextCursor` until it is `null`; no ceiling, not combined with a `page` past 1). `since` is for
+revalidation, cursor mode for a full crawl; `sitemapEntries` ([SEO](#seo)) does the walk for you.
 
 `/v1/search/suggest` takes `q` only, and `/v1/products/facets/{key}` takes `q` plus the same `filter` object as a
 listing — both are described under [Search-as-you-type and search-in-facet](#search-as-you-type-and-search-in-facet).

package/dist/account/browser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@asstio-dev/storefront/account/browser` — the one browser-side piece of sign-in (accounts spec §6.2): the link's secret
+ * travels in the URL fragment, so no access log or mail scanner sees it. The landing page's client component reads it
+ * once, strips it from the address bar, and posts it through a server action.
+ */
+/** The parts of `window` this module touches (a fake in tests). */
+export interface LinkWindow {
+    location: {
+        readonly hash: string;
+        readonly pathname: string;
+        readonly search: string;
+    };
+    history: {
+        readonly state: unknown;
+        replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+    };
+}
+/**
+ * The link token `sfl_{challengeId}.{secret}` from `location.hash`, or null; pass it as `link` (it carries its challenge id). The fragment is removed with `history.replaceState` before returning, so
+ * a reload, a shared screenshot or a second call never sees it again. Any other fragment is left alone.
+ */
+export declare function readLinkFragment(win?: LinkWindow | undefined): string | null;

package/dist/account/browser.js

@@ -0,0 +1,19 @@
+/**
+ * `@asstio-dev/storefront/account/browser` — the one browser-side piece of sign-in (accounts spec §6.2): the link's secret
+ * travels in the URL fragment, so no access log or mail scanner sees it. The landing page's client component reads it
+ * once, strips it from the address bar, and posts it through a server action.
+ */
+const PREFIX = "#sfl_";
+/**
+ * The link token `sfl_{challengeId}.{secret}` from `location.hash`, or null; pass it as `link` (it carries its challenge id). The fragment is removed with `history.replaceState` before returning, so
+ * a reload, a shared screenshot or a second call never sees it again. Any other fragment is left alone.
+ */
+export function readLinkFragment(win = globalThis.window) {
+    if (!win)
+        return null;
+    const hash = win.location.hash;
+    if (!hash.startsWith(PREFIX))
+        return null;
+    win.history.replaceState(win.history.state, "", win.location.pathname + win.location.search);
+    return hash.slice(1);
+}

package/dist/account/cart.d.ts

@@ -0,0 +1,24 @@
+import type { AccountProblem, ShopperClient } from "./index.js";
+/** Line ids of A: `copied` (added to B, or already added by an earlier run), `skipped` (the product is gone or cannot be sold:
+ * `409`), `failed` (anything else — retry; the keys make copied lines no-ops). */
+export interface CopyBrowserCartResult {
+    copied: string[];
+    skipped: string[];
+    failed: string[];
+}
+/** A failed read of the browser cart that is not "the cart is gone": nothing was copied, keep the token and retry. */
+export declare class CopyBrowserCartError extends Error {
+    readonly status: number;
+    readonly problem: AccountProblem | null;
+    constructor(status: number, problem: AccountProblem | null);
+}
+/** The idempotency key of one copied line (spec §9.2). */
+export declare const copyKey: (browserCartToken: string, lineId: string) => string;
+/**
+ * Copies the lines of the browser cart A into the saved cart B. A is read through the session-bearing client (`GET /v1/cart`
+ * with A's token): A is an anonymous cart, which any shopper may read, and this is the only read of it. Each line is posted to
+ * B as `{ sku, quantity }` exactly as A holds it — never a price or any other field; B prices the line itself. Quantities add
+ * up as any line add does. A that is gone (`404`, `410`) has nothing to copy: every list is empty. Any other failed read
+ * throws `CopyBrowserCartError`.
+ */
+export declare function copyBrowserCart(client: ShopperClient, browserCartToken: string, savedCartToken: string): Promise<CopyBrowserCartResult>;

package/dist/account/cart.js

@@ -0,0 +1,51 @@
+/** A failed read of the browser cart that is not "the cart is gone": nothing was copied, keep the token and retry. */
+export class CopyBrowserCartError extends Error {
+    status;
+    problem;
+    constructor(status, problem) {
+        super(`The browser cart could not be read (${status}${problem?.code ? " " + problem.code : ""}).`);
+        this.status = status;
+        this.problem = problem;
+        this.name = "CopyBrowserCartError";
+    }
+}
+/** The idempotency key of one copied line (spec §9.2). */
+export const copyKey = (browserCartToken, lineId) => `copy:${browserCartToken}:${lineId}`;
+/**
+ * Copies the lines of the browser cart A into the saved cart B. A is read through the session-bearing client (`GET /v1/cart`
+ * with A's token): A is an anonymous cart, which any shopper may read, and this is the only read of it. Each line is posted to
+ * B as `{ sku, quantity }` exactly as A holds it — never a price or any other field; B prices the line itself. Quantities add
+ * up as any line add does. A that is gone (`404`, `410`) has nothing to copy: every list is empty. Any other failed read
+ * throws `CopyBrowserCartError`.
+ */
+export async function copyBrowserCart(client, browserCartToken, savedCartToken) {
+    const read = await client.GET("/v1/cart", { headers: { "X-Cart-Token": browserCartToken } });
+    const result = { copied: [], skipped: [], failed: [] };
+    if (!read.response.ok || !read.data) {
+        if (read.response.status === 404 || read.response.status === 410)
+            return result;
+        throw new CopyBrowserCartError(read.response.status, problemOf(read.error));
+    }
+    for (const line of read.data.lines) {
+        try {
+            const { response, error } = await client.POST("/v1/cart/lines", {
+                headers: { "X-Cart-Token": savedCartToken, "Idempotency-Key": copyKey(browserCartToken, line.id) },
+                body: { sku: line.sku, quantity: Number(line.quantity) },
+            });
+            if (response.ok)
+                result.copied.push(line.id);
+            // 409 is the line's own product (PRODUCT_GONE, STOCK_INSUFFICIENT); a lost race (CART_CONFLICT) is worth a retry.
+            else if (response.status === 409 && problemOf(error)?.code !== "CART_CONFLICT")
+                result.skipped.push(line.id);
+            else
+                result.failed.push(line.id);
+        }
+        catch {
+            result.failed.push(line.id);
+        }
+    }
+    return result;
+}
+function problemOf(error) {
+    return typeof error === "object" && error !== null && typeof error.code === "string" ? error : null;
+}

package/dist/account/cookies.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cookie descriptors for the account flow (accounts spec §6.2, §7.3). Framework-neutral: hand a spec to Next.js's
+ * `cookies().set(spec)`, or `serializeCookie(spec)` into a `Set-Cookie` header. Every cookie is `HttpOnly; SameSite=Lax;
+ * Path=/` with no `Domain`; `Secure` and the `__Host-` prefix are dropped only on `http://localhost` (`cookieSecurity`).
+ */
+export interface CookieSecurity {
+    /** false only for a development origin on http://localhost; drops `Secure` and the `__Host-` prefix. */
+    secure: boolean;
+}
+export interface CookieSpec {
+    name: string;
+    value: string;
+    httpOnly: true;
+    secure: boolean;
+    sameSite: "lax";
+    path: "/";
+    /** Seconds; 0 deletes the cookie. */
+    maxAge: number;
+}
+export interface SignInCookieValue {
+    binding: string;
+    challengeId: string | null;
+}
+/** The cookie security of the frontend's own origin: `{ secure: false }` only for `http://localhost` (and its loopback forms). */
+export declare function cookieSecurity(origin: string | URL): CookieSecurity;
+interface SessionCookie {
+    /** The session cookie: `Max-Age` runs to the session's absolute expiry. */
+    (token: string, expiresAt: string | Date, opts: CookieSecurity & {
+        now?: number;
+    }): CookieSpec;
+    clear(opts: CookieSecurity): CookieSpec;
+    cookieName(opts: CookieSecurity): string;
+}
+export declare const sessionCookie: SessionCookie;
+interface SignInCookie {
+    /** The sign-in binding cookie (10 minutes). With `challengeId`, the cookie also remembers which challenge it binds, so a
+     * link opened in this browser can be verified without the start page's state. */
+    (binding: string, opts: CookieSecurity & {
+        challengeId?: string | null;
+    }): CookieSpec;
+    clear(opts: CookieSecurity): CookieSpec;
+    cookieName(opts: CookieSecurity): string;
+}
+export declare const signInCookie: SignInCookie;
+/** The sign-in cookie's value back: the binding and, when it was stored, the challenge id. Null when absent or empty. */
+export declare function readSignInCookie(value: string | null | undefined): SignInCookieValue | null;
+/**
+ * The frontend's own cart cookie, by the name the frontend gave it (no prefix is added). The SDK sets it only when a sign-in or a
+ * switch hands back another cart (spec §7.8; for as long as a cart lives untouched, 30 days) and clears it at sign-out (§9.2).
+ */
+export declare function cartCookie(name: string): {
+    set: (token: string, opts: CookieSecurity) => CookieSpec;
+    clear: (opts: CookieSecurity) => CookieSpec;
+};
+interface BrowserCartCookie {
+    /** The browser cart A's token beside a saved cart B (spec §9.2), for "Lägg till i sparad varukorg": 30 minutes. */
+    (token: string, opts: CookieSecurity): CookieSpec;
+    clear(opts: CookieSecurity): CookieSpec;
+    cookieName(opts: CookieSecurity): string;
+}
+export declare const browserCartCookie: BrowserCartCookie;
+/** A `Set-Cookie` header value for a route handler or middleware. */
+export declare function serializeCookie(c: CookieSpec): string;
+export {};

package/dist/account/cookies.js

@@ -0,0 +1,56 @@
+/**
+ * Cookie descriptors for the account flow (accounts spec §6.2, §7.3). Framework-neutral: hand a spec to Next.js's
+ * `cookies().set(spec)`, or `serializeCookie(spec)` into a `Set-Cookie` header. Every cookie is `HttpOnly; SameSite=Lax;
+ * Path=/` with no `Domain`; `Secure` and the `__Host-` prefix are dropped only on `http://localhost` (`cookieSecurity`).
+ */
+const SESSION = "sf_session";
+const SIGN_IN = "sf_signin";
+/** Spec §6.2: the binding cookie lives as long as the challenge, 10 minutes. */
+const SIGN_IN_SECONDS = 600;
+const BROWSER_CART = "sf_browser_cart";
+/** Spec §9.2: the browser-cart cookie lives 30 minutes. */
+const BROWSER_CART_SECONDS = 1800;
+/** A cart's sliding expiry on the API: 30 days after its last change. */
+const CART_SECONDS = 30 * 24 * 3600;
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** The cookie security of the frontend's own origin: `{ secure: false }` only for `http://localhost` (and its loopback forms). */
+export function cookieSecurity(origin) {
+    const url = new URL(origin);
+    return { secure: !(url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname)) };
+}
+const named = (base, { secure }) => (secure ? "__Host-" + base : base);
+const spec = (name, value, maxAge, { secure }) => ({ name, value, httpOnly: true, secure, sameSite: "lax", path: "/", maxAge: Math.max(0, Math.floor(maxAge)) });
+export const sessionCookie = Object.assign((token, expiresAt, opts) => spec(named(SESSION, opts), token, (new Date(expiresAt).getTime() - (opts.now ?? Date.now())) / 1000, opts), {
+    clear: (opts) => spec(named(SESSION, opts), "", 0, opts),
+    cookieName: (opts) => named(SESSION, opts),
+});
+export const signInCookie = Object.assign((binding, opts) => spec(named(SIGN_IN, opts), opts.challengeId ? `${opts.challengeId}.${binding}` : binding, SIGN_IN_SECONDS, opts), {
+    clear: (opts) => spec(named(SIGN_IN, opts), "", 0, opts),
+    cookieName: (opts) => named(SIGN_IN, opts),
+});
+/** The sign-in cookie's value back: the binding and, when it was stored, the challenge id. Null when absent or empty. */
+export function readSignInCookie(value) {
+    if (!value)
+        return null;
+    // A binding is base64url and a challenge id a uuid: neither holds a '.'.
+    const dot = value.indexOf(".");
+    return dot < 0 ? { binding: value, challengeId: null } : { binding: value.slice(dot + 1), challengeId: value.slice(0, dot) || null };
+}
+/**
+ * The frontend's own cart cookie, by the name the frontend gave it (no prefix is added). The SDK sets it only when a sign-in or a
+ * switch hands back another cart (spec §7.8; for as long as a cart lives untouched, 30 days) and clears it at sign-out (§9.2).
+ */
+export function cartCookie(name) {
+    return {
+        set: (token, opts) => spec(name, token, CART_SECONDS, opts),
+        clear: (opts) => spec(name, "", 0, opts),
+    };
+}
+export const browserCartCookie = Object.assign((token, opts) => spec(named(BROWSER_CART, opts), token, BROWSER_CART_SECONDS, opts), {
+    clear: (opts) => spec(named(BROWSER_CART, opts), "", 0, opts),
+    cookieName: (opts) => named(BROWSER_CART, opts),
+});
+/** A `Set-Cookie` header value for a route handler or middleware. */
+export function serializeCookie(c) {
+    return `${c.name}=${encodeURIComponent(c.value)}; Path=${c.path}; Max-Age=${c.maxAge}; HttpOnly${c.secure ? "; Secure" : ""}; SameSite=Lax`;
+}

package/dist/account/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `@asstio-dev/storefront/account` — shopper accounts (sign-in and sessions), **server-only** (accounts spec §7.1, §11.4).
+ *
+ * Every call needs the site's server key (`sfk_srv_…`), which never reaches a browser, and the session token travels in
+ * `X-Shopper-Session`, which the API refuses from a browser. Create one client per request with that request's session:
+ * a client is never a module-level singleton, so one shopper's token can never serve another shopper's request.
+ */
+import { type Client } from "openapi-fetch";
+import type { components } from "../schema";
+import type { StorefrontPaths } from "../index.js";
+export type SignInStartedDto = components["schemas"]["SignInStartedDto"];
+export type SignedInDto = components["schemas"]["SignedInDto"];
+export type SessionDto = components["schemas"]["SessionDto"];
+export type AccountDto = components["schemas"]["AccountDto"];
+export type MyCompanyDto = components["schemas"]["MyCompanyDto"];
+export type PrincipalDto = components["schemas"]["PrincipalDto"];
+export type SiteAccountsDto = components["schemas"]["SiteAccountsDto"];
+/** The problem body; `maskedEmail` and `siteName` come with `409 SIGN_IN_CONFIRM_REQUIRED`. */
+export type AccountProblem = components["schemas"]["StorefrontProblem"] & {
+    maskedEmail?: string;
+    siteName?: string;
+};
+/** The repo's result shape: the data, or the HTTP status and the problem (branch on `problem.code`). */
+export type AccountResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    problem: AccountProblem;
+    retryAfter?: number;
+};
+export interface ShopperClientOptions {
+    /** e.g. https://api.storefront.asstio.com */
+    baseUrl: string;
+    /** The site's server key (`sfk_srv_…`). Server-side only. */
+    serverKey: string;
+    /** Market code, e.g. "se". */
+    market: string;
+    /** The request's session token (`sfs_…`) from the session cookie; omit when the shopper is signed out. */
+    session?: string | null;
+    /** The shopper's IP (`shopperIpFrom`); the sign-in rate limits are per shopper IP. `null` when it cannot be known. */
+    shopperIp: string | null;
+    /** BCP-47 tag; omit to use the market's language. */
+    acceptLanguage?: string;
+    fetch?: typeof fetch;
+}
+/** A client for one request. Construct it per request; never cache it beyond that request. */
+export type ShopperClient = Client<StorefrontPaths>;
+/**
+ * A request-scoped client: every call carries the server key, the market, the shopper IP and (when given) the session, and
+ * every fetch is `cache: "no-store"` — an account answer is never shared or cached (spec §10.1).
+ */
+export declare function createShopperClient(opts: ShopperClientOptions): ShopperClient;
+/** `POST /v1/auth/sign-in`. The 202 is the same whether or not the address may sign in; keep `binding` in the sign-in cookie
+ * (`signInCookie`) and never show it. An unsafe `returnPath` is dropped by the API. */
+export declare function startSignIn(client: ShopperClient, email: string, returnPath?: string | null): Promise<AccountResult<SignInStartedDto>>;
+export interface VerifySignInInput {
+    /** The start answer's challenge id: required with `code`. Ignored with `link`, which carries its own (ruling R12). */
+    challengeId?: string | null;
+    /** The 8-digit code; spaces allowed. Exactly one of `code` and `link`. */
+    code?: string | null;
+    /** The `sfl_{challengeId}.{secret}` token from the link's fragment (`readLinkFragment`), or the whole sign-in URL. */
+    link?: string | null;
+    /** The start answer's binding, from the sign-in cookie, when this browser has it. */
+    binding?: string | null;
+    /** The shopper's answer to the `409 SIGN_IN_CONFIRM_REQUIRED` question. */
+    confirm?: boolean | null;
+}
+/** The link token of a whole sign-in URL or a bare token: the part after the last '#', as the API reads it. */
+export declare function linkToken(link: string): string;
+/** The challenge id a link token (or a whole sign-in URL) carries (`sfl_{challengeId:N}.{secret}`, ruling R12), or null. */
+export declare function linkChallengeId(link: string): string | null;
+/** A failure that never reached the API (`status: 0`). */
+export declare function localFailure(code: string, detail: string): {
+    ok: false;
+    status: number;
+    problem: AccountProblem;
+};
+/**
+ * `POST /v1/auth/sign-in/verify` → the session (`409 SIGN_IN_CONFIRM_REQUIRED` without the binding until `confirm: true`).
+ * With a link the challenge id is the link's own; a code without a challenge id fails locally (`SIGN_IN_CHALLENGE_MISSING`,
+ * no request, no rate-limit slot spent).
+ */
+export declare function verifySignIn(client: ShopperClient, input: VerifySignInInput, cartToken?: string | null): Promise<AccountResult<SignedInDto>>;
+/** `POST /v1/auth/sign-out` (the client's session); `everywhere` ends every session of the account. */
+export declare function signOut(client: ShopperClient, opts?: {
+    everywhere?: boolean;
+}): Promise<AccountResult<void>>;
+/** `PUT /v1/session/principal`: `"consumer"` or a membership id. The answer carries a rotated token: store it at once. */
+export declare function switchPrincipal(client: ShopperClient, principal: string): Promise<AccountResult<SignedInDto>>;
+/** `GET /v1/session`. `401 SESSION_INVALID` means signed out: render so, and clear the cookie in the next action. */
+export declare function getSession(client: ShopperClient): Promise<AccountResult<SessionDto>>;
+/** `GET /v1/me`. */
+export declare function getMe(client: ShopperClient): Promise<AccountResult<AccountDto>>;
+/** `GET /v1/me/company`: `403 PRINCIPAL_NOT_AVAILABLE` while the principal is the consumer. */
+export declare function getMyCompany(client: ShopperClient): Promise<AccountResult<MyCompanyDto>>;
+export { copyBrowserCart, copyKey, CopyBrowserCartError, type CopyBrowserCartResult } from "./cart.js";
+export { browserCartCookie, cartCookie, cookieSecurity, readSignInCookie, serializeCookie, sessionCookie, signInCookie, type CookieSecurity, type CookieSpec, type SignInCookieValue, } from "./cookies.js";
+export { assertSameOrigin, CrossOriginError, safeReturnPath, shopperIpFrom, type HeadersLike } from "./security.js";

package/dist/account/index.js

@@ -0,0 +1,114 @@
+/**
+ * `@asstio-dev/storefront/account` — shopper accounts (sign-in and sessions), **server-only** (accounts spec §7.1, §11.4).
+ *
+ * Every call needs the site's server key (`sfk_srv_…`), which never reaches a browser, and the session token travels in
+ * `X-Shopper-Session`, which the API refuses from a browser. Create one client per request with that request's session:
+ * a client is never a module-level singleton, so one shopper's token can never serve another shopper's request.
+ */
+import createClient from "openapi-fetch";
+/**
+ * A request-scoped client: every call carries the server key, the market, the shopper IP and (when given) the session, and
+ * every fetch is `cache: "no-store"` — an account answer is never shared or cached (spec §10.1).
+ */
+export function createShopperClient(opts) {
+    if (typeof globalThis.window !== "undefined") {
+        throw new Error("@asstio-dev/storefront/account is server-only: the server key and the session token never reach a browser.");
+    }
+    const baseFetch = opts.fetch ?? globalThis.fetch;
+    // The init's cache wins in Next.js's patched fetch; the Request's carries it everywhere else.
+    const noStore = ((input, init) => baseFetch(input, { ...init, cache: "no-store" }));
+    const client = createClient({ baseUrl: opts.baseUrl.replace(/\/$/, ""), fetch: noStore, cache: "no-store" });
+    const session = opts.session || null;
+    const headers = {
+        onRequest({ request }) {
+            request.headers.set("X-Site-Key", opts.serverKey);
+            request.headers.set("X-Market", opts.market);
+            if (opts.acceptLanguage)
+                request.headers.set("Accept-Language", opts.acceptLanguage);
+            if (opts.shopperIp)
+                request.headers.set("X-Shopper-Ip", opts.shopperIp);
+            if (session)
+                request.headers.set("X-Shopper-Session", session);
+            return request;
+        },
+    };
+    client.use(headers);
+    return client;
+}
+/** `POST /v1/auth/sign-in`. The 202 is the same whether or not the address may sign in; keep `binding` in the sign-in cookie
+ * (`signInCookie`) and never show it. An unsafe `returnPath` is dropped by the API. */
+export async function startSignIn(client, email, returnPath) {
+    return answer(await client.POST("/v1/auth/sign-in", { body: { email, returnPath: returnPath ?? null } }));
+}
+/** The link token of a whole sign-in URL or a bare token: the part after the last '#', as the API reads it. */
+export function linkToken(link) {
+    const hash = link.lastIndexOf("#");
+    return hash >= 0 ? link.slice(hash + 1) : link;
+}
+const LINK_TOKEN = /^sfl_([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})\.[A-Za-z0-9_-]{43}$/;
+/** The challenge id a link token (or a whole sign-in URL) carries (`sfl_{challengeId:N}.{secret}`, ruling R12), or null. */
+export function linkChallengeId(link) {
+    const m = LINK_TOKEN.exec(linkToken(link));
+    return m ? `${m[1]}-${m[2]}-${m[3]}-${m[4]}-${m[5]}` : null;
+}
+/** A failure that never reached the API (`status: 0`). */
+export function localFailure(code, detail) {
+    return { ok: false, status: 0, problem: { type: "https://docs.asstio.com/storefront/errors#" + code, title: code, status: 0, detail, code } };
+}
+/**
+ * `POST /v1/auth/sign-in/verify` → the session (`409 SIGN_IN_CONFIRM_REQUIRED` without the binding until `confirm: true`).
+ * With a link the challenge id is the link's own; a code without a challenge id fails locally (`SIGN_IN_CHALLENGE_MISSING`,
+ * no request, no rate-limit slot spent).
+ */
+export async function verifySignIn(client, input, cartToken) {
+    const challengeId = input.link ? linkChallengeId(input.link) : input.challengeId || null;
+    if (!input.link && !challengeId)
+        return localFailure("SIGN_IN_CHALLENGE_MISSING", "A code needs the challenge id of its sign-in start.");
+    return answer(await client.POST("/v1/auth/sign-in/verify", {
+        body: { challengeId, code: input.code ?? null, link: input.link ? linkToken(input.link) : null, binding: input.binding ?? null, confirm: input.confirm ?? null },
+        headers: cartToken ? { "X-Cart-Token": cartToken } : {},
+    }));
+}
+/** `POST /v1/auth/sign-out` (the client's session); `everywhere` ends every session of the account. */
+export async function signOut(client, opts = {}) {
+    const { error, response } = await client.POST("/v1/auth/sign-out", { body: { everywhere: opts.everywhere ?? false } });
+    if (response.ok)
+        return { ok: true, data: undefined };
+    return failure(response, error);
+}
+/** `PUT /v1/session/principal`: `"consumer"` or a membership id. The answer carries a rotated token: store it at once. */
+export async function switchPrincipal(client, principal) {
+    return answer(await client.PUT("/v1/session/principal", { body: { principal } }));
+}
+/** `GET /v1/session`. `401 SESSION_INVALID` means signed out: render so, and clear the cookie in the next action. */
+export async function getSession(client) {
+    return answer(await client.GET("/v1/session"));
+}
+/** `GET /v1/me`. */
+export async function getMe(client) {
+    return answer(await client.GET("/v1/me"));
+}
+/** `GET /v1/me/company`: `403 PRINCIPAL_NOT_AVAILABLE` while the principal is the consumer. */
+export async function getMyCompany(client) {
+    return answer(await client.GET("/v1/me/company"));
+}
+function answer(r) {
+    if (r.response.ok && r.data !== undefined && r.data !== null && r.error === undefined)
+        return { ok: true, data: r.data };
+    return failure(r.response, r.error);
+}
+function failure(response, error) {
+    const problem = isProblem(error)
+        ? error
+        : { type: "https://docs.asstio.com/storefront/errors#SDK_EMPTY_ANSWER", title: "SDK_EMPTY_ANSWER", status: response.status, detail: "no problem body", code: "SDK_EMPTY_ANSWER" };
+    const retry = Number(response.headers.get("Retry-After"));
+    return Number.isFinite(retry) && retry > 0 && response.headers.has("Retry-After")
+        ? { ok: false, status: response.status, problem, retryAfter: Math.ceil(retry) }
+        : { ok: false, status: response.status, problem };
+}
+function isProblem(value) {
+    return typeof value === "object" && value !== null && typeof value.code === "string";
+}
+export { copyBrowserCart, copyKey, CopyBrowserCartError } from "./cart.js";
+export { browserCartCookie, cartCookie, cookieSecurity, readSignInCookie, serializeCookie, sessionCookie, signInCookie, } from "./cookies.js";
+export { assertSameOrigin, CrossOriginError, safeReturnPath, shopperIpFrom } from "./security.js";