@asteby/storefront 0.16.1 → 0.18.0

package/README.md

@@ -408,6 +408,30 @@ a rule that produces a `discard_fields` field. `qr_canonical` (top level) is a t
 (`fiscal_regime`, `invoice_use`). A text that does not match yields `missing` (required fields); only a spec that cannot
 run throws `IdentityRulesError`.
 
+## Buyer items: «My items» / «My garage» (Storefront API 1.9)
+
+A **subject** is something the buyer shops for: a vehicle, a printer, a phone, a pet, a size. WHICH kinds a store has is data the organization publishes (`content.subjectKinds()`); the SDK names none. A store that declares none (`customer.capabilities().subjects` absent, `subjectKinds()` empty) has no such section: show nothing.
+
+```ts
+const kinds = await sf.content.subjectKinds()                         // [] when the store declares none (or the server is older)
+const me = sf.withCustomerToken(token)
+const item = await me.customer.subjects.create({ kind: 'vehicle', attributes: { make: 'nissan', model: 'np300', year: 2012, engine: '2.5', plate: 'ABC-123' } })
+item.label    // 'Nissan NP300 Frontier 2012 2.5 L'  (built by the server from the catalog and the PUBLIC values)
+item.fit_key  // 'nissan/np300/2012/2.5'             (the `fit:<key>` tag of the products; '' if it does not resolve completely)
+item.attributes.plate // '••23'                       (a `private` field is returned masked, always)
+
+// Only the parts that fit: its own tag plus the universal one.
+await sf.products.list({ tags_any: fitTagsAny(item.fit_key) })        // ?tags_any=fit:nissan/np300/2012/2.5,fit:universal
+```
+
+- `customer.subjects.list({ kind? })`, `create`, `update(id, patch)` (attributes merge; `null` clears a field; a private value sent back as its mask is kept), `delete(id)`. Errors: `422` with `field: 'attributes.<field>'` (never the value), `409` repeated or past the limit, `429` too many saves, `404` for an item that is not the buyer's.
+- **Privacy**: a `private` field (a licence plate) is stored for the buyer and never enters the label, the key, a filter, a cache key, a cookie or an order. Never prefill it from the server (it only comes masked, `isMasked`), never log it, never put it in a URL.
+- Pure helpers (`@asteby/storefront`), no UI: `subjectOptions(kind, field, values)` (the cascade), `reconcileSubjectValues`, `resolveSubject(kind, values)` (the same validation as the server, so the form answers without a round trip; the server stays the authority), `fitTagsAny`, `fitTag`, `isMasked`.
+- `splitSubjectTree(tree, maxBytes?)`: a catalog larger than one page (a page is one 64 KiB write with the draft and the published copy, ~28 KB of tree) is published as several `subject_catalog` pages, split by its first level; the kind names them all (`catalog_ref: ["page:x-1", "page:x-2"]`) and the server joins them.
+- Catalog: the levels of the tree follow the kind's `catalog` fields that are not years; an option may declare `from`/`to`/`ranges` (model years) and a `year` field must satisfy every option on the chosen path. A year chosen before an engine narrows the engines; an engine never narrows the year.
+- `products.list({ tags_any })`: at most 5 tags of 120 characters, comma-separated on the wire (a tag with a comma is refused by the client); a hard filter, so facets count inside it.
+- Mock: `createMockStorefront({ subjectKinds: MOCK_SUBJECT_KINDS })` serves the kinds and the whole CRUD with the same rules (default: none, like a store that declares nothing).
+
 ## Buyer account: orders, shipments, invoices (Storefront API 1.8)
 
 `customer.order(id)` carries `progress` (unified timeline), `next_action`, `shipments[]` (events, carrier, `https`

package/dist/{types-DSHzYSHU.d.ts → account-settings-Cw3PamUA.d.ts}

@@ -375,6 +375,10 @@ type DeliveryOptions = {
     /** `true` when some provider failed: `rates` holds only what arrived. */
     partial?: boolean;
     unavailable?: UnavailableRateProvider[];
+    /** The shop's own fixed price: no carrier was asked (addon setting `shipping_quote_mode`). */
+    fixed?: boolean;
+    /** Every shipping rate costs 0 (free-shipping minimum reached): nothing to choose, show "Free shipping" and go on. */
+    free?: boolean;
 };
 /** One way to pay (`GET /storefront/carts/:id/payment-methods`). `key` is sent as `payment_method` at checkout. */
 type PaymentMethod = {
@@ -494,6 +498,10 @@ type Customer = {
     /** Saved fiscal data; `null`/absent when none. */
     fiscal?: FiscalIdentity | null;
     created_at: string;
+    /** Preferred language, one of the store's (contract 1.9). Absent on older servers. */
+    locale?: string | null;
+    /** Notification preferences (contract 1.9). Absent on older servers. */
+    preferences?: CustomerPreferences;
 };
 type CustomerIdentifier = {
     email: string;
@@ -531,6 +539,22 @@ type CustomerCapabilities = {
     fiscal_profiles?: {
         max: number;
     };
+    /**
+     * The kinds of saved item the store declares («My items»; contract 1.9). Absent when the store declares none (or on
+     * older servers): there is no such section, show nothing.
+     */
+    subjects?: {
+        kinds: string[];
+        share_with_workshop?: boolean;
+    };
+    /** Channels the notification preferences can use (connector installed). Absent on older servers: no preferences section. */
+    notifications?: {
+        channels: string[];
+    };
+    /** The buyer can download their data (`customer.exportData`). Absent on older servers. */
+    data_export?: boolean;
+    /** The buyer can delete their account (`customer.deleteAccount`). Absent on older servers. */
+    account_delete?: boolean;
 };
 /** `GET {gateway}/_token`: what the token in use is and what it can do. Needs no scope. */
 type TokenIntrospection = {
@@ -1379,12 +1403,101 @@ type FiscalProfileInput = Partial<FiscalIdentityInput> & {
     label?: string;
     is_default?: boolean;
 };
+/**
+ * A subject is something the buyer shops for: a vehicle, a printer, a phone, a pet, a size. WHICH kinds exist is
+ * data the organization publishes (`content.subjectKinds()`); nothing in the SDK or the contract names one. A store
+ * with no kinds has no such section.
+ */
+type SubjectFieldType = 'text' | 'year' | 'select';
+type SubjectField = {
+    key: string;
+    label: string;
+    type: SubjectFieldType;
+    /** `catalog`: the value is an option of the kind's catalog (a `year` is checked against the options' years). Default `free`. */
+    source?: 'catalog' | 'free';
+    /** The field whose choice narrows this one (the cascade order). */
+    depends_on?: string | null;
+    required?: boolean;
+    /**
+     * Stored for the buyer and NEVER part of the label, the compatibility key, a filter, a cache key, a cookie or an
+     * order (a licence plate). The server returns it only masked (`••34`): never prefill it, never log it.
+     */
+    private?: boolean;
+    max?: number;
+};
+/**
+ * One option of a catalog level (make, model, engine…). `from`/`to`/`ranges` bound the model years it covers: a
+ * `year` field must satisfy every option on the chosen path that declares them.
+ */
+type SubjectCatalogNode = {
+    label: string;
+    from?: number;
+    to?: number;
+    ranges?: [number, number][];
+    children?: Record<string, SubjectCatalogNode>;
+};
+/** The cascade of options of a kind: levels follow the kind's `catalog` fields that are not years. */
+type SubjectCatalog = {
+    version?: string | null;
+    tree: Record<string, SubjectCatalogNode>;
+};
+type SubjectKind = {
+    key: string;
+    /** Singular («Vehicle»). */
+    label: string;
+    /** The section's name («My garage»). */
+    label_plural: string;
+    max_per_account: number;
+    fields: SubjectField[];
+    /** Template of the compatibility key with the fields in braces (public ones only). */
+    fit_key_template: string;
+    /** The checkout may ask «which one is this order for?». */
+    attach_to_order?: boolean;
+    /** `null` for kinds with free fields only. */
+    catalog?: SubjectCatalog | null;
+};
+/** A saved item. `attributes` holds the public values; private ones come masked (`••34`). */
+type Subject = {
+    id: string;
+    kind: string;
+    /** Public label built by the server from the catalog and the public values. */
+    label: string;
+    nickname?: string | null;
+    /** Compatibility key (the `fit:<key>` tag of the products); `''` when the item does not resolve completely. */
+    fit_key: string;
+    attributes: Record<string, unknown>;
+    /** The active item of its kind. */
+    is_default: boolean;
+    last_used_at?: string | null;
+    created_at: string;
+};
+type SubjectInput = {
+    kind: string;
+    attributes: Record<string, unknown>;
+    nickname?: string | null;
+    is_default?: boolean;
+};
+/** Merged over the stored item: `null` clears a field; a private value sent back as its mask is kept. */
+type SubjectPatch = {
+    attributes?: Record<string, unknown>;
+    nickname?: string | null;
+    is_default?: boolean;
+};
+/** The item an order is for (kinds with `attach_to_order`). */
+type SubjectRef = {
+    kind: string;
+    id: 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;
+    /** One of the store's languages (`400` with `field: 'locale'` otherwise); `null` clears it. */
+    locale?: string | null;
+    /** Merged by event and channel; `null` restores the defaults. `400` for an event that cannot be turned off. */
+    preferences?: CustomerPreferences | null;
 };
 /** Post-processing: the value must match `pattern`; `group` of it replaces the value. */
 type IdentityCapture = {
@@ -1448,4 +1561,131 @@ type IdentityRulesV1 = {
     fields: IdentityFieldRule[];
 };
 
-export type { IdentityCapture 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, FiscalProfile as X, FiscalProfileInput as Y, FiscalVerification as Z, GeoHint as _, AddressInput as a, ProductOption as a$, IdentityDocumentSpec as a0, IdentityFieldRule as a1, IdentityRulesV1 as a2, IdentityStrategy as a3, Image as a4, InsufficientStockDetails as a5, InsufficientStockLine as a6, InvoiceAction as a7, InvoiceDoc as a8, InvoiceFile as a9, OrderStepKey as aA, OrderStepState as aB, Page as aC, PageInfo as aD, PaymentAction as aE, PaymentAttemptResult as aF, PaymentAttemptStatus as aG, PaymentClient as aH, PaymentClientCsp as aI, PaymentConfig as aJ, PaymentFlow as aK, PaymentInfo as aL, PaymentMethod as aM, PaymentMethods as aN, PaymentNextStep as aO, PaymentOption as aP, PaymentOptionKey as aQ, PaymentPoint as aR, PaymentSubmitInput as aS, PaymentVoucher as aT, PendingPayment as aU, PendingPaymentVoucher as aV, PickupOption as aW, Product as aX, ProductAttributeValue as aY, ProductCategory as aZ, ProductConnection as a_, InvoiceFileKind as aa, InvoiceRequest as ab, InvoiceResult as ac, InvoiceStage as ad, InvoiceSummary as ae, InvoicingCapabilities as af, Location as ag, LocationContacts as ah, LocationKind as ai, LocationListParams as aj, LocationPickup as ak, Menu as al, MenuItem as am, Money as an, MoneyRange as ao, NearestLocation as ap, NextAction as aq, NextActionKind as ar, Order as as, OrderLine as at, OrderPickup as au, OrderProblem as av, OrderProgress as aw, OrderProgressStep as ax, OrderSection as ay, OrderStage as az, Article as b, ProductSort as b0, ProductVariant as b1, PromotionAnnouncement as b2, PromotionReward as b3, PromotionTier as b4, PromotionsList as b5, RecommendationPlacement as b6, Refund as b7, Region as b8, RegionFiscalEntry as b9, UnavailableRateProvider as bA, RegionFiscalId as ba, RegionPaymentMethod as bb, RegionPostalCode as bc, RestockSubscriptionInput as bd, RestockSubscriptionResult as be, ReturnRequest as bf, ReturnRequestInput as bg, SEO as bh, Section as bi, SelectedOption as bj, Shipment as bk, ShipmentEvent as bl, ShipmentKind as bm, ShipmentMap as bn, ShipmentStatus as bo, ShipmentsSummary as bp, ShippingRate as bq, Shop as br, ShopBranch as bs, ShopContact as bt, ShopPolicies as bu, StockLevel as bv, StorefrontErrorBody as bw, StorefrontErrorCode as bx, Theme as by, TokenIntrospection as bz, 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 };
+type StorefrontErrorInit = {
+    status: number;
+    code: StorefrontErrorCode;
+    message: string;
+    field?: string;
+    /** Raw `error.details` from the body (untrusted shape). */
+    details?: unknown;
+    /** Request URL that failed (without credentials). */
+    url?: string;
+    cause?: unknown;
+    /** Scopes named by the gateway on a `403 insufficient_scope`. */
+    requiredScopes?: string[];
+    /** `error.retryable` as OPS declared it (payment failures). `undefined` = OPS did not say. */
+    retryable?: boolean;
+    /** `error.retry_after` in seconds. */
+    retryAfter?: number;
+    /** `error.checkout_id`: the checkout a refused cart write can resume. */
+    checkoutId?: string;
+    /** `error.cost` of a `price_mismatch` (the cart's current cost; untrusted shape). */
+    cost?: unknown;
+    /** `error.message_en`. */
+    messageEn?: string;
+};
+/**
+ * Error thrown by the client for any non-2xx response, network failure,
+ * timeout or abort. `status` is `0` when no HTTP response was received.
+ */
+declare class StorefrontError extends Error {
+    readonly name = "StorefrontError";
+    readonly status: number;
+    readonly code: StorefrontErrorCode;
+    readonly field: string | undefined;
+    readonly details: unknown;
+    readonly url: string | undefined;
+    /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
+    readonly requiredScopes: string[];
+    /** `true`: repeating the request (same idempotency key) can succeed. `false`: not until someone fixes something. `undefined`: OPS did not say. */
+    readonly retryable: boolean | undefined;
+    /** Seconds OPS asks to wait before retrying. */
+    readonly retryAfter: number | undefined;
+    /** Checkout that a refused cart write can resume. */
+    readonly checkoutId: string | undefined;
+    /** Current cart cost sent with a `price_mismatch` (untrusted shape). */
+    readonly cost: unknown;
+    /** English version of `message`, when OPS sent one. */
+    readonly messageEn: string | undefined;
+    constructor(init: StorefrontErrorInit);
+    /**
+     * Affected lines of a `409 insufficient_stock` (empty for any other error or a
+     * server older than contract 1.1). The cart is untouched: show the lines and
+     * let the buyer adjust or remove them.
+     */
+    get stockLines(): InsufficientStockLine[];
+    toJSON(): {
+        checkoutId?: string | undefined;
+        retryAfter?: number | undefined;
+        retryable?: boolean | undefined;
+        requiredScopes?: string[] | undefined;
+        name: string;
+        status: number;
+        code: StorefrontErrorCode;
+        message: string;
+        field: string | undefined;
+    };
+}
+declare function isStorefrontError(err: unknown): err is StorefrontError;
+
+/**
+ * Account settings of the buyer (contract 1.9): active sessions, recent re-authentication, language and
+ * notification preferences, data export and account deletion. Types and small pure helpers; the calls live on
+ * `client.customer`.
+ */
+/** Notification preferences: event → channel → on. Only optional events can be configured (never the order confirmation or the invoice). */
+type CustomerPreferences = {
+    notifications?: Record<string, Record<string, boolean>>;
+};
+/** One session of the buyer for a «Devices» list. The server never sends an address or a token. */
+type CustomerSessionInfo = {
+    id: string;
+    /** `true` for the session that made the request. */
+    current: boolean;
+    /** A summary such as «Chrome · Windows». Never a full user agent. */
+    device_label: string;
+    login_method: 'email' | 'phone' | 'password' | (string & {});
+    last_used_at?: string | null;
+    created_at: string;
+};
+/** What proves the buyer is who they say: the password, or a sign-in code requested with `customer.requestOtp`. Exactly one. */
+type ReauthInput = {
+    password: string;
+    otp_code?: never;
+} | {
+    otp_code: string;
+    password?: never;
+};
+type ReauthResult = {
+    reauth_at: string;
+    /** How long the confirmation lasts (seconds). It applies to the session that made the call, nowhere else. */
+    valid_for_seconds?: number;
+};
+/** The buyer's data as a JSON file, in memory. `content_base64` is the file; serve it as a download and do not keep it. */
+type DataExportFile = {
+    filename: string;
+    content_type: string;
+    content_base64: string;
+};
+/** `DELETE /customer`. `confirm` is the text your interface asked the buyer to type. */
+type AccountDeleteInput = {
+    confirm: string;
+};
+/**
+ * `true` when a call was refused because the buyer must confirm their password or a code first
+ * (`403` with code `reauth_required`): show your confirmation step, call `customer.reauth`, and repeat the call.
+ */
+declare function isReauthRequired(error: unknown): error is StorefrontError;
+/**
+ * `true` when deleting the account was refused because an order is on its way or a payment is still pending
+ * (`409`; `field` says which: `orders` or `pending_payments`).
+ */
+declare function isAccountDeleteBlocked(error: unknown): error is StorefrontError & {
+    field: 'orders' | 'pending_payments';
+};
+/** Decodes `content_base64` of a data export. Throws `TypeError` when it is not valid base64. */
+declare function dataExportBytes(file: Pick<DataExportFile, 'content_base64'>): Uint8Array;
+/** A download filename that is safe in a `Content-Disposition` header: no path, quotes, control characters or spaces. */
+declare function safeExportFilename(name: unknown, fallback?: string): string;
+
+export { type FiscalProfile as $, type AccountDeleteInput as A, type Customer as B, type Cart as C, type CustomerCapabilities as D, type CustomerIdentifier as E, type CustomerPasswordLoginInput as F, type CustomerPreferences as G, type CustomerRegisterInput as H, type CustomerRegisterResult as I, type CustomerResetPasswordInput as J, type CustomerSession as K, type CustomerSessionInfo as L, type CustomerSessionInput as M, type CustomerSetPasswordInput as N, type CustomerUpdateInput as O, type CustomerVerifyRegistrationInput as P, type DataExportFile as Q, type DeclineCode as R, type DeliveryInput as S, type DeliveryMethod as T, type DeliveryOptions as U, type Facet as V, type FacetValue as W, type FiscalDocumentEvidence as X, type FiscalDocumentSource as Y, type FiscalIdentity as Z, type FiscalIdentityInput as _, type Address as a, type Product as a$, type FiscalProfileInput as a0, type FiscalVerification as a1, type GeoHint as a2, type IdentityCapture as a3, type IdentityDocumentSpec as a4, type IdentityFieldRule as a5, type IdentityRulesV1 as a6, type IdentityStrategy as a7, type Image as a8, type InsufficientStockDetails as a9, type OrderProgress as aA, type OrderProgressStep as aB, type OrderSection as aC, type OrderStage as aD, type OrderStepKey as aE, type OrderStepState as aF, type Page as aG, type PageInfo as aH, type PaymentAction as aI, type PaymentAttemptResult as aJ, type PaymentAttemptStatus as aK, type PaymentClient as aL, type PaymentClientCsp as aM, type PaymentConfig as aN, type PaymentFlow as aO, type PaymentInfo as aP, type PaymentMethod as aQ, type PaymentMethods as aR, type PaymentNextStep as aS, type PaymentOption as aT, type PaymentOptionKey as aU, type PaymentPoint as aV, type PaymentSubmitInput as aW, type PaymentVoucher as aX, type PendingPayment as aY, type PendingPaymentVoucher as aZ, type PickupOption as a_, type InsufficientStockLine as aa, type InvoiceAction as ab, type InvoiceDoc as ac, type InvoiceFile as ad, type InvoiceFileKind as ae, type InvoiceRequest as af, type InvoiceResult as ag, type InvoiceStage as ah, type InvoiceSummary as ai, type InvoicingCapabilities as aj, type Location as ak, type LocationContacts as al, type LocationKind as am, type LocationListParams as an, type LocationPickup as ao, type Menu as ap, type MenuItem as aq, type Money as ar, type MoneyRange as as, type NearestLocation as at, type NextAction as au, type NextActionKind as av, type Order as aw, type OrderLine as ax, type OrderPickup as ay, type OrderProblem as az, type AddressInput as b, type ProductAttributeValue as b0, type ProductCategory as b1, type ProductConnection as b2, type ProductOption as b3, type ProductSort as b4, type ProductVariant as b5, type PromotionAnnouncement as b6, type PromotionReward as b7, type PromotionTier as b8, type PromotionsList as b9, type ShopPolicies as bA, type StockLevel as bB, StorefrontError as bC, type StorefrontErrorBody as bD, type StorefrontErrorCode as bE, type StorefrontErrorInit as bF, type Subject as bG, type SubjectCatalog as bH, type SubjectCatalogNode as bI, type SubjectField as bJ, type SubjectFieldType as bK, type SubjectInput as bL, type SubjectKind as bM, type SubjectPatch as bN, type SubjectRef as bO, type Theme as bP, type TokenIntrospection as bQ, type UnavailableRateProvider as bR, dataExportBytes as bS, isAccountDeleteBlocked as bT, isReauthRequired as bU, isStorefrontError as bV, safeExportFilename as bW, type ReauthInput as ba, type ReauthResult as bb, type RecommendationPlacement as bc, type Refund as bd, type Region as be, type RegionFiscalEntry as bf, type RegionFiscalId as bg, type RegionPaymentMethod as bh, type RegionPostalCode as bi, type RestockSubscriptionInput as bj, type RestockSubscriptionResult as bk, type ReturnRequest as bl, type ReturnRequestInput as bm, type SEO as bn, type Section as bo, type SelectedOption as bp, type Shipment as bq, type ShipmentEvent as br, type ShipmentKind as bs, type ShipmentMap as bt, type ShipmentStatus as bu, type ShipmentsSummary as bv, type ShippingRate as bw, type Shop as bx, type ShopBranch as by, type ShopContact as bz, type Article as c, type Availability as d, type AvailabilityStatus as e, type CartBuyer as f, type CartBuyerInput as g, type CartCost as h, type CartDelivery as i, type CartDiscountCode as j, type CartDiscountLine as k, type CartInvoice as l, type CartLine as m, type CartLineInput as n, type CartLineMerchandise as o, type CartLineProblem as p, type CartLineUpdateInput as q, type CartPromotions as r, type CartRecommendation as s, type CartRecommendations as t, type CheckoutInfo as u, type CheckoutInput as v, type CheckoutPayment as w, type CheckoutResult as x, type Collection as y, type Connection as z };

package/dist/{types-C5nEQicj.d.cts → account-settings-DAzmXHIn.d.cts}

@@ -375,6 +375,10 @@ type DeliveryOptions = {
     /** `true` when some provider failed: `rates` holds only what arrived. */
     partial?: boolean;
     unavailable?: UnavailableRateProvider[];
+    /** The shop's own fixed price: no carrier was asked (addon setting `shipping_quote_mode`). */
+    fixed?: boolean;
+    /** Every shipping rate costs 0 (free-shipping minimum reached): nothing to choose, show "Free shipping" and go on. */
+    free?: boolean;
 };
 /** One way to pay (`GET /storefront/carts/:id/payment-methods`). `key` is sent as `payment_method` at checkout. */
 type PaymentMethod = {
@@ -494,6 +498,10 @@ type Customer = {
     /** Saved fiscal data; `null`/absent when none. */
     fiscal?: FiscalIdentity | null;
     created_at: string;
+    /** Preferred language, one of the store's (contract 1.9). Absent on older servers. */
+    locale?: string | null;
+    /** Notification preferences (contract 1.9). Absent on older servers. */
+    preferences?: CustomerPreferences;
 };
 type CustomerIdentifier = {
     email: string;
@@ -531,6 +539,22 @@ type CustomerCapabilities = {
     fiscal_profiles?: {
         max: number;
     };
+    /**
+     * The kinds of saved item the store declares («My items»; contract 1.9). Absent when the store declares none (or on
+     * older servers): there is no such section, show nothing.
+     */
+    subjects?: {
+        kinds: string[];
+        share_with_workshop?: boolean;
+    };
+    /** Channels the notification preferences can use (connector installed). Absent on older servers: no preferences section. */
+    notifications?: {
+        channels: string[];
+    };
+    /** The buyer can download their data (`customer.exportData`). Absent on older servers. */
+    data_export?: boolean;
+    /** The buyer can delete their account (`customer.deleteAccount`). Absent on older servers. */
+    account_delete?: boolean;
 };
 /** `GET {gateway}/_token`: what the token in use is and what it can do. Needs no scope. */
 type TokenIntrospection = {
@@ -1379,12 +1403,101 @@ type FiscalProfileInput = Partial<FiscalIdentityInput> & {
     label?: string;
     is_default?: boolean;
 };
+/**
+ * A subject is something the buyer shops for: a vehicle, a printer, a phone, a pet, a size. WHICH kinds exist is
+ * data the organization publishes (`content.subjectKinds()`); nothing in the SDK or the contract names one. A store
+ * with no kinds has no such section.
+ */
+type SubjectFieldType = 'text' | 'year' | 'select';
+type SubjectField = {
+    key: string;
+    label: string;
+    type: SubjectFieldType;
+    /** `catalog`: the value is an option of the kind's catalog (a `year` is checked against the options' years). Default `free`. */
+    source?: 'catalog' | 'free';
+    /** The field whose choice narrows this one (the cascade order). */
+    depends_on?: string | null;
+    required?: boolean;
+    /**
+     * Stored for the buyer and NEVER part of the label, the compatibility key, a filter, a cache key, a cookie or an
+     * order (a licence plate). The server returns it only masked (`••34`): never prefill it, never log it.
+     */
+    private?: boolean;
+    max?: number;
+};
+/**
+ * One option of a catalog level (make, model, engine…). `from`/`to`/`ranges` bound the model years it covers: a
+ * `year` field must satisfy every option on the chosen path that declares them.
+ */
+type SubjectCatalogNode = {
+    label: string;
+    from?: number;
+    to?: number;
+    ranges?: [number, number][];
+    children?: Record<string, SubjectCatalogNode>;
+};
+/** The cascade of options of a kind: levels follow the kind's `catalog` fields that are not years. */
+type SubjectCatalog = {
+    version?: string | null;
+    tree: Record<string, SubjectCatalogNode>;
+};
+type SubjectKind = {
+    key: string;
+    /** Singular («Vehicle»). */
+    label: string;
+    /** The section's name («My garage»). */
+    label_plural: string;
+    max_per_account: number;
+    fields: SubjectField[];
+    /** Template of the compatibility key with the fields in braces (public ones only). */
+    fit_key_template: string;
+    /** The checkout may ask «which one is this order for?». */
+    attach_to_order?: boolean;
+    /** `null` for kinds with free fields only. */
+    catalog?: SubjectCatalog | null;
+};
+/** A saved item. `attributes` holds the public values; private ones come masked (`••34`). */
+type Subject = {
+    id: string;
+    kind: string;
+    /** Public label built by the server from the catalog and the public values. */
+    label: string;
+    nickname?: string | null;
+    /** Compatibility key (the `fit:<key>` tag of the products); `''` when the item does not resolve completely. */
+    fit_key: string;
+    attributes: Record<string, unknown>;
+    /** The active item of its kind. */
+    is_default: boolean;
+    last_used_at?: string | null;
+    created_at: string;
+};
+type SubjectInput = {
+    kind: string;
+    attributes: Record<string, unknown>;
+    nickname?: string | null;
+    is_default?: boolean;
+};
+/** Merged over the stored item: `null` clears a field; a private value sent back as its mask is kept. */
+type SubjectPatch = {
+    attributes?: Record<string, unknown>;
+    nickname?: string | null;
+    is_default?: boolean;
+};
+/** The item an order is for (kinds with `attach_to_order`). */
+type SubjectRef = {
+    kind: string;
+    id: 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;
+    /** One of the store's languages (`400` with `field: 'locale'` otherwise); `null` clears it. */
+    locale?: string | null;
+    /** Merged by event and channel; `null` restores the defaults. `400` for an event that cannot be turned off. */
+    preferences?: CustomerPreferences | null;
 };
 /** Post-processing: the value must match `pattern`; `group` of it replaces the value. */
 type IdentityCapture = {
@@ -1448,4 +1561,131 @@ type IdentityRulesV1 = {
     fields: IdentityFieldRule[];
 };
 
-export type { IdentityCapture 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, FiscalProfile as X, FiscalProfileInput as Y, FiscalVerification as Z, GeoHint as _, AddressInput as a, ProductOption as a$, IdentityDocumentSpec as a0, IdentityFieldRule as a1, IdentityRulesV1 as a2, IdentityStrategy as a3, Image as a4, InsufficientStockDetails as a5, InsufficientStockLine as a6, InvoiceAction as a7, InvoiceDoc as a8, InvoiceFile as a9, OrderStepKey as aA, OrderStepState as aB, Page as aC, PageInfo as aD, PaymentAction as aE, PaymentAttemptResult as aF, PaymentAttemptStatus as aG, PaymentClient as aH, PaymentClientCsp as aI, PaymentConfig as aJ, PaymentFlow as aK, PaymentInfo as aL, PaymentMethod as aM, PaymentMethods as aN, PaymentNextStep as aO, PaymentOption as aP, PaymentOptionKey as aQ, PaymentPoint as aR, PaymentSubmitInput as aS, PaymentVoucher as aT, PendingPayment as aU, PendingPaymentVoucher as aV, PickupOption as aW, Product as aX, ProductAttributeValue as aY, ProductCategory as aZ, ProductConnection as a_, InvoiceFileKind as aa, InvoiceRequest as ab, InvoiceResult as ac, InvoiceStage as ad, InvoiceSummary as ae, InvoicingCapabilities as af, Location as ag, LocationContacts as ah, LocationKind as ai, LocationListParams as aj, LocationPickup as ak, Menu as al, MenuItem as am, Money as an, MoneyRange as ao, NearestLocation as ap, NextAction as aq, NextActionKind as ar, Order as as, OrderLine as at, OrderPickup as au, OrderProblem as av, OrderProgress as aw, OrderProgressStep as ax, OrderSection as ay, OrderStage as az, Article as b, ProductSort as b0, ProductVariant as b1, PromotionAnnouncement as b2, PromotionReward as b3, PromotionTier as b4, PromotionsList as b5, RecommendationPlacement as b6, Refund as b7, Region as b8, RegionFiscalEntry as b9, UnavailableRateProvider as bA, RegionFiscalId as ba, RegionPaymentMethod as bb, RegionPostalCode as bc, RestockSubscriptionInput as bd, RestockSubscriptionResult as be, ReturnRequest as bf, ReturnRequestInput as bg, SEO as bh, Section as bi, SelectedOption as bj, Shipment as bk, ShipmentEvent as bl, ShipmentKind as bm, ShipmentMap as bn, ShipmentStatus as bo, ShipmentsSummary as bp, ShippingRate as bq, Shop as br, ShopBranch as bs, ShopContact as bt, ShopPolicies as bu, StockLevel as bv, StorefrontErrorBody as bw, StorefrontErrorCode as bx, Theme as by, TokenIntrospection as bz, 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 };
+type StorefrontErrorInit = {
+    status: number;
+    code: StorefrontErrorCode;
+    message: string;
+    field?: string;
+    /** Raw `error.details` from the body (untrusted shape). */
+    details?: unknown;
+    /** Request URL that failed (without credentials). */
+    url?: string;
+    cause?: unknown;
+    /** Scopes named by the gateway on a `403 insufficient_scope`. */
+    requiredScopes?: string[];
+    /** `error.retryable` as OPS declared it (payment failures). `undefined` = OPS did not say. */
+    retryable?: boolean;
+    /** `error.retry_after` in seconds. */
+    retryAfter?: number;
+    /** `error.checkout_id`: the checkout a refused cart write can resume. */
+    checkoutId?: string;
+    /** `error.cost` of a `price_mismatch` (the cart's current cost; untrusted shape). */
+    cost?: unknown;
+    /** `error.message_en`. */
+    messageEn?: string;
+};
+/**
+ * Error thrown by the client for any non-2xx response, network failure,
+ * timeout or abort. `status` is `0` when no HTTP response was received.
+ */
+declare class StorefrontError extends Error {
+    readonly name = "StorefrontError";
+    readonly status: number;
+    readonly code: StorefrontErrorCode;
+    readonly field: string | undefined;
+    readonly details: unknown;
+    readonly url: string | undefined;
+    /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
+    readonly requiredScopes: string[];
+    /** `true`: repeating the request (same idempotency key) can succeed. `false`: not until someone fixes something. `undefined`: OPS did not say. */
+    readonly retryable: boolean | undefined;
+    /** Seconds OPS asks to wait before retrying. */
+    readonly retryAfter: number | undefined;
+    /** Checkout that a refused cart write can resume. */
+    readonly checkoutId: string | undefined;
+    /** Current cart cost sent with a `price_mismatch` (untrusted shape). */
+    readonly cost: unknown;
+    /** English version of `message`, when OPS sent one. */
+    readonly messageEn: string | undefined;
+    constructor(init: StorefrontErrorInit);
+    /**
+     * Affected lines of a `409 insufficient_stock` (empty for any other error or a
+     * server older than contract 1.1). The cart is untouched: show the lines and
+     * let the buyer adjust or remove them.
+     */
+    get stockLines(): InsufficientStockLine[];
+    toJSON(): {
+        checkoutId?: string | undefined;
+        retryAfter?: number | undefined;
+        retryable?: boolean | undefined;
+        requiredScopes?: string[] | undefined;
+        name: string;
+        status: number;
+        code: StorefrontErrorCode;
+        message: string;
+        field: string | undefined;
+    };
+}
+declare function isStorefrontError(err: unknown): err is StorefrontError;
+
+/**
+ * Account settings of the buyer (contract 1.9): active sessions, recent re-authentication, language and
+ * notification preferences, data export and account deletion. Types and small pure helpers; the calls live on
+ * `client.customer`.
+ */
+/** Notification preferences: event → channel → on. Only optional events can be configured (never the order confirmation or the invoice). */
+type CustomerPreferences = {
+    notifications?: Record<string, Record<string, boolean>>;
+};
+/** One session of the buyer for a «Devices» list. The server never sends an address or a token. */
+type CustomerSessionInfo = {
+    id: string;
+    /** `true` for the session that made the request. */
+    current: boolean;
+    /** A summary such as «Chrome · Windows». Never a full user agent. */
+    device_label: string;
+    login_method: 'email' | 'phone' | 'password' | (string & {});
+    last_used_at?: string | null;
+    created_at: string;
+};
+/** What proves the buyer is who they say: the password, or a sign-in code requested with `customer.requestOtp`. Exactly one. */
+type ReauthInput = {
+    password: string;
+    otp_code?: never;
+} | {
+    otp_code: string;
+    password?: never;
+};
+type ReauthResult = {
+    reauth_at: string;
+    /** How long the confirmation lasts (seconds). It applies to the session that made the call, nowhere else. */
+    valid_for_seconds?: number;
+};
+/** The buyer's data as a JSON file, in memory. `content_base64` is the file; serve it as a download and do not keep it. */
+type DataExportFile = {
+    filename: string;
+    content_type: string;
+    content_base64: string;
+};
+/** `DELETE /customer`. `confirm` is the text your interface asked the buyer to type. */
+type AccountDeleteInput = {
+    confirm: string;
+};
+/**
+ * `true` when a call was refused because the buyer must confirm their password or a code first
+ * (`403` with code `reauth_required`): show your confirmation step, call `customer.reauth`, and repeat the call.
+ */
+declare function isReauthRequired(error: unknown): error is StorefrontError;
+/**
+ * `true` when deleting the account was refused because an order is on its way or a payment is still pending
+ * (`409`; `field` says which: `orders` or `pending_payments`).
+ */
+declare function isAccountDeleteBlocked(error: unknown): error is StorefrontError & {
+    field: 'orders' | 'pending_payments';
+};
+/** Decodes `content_base64` of a data export. Throws `TypeError` when it is not valid base64. */
+declare function dataExportBytes(file: Pick<DataExportFile, 'content_base64'>): Uint8Array;
+/** A download filename that is safe in a `Content-Disposition` header: no path, quotes, control characters or spaces. */
+declare function safeExportFilename(name: unknown, fallback?: string): string;
+
+export { type FiscalProfile as $, type AccountDeleteInput as A, type Customer as B, type Cart as C, type CustomerCapabilities as D, type CustomerIdentifier as E, type CustomerPasswordLoginInput as F, type CustomerPreferences as G, type CustomerRegisterInput as H, type CustomerRegisterResult as I, type CustomerResetPasswordInput as J, type CustomerSession as K, type CustomerSessionInfo as L, type CustomerSessionInput as M, type CustomerSetPasswordInput as N, type CustomerUpdateInput as O, type CustomerVerifyRegistrationInput as P, type DataExportFile as Q, type DeclineCode as R, type DeliveryInput as S, type DeliveryMethod as T, type DeliveryOptions as U, type Facet as V, type FacetValue as W, type FiscalDocumentEvidence as X, type FiscalDocumentSource as Y, type FiscalIdentity as Z, type FiscalIdentityInput as _, type Address as a, type Product as a$, type FiscalProfileInput as a0, type FiscalVerification as a1, type GeoHint as a2, type IdentityCapture as a3, type IdentityDocumentSpec as a4, type IdentityFieldRule as a5, type IdentityRulesV1 as a6, type IdentityStrategy as a7, type Image as a8, type InsufficientStockDetails as a9, type OrderProgress as aA, type OrderProgressStep as aB, type OrderSection as aC, type OrderStage as aD, type OrderStepKey as aE, type OrderStepState as aF, type Page as aG, type PageInfo as aH, type PaymentAction as aI, type PaymentAttemptResult as aJ, type PaymentAttemptStatus as aK, type PaymentClient as aL, type PaymentClientCsp as aM, type PaymentConfig as aN, type PaymentFlow as aO, type PaymentInfo as aP, type PaymentMethod as aQ, type PaymentMethods as aR, type PaymentNextStep as aS, type PaymentOption as aT, type PaymentOptionKey as aU, type PaymentPoint as aV, type PaymentSubmitInput as aW, type PaymentVoucher as aX, type PendingPayment as aY, type PendingPaymentVoucher as aZ, type PickupOption as a_, type InsufficientStockLine as aa, type InvoiceAction as ab, type InvoiceDoc as ac, type InvoiceFile as ad, type InvoiceFileKind as ae, type InvoiceRequest as af, type InvoiceResult as ag, type InvoiceStage as ah, type InvoiceSummary as ai, type InvoicingCapabilities as aj, type Location as ak, type LocationContacts as al, type LocationKind as am, type LocationListParams as an, type LocationPickup as ao, type Menu as ap, type MenuItem as aq, type Money as ar, type MoneyRange as as, type NearestLocation as at, type NextAction as au, type NextActionKind as av, type Order as aw, type OrderLine as ax, type OrderPickup as ay, type OrderProblem as az, type AddressInput as b, type ProductAttributeValue as b0, type ProductCategory as b1, type ProductConnection as b2, type ProductOption as b3, type ProductSort as b4, type ProductVariant as b5, type PromotionAnnouncement as b6, type PromotionReward as b7, type PromotionTier as b8, type PromotionsList as b9, type ShopPolicies as bA, type StockLevel as bB, StorefrontError as bC, type StorefrontErrorBody as bD, type StorefrontErrorCode as bE, type StorefrontErrorInit as bF, type Subject as bG, type SubjectCatalog as bH, type SubjectCatalogNode as bI, type SubjectField as bJ, type SubjectFieldType as bK, type SubjectInput as bL, type SubjectKind as bM, type SubjectPatch as bN, type SubjectRef as bO, type Theme as bP, type TokenIntrospection as bQ, type UnavailableRateProvider as bR, dataExportBytes as bS, isAccountDeleteBlocked as bT, isReauthRequired as bU, isStorefrontError as bV, safeExportFilename as bW, type ReauthInput as ba, type ReauthResult as bb, type RecommendationPlacement as bc, type Refund as bd, type Region as be, type RegionFiscalEntry as bf, type RegionFiscalId as bg, type RegionPaymentMethod as bh, type RegionPostalCode as bi, type RestockSubscriptionInput as bj, type RestockSubscriptionResult as bk, type ReturnRequest as bl, type ReturnRequestInput as bm, type SEO as bn, type Section as bo, type SelectedOption as bp, type Shipment as bq, type ShipmentEvent as br, type ShipmentKind as bs, type ShipmentMap as bt, type ShipmentStatus as bu, type ShipmentsSummary as bv, type ShippingRate as bw, type Shop as bx, type ShopBranch as by, type ShopContact as bz, type Article as c, type Availability as d, type AvailabilityStatus as e, type CartBuyer as f, type CartBuyerInput as g, type CartCost as h, type CartDelivery as i, type CartDiscountCode as j, type CartDiscountLine as k, type CartInvoice as l, type CartLine as m, type CartLineInput as n, type CartLineMerchandise as o, type CartLineProblem as p, type CartLineUpdateInput as q, type CartPromotions as r, type CartRecommendation as s, type CartRecommendations as t, type CheckoutInfo as u, type CheckoutInput as v, type CheckoutPayment as w, type CheckoutResult as x, type Collection as y, type Connection as z };