@asteby/storefront 0.10.0 → 0.11.1

package/dist/{types-DdLzlxw4.d.cts → types-bsdlAumU.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 = {
@@ -497,6 +512,25 @@ type CustomerCapabilities = {
     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 & {}) | null;
+    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;
@@ -545,6 +579,8 @@ type Order = {
     created_at: string;
     total: Money;
     lines: OrderLine[];
+    /** Invoice state; absent on older servers. */
+    invoice?: InvoiceSummary;
 };
 type ReturnRequestInput = {
     lines: {
@@ -558,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' }`. */
@@ -602,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;
@@ -620,6 +661,7 @@ type StorefrontErrorBody = {
         message: string;
         field?: string;
         details?: unknown;
+        required_scopes?: string[];
     };
 };
 type RestockSubscriptionInput = {
@@ -871,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 { Menu as $, Address as A, CustomerIdentifier as B, Cart as C, CustomerPasswordLoginInput as D, CustomerRegisterInput as E, CustomerRegisterResult as F, CustomerResetPasswordInput as G, CustomerSession as H, CustomerSessionInput as I, CustomerSetPasswordInput as J, CustomerVerifyRegistrationInput as K, DeclineCode as L, DeliveryInput as M, DeliveryMethod as N, DeliveryOptions as O, Facet as P, FacetValue as Q, Image as R, InsufficientStockDetails as S, InsufficientStockLine as T, InvoiceRequest as U, InvoiceResult as V, Location as W, LocationContacts as X, LocationKind as Y, LocationListParams as Z, LocationPickup as _, AddressInput as a, MenuItem as a0, Money as a1, MoneyRange as a2, NearestLocation as a3, Order as a4, OrderLine as a5, Page as a6, PageInfo as a7, PaymentAction as a8, PaymentAttemptResult as a9, RestockSubscriptionInput as aA, RestockSubscriptionResult as aB, ReturnRequest as aC, ReturnRequestInput as aD, SEO as aE, Section as aF, SelectedOption as aG, ShippingRate as aH, Shop as aI, ShopBranch as aJ, ShopContact as aK, ShopPolicies as aL, StockLevel as aM, StorefrontErrorBody as aN, StorefrontErrorCode as aO, Theme as aP, UnavailableRateProvider as aQ, PaymentAttemptStatus as aa, PaymentClient as ab, PaymentClientCsp as ac, PaymentConfig as ad, PaymentFlow as ae, PaymentMethod as af, PaymentMethods as ag, PaymentNextStep as ah, PaymentOption as ai, PaymentOptionKey as aj, PaymentPoint as ak, PaymentSubmitInput as al, PaymentVoucher as am, PickupOption as an, Product as ao, ProductAttributeValue as ap, ProductCategory as aq, ProductConnection as ar, ProductOption as as, ProductSort as at, ProductVariant as au, PromotionAnnouncement as av, PromotionReward as aw, PromotionTier as ax, PromotionsList as ay, RecommendationPlacement 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, CustomerCapabilities 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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@asteby/storefront",
-  "version": "0.10.0",
-  "description": "Typed client for the Storefront API v1 (catalog, cart, checkout, customer, content) using only global fetch — Node 20+, edge runtimes and browsers — plus an in-memory mock of the whole contract.",
+  "version": "0.11.1",
+  "description": "Typed client for the Storefront API v1 (catalog, cart, checkout, customer, content) using only global fetch — Node 20+, edge runtimes and browsers — plus an in-memory mock of the whole contract and, in `@asteby/storefront/fiscal-document`, a country-agnostic engine that reads a buyer's fiscal document (PDF) in the browser or Node.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -57,6 +57,26 @@
         "default": "./dist/mockup.cjs"
       }
     },
+    "./fiscal-document": {
+      "import": {
+        "types": "./dist/fiscal-document.d.ts",
+        "default": "./dist/fiscal-document.js"
+      },
+      "require": {
+        "types": "./dist/fiscal-document.d.cts",
+        "default": "./dist/fiscal-document.cjs"
+      }
+    },
+    "./node": {
+      "import": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -64,7 +84,22 @@
     "node": ">=20"
   },
   "dependencies": {},
+  "peerDependencies": {
+    "pdfjs-dist": ">=4.2.67",
+    "jsqr": "^1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "pdfjs-dist": {
+      "optional": true
+    },
+    "jsqr": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "jsqr": "^1.4.0",
+    "pdfjs-dist": "^5.7.284",
     "tsup": "^8.3.5",
     "typescript": "^6.0.0",
     "vitest": "^4.0.0"
@@ -72,8 +107,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "storefront": "./dist/cli.js"
+  },
   "scripts": {
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",