@asteby/storefront 0.10.0 → 0.11.1

package/README.md

@@ -8,7 +8,9 @@ and CommonJS builds with types.
 
 Includes `@asteby/storefront/mock`: an in-memory implementation of the whole
 contract (catalog with facets, carts, discounts, delivery, checkout, OTP
-login, content) to build a store without OPS.
+login, content, region and invoices) to build a store without OPS, and
+`@asteby/storefront/fiscal-document`: reads a buyer's fiscal document (PDF)
+in the browser or Node with rules published by the region.
 
 React bindings (cart, prices, images, SEO, sections, theme) live in
 [`@asteby/storefront-react`](../storefront-react).
@@ -301,6 +303,151 @@ Pure helpers, no DOM: `visitorCountry(headers)` (CDN country headers),
 (suggests, never redirects; respects crawlers and a saved choice; country wins
 over language) and `hreflangLinks` for per-market SEO.
 
+## Fiscal identity and invoices (Storefront API 1.6)
+
+The buyer's tax data travels in four pieces, all country-agnostic. What changes per country is DATA the region
+publishes; the SDK knows no tax authority.
+
+```ts
+const region = await sf.region()              // GET /storefront/region (null on 404)
+const fid = region?.fiscal_id                 // { kind, label, pattern, generic_ids, regimes[], invoice_uses[], documents[] }
+
+// Ask for an invoice in the checkout. 422 names the exact field: `invoice.tax_id`, `invoice.tax_regime`, `invoice.use`...
+await sf.carts.setInvoice(cart.id, { tax_id, legal_name, tax_regime, use, postal_code, document })
+await sf.carts.setInvoice(cart.id, null)      // withdraw (sends { requested: false })
+// checkout uses `carts.invoice` when `CheckoutInput.invoice` is omitted; both are validated BEFORE any charge.
+
+await customer.customer.update({ fiscal: { ...data } })   // save to the account (PATCH /customer)
+await customer.customer.update({ fiscal: null })          // delete it (ARCO)
+await customer.customer.requestInvoice(order.id, data)    // later; order.invoice.stage / can_request / action drive the UI
+```
+
+`customer.capabilities().invoicing` says whether the store invoices (`available`, `countries`, `checkout`,
+`post_purchase`, `identity_documents`). Types: `Region`, `RegionFiscalId`, `IdentityDocumentSpec`, `FiscalIdentity`,
+`FiscalDocumentEvidence`, `InvoiceSummary` (`stage`, `reason_code`, `action`, `can_request`, `blocked_reason`, `url`,
+`xml_url`), `CartInvoice`, `InvoicingCapabilities`.
+
+### Reading the buyer's document (`@asteby/storefront/fiscal-document`)
+
+The buyer can upload the authority's PDF (in Mexico, the constancia de situación fiscal) to prefill the form. It is
+read **on the buyer's device** (or in memory on your server for the no-JS path); the PDF is never uploaded, stored or
+logged. Only the fields the buyer reviews, plus minimal evidence (document id, SHA-256, extractor, QR match), travel.
+
+```ts
+import { readPdfText, extractIdentityDocument, decodePdfQr, buildDocumentEvidence, catalogsFromRegion, isIdentityDocumentError } from '@asteby/storefront/fiscal-document'
+
+const spec = region.fiscal_id.documents.find((d) => d.kind === 'MX:csf')!
+
+try {
+  const { text, sha256 } = await readPdfText(file, { workerSrc: '/assets/pdf.worker.mjs', maxBytes: spec.max_bytes, maxPages: spec.max_pages }) // browser: YOUR worker URL
+  const qr = await decodePdfQr(file, { workerSrc: '/assets/pdf.worker.mjs' })             // optional; null if it cannot (the URL the QR encodes)
+  const x = extractIdentityDocument(text, spec, { catalogs: catalogsFromRegion(region.fiscal_id), qr })
+  x.fields      // { tax_id, legal_name, postal_code, tax_regime: ['612', '605'], document_id, issued_on } (what was read)
+  x.missing     // fields to leave empty for the buyer to type
+  x.qr.match    // true | false | null (no QR / nothing to compare)
+  x.stale       // older than spec.freshness_days
+  const document = buildDocumentEvidence(x, { sha256, source: 'pdf_client' }) // goes in InvoiceRequest.document
+} catch (err) {
+  if (isIdentityDocumentError(err)) err.code // 'too_large' | 'not_pdf' | 'unreadable' | 'no_text' | 'password'
+}
+```
+
+- **Sensitive data never comes out.** The spec's `discard_fields` (a national person id, street, activities...) are
+  removed from the output whatever produced them (rules may not even declare them). The extraction carries no
+  text and no error message contains document text.
+- **pdf.js is loaded on demand** (`import('pdfjs-dist/legacy/build/pdf.mjs')`) with `isEvalSupported: false`; the
+  main entry point does not include it. Install `pdfjs-dist@>=4.2.67` (older versions are affected by CVE-2024-4367).
+  In browsers there is deliberately **no default worker and no CDN**: copy `pdf.worker.mjs` to your own assets and pass
+  `workerSrc` (or `setPdfjsLoader` to configure it once). Allow it in your CSP with `worker-src 'self'`. Node needs no worker file.
+- **Limits** (`readPdfText` options): `maxBytes` 5 MiB, `maxPages` 6, `timeoutMs` 3000, `%PDF-` signature checked first.
+  Scans have no text layer: `no_text` means "ask for manual entry" (no OCR).
+- **`decodePdfQr`** is best effort: `BarcodeDetector` or the optional `jsqr` package (both on demand) on a rendered page.
+  Without a canvas (Node) it returns `null` unless you pass your own `decode(imageData)`. It never blocks the flow.
+- **Countries with code**: `registerIdentityExtractor('<id or kind>', (text, spec, options) => ({ fields, qr }))`
+  for a spec with `engine: 'plugin:<id>'`. `discard_fields` still applies to it. The server-side validator is the region's.
+
+#### `rules@1`
+
+The generic engine runs the rules of the spec (`spec.rules`; the API publishes an object, JSON text is accepted).
+It is the TypeScript twin of the reference interpreter of the region packs (`regionspec.ExtractIdentity`): same
+semantics, held to the same synthetic documents. The text is normalized (`nbsp`, `collapse_ws`), then each field
+tries its strategies in order and the first non-empty value wins.
+
+```jsonc
+{
+  "version": 1,
+  "normalize": ["nbsp", "collapse_ws"],
+  "labels": ["RFC", "CURP", "C[óo]digo Postal", "Reg[íi]menes", "Obligaciones"],  // a labelled value ends at the next caption
+  "fields": [
+    { "key": "tax_id", "required": true, "strategies": [
+        { "strategy": "labeled_lines", "label": "RFC", "upper": true, "capture": { "pattern": "\\b([A-Z]{4}[0-9]{6}[A-Z0-9]{3})\\b", "group": 1 } },
+        { "strategy": "qr_param", "param": "D3", "split": "_", "parts": 2, "match": "^[A-Z]{4}[0-9]{6}[A-Z0-9]{3}$" } ] },
+    { "key": "tax_regime", "multiple": true, "strategies": [
+        { "strategy": "catalog_phrases", "catalog": "fiscal_regime", "start": "Reg[íi]menes\\s*:?", "end": "Obligaciones\\s*:" } ] }
+  ]
+}
+```
+
+| Strategy | Reads |
+|---|---|
+| `regex` | `group` (0 = whole match) of the first match of `pattern` (`flags`: `i`, `s`, `m`) |
+| `labeled_lines` | the value after the caption `label` up to the next caption of `labels`, line breaks or not |
+| `concat_labeled` | the values of several captions joined with `separator` (first names + surnames) |
+| `catalog_phrases` | the codes of the catalog entries whose phrases appear between `start` and `end`, in order of first mention. Phrases come from `match_phrases`, or the label when absent. No `start` found: no section |
+| `date` | `pattern` with three groups in the order of `order` (`dmy`, `ymd`...); `months` (12 names) reads a month in text; calendar-invalid dates are dropped. Result `YYYY-MM-DD` |
+| `qr_param` | from the QR URL: parameter `param`, split on `split` into exactly `parts` parts; the part matching `match` (uppercased). `scan` (+ `flags`, `group`) is the fallback for QRs read by a keyboard-wedge scanner that garbled the punctuation: a pattern over the raw text |
+
+Any strategy takes `upper` and `capture` (`{pattern, flags, group}`: the value must match it and the group replaces
+the value). **The text wins over the QR**; a `qr_param` strategy only fills what the text lacks, and `extraction.qr.match`
+is `false` when both carry a field and differ (a warning, never a block). Patterns are limited to the subset common to Go and
+JavaScript (no lookaround, backreferences, named groups, inline flags or `\p`); `validateRules` rejects the rest, and
+a rule that produces a `discard_fields` field. `qr_canonical` (top level) is a template, e.g. `https://host/path?D3={document_id}_{tax_id}`, filled with what the QR carried; `extraction.qr.canonical` returns it rebuilt (always the canonical form, however the scanner garbled it). Catalogs for `catalog_phrases` come from `catalogsFromRegion(region.fiscal_id)`
+(`fiscal_regime`, `invoice_use`). A text that does not match yields `missing` (required fields); only a spec that cannot
+run throws `IdentityRulesError`.
+
+## Connecting the store to OPS (`connect`, `diagnose`, token files)
+
+A server-side store (`sk_`) is connected to OPS with a one-time code, never by copying a secret around.
+
+```sh
+# on the store's server; the code (K7QM-2XPA, 10 min, single use) is typed at the prompt, never an argument
+npx @asteby/storefront connect --ops https://ops.example.com --env-file .env --token-file /etc/mystore/storefront_token
+# Conectada ✓ · 7 alcances · sk_…a91f
+```
+
+`connect` redeems the code (`POST {ops}/api/connect/v1/redeem` with `{code, client:{name,version,runtime,hostname}}`; OPS
+answers `{success:true,data:{token, connection, scopes, rotation_days, api_base}}`, an invalid, expired or used code is one
+answer: `400 invalid_code`), writes the key ATOMICALLY (temp file + rename, mode `0600`; default `./storefront_token`)
+with its non-secret state beside it (`<file>.json`: connection, `api_base`, `rotation_days`, `rotate_after`), leaves ONLY `OPS_URL` and
+`STOREFRONT_TOKEN_FILE` in the env file (never the key), prints just the prefix and last four characters, and checks
+the key with `token.introspect()`. Exit code is `1` with an es-MX message for an expired or used code, an unreachable
+OPS or a non-TTY stdin.
+
+Read the key without restarting when it rotates (`@asteby/storefront/node`, Node only):
+
+```ts
+import { createStorefrontClient, diagnose } from '@asteby/storefront'
+import { connectStore, storefrontTokenFromEnv } from '@asteby/storefront/node'
+
+const storefront = createStorefrontClient({
+  baseUrl: `${process.env.OPS_URL}/api/gw`,
+  // STOREFRONT_TOKEN_FILE, then $CREDENTIALS_DIRECTORY/storefront_token (systemd LoadCredential=), then STOREFRONT_TOKEN.
+  // Files are re-read every 30 s (only when the mtime changed); a failed re-read keeps the last good key.
+  token: storefrontTokenFromEnv()!,
+})
+void diagnose(storefront)                 // one warning if scopes are missing; never throws, never delays boot
+connectStore().keepFresh()                // heartbeat; rotates (POST /api/connect/v1/rotate) on rotate_now / next_rotation_at; honors Retry-After on 429
+```
+
+`token` also accepts any `() => string`, called on every request. `diagnose` logs, at most once, which scopes are
+missing and where to repair them (`OPS → Conexiones y API → <conexión> → Reparar permisos`), showing `sk_…a91f` and never
+the key. Repairing permissions does not change the key.
+
+Errors: a `403 insufficient_scope` is a `StorefrontError` with `code: 'insufficient_scope'`, `status: 403` and
+`requiredScopes: ['customer:write']`. `customer.capabilities()` reports `password: false`, `unavailable_reason:
+'missing_scope'` and `missing_scopes` when the key cannot create accounts. The mock rehearses all of it with
+`createMockStorefront({ missingScopes: ['customer:write'] })`.
+
 ## API
 
 `createStorefrontClient(options)`:
