@asteby/storefront 0.9.0 → 0.11.0

package/dist/node.js

@@ -0,0 +1,209 @@
+// src/node.ts
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { hostname } from "os";
+
+// src/diagnose.ts
+function maskToken(token) {
+  if (!token) return "(sin token)";
+  const prefix = /^[a-z]{2}_/.exec(token)?.[0] ?? "";
+  return token.length <= prefix.length + 8 ? `${prefix}\u2026` : `${prefix}\u2026${token.slice(-4)}`;
+}
+
+// src/node.ts
+var SDK_VERSION = true ? "0.11.0" : "dev";
+function createFileTokenSource(file, options = {}) {
+  const ttl = options.ttlMs ?? 3e4;
+  const now = options.now ?? Date.now;
+  let token = "";
+  let stamp = "";
+  let checkedAt = -Infinity;
+  return () => {
+    if (token && now() - checkedAt < ttl) return token;
+    checkedAt = now();
+    try {
+      const st = statSync(file);
+      const next = `${st.mtimeMs}:${st.size}`;
+      if (!token || next !== stamp) {
+        const text = readFileSync(file, "utf8").trim();
+        if (text) {
+          token = text;
+          stamp = next;
+        } else if (!token) {
+          throw new Error("token file is empty");
+        }
+      }
+    } catch (err) {
+      if (!token) throw new Error(`Cannot read the storefront token file ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return token;
+  };
+}
+function storefrontTokenFromEnv(env = process.env, options = {}) {
+  const file = env.STOREFRONT_TOKEN_FILE?.trim();
+  if (file) return createFileTokenSource(file, options);
+  const dir = env.CREDENTIALS_DIRECTORY?.trim();
+  if (dir) {
+    const f = join(dir, "storefront_token");
+    if (existsSync(f)) return createFileTokenSource(f, options);
+  }
+  const plain = env.STOREFRONT_TOKEN?.trim();
+  return plain || void 0;
+}
+function writeFileAtomic(file, content, mode = 384) {
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.${file.split("/").pop()}.${process.pid}.${Date.now().toString(36)}.tmp`);
+  const fd = openSync(tmp, "wx", mode);
+  try {
+    writeSync(fd, content);
+    fsyncSync(fd);
+  } catch (err) {
+    closeSync(fd);
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+  closeSync(fd);
+  try {
+    chmodSync(tmp, mode);
+    renameSync(tmp, file);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+var ConnectError = class extends Error {
+  constructor(kind, message, status = 0) {
+    super(message);
+    this.kind = kind;
+    this.status = status;
+  }
+  kind;
+  status;
+  name = "ConnectError";
+};
+var trimSlash = (u) => u.replace(/\/+$/, "");
+async function post(fetchImpl, url, body, bearer) {
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json", ...bearer ? { Authorization: `Bearer ${bearer}` } : {} },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(15e3)
+    });
+  } catch {
+    throw new ConnectError("network", "No pudimos comunicarnos con OPS. Revisa la direcci\xF3n y tu conexi\xF3n a internet.");
+  }
+  const text = await res.text().catch(() => "");
+  if (!res.ok) {
+    if (res.status === 429) throw new ConnectError("rate_limited", "Demasiados intentos. Espera unos minutos e int\xE9ntalo de nuevo.", 429);
+    if (res.status === 401 || res.status === 403) throw new ConnectError("unauthorized", "OPS rechaz\xF3 la credencial de esta tienda.", res.status);
+    if (res.status >= 500) throw new ConnectError("server", "OPS no pudo atender la solicitud. Int\xE9ntalo de nuevo en un momento.", res.status);
+    throw new ConnectError("invalid_code", "El c\xF3digo no es v\xE1lido, ya se us\xF3 o venci\xF3. Genera uno nuevo en OPS \u2192 Conexiones y API.", res.status);
+  }
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ConnectError("invalid_response", "OPS respondi\xF3 algo que no entendimos.", res.status);
+  }
+}
+function assertRedeem(r) {
+  const o = r;
+  if (!o || typeof o.secret_token !== "string" || !o.secret_token || typeof o.connection_id !== "string" || !Array.isArray(o.scopes)) {
+    throw new ConnectError("invalid_response", "OPS respondi\xF3 algo que no entendimos.");
+  }
+}
+async function redeemConnectionCode(opts) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const client_info = { sdk_version: SDK_VERSION, hostname: hostname(), ...opts.siteUrl ? { site_url: opts.siteUrl } : {} };
+  const res = await post(fetchImpl, `${trimSlash(opts.opsUrl)}/api/connect/v1/redeem`, { code: opts.code.trim(), client_info });
+  assertRedeem(res);
+  return res;
+}
+var stateFileFor = (tokenFile) => `${tokenFile}.json`;
+function saveConnection(tokenFile, r, opsUrl = r.ops_url) {
+  const state = { ops_url: trimSlash(r.ops_url || opsUrl), connection_id: r.connection_id, environment: r.environment, scopes: r.scopes, rotate_after: r.rotate_after };
+  writeFileAtomic(stateFileFor(tokenFile), JSON.stringify(state, null, 2) + "\n");
+  writeFileAtomic(tokenFile, r.secret_token + "\n");
+}
+function loadConnectionState(tokenFile) {
+  try {
+    return JSON.parse(readFileSync(stateFileFor(tokenFile), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function connectStore(options = {}) {
+  const tokenFile = resolve(options.tokenFile ?? process.env.STOREFRONT_TOKEN_FILE ?? "storefront_token");
+  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const now = options.now ?? Date.now;
+  const report = (m) => {
+    try {
+      options.onError?.(m);
+    } catch {
+    }
+  };
+  async function tick() {
+    const state = loadConnectionState(tokenFile);
+    const opsUrl = options.opsUrl ?? state?.ops_url;
+    let token;
+    try {
+      token = readFileSync(tokenFile, "utf8").trim();
+    } catch {
+      report(`No se pudo leer el archivo del token (${tokenFile}).`);
+      return "failed";
+    }
+    if (!opsUrl || !token) {
+      report("Falta la direcci\xF3n de OPS o el token: vuelve a ejecutar `npx @asteby/storefront connect`.");
+      return "failed";
+    }
+    const base = `${trimSlash(opsUrl)}/api/connect/v1`;
+    try {
+      await post(fetchImpl, `${base}/heartbeat`, { sdk_version: SDK_VERSION, hostname: hostname() }, token);
+      const due = state?.rotate_after ? Date.parse(state.rotate_after) : NaN;
+      if (!Number.isNaN(due) && now() >= due) {
+        const next = await post(fetchImpl, `${base}/rotate`, {}, token);
+        assertRedeem(next);
+        saveConnection(tokenFile, { ...next, ops_url: next.ops_url || opsUrl }, opsUrl);
+        return "rotated";
+      }
+      return "ok";
+    } catch (err) {
+      report(err instanceof ConnectError ? `${err.message} (${maskToken(token)})` : `Fall\xF3 el latido de la conexi\xF3n (${maskToken(token)}).`);
+      return "failed";
+    }
+  }
+  return {
+    tokenFile,
+    /** One heartbeat (+ rotation when due). Resolves, never rejects. */
+    tick,
+    /** Starts the periodic heartbeat; returns `stop()`. */
+    keepFresh(opts = {}) {
+      const timer = setInterval(() => void tick(), opts.intervalMs ?? 6e5);
+      timer.unref?.();
+      void tick();
+      return () => clearInterval(timer);
+    }
+  };
+}
+export {
+  ConnectError,
+  SDK_VERSION,
+  connectStore,
+  createFileTokenSource,
+  loadConnectionState,
+  redeemConnectionCode,
+  saveConnection,
+  stateFileFor,
+  storefrontTokenFromEnv,
+  writeFileAtomic
+};
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node.ts","../src/diagnose.ts"],"sourcesContent":["/**\n * Node-only helpers (`@asteby/storefront/node`): read the store's token from a file that can rotate, and the\n * connection protocol with OPS (`connectStore`). Nothing here runs in browsers or edge runtimes.\n */\nimport { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from 'node:fs'\nimport { dirname, join, resolve } from 'node:path'\nimport { hostname } from 'node:os'\nimport { maskToken } from './diagnose.js'\nimport type { FetchLike } from './client.js'\n\ndeclare const __SDK_VERSION__: string | undefined\nexport const SDK_VERSION: string = typeof __SDK_VERSION__ === 'string' ? __SDK_VERSION__ : 'dev'\n\n// ---------------------------------------------------------------------------\n// Token from a file\n// ---------------------------------------------------------------------------\n\nexport type FileTokenSourceOptions = {\n  /** How often the file is checked again (default 30 s). Between checks the cached token is returned. */\n  ttlMs?: number\n  /** Clock, for tests. */\n  now?: () => number\n}\n\n/**\n * A `() => string` for `createStorefrontClient({ token })` that reads `file`, caches it and looks again every\n * `ttlMs` (30 s): the file is read only when its mtime or size changed. A failed re-read keeps the last good token\n * (a rotation in progress never takes the store down); only a first read that fails throws.\n */\nexport function createFileTokenSource(file: string, options: FileTokenSourceOptions = {}): () => string {\n  const ttl = options.ttlMs ?? 30_000\n  const now = options.now ?? Date.now\n  let token = ''\n  let stamp = ''\n  let checkedAt = -Infinity\n  return () => {\n    if (token && now() - checkedAt < ttl) return token\n    checkedAt = now()\n    try {\n      const st = statSync(file)\n      const next = `${st.mtimeMs}:${st.size}`\n      if (!token || next !== stamp) {\n        const text = readFileSync(file, 'utf8').trim()\n        if (text) {\n          token = text\n          stamp = next\n        } else if (!token) {\n          throw new Error('token file is empty')\n        }\n      }\n    } catch (err) {\n      if (!token) throw new Error(`Cannot read the storefront token file ${file}: ${err instanceof Error ? err.message : String(err)}`)\n    }\n    return token\n  }\n}\n\nexport type TokenEnv = Record<string, string | undefined>\n\n/**\n * The store's token from the environment, in this order:\n * 1. `STOREFRONT_TOKEN_FILE` (path),\n * 2. `$CREDENTIALS_DIRECTORY/storefront_token` (systemd `LoadCredential=`),\n * 3. `STOREFRONT_TOKEN` (the plain variable, as before).\n * Files come back as a rotating source (re-read every 30 s); the variable as a plain string. `undefined` when\n * nothing is configured.\n */\nexport function storefrontTokenFromEnv(env: TokenEnv = process.env, options: FileTokenSourceOptions = {}): string | (() => string) | undefined {\n  const file = env.STOREFRONT_TOKEN_FILE?.trim()\n  if (file) return createFileTokenSource(file, options)\n  const dir = env.CREDENTIALS_DIRECTORY?.trim()\n  if (dir) {\n    const f = join(dir, 'storefront_token')\n    if (existsSync(f)) return createFileTokenSource(f, options)\n  }\n  const plain = env.STOREFRONT_TOKEN?.trim()\n  return plain || undefined\n}\n\n// ---------------------------------------------------------------------------\n// Atomic write\n// ---------------------------------------------------------------------------\n\n/** Writes `content` to `file` atomically (temp file in the same directory, fsync, rename) with mode 0600. */\nexport function writeFileAtomic(file: string, content: string, mode = 0o600): void {\n  const dir = dirname(file)\n  mkdirSync(dir, { recursive: true })\n  const tmp = join(dir, `.${file.split('/').pop()}.${process.pid}.${Date.now().toString(36)}.tmp`)\n  const fd = openSync(tmp, 'wx', mode)\n  try {\n    writeSync(fd, content)\n    fsyncSync(fd)\n  } catch (err) {\n    closeSync(fd)\n    try {\n      unlinkSync(tmp)\n    } catch {\n      /* best effort */\n    }\n    throw err\n  }\n  closeSync(fd)\n  try {\n    chmodSync(tmp, mode) // umask can only remove bits at creation; make it exact\n    renameSync(tmp, file)\n  } catch (err) {\n    try {\n      unlinkSync(tmp)\n    } catch {\n      /* best effort */\n    }\n    throw err\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Connection protocol\n// ---------------------------------------------------------------------------\n\nexport type RedeemResponse = {\n  ops_url: string\n  connection_id: string\n  environment: string\n  secret_token: string\n  publishable_token?: string\n  scopes: string[]\n  /** ISO time from which the token should be rotated. */\n  rotate_after: string\n}\n\nexport type ConnectClientInfo = { sdk_version: string; hostname: string; site_url?: string }\n\n/** Why a connection call failed, in terms an operator can act on. */\nexport type ConnectErrorKind = 'invalid_code' | 'rate_limited' | 'network' | 'unauthorized' | 'server' | 'invalid_response'\n\nexport class ConnectError extends Error {\n  override readonly name = 'ConnectError'\n  constructor(\n    readonly kind: ConnectErrorKind,\n    message: string,\n    readonly status = 0,\n  ) {\n    super(message)\n  }\n}\n\nconst trimSlash = (u: string) => u.replace(/\\/+$/, '')\n\nasync function post<T>(fetchImpl: FetchLike, url: string, body: unknown, bearer?: string): Promise<T> {\n  let res: Response\n  try {\n    res = await fetchImpl(url, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}) },\n      body: JSON.stringify(body),\n      signal: AbortSignal.timeout(15_000),\n    })\n  } catch {\n    throw new ConnectError('network', 'No pudimos comunicarnos con OPS. Revisa la dirección y tu conexión a internet.')\n  }\n  const text = await res.text().catch(() => '')\n  if (!res.ok) {\n    if (res.status === 429) throw new ConnectError('rate_limited', 'Demasiados intentos. Espera unos minutos e inténtalo de nuevo.', 429)\n    if (res.status === 401 || res.status === 403) throw new ConnectError('unauthorized', 'OPS rechazó la credencial de esta tienda.', res.status)\n    if (res.status >= 500) throw new ConnectError('server', 'OPS no pudo atender la solicitud. Inténtalo de nuevo en un momento.', res.status)\n    throw new ConnectError('invalid_code', 'El código no es válido, ya se usó o venció. Genera uno nuevo en OPS → Conexiones y API.', res.status)\n  }\n  if (!text) return undefined as T\n  try {\n    return JSON.parse(text) as T\n  } catch {\n    throw new ConnectError('invalid_response', 'OPS respondió algo que no entendimos.', res.status)\n  }\n}\n\nfunction assertRedeem(r: unknown): asserts r is RedeemResponse {\n  const o = r as Partial<RedeemResponse> | undefined\n  if (!o || typeof o.secret_token !== 'string' || !o.secret_token || typeof o.connection_id !== 'string' || !Array.isArray(o.scopes)) {\n    throw new ConnectError('invalid_response', 'OPS respondió algo que no entendimos.')\n  }\n}\n\nexport type RedeemOptions = { opsUrl: string; code: string; siteUrl?: string; fetch?: FetchLike }\n\n/** Exchanges the one-time connection code for the store's token. `POST {ops}/api/connect/v1/redeem`. */\nexport async function redeemConnectionCode(opts: RedeemOptions): Promise<RedeemResponse> {\n  const fetchImpl = opts.fetch ?? (globalThis.fetch.bind(globalThis) as FetchLike)\n  const client_info: ConnectClientInfo = { sdk_version: SDK_VERSION, hostname: hostname(), ...(opts.siteUrl ? { site_url: opts.siteUrl } : {}) }\n  const res = await post<unknown>(fetchImpl, `${trimSlash(opts.opsUrl)}/api/connect/v1/redeem`, { code: opts.code.trim(), client_info })\n  assertRedeem(res)\n  return res\n}\n\n/** What is kept next to the token file: everything but the secret. */\nexport type ConnectionState = {\n  ops_url: string\n  connection_id: string\n  environment: string\n  scopes: string[]\n  rotate_after: string\n}\n\nexport const stateFileFor = (tokenFile: string) => `${tokenFile}.json`\n\n/** Saves a redeemed/rotated connection: the token (0600, atomic) and its non-secret state beside it. */\nexport function saveConnection(tokenFile: string, r: RedeemResponse, opsUrl = r.ops_url): void {\n  const state: ConnectionState = { ops_url: trimSlash(r.ops_url || opsUrl), connection_id: r.connection_id, environment: r.environment, scopes: r.scopes, rotate_after: r.rotate_after }\n  // State first: if the process dies in between, the old token still works and rotation is just retried.\n  writeFileAtomic(stateFileFor(tokenFile), JSON.stringify(state, null, 2) + '\\n')\n  writeFileAtomic(tokenFile, r.secret_token + '\\n')\n}\n\nexport function loadConnectionState(tokenFile: string): ConnectionState | null {\n  try {\n    return JSON.parse(readFileSync(stateFileFor(tokenFile), 'utf8')) as ConnectionState\n  } catch {\n    return null\n  }\n}\n\nexport type ConnectStoreOptions = {\n  /** OPS base URL (`https://ops.example.com`). Defaults to the one saved by `connect`. */\n  opsUrl?: string\n  /** File `connect` wrote (default: `STOREFRONT_TOKEN_FILE`, then `./storefront_token`). */\n  tokenFile?: string\n  fetch?: FetchLike\n  /** Clock, for tests. */\n  now?: () => number\n  /** Called with a short message when a heartbeat or rotation fails. It never receives a token. */\n  onError?: (message: string) => void\n}\n\nexport type KeepFreshOptions = {\n  /** Heartbeat period (default 10 min). */\n  intervalMs?: number\n}\n\n/**\n * The store's side of the connection after `connect`: `keepFresh()` sends a heartbeat and, when `rotate_after`\n * passes, rotates the token (`POST /api/connect/v1/rotate`, Bearer = current `sk_`), writes the new file and lets a\n * `createFileTokenSource` client pick it up within its re-read interval. The old token keeps working during a grace\n * period set by OPS. It never throws and never keeps the process alive.\n */\nexport function connectStore(options: ConnectStoreOptions = {}) {\n  const tokenFile = resolve(options.tokenFile ?? process.env.STOREFRONT_TOKEN_FILE ?? 'storefront_token')\n  const fetchImpl = options.fetch ?? (globalThis.fetch.bind(globalThis) as FetchLike)\n  const now = options.now ?? Date.now\n  const report = (m: string) => {\n    try {\n      options.onError?.(m)\n    } catch {\n      /* ignore */\n    }\n  }\n\n  async function tick(): Promise<'ok' | 'rotated' | 'failed'> {\n    const state = loadConnectionState(tokenFile)\n    const opsUrl = options.opsUrl ?? state?.ops_url\n    let token: string\n    try {\n      token = readFileSync(tokenFile, 'utf8').trim()\n    } catch {\n      report(`No se pudo leer el archivo del token (${tokenFile}).`)\n      return 'failed'\n    }\n    if (!opsUrl || !token) {\n      report('Falta la dirección de OPS o el token: vuelve a ejecutar `npx @asteby/storefront connect`.')\n      return 'failed'\n    }\n    const base = `${trimSlash(opsUrl)}/api/connect/v1`\n    try {\n      await post<unknown>(fetchImpl, `${base}/heartbeat`, { sdk_version: SDK_VERSION, hostname: hostname() }, token)\n      const due = state?.rotate_after ? Date.parse(state.rotate_after) : NaN\n      if (!Number.isNaN(due) && now() >= due) {\n        const next = await post<unknown>(fetchImpl, `${base}/rotate`, {}, token)\n        assertRedeem(next)\n        saveConnection(tokenFile, { ...next, ops_url: next.ops_url || opsUrl }, opsUrl)\n        return 'rotated'\n      }\n      return 'ok'\n    } catch (err) {\n      report(err instanceof ConnectError ? `${err.message} (${maskToken(token)})` : `Falló el latido de la conexión (${maskToken(token)}).`)\n      return 'failed'\n    }\n  }\n\n  return {\n    tokenFile,\n    /** One heartbeat (+ rotation when due). Resolves, never rejects. */\n    tick,\n    /** Starts the periodic heartbeat; returns `stop()`. */\n    keepFresh(opts: KeepFreshOptions = {}): () => void {\n      const timer = setInterval(() => void tick(), opts.intervalMs ?? 600_000)\n      timer.unref?.()\n      void tick()\n      return () => clearInterval(timer)\n    },\n  }\n}\n","import type { StorefrontClient } from './client.js'\nimport { isStorefrontError } from './errors.js'\nimport type { TokenIntrospection } from './types.js'\n\n/** `sk_…a91f`: the prefix and the last four characters, never enough to use the token. */\nexport function maskToken(token: string | null | undefined): string {\n  if (!token) return '(sin token)'\n  const prefix = /^[a-z]{2}_/.exec(token)?.[0] ?? ''\n  return token.length <= prefix.length + 8 ? `${prefix}…` : `${prefix}…${token.slice(-4)}`\n}\n\nexport type DiagnoseOptions = {\n  /** Where the warning goes (default `console.warn`). Receives ONE line per problem. */\n  log?: (message: string) => void\n  /** Name of the connection, shown in the repair path. */\n  connectionName?: string\n  /** Give up after this long (default 3000 ms). */\n  timeoutMs?: number\n}\n\n/** Where the operator repairs a connection in OPS (es-MX, as the screen names it). */\nexport function repairPath(connectionName?: string): string {\n  return `OPS → Conexiones y API → ${connectionName ?? '<conexión>'} → Reparar permisos`\n}\n\n/**\n * Startup check of the store's credential: asks `token.introspect()` and, when scopes are missing, logs ONE clear\n * warning with the repair path (never the token, only `sk_…a91f`). It NEVER throws and is meant to be fired and\n * forgotten, so it cannot delay or break the boot:\n *\n * ```ts\n * void diagnose(storefront)\n * ```\n *\n * Resolves with the introspection, or `null` when it could not be obtained (older OPS, outage, bad token).\n */\nexport async function diagnose(client: StorefrontClient, options: DiagnoseOptions = {}): Promise<TokenIntrospection | null> {\n  const log = options.log ?? ((m: string) => console.warn(m))\n  const timeoutMs = options.timeoutMs ?? 3000\n  const raw = client.config.token\n  let mask: string\n  try {\n    mask = maskToken(typeof raw === 'function' ? raw() : raw)\n  } catch {\n    mask = maskToken(null)\n  }\n  try {\n    const info = await client.token.introspect({ signal: AbortSignal.timeout(timeoutMs) })\n    const missing = Array.isArray(info?.missing_scopes) ? info.missing_scopes : []\n    if (missing.length > 0) {\n      log(\n        `[@asteby/storefront] La credencial ${mask} no tiene permisos que la tienda necesita: ${missing.join(', ')}. ` +\n          `Repáralo en ${repairPath(options.connectionName)} (no hace falta cambiar la clave ni reiniciar).`,\n      )\n    }\n    return info ?? null\n  } catch (err) {\n    if (isStorefrontError(err) && err.status === 401) {\n      try {\n        log(`[@asteby/storefront] OPS rechazó la credencial ${mask} (401): está revocada o vencida. Vuelve a conectar la tienda en OPS → Conexiones y API.`)\n      } catch {\n        /* a broken logger must not break boot */\n      }\n    }\n    return null\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{types-CSMuPSQA.d.cts → types-C-Ley-Mt.d.cts}

@@ -318,6 +318,8 @@ type Cart = {
     note?: string | null;
     /** Automatic-discount tiers and free-shipping progress (contract 1.2); `null`/absent without the promotions addon. */
     promotions?: CartPromotions | null;
+    /** Invoice the buyer asked for (`carts.setInvoice`); `null`/absent when none. */
+    invoice?: CartInvoice | null;
     updated_at: string;
 };
 type CartLineInput = {
@@ -395,20 +397,31 @@ type DeliveryInput = {
     rate_id?: string;
     branch_id?: string;
 };
+/**
+ * Fiscal data the buyer asks an invoice for. The Spanish aliases are still accepted by the API.
+ * `document` is the evidence of where the data came from (never the document itself).
+ */
 type InvoiceRequest = {
     requested?: boolean;
     tax_id?: string;
     legal_name?: string;
     tax_regime?: string;
-    /** CFDI use. */
+    /** Invoice use; the region says which are allowed for `tax_regime`. */
     use?: string;
     postal_code?: string;
+    /** Defaults to the market's country. */
+    country_code?: string;
+    document?: FiscalDocumentEvidence;
     /** Spanish aliases the API also accepts. */
     rfc?: string;
     razon_social?: string;
     regimen?: string;
     uso_cfdi?: string;
     cp?: string;
+    /** Alias of `use`. */
+    invoice_use?: string;
+    /** Also save the data to the buyer's account (needs a session). */
+    save?: boolean;
     [key: string]: unknown;
 };
 type CheckoutInput = {
@@ -472,6 +485,8 @@ type Customer = {
     first_name: string | null;
     last_name: string | null;
     default_address_id: string | null;
+    /** Saved fiscal data; `null`/absent when none. */
+    fiscal?: FiscalIdentity | null;
     created_at: string;
 };
 type CustomerIdentifier = {
@@ -489,6 +504,65 @@ type CustomerSession = {
     expires_at: string;
     customer: Customer;
 };
+/** What the store's buyer accounts support (`GET /storefront/customer/capabilities`). Cache briefly, not forever. */
+type CustomerCapabilities = {
+    /** Email + password registration and login are enabled. */
+    password: boolean;
+    /** Registration needs an emailed code (`customer.verifyRegistration`) before the account exists. */
+    email_verification: boolean;
+    /** Channels `customer.requestOtp` can deliver the code through. */
+    otp_channels: ('email' | 'whatsapp')[];
+    /** What invoicing the store offers. Absent on older servers: treat as `available: false`. */
+    invoicing?: InvoicingCapabilities;
+    /**
+     * Why a way of signing in is off. `missing_scope`: the store's token lacks a scope (see `missing_scopes`), so
+     * the store is misconfigured; it is not a choice of the merchant. Absent when everything is as configured.
+     */
+    unavailable_reason?: 'missing_scope' | (string & {});
+    /** Scopes the token lacks (e.g. `customer:write`) when `unavailable_reason` is `missing_scope`. */
+    missing_scopes?: string[];
+};
+/** `GET {gateway}/_token`: what the token in use is and what it can do. Needs no scope. */
+type TokenIntrospection = {
+    kind: string;
+    environment: 'sandbox' | 'production' | (string & {});
+    scopes: string[];
+    /** Scopes the connection should have but the token lacks. Empty when healthy. */
+    missing_scopes: string[];
+    connection_id: string | null;
+    expires_at: string | null;
+};
+type CustomerRegisterInput = {
+    email: string;
+    password: string;
+    first_name?: string;
+    last_name?: string;
+};
+/** `verification_required`: a code was emailed, finish with `customer.verifyRegistration`. `created`: the account is ready and signed in. */
+type CustomerRegisterResult = {
+    status: 'verification_required';
+} | {
+    status: 'created';
+    session: CustomerSession;
+};
+type CustomerVerifyRegistrationInput = {
+    email: string;
+    code: string;
+};
+type CustomerPasswordLoginInput = {
+    email: string;
+    password: string;
+};
+/** `current_password` is required by the server when the account already has a password. */
+type CustomerSetPasswordInput = {
+    password: string;
+    current_password?: string;
+};
+type CustomerResetPasswordInput = {
+    email: string;
+    code: string;
+    password: string;
+};
 type OrderLine = {
     title: string;
     variant_title: string | null;
@@ -505,6 +579,8 @@ type Order = {
     created_at: string;
     total: Money;
     lines: OrderLine[];
+    /** Invoice state; absent on older servers. */
+    invoice?: InvoiceSummary;
 };
 type ReturnRequestInput = {
     lines: {
@@ -518,9 +594,12 @@ type ReturnRequest = {
     order_id: string;
     status: string;
 };
+/** `200` issued, `202` pending. The 422 / 409 / 503 outcomes arrive as a `StorefrontError`. */
 type InvoiceResult = {
     status: string;
     url?: string | null;
+    stage?: InvoiceStage;
+    invoice?: InvoiceSummary;
 };
 type Theme = {
     /** Design tokens, e.g. `{ primary: '#0f766e', 'primary-foreground': '#ffffff' }`. */
@@ -562,7 +641,9 @@ type Article = {
     published_at: string;
     seo: SEO;
 };
-type StorefrontErrorCode = 'validation' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'insufficient_stock' | 'price_mismatch' | 'invalid_state' | 'rate_limited' | 'not_modified' | 'server_error' | 'network' | 'timeout' | 'aborted' | 'invalid_response' | (string & {});
+type StorefrontErrorCode = 'validation' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'insufficient_stock' | 'price_mismatch' | 'invalid_state' | 'rate_limited' | 'not_modified' | 'server_error' | 'network' | 'timeout' | 'aborted' | 'invalid_response'
+/** `403`: the token lacks a scope the route needs. `StorefrontError.requiredScopes` lists them. */
+ | 'insufficient_scope' | (string & {});
 /** One affected line of a `409 insufficient_stock`. `line_id` is `null` when the line did not exist yet (add). */
 type InsufficientStockLine = {
     line_id: string | null;
@@ -580,6 +661,7 @@ type StorefrontErrorBody = {
         message: string;
         field?: string;
         details?: unknown;
+        required_scopes?: string[];
     };
 };
 type RestockSubscriptionInput = {
@@ -831,5 +913,253 @@ type PromotionsList = {
     nodes: unknown[];
     announcements: PromotionAnnouncement[];
 };
+/** Where an invoice is. `needs_data`: the buyer must fix something. `needs_review`: the store must act. */
+type InvoiceStage = 'not_requested' | 'requested' | 'awaiting_payment' | 'queued' | 'issuing' | 'issued' | 'cancelled' | 'needs_data' | 'retrying' | 'needs_review' | 'window_closed' | (string & {});
+/** What the buyer can do next about an invoice. */
+type InvoiceAction = 'none' | 'request' | 'wait' | 'correct_data' | 'download' | 'contact_store' | (string & {});
+type InvoiceSummary = {
+    /** Single-word status (`requested`, `issued`...). Prefer `stage`. */
+    status: string;
+    stage?: InvoiceStage;
+    requested?: boolean;
+    /** Machine-readable cause when `stage` is `needs_data` / `needs_review` (e.g. `invoice.tax_regime`). */
+    reason_code?: string | null;
+    action?: InvoiceAction;
+    /** The buyer may ask for it now. */
+    can_request?: boolean;
+    /** Why `can_request` is `false` (e.g. `awaiting_payment`, `window_closed`, `not_invoiceable`). */
+    blocked_reason?: string | null;
+    /** Fiscal folio (UUID in Mexico) once issued. */
+    folio?: string | null;
+    /** Signed, short-lived download links. */
+    url?: string | null;
+    xml_url?: string | null;
+};
+/** The invoice request of a cart (`Cart.invoice`). The tax id is masked: the full value is never echoed back. */
+type CartInvoice = {
+    requested: boolean;
+    tax_id_masked?: string | null;
+    legal_name?: string | null;
+    country_code?: string | null;
+    /** `IdentityDocumentSpec.kind` the data was read from, when it was. */
+    document_kind?: string | null;
+};
+type InvoicingCapabilities = {
+    available: boolean;
+    /** Countries (ISO 3166-1 alpha-2) the store can invoice for. */
+    countries: string[];
+    /** `optional`: the checkout offers "I need an invoice". `off`: invoices can only be requested afterwards. */
+    checkout: 'off' | 'optional';
+    /** Invoices can be requested after the purchase (`customer.requestInvoice`). */
+    post_purchase: boolean;
+    /** Days after the purchase in which an invoice can still be requested. */
+    window_days?: number;
+    /** `IdentityDocumentSpec.kind` values the buyer can upload to prefill the data. */
+    identity_documents: string[];
+    /** The store can check the data against the tax authority online (informative, never blocks). */
+    online_verify: boolean;
+};
+/** One regime or invoice use of the region's fiscal catalog. */
+type RegionFiscalEntry = {
+    code: string;
+    label: string;
+    label_en?: string;
+    /** Region-defined (`individual`, `company`...); compare as opaque strings. */
+    person_types: string[];
+    /** Invoice uses only: the regimes that may use it. Absent: any. */
+    allowed_regimes?: string[];
+    /** Folded phrases that identify the entry in a document (`catalog_phrases`); without them the label is used. */
+    match_phrases?: string[];
+};
+/**
+ * A document the buyer can upload to prefill their fiscal data, with the rules to read it. Published by the
+ * region in `fiscal_id.documents[]` (texts already in the response locale); the SDK engine knows no country.
+ */
+type IdentityDocumentSpec = {
+    /** `<COUNTRY>:<kind>`. */
+    kind: string;
+    country_code?: string;
+    label: string;
+    /** Explanation for the buyer; absent when the region has none in the response language. */
+    help?: string;
+    /** Where the buyer gets the document from the authority. */
+    obtain_url?: string;
+    /** MIME types the document comes in (the SDK reads PDFs). */
+    accept: string[];
+    max_bytes: number;
+    max_pages?: number;
+    /** `rules@1` runs the generic engine on `rules`; `plugin:<id>` runs an extractor from `registerIdentityExtractor`. */
+    engine: 'rules@1' | `plugin:${string}` | (string & {});
+    /** The `rules@1` rules (the API publishes them as an object; JSON text is accepted too). */
+    rules?: IdentityRulesV1 | string | null;
+    /** How the server can check the document against the authority (e.g. `qr_validator`). Informative. */
+    verify_kind?: string;
+    /** Days after `issued_on` in which the document counts as fresh. */
+    freshness_days?: number;
+    /** Fields the extractor never returns (sensitive data the store has no use for). */
+    discard_fields: string[];
+};
+/** Region fiscal identity (`Region.fiscal_id`). */
+type RegionFiscalId = {
+    /** Name of the tax id (`RFC`, `EIN`...). */
+    kind: string;
+    label: string;
+    /** Regular expression a valid tax id matches. */
+    pattern?: string;
+    /** Generic ids valid without a document (e.g. the national generic public id). */
+    generic_ids: string[];
+    regimes: RegionFiscalEntry[];
+    invoice_uses: RegionFiscalEntry[];
+    /** Documents the buyer can upload; absent on older servers. */
+    documents?: IdentityDocumentSpec[];
+};
+type RegionPaymentMethod = {
+    code: string;
+    label: string;
+    description?: string;
+    kind: string;
+    flow: string;
+    providers: string[];
+    installments: {
+        months: number[];
+        min_amount: Money | null;
+    } | null;
+    min_amount: Money | null;
+    max_amount: Money | null;
+    expires_hours?: number;
+    icon?: string;
+    /** Payment forms the invoice may report for this method, comma separated; the first is the default (e.g. `04,28`). */
+    fiscal_payment_form?: string;
+};
+/** `GET /storefront/region`: how the market formats, taxes, addresses and invoices. */
+type Region = {
+    country_code: string;
+    name: string;
+    locale: {
+        default: string;
+        available: string[];
+        current: string;
+    };
+    timezone?: string;
+    currency: Record<string, unknown>;
+    formats?: Record<string, unknown>;
+    tax: Record<string, unknown>;
+    address?: {
+        postal_code?: {
+            pattern: string;
+            example?: string;
+        };
+        [key: string]: unknown;
+    };
+    subdivisions?: Record<string, unknown>[];
+    phone?: Record<string, unknown>;
+    fiscal_id?: RegionFiscalId;
+    payment_methods?: RegionPaymentMethod[];
+};
+/** Where the fiscal data came from. `manual`: typed by the buyer. */
+type FiscalDocumentSource = 'pdf_client' | 'pdf_server' | 'qr' | 'manual';
+/** What is kept about the document the data was read from. Never the document itself. */
+type FiscalDocumentEvidence = {
+    /** `IdentityDocumentSpec.kind`. */
+    kind: string;
+    /** The authority's id of the document. */
+    document_id?: string | null;
+    /** ISO date the authority issued it. */
+    issued_on?: string | null;
+    /** SHA-256 of the file, lowercase hex. */
+    sha256?: string | null;
+    /** Engine that read it, e.g. `rules@1`. */
+    extractor?: string;
+    source: FiscalDocumentSource;
+    /** The QR agreed with the text: `true`/`false`, `null` when there was no QR to compare. */
+    qr_match?: boolean | null;
+};
+type FiscalVerification = {
+    /** `reviewed` (the buyer confirmed it), `verified`, `mismatch`, `unverified`, `stale`. */
+    status: 'reviewed' | 'verified' | 'mismatch' | 'unverified' | 'stale' | (string & {});
+    checked_at?: string | null;
+};
+/** Fiscal data as stored for a buyer. */
+type FiscalIdentity = {
+    country_code: string;
+    tax_id: string;
+    legal_name: string;
+    tax_regime: string;
+    postal_code: string;
+    invoice_use?: string | null;
+    document?: FiscalDocumentEvidence | null;
+    verification?: FiscalVerification | null;
+};
+type FiscalIdentityInput = Omit<FiscalIdentity, 'verification' | 'country_code'> & {
+    country_code?: string;
+};
+/** `PATCH /customer`. `fiscal: null` deletes the saved fiscal data (ARCO). */
+type CustomerUpdateInput = {
+    first_name?: string | null;
+    last_name?: string | null;
+    phone?: string | null;
+    fiscal?: FiscalIdentityInput | null;
+};
+/** Post-processing: the value must match `pattern`; `group` of it replaces the value. */
+type IdentityCapture = {
+    pattern: string;
+    flags?: string;
+    group?: number;
+};
+/**
+ * One way to find a field. Only the members of its `strategy` apply:
+ * `regex` (`pattern`, `flags`, `group`), `labeled_lines` (`label`), `concat_labeled` (`labels`, `separator`),
+ * `catalog_phrases` (`catalog`, `start`, `end`), `date` (`pattern` with three groups, `flags`, `order`, `months`),
+ * `qr_param` (`param`, `split`, `parts`, `match`). Any strategy takes `upper` and `capture`.
+ */
+type IdentityStrategy = {
+    strategy: 'regex' | 'labeled_lines' | 'concat_labeled' | 'catalog_phrases' | 'date' | 'qr_param';
+    pattern?: string;
+    /** `i`, `s`, `m`. */
+    flags?: string;
+    group?: number;
+    label?: string;
+    labels?: string[];
+    separator?: string;
+    catalog?: string;
+    start?: string;
+    end?: string;
+    /** Permutation of `d`, `m`, `y`: the meaning of the three groups. */
+    order?: string;
+    /** 12 month names, to read a month written in text. */
+    months?: string[];
+    /** `qr_param` fallback for a QR read by a keyboard scanner that garbled the punctuation: a pattern over the raw text whose group `group` is the value. Runs when `param` finds nothing. */
+    scan?: string;
+    param?: string;
+    split?: string;
+    parts?: number;
+    match?: string;
+    upper?: boolean;
+    capture?: IdentityCapture;
+};
+type IdentityFieldRule = {
+    /** Output name: `tax_id`, `legal_name`, `postal_code`, `tax_regime`, `document_id`, `issued_on`... */
+    key: string;
+    /** Listed in `missing` when not found. */
+    required?: boolean;
+    /** A list (e.g. every regime the document names). */
+    multiple?: boolean;
+    /** Tried in order; the first non-empty value wins. `qr_param` ones only fill what the text lacks. */
+    strategies: IdentityStrategy[];
+};
+/**
+ * `rules@1`, as the region publishes it (same semantics as the reference interpreter of the region packs). Text
+ * is normalized (`nbsp`, `collapse_ws`), then each field is resolved. Patterns are in the subset common to Go
+ * (RE2) and JavaScript: no lookaround, backreferences, named groups, inline flags or `\p`.
+ */
+type IdentityRulesV1 = {
+    version: 1;
+    normalize?: ('nbsp' | 'collapse_ws')[];
+    /** Captions of the document (regex fragments, case-insensitive, followed by a colon). A labelled value ends at the next caption. */
+    labels?: string[];
+    /** Template of the canonical QR URL, rebuilt from the fields the QR carried (`{field}` placeholders). It survives readers that garble the URL. */
+    qr_canonical?: string;
+    fields: IdentityFieldRule[];
+};
 
-export type { Page as $, Address as A, CustomerSession as B, Cart as C, CustomerSessionInput as D, DeclineCode as E, DeliveryInput as F, DeliveryMethod as G, DeliveryOptions as H, Facet as I, FacetValue as J, Image as K, InsufficientStockDetails as L, InsufficientStockLine as M, InvoiceRequest as N, InvoiceResult as O, Location as P, LocationContacts as Q, LocationKind as R, LocationListParams as S, LocationPickup as T, Menu as U, MenuItem as V, Money as W, MoneyRange as X, NearestLocation as Y, Order as Z, OrderLine as _, AddressInput as a, PageInfo as a0, PaymentAction as a1, PaymentAttemptResult as a2, PaymentAttemptStatus as a3, PaymentClient as a4, PaymentClientCsp as a5, PaymentConfig as a6, PaymentFlow as a7, PaymentMethod as a8, PaymentMethods as a9, ShippingRate as aA, Shop as aB, ShopBranch as aC, ShopContact as aD, ShopPolicies as aE, StockLevel as aF, StorefrontErrorBody as aG, StorefrontErrorCode as aH, Theme as aI, UnavailableRateProvider as aJ, PaymentNextStep as aa, PaymentOption as ab, PaymentOptionKey as ac, PaymentPoint as ad, PaymentSubmitInput as ae, PaymentVoucher as af, PickupOption as ag, Product as ah, ProductAttributeValue as ai, ProductCategory as aj, ProductConnection as ak, ProductOption as al, ProductSort as am, ProductVariant as an, PromotionAnnouncement as ao, PromotionReward as ap, PromotionTier as aq, PromotionsList as ar, RecommendationPlacement as as, RestockSubscriptionInput as at, RestockSubscriptionResult as au, ReturnRequest as av, ReturnRequestInput as aw, SEO as ax, Section as ay, SelectedOption as az, Article as b, Availability as c, AvailabilityStatus as d, CartBuyer as e, CartBuyerInput as f, CartCost as g, CartDelivery as h, CartDiscountCode as i, CartDiscountLine as j, CartLine as k, CartLineInput as l, CartLineMerchandise as m, CartLineProblem as n, CartLineUpdateInput as o, CartPromotions as p, CartRecommendation as q, CartRecommendations as r, CheckoutInfo as s, CheckoutInput as t, CheckoutPayment as u, CheckoutResult as v, Collection as w, Connection as x, Customer as y, CustomerIdentifier as z };
+export type { IdentityRulesV1 as $, Address as A, CustomerCapabilities as B, Cart as C, CustomerIdentifier as D, CustomerPasswordLoginInput as E, CustomerRegisterInput as F, CustomerRegisterResult as G, CustomerResetPasswordInput as H, CustomerSession as I, CustomerSessionInput as J, CustomerSetPasswordInput as K, CustomerUpdateInput as L, CustomerVerifyRegistrationInput as M, DeclineCode as N, DeliveryInput as O, DeliveryMethod as P, DeliveryOptions as Q, Facet as R, FacetValue as S, FiscalDocumentEvidence as T, FiscalDocumentSource as U, FiscalIdentity as V, FiscalIdentityInput as W, FiscalVerification as X, IdentityCapture as Y, IdentityDocumentSpec as Z, IdentityFieldRule as _, AddressInput as a, ShippingRate as a$, IdentityStrategy as a0, Image as a1, InsufficientStockDetails as a2, InsufficientStockLine as a3, InvoiceAction as a4, InvoiceRequest as a5, InvoiceResult as a6, InvoiceStage as a7, InvoiceSummary as a8, InvoicingCapabilities as a9, PaymentPoint as aA, PaymentSubmitInput as aB, PaymentVoucher as aC, PickupOption as aD, Product as aE, ProductAttributeValue as aF, ProductCategory as aG, ProductConnection as aH, ProductOption as aI, ProductSort as aJ, ProductVariant as aK, PromotionAnnouncement as aL, PromotionReward as aM, PromotionTier as aN, PromotionsList as aO, RecommendationPlacement as aP, Region as aQ, RegionFiscalEntry as aR, RegionFiscalId as aS, RegionPaymentMethod as aT, RestockSubscriptionInput as aU, RestockSubscriptionResult as aV, ReturnRequest as aW, ReturnRequestInput as aX, SEO as aY, Section as aZ, SelectedOption as a_, Location as aa, LocationContacts as ab, LocationKind as ac, LocationListParams as ad, LocationPickup as ae, Menu as af, MenuItem as ag, Money as ah, MoneyRange as ai, NearestLocation as aj, Order as ak, OrderLine as al, Page as am, PageInfo as an, PaymentAction as ao, PaymentAttemptResult as ap, PaymentAttemptStatus as aq, PaymentClient as ar, PaymentClientCsp as as, PaymentConfig as at, PaymentFlow as au, PaymentMethod as av, PaymentMethods as aw, PaymentNextStep as ax, PaymentOption as ay, PaymentOptionKey as az, Article as b, Shop as b0, ShopBranch as b1, ShopContact as b2, ShopPolicies as b3, StockLevel as b4, StorefrontErrorBody as b5, StorefrontErrorCode as b6, Theme as b7, TokenIntrospection as b8, UnavailableRateProvider as b9, Availability as c, AvailabilityStatus as d, CartBuyer as e, CartBuyerInput as f, CartCost as g, CartDelivery as h, CartDiscountCode as i, CartDiscountLine as j, CartInvoice as k, CartLine as l, CartLineInput as m, CartLineMerchandise as n, CartLineProblem as o, CartLineUpdateInput as p, CartPromotions as q, CartRecommendation as r, CartRecommendations as s, CheckoutInfo as t, CheckoutInput as u, CheckoutPayment as v, CheckoutResult as w, Collection as x, Connection as y, Customer as z };