@@ -320,10 +467,10 @@ over language) and `hreflangLinks` for per-market SEO.
 | `onRequest?(ctx)` | Runs before each request; return a `Response` to short-circuit (SSR cache hit) |
 | `onResponse?(ctx)` | Runs after each response (cache store, logging, metrics) |
 
-Resources: `shop.get`, `products.list/get/recommendations`,
+Resources: `shop.get`, `region`, `products.list/get/recommendations`,
 `collections.list/get`, `stock.get`,
-`carts.create/get/addLines/updateLines/removeLines/setDiscountCodes/setBuyer/setShippingAddress/deliveryOptions/setDelivery/checkout`,
-`customer.requestOtp/createSession/capabilities/register/verifyRegistration/loginWithPassword/setPassword/resetPassword/get/orders/order/requestReturn/requestInvoice/addresses.{list,create,update,delete}`,
+`carts.create/get/addLines/updateLines/removeLines/setDiscountCodes/setBuyer/setShippingAddress/deliveryOptions/setDelivery/setInvoice/checkout`,
+`customer.requestOtp/createSession/capabilities/register/verifyRegistration/loginWithPassword/setPassword/resetPassword/get/update/orders/order/requestReturn/requestInvoice/addresses.{list,create,update,delete}`,
 `content.theme/page/menu/articles/article`. Every method takes a last
 `options` argument: `{ cache, signal, next, headers, timeoutMs, customerToken, clientIp }`
 (plus `idempotencyKey` on writes and `preview` on pages/articles); unknown keys