@asteby/storefront 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.cjs';
 export { OpenStatus, OpeningHours } from './geo.cjs';
-import { am as ProductSort, aB as Shop, ak as ProductConnection, ah as Product, x as Connection, w as Collection, S as LocationListParams, P as Location, Y as NearestLocation, aF as StockLevel, at as RestockSubscriptionInput, au as RestockSubscriptionResult, l as CartLineInput, C as Cart, o as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, H as DeliveryOptions, a9 as PaymentMethods, F as DeliveryInput, as as RecommendationPlacement, r as CartRecommendations, t as CheckoutInput, v as CheckoutResult, ar as PromotionsList, a6 as PaymentConfig, ae as PaymentSubmitInput, a2 as PaymentAttemptResult, z as CustomerIdentifier, D as CustomerSessionInput, B as CustomerSession, y as Customer, Z as Order, aw as ReturnRequestInput, av as ReturnRequest, N as InvoiceRequest, O as InvoiceResult, A as Address, aI as Theme, $ as Page, U as Menu, b as Article, aH as StorefrontErrorCode, M as InsufficientStockLine, W as Money, d as AvailabilityStatus, n as CartLineProblem, c as Availability, an as ProductVariant, E as DeclineCode, af as PaymentVoucher, aa as PaymentNextStep, p as CartPromotions, ap as PromotionReward, G as DeliveryMethod, aJ as UnavailableRateProvider } from './types-CSMuPSQA.cjs';
-export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartLine, m as CartLineMerchandise, q as CartRecommendation, s as CheckoutInfo, u as CheckoutPayment, I as Facet, J as FacetValue, K as Image, L as InsufficientStockDetails, Q as LocationContacts, R as LocationKind, T as LocationPickup, V as MenuItem, X as MoneyRange, _ as OrderLine, a0 as PageInfo, a1 as PaymentAction, a3 as PaymentAttemptStatus, a4 as PaymentClient, a5 as PaymentClientCsp, a7 as PaymentFlow, a8 as PaymentMethod, ab as PaymentOption, ac as PaymentOptionKey, ad as PaymentPoint, ag as PickupOption, ai as ProductAttributeValue, aj as ProductCategory, al as ProductOption, ao as PromotionAnnouncement, aq as PromotionTier, ax as SEO, ay as Section, az as SelectedOption, aA as ShippingRate, aC as ShopBranch, aD as ShopContact, aE as ShopPolicies, aG as StorefrontErrorBody } from './types-CSMuPSQA.cjs';
+import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-C-Ley-Mt.cjs';
+export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-C-Ley-Mt.cjs';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -67,8 +67,12 @@ type StorefrontResponseContext = StorefrontRequestContext & {
 type StorefrontClientOptions = {
     /** Base URL of the gateway, e.g. `https://ops.example.com/api/gw`. Routes are appended as `/storefront/...`. */
     baseUrl: string;
-    /** `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. */
-    token: string;
+    /**
+     * `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. A function is called on
+     * EVERY request, so a token read from a file (`createFileTokenSource` in `@asteby/storefront/node`) can rotate
+     * without restarting the server.
+     */
+    token: string | (() => string);
     /** Buyer session (`X-Customer-Token`) for `/storefront/customer/*` routes. */
     customerToken?: string | null;
     /** Custom fetch (defaults to `globalThis.fetch`). */
@@ -162,6 +166,13 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         }): Promise<T | null>;
         <T>(spec: RequestSpec): Promise<T>;
     };
+    token: {
+        /**
+         * What the token in use is and can do (`GET {baseUrl}/_token`, a gateway route, not a `/storefront` one).
+         * Needs no scope, so it answers even when the token is under-provisioned: `missing_scopes` says what to repair.
+         */
+        introspect: (options?: RequestOptions) => Promise<TokenIntrospection>;
+    };
     /** Returns a new client that sends the given buyer session token. */
     withCustomerToken(customerToken: string | null): /*elided*/ any;
     /** Returns a new client that reports the shopper's IP (`X-Storefront-Client-IP`) on every call. */
@@ -169,6 +180,12 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
     shop: {
         get: (options?: RequestOptions) => Promise<Shop>;
     };
+    /**
+     * How the market formats, taxes, addresses and invoices (`fiscal_id` carries the tax-id pattern, the regimes,
+     * the invoice uses and the identity documents the buyer can upload). Cacheable; `null` when the organization
+     * has no region configured.
+     */
+    region: (options?: RequestOptions) => Promise<Region | null>;
     products: {
         list: (params?: ProductListParams, options?: RequestOptions) => Promise<ProductConnection>;
         /** `null` when the product does not exist or is unpublished. */
@@ -231,6 +248,13 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         setDelivery: (id: string, delivery: DeliveryInput, options?: WriteOptions) => Promise<Cart>;
         /** Order note (up to 1000 characters). `null` or empty clears it. */
         setNote: (id: string, note: string | null, options?: WriteOptions) => Promise<Cart>;
+        /**
+         * Asks for an invoice for this cart (`null` or `{ requested: false }` withdraws it). The server validates the
+         * data against the region BEFORE any charge: `422` with `field: 'invoice.<field>'` (e.g. `invoice.tax_regime`)
+         * names what to fix. `409 already_checked_out` when the cart is already an order. Checkout uses it when
+         * `CheckoutInput.invoice` is omitted.
+         */
+        setInvoice: (id: string, invoice: InvoiceRequest | null, options?: WriteOptions) => Promise<Cart>;
         /**
          * Cross-sell suggestions: only sellable variants, with `unlocks` when adding one reaches the next
          * discount tier. `first` 1-8 (default 4). `private, no-store`; ask on demand, not on every render.
@@ -270,7 +294,24 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         requestOtp: (identifier: CustomerIdentifier, options?: WriteOptions) => Promise<void>;
         /** Exchanges the code for a buyer session (`token` goes in `customerToken`). */
         createSession: (input: CustomerSessionInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** What the store supports (password login, email verification, OTP channels). Drives which forms to show. */
+        capabilities: (options?: RequestOptions) => Promise<CustomerCapabilities>;
+        /**
+         * Creates an account with email + password. `verification_required` (202): a code was emailed, finish with
+         * `verifyRegistration`. `created` (201): the account exists and `session` is ready. `409` when the email is taken.
+         */
+        register: (input: CustomerRegisterInput, options?: WriteOptions) => Promise<CustomerRegisterResult>;
+        /** Confirms the emailed registration code and returns the new buyer session. */
+        verifyRegistration: (input: CustomerVerifyRegistrationInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** Email + password login. `401` for wrong credentials. */
+        loginWithPassword: (input: CustomerPasswordLoginInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** Sets or changes the password of the signed-in buyer (`options.customerToken`, or a `withCustomerToken` client). */
+        setPassword: (input: CustomerSetPasswordInput, options?: WriteOptions) => Promise<void>;
+        /** Resets a forgotten password with the code from `requestOtp({ email })`. */
+        resetPassword: (input: CustomerResetPasswordInput, options?: WriteOptions) => Promise<void>;
         get: (options?: RequestOptions) => Promise<Customer>;
+        /** Updates the profile and the saved fiscal data; `fiscal: null` deletes the latter. `422` with `field: 'fiscal.<field>'`. */
+        update: (input: CustomerUpdateInput, options?: WriteOptions) => Promise<Customer>;
         orders: (params?: PaginationParams, options?: RequestOptions) => Promise<Connection<Order>>;
         /** `null` when the order does not exist or belongs to someone else. */
         order: (id: string, options?: RequestOptions) => Promise<Order | null>;
@@ -310,6 +351,8 @@ type StorefrontErrorInit = {
     /** Request URL that failed (without credentials). */
     url?: string;
     cause?: unknown;
+    /** Scopes named by the gateway on a `403 insufficient_scope`. */
+    requiredScopes?: string[];
 };
 /**
  * Error thrown by the client for any non-2xx response, network failure,
@@ -322,6 +365,8 @@ declare class StorefrontError extends Error {
     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[];
     constructor(init: StorefrontErrorInit);
     /**
      * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -330,6 +375,7 @@ declare class StorefrontError extends Error {
      */
     get stockLines(): InsufficientStockLine[];
     toJSON(): {
+        requiredScopes?: string[] | undefined;
         name: string;
         status: number;
         code: StorefrontErrorCode;
@@ -339,6 +385,31 @@ declare class StorefrontError extends Error {
 }
 declare function isStorefrontError(err: unknown): err is StorefrontError;
 
+/** `sk_…a91f`: the prefix and the last four characters, never enough to use the token. */
+declare function maskToken(token: string | null | undefined): string;
+type DiagnoseOptions = {
+    /** Where the warning goes (default `console.warn`). Receives ONE line per problem. */
+    log?: (message: string) => void;
+    /** Name of the connection, shown in the repair path. */
+    connectionName?: string;
+    /** Give up after this long (default 3000 ms). */
+    timeoutMs?: number;
+};
+/** Where the operator repairs a connection in OPS (es-MX, as the screen names it). */
+declare function repairPath(connectionName?: string): string;
+/**
+ * Startup check of the store's credential: asks `token.introspect()` and, when scopes are missing, logs ONE clear
+ * warning with the repair path (never the token, only `sk_…a91f`). It NEVER throws and is meant to be fired and
+ * forgotten, so it cannot delay or break the boot:
+ *
+ * ```ts
+ * void diagnose(storefront)
+ * ```
+ *
+ * Resolves with the introspection, or `null` when it could not be obtained (older OPS, outage, bad token).
+ */
+declare function diagnose(client: StorefrontClient, options?: DiagnoseOptions): Promise<TokenIntrospection | null>;
+
 type FormatMoneyOptions = {
     /** Drop `.00` when the amount is a whole number. */
     withoutTrailingZeros?: boolean;
@@ -677,4 +748,4 @@ type DeliveryNotices = {
 /** Splits `delivery.unavailable` into the `missing_weight` notice and the generic one. */
 declare function deliveryNotices(delivery: Pick<DeliveryOptions, 'unavailable' | 'partial'> | null | undefined): DeliveryNotices;
 
-export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, COUNTRY_HEADERS, Cart, CartBuyerInput, CartLineInput, CartLineProblem, type CartLineProblemView, CartLineUpdateInput, CartPromotions, CartRecommendations, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorKind, type PaymentErrorView, type PaymentLocale, type PaymentMessageKey, type PaymentMessages, PaymentMethods, PaymentNextStep, type PaymentOutcome, type PaymentOutcomeKind, PaymentSubmitInput, PaymentVoucher, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, ProductVariant, type PromoProgressView, type PromotionLocale, type PromotionMessageKey, type PromotionMessages, PromotionReward, PromotionsList, type QueryParams, type QueryValue, RecommendationPlacement, type RequestOptions, type ResolveAvailabilityOptions, RestockSubscriptionInput, RestockSubscriptionResult, ReturnRequest, ReturnRequestInput, type ShippingBarState, type ShippingBarView, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, COUNTRY_HEADERS, Cart, CartBuyerInput, CartLineInput, CartLineProblem, type CartLineProblemView, CartLineUpdateInput, CartPromotions, CartRecommendations, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorKind, type PaymentErrorView, type PaymentLocale, type PaymentMessageKey, type PaymentMessages, PaymentMethods, PaymentNextStep, type PaymentOutcome, type PaymentOutcomeKind, PaymentSubmitInput, PaymentVoucher, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, ProductVariant, type PromoProgressView, type PromotionLocale, type PromotionMessageKey, type PromotionMessages, PromotionReward, PromotionsList, type QueryParams, type QueryValue, RecommendationPlacement, Region, type RequestOptions, type ResolveAvailabilityOptions, RestockSubscriptionInput, RestockSubscriptionResult, ReturnRequest, ReturnRequestInput, type ShippingBarState, type ShippingBarView, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.js';
 export { OpenStatus, OpeningHours } from './geo.js';
-import { am as ProductSort, aB as Shop, ak as ProductConnection, ah as Product, x as Connection, w as Collection, S as LocationListParams, P as Location, Y as NearestLocation, aF as StockLevel, at as RestockSubscriptionInput, au as RestockSubscriptionResult, l as CartLineInput, C as Cart, o as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, H as DeliveryOptions, a9 as PaymentMethods, F as DeliveryInput, as as RecommendationPlacement, r as CartRecommendations, t as CheckoutInput, v as CheckoutResult, ar as PromotionsList, a6 as PaymentConfig, ae as PaymentSubmitInput, a2 as PaymentAttemptResult, z as CustomerIdentifier, D as CustomerSessionInput, B as CustomerSession, y as Customer, Z as Order, aw as ReturnRequestInput, av as ReturnRequest, N as InvoiceRequest, O as InvoiceResult, A as Address, aI as Theme, $ as Page, U as Menu, b as Article, aH as StorefrontErrorCode, M as InsufficientStockLine, W as Money, d as AvailabilityStatus, n as CartLineProblem, c as Availability, an as ProductVariant, E as DeclineCode, af as PaymentVoucher, aa as PaymentNextStep, p as CartPromotions, ap as PromotionReward, G as DeliveryMethod, aJ as UnavailableRateProvider } from './types-iGGZ9EiC.js';
-export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartLine, m as CartLineMerchandise, q as CartRecommendation, s as CheckoutInfo, u as CheckoutPayment, I as Facet, J as FacetValue, K as Image, L as InsufficientStockDetails, Q as LocationContacts, R as LocationKind, T as LocationPickup, V as MenuItem, X as MoneyRange, _ as OrderLine, a0 as PageInfo, a1 as PaymentAction, a3 as PaymentAttemptStatus, a4 as PaymentClient, a5 as PaymentClientCsp, a7 as PaymentFlow, a8 as PaymentMethod, ab as PaymentOption, ac as PaymentOptionKey, ad as PaymentPoint, ag as PickupOption, ai as ProductAttributeValue, aj as ProductCategory, al as ProductOption, ao as PromotionAnnouncement, aq as PromotionTier, ax as SEO, ay as Section, az as SelectedOption, aA as ShippingRate, aC as ShopBranch, aD as ShopContact, aE as ShopPolicies, aG as StorefrontErrorBody } from './types-iGGZ9EiC.js';
+import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-D7UJxrba.js';
+export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-D7UJxrba.js';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -67,8 +67,12 @@ type StorefrontResponseContext = StorefrontRequestContext & {
 type StorefrontClientOptions = {
     /** Base URL of the gateway, e.g. `https://ops.example.com/api/gw`. Routes are appended as `/storefront/...`. */
     baseUrl: string;
-    /** `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. */
-    token: string;
+    /**
+     * `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. A function is called on
+     * EVERY request, so a token read from a file (`createFileTokenSource` in `@asteby/storefront/node`) can rotate
+     * without restarting the server.
+     */
+    token: string | (() => string);
     /** Buyer session (`X-Customer-Token`) for `/storefront/customer/*` routes. */
     customerToken?: string | null;
     /** Custom fetch (defaults to `globalThis.fetch`). */
@@ -162,6 +166,13 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         }): Promise<T | null>;
         <T>(spec: RequestSpec): Promise<T>;
     };
+    token: {
+        /**
+         * What the token in use is and can do (`GET {baseUrl}/_token`, a gateway route, not a `/storefront` one).
+         * Needs no scope, so it answers even when the token is under-provisioned: `missing_scopes` says what to repair.
+         */
+        introspect: (options?: RequestOptions) => Promise<TokenIntrospection>;
+    };
     /** Returns a new client that sends the given buyer session token. */
     withCustomerToken(customerToken: string | null): /*elided*/ any;
     /** Returns a new client that reports the shopper's IP (`X-Storefront-Client-IP`) on every call. */
@@ -169,6 +180,12 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
     shop: {
         get: (options?: RequestOptions) => Promise<Shop>;
     };
+    /**
+     * How the market formats, taxes, addresses and invoices (`fiscal_id` carries the tax-id pattern, the regimes,
+     * the invoice uses and the identity documents the buyer can upload). Cacheable; `null` when the organization
+     * has no region configured.
+     */
+    region: (options?: RequestOptions) => Promise<Region | null>;
     products: {
         list: (params?: ProductListParams, options?: RequestOptions) => Promise<ProductConnection>;
         /** `null` when the product does not exist or is unpublished. */
@@ -231,6 +248,13 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         setDelivery: (id: string, delivery: DeliveryInput, options?: WriteOptions) => Promise<Cart>;
         /** Order note (up to 1000 characters). `null` or empty clears it. */
         setNote: (id: string, note: string | null, options?: WriteOptions) => Promise<Cart>;
+        /**
+         * Asks for an invoice for this cart (`null` or `{ requested: false }` withdraws it). The server validates the
+         * data against the region BEFORE any charge: `422` with `field: 'invoice.<field>'` (e.g. `invoice.tax_regime`)
+         * names what to fix. `409 already_checked_out` when the cart is already an order. Checkout uses it when
+         * `CheckoutInput.invoice` is omitted.
+         */
+        setInvoice: (id: string, invoice: InvoiceRequest | null, options?: WriteOptions) => Promise<Cart>;
         /**
          * Cross-sell suggestions: only sellable variants, with `unlocks` when adding one reaches the next
          * discount tier. `first` 1-8 (default 4). `private, no-store`; ask on demand, not on every render.
@@ -270,7 +294,24 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         requestOtp: (identifier: CustomerIdentifier, options?: WriteOptions) => Promise<void>;
         /** Exchanges the code for a buyer session (`token` goes in `customerToken`). */
         createSession: (input: CustomerSessionInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** What the store supports (password login, email verification, OTP channels). Drives which forms to show. */
+        capabilities: (options?: RequestOptions) => Promise<CustomerCapabilities>;
+        /**
+         * Creates an account with email + password. `verification_required` (202): a code was emailed, finish with
+         * `verifyRegistration`. `created` (201): the account exists and `session` is ready. `409` when the email is taken.
+         */
+        register: (input: CustomerRegisterInput, options?: WriteOptions) => Promise<CustomerRegisterResult>;
+        /** Confirms the emailed registration code and returns the new buyer session. */
+        verifyRegistration: (input: CustomerVerifyRegistrationInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** Email + password login. `401` for wrong credentials. */
+        loginWithPassword: (input: CustomerPasswordLoginInput, options?: WriteOptions) => Promise<CustomerSession>;
+        /** Sets or changes the password of the signed-in buyer (`options.customerToken`, or a `withCustomerToken` client). */
+        setPassword: (input: CustomerSetPasswordInput, options?: WriteOptions) => Promise<void>;
+        /** Resets a forgotten password with the code from `requestOtp({ email })`. */
+        resetPassword: (input: CustomerResetPasswordInput, options?: WriteOptions) => Promise<void>;
         get: (options?: RequestOptions) => Promise<Customer>;
+        /** Updates the profile and the saved fiscal data; `fiscal: null` deletes the latter. `422` with `field: 'fiscal.<field>'`. */
+        update: (input: CustomerUpdateInput, options?: WriteOptions) => Promise<Customer>;
         orders: (params?: PaginationParams, options?: RequestOptions) => Promise<Connection<Order>>;
         /** `null` when the order does not exist or belongs to someone else. */
         order: (id: string, options?: RequestOptions) => Promise<Order | null>;
@@ -310,6 +351,8 @@ type StorefrontErrorInit = {
     /** Request URL that failed (without credentials). */
     url?: string;
     cause?: unknown;
+    /** Scopes named by the gateway on a `403 insufficient_scope`. */
+    requiredScopes?: string[];
 };
 /**
  * Error thrown by the client for any non-2xx response, network failure,
@@ -322,6 +365,8 @@ declare class StorefrontError extends Error {
     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[];
     constructor(init: StorefrontErrorInit);
     /**
      * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -330,6 +375,7 @@ declare class StorefrontError extends Error {
      */
     get stockLines(): InsufficientStockLine[];
     toJSON(): {
+        requiredScopes?: string[] | undefined;
         name: string;
         status: number;
         code: StorefrontErrorCode;
@@ -339,6 +385,31 @@ declare class StorefrontError extends Error {
 }
 declare function isStorefrontError(err: unknown): err is StorefrontError;
 
+/** `sk_…a91f`: the prefix and the last four characters, never enough to use the token. */
+declare function maskToken(token: string | null | undefined): string;
+type DiagnoseOptions = {
+    /** Where the warning goes (default `console.warn`). Receives ONE line per problem. */
+    log?: (message: string) => void;
+    /** Name of the connection, shown in the repair path. */
+    connectionName?: string;
+    /** Give up after this long (default 3000 ms). */
+    timeoutMs?: number;
+};
+/** Where the operator repairs a connection in OPS (es-MX, as the screen names it). */
+declare function repairPath(connectionName?: string): string;
+/**
+ * Startup check of the store's credential: asks `token.introspect()` and, when scopes are missing, logs ONE clear
+ * warning with the repair path (never the token, only `sk_…a91f`). It NEVER throws and is meant to be fired and
+ * forgotten, so it cannot delay or break the boot:
+ *
+ * ```ts
+ * void diagnose(storefront)
+ * ```
+ *
+ * Resolves with the introspection, or `null` when it could not be obtained (older OPS, outage, bad token).
+ */
+declare function diagnose(client: StorefrontClient, options?: DiagnoseOptions): Promise<TokenIntrospection | null>;
+
 type FormatMoneyOptions = {
     /** Drop `.00` when the amount is a whole number. */
     withoutTrailingZeros?: boolean;
@@ -677,4 +748,4 @@ type DeliveryNotices = {
 /** Splits `delivery.unavailable` into the `missing_weight` notice and the generic one. */
 declare function deliveryNotices(delivery: Pick<DeliveryOptions, 'unavailable' | 'partial'> | null | undefined): DeliveryNotices;
 
-export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, COUNTRY_HEADERS, Cart, CartBuyerInput, CartLineInput, CartLineProblem, type CartLineProblemView, CartLineUpdateInput, CartPromotions, CartRecommendations, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorKind, type PaymentErrorView, type PaymentLocale, type PaymentMessageKey, type PaymentMessages, PaymentMethods, PaymentNextStep, type PaymentOutcome, type PaymentOutcomeKind, PaymentSubmitInput, PaymentVoucher, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, ProductVariant, type PromoProgressView, type PromotionLocale, type PromotionMessageKey, type PromotionMessages, PromotionReward, PromotionsList, type QueryParams, type QueryValue, RecommendationPlacement, type RequestOptions, type ResolveAvailabilityOptions, RestockSubscriptionInput, RestockSubscriptionResult, ReturnRequest, ReturnRequestInput, type ShippingBarState, type ShippingBarView, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, COUNTRY_HEADERS, Cart, CartBuyerInput, CartLineInput, CartLineProblem, type CartLineProblemView, CartLineUpdateInput, CartPromotions, CartRecommendations, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorKind, type PaymentErrorView, type PaymentLocale, type PaymentMessageKey, type PaymentMessages, PaymentMethods, PaymentNextStep, type PaymentOutcome, type PaymentOutcomeKind, PaymentSubmitInput, PaymentVoucher, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, ProductVariant, type PromoProgressView, type PromotionLocale, type PromotionMessageKey, type PromotionMessages, PromotionReward, PromotionsList, type QueryParams, type QueryValue, RecommendationPlacement, Region, type RequestOptions, type ResolveAvailabilityOptions, RestockSubscriptionInput, RestockSubscriptionResult, ReturnRequest, ReturnRequestInput, type ShippingBarState, type ShippingBarView, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };

package/dist/index.js

@@ -10,6 +10,8 @@ var StorefrontError = class extends Error {
   field;
   details;
   url;
+  /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
+  requiredScopes;
   constructor(init) {
     super(init.message, init.cause === void 0 ? void 0 : { cause: init.cause });
     this.status = init.status;
@@ -17,6 +19,7 @@ var StorefrontError = class extends Error {
     this.field = init.field;
     this.details = init.details;
     this.url = init.url;
+    this.requiredScopes = init.requiredScopes ?? [];
   }
   /**
    * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -29,7 +32,14 @@ var StorefrontError = class extends Error {
     return lines.filter((l) => typeof l === "object" && l !== null && typeof l.sku === "string");
   }
   toJSON() {
-    return { name: this.name, status: this.status, code: this.code, message: this.message, field: this.field };
+    return {
+      name: this.name,
+      status: this.status,
+      code: this.code,
+      message: this.message,
+      field: this.field,
+      ...this.requiredScopes.length ? { requiredScopes: this.requiredScopes } : {}
+    };
   }
 };
 function isStorefrontError(err) {
@@ -167,6 +177,9 @@ function linkSignals(signals) {
     cleanup: () => listeners.forEach(([s, on]) => s.removeEventListener("abort", on))
   };
 }
+function scopeList(raw) {
+  return Array.isArray(raw) ? raw.filter((s) => typeof s === "string" && s.length > 0) : [];
+}
 async function readError(res, url) {
   let body;
   try {
@@ -176,9 +189,13 @@ async function readError(res, url) {
     body = void 0;
   }
   const e = body?.error;
+  const top = body;
+  const code = e?.code ?? (typeof top?.code === "string" ? top.code : void 0);
+  const requiredScopes = code === "insufficient_scope" ? scopeList(e?.required_scopes ?? top?.required_scopes ?? e?.details?.required_scopes) : [];
   return new StorefrontError({
     status: res.status,
-    code: e?.code ?? defaultCodeForStatus(res.status),
+    code: code ?? defaultCodeForStatus(res.status),
+    ...requiredScopes.length ? { requiredScopes } : {},
     message: e?.message ?? `Storefront API responded ${res.status}${res.statusText ? " " + res.statusText : ""}`,
     ...e?.field ? { field: e.field } : {},
     ...e?.details !== void 0 ? { details: e.details } : {},
@@ -188,8 +205,14 @@ async function readError(res, url) {
 function createStorefrontClient(config) {
   if (!config.baseUrl) throw new TypeError("createStorefrontClient: baseUrl is required");
   if (!config.token) throw new TypeError("createStorefrontClient: token is required");
+  const currentToken = () => {
+    const t = typeof config.token === "function" ? config.token() : config.token;
+    if (!t) throw new StorefrontError({ status: 0, code: "unauthorized", message: "Storefront token is empty (token source returned nothing)" });
+    return t;
+  };
   const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
-  if (isBrowser && !isTokenPublishable(config.token) && config.token.startsWith("sk_")) {
+  const initialToken = typeof config.token === "string" ? config.token : "";
+  if (isBrowser && initialToken.startsWith("sk_")) {
     console.warn("[@asteby/storefront] A private sk_ token is being used in a browser. Use a public pk_ token instead.");
   }
   async function request(spec) {
@@ -201,13 +224,14 @@ function createStorefrontClient(config) {
     const url = joinUrl(config.baseUrl, spec.path) + (qs ? `?${qs}` : "");
     const headers = new Headers(config.headers);
     headers.set("Accept", "application/json");
-    headers.set("Authorization", `Bearer ${config.token}`);
+    const token = currentToken();
+    headers.set("Authorization", `Bearer ${token}`);
     if (config.locale) headers.set("Accept-Language", config.locale);
     if (config.domain) headers.set("X-Storefront-Domain", storefrontDomainHeader(config.domain, config.market));
     const customerToken = options.customerToken !== void 0 ? options.customerToken : config.customerToken;
     if (customerToken) headers.set("X-Customer-Token", customerToken);
     const clientIp = options.clientIp !== void 0 ? options.clientIp : config.clientIp;
-    const ip = isTokenPublishable(config.token) ? void 0 : normalizeClientIp(clientIp);
+    const ip = isTokenPublishable(token) ? void 0 : normalizeClientIp(clientIp);
     if (ip) headers.set(CLIENT_IP_HEADER, ip);
     if (options.idempotencyKey) headers.set("Idempotency-Key", options.idempotencyKey);
     if (spec.body !== void 0) headers.set("Content-Type", "application/json");
@@ -272,6 +296,13 @@ function createStorefrontClient(config) {
     config: Object.freeze({ ...config }),
     /** Low-level escape hatch: any route under `baseUrl`. */
     request,
+    token: {
+      /**
+       * What the token in use is and can do (`GET {baseUrl}/_token`, a gateway route, not a `/storefront` one).
+       * Needs no scope, so it answers even when the token is under-provisioned: `missing_scopes` says what to repair.
+       */
+      introspect: (options) => get("/_token", void 0, options)
+    },
     /** Returns a new client that sends the given buyer session token. */
     withCustomerToken(customerToken) {
       return createStorefrontClient({ ...config, customerToken });
@@ -283,6 +314,12 @@ function createStorefrontClient(config) {
     shop: {
       get: (options) => get("/storefront/shop", void 0, options)
     },
+    /**
+     * How the market formats, taxes, addresses and invoices (`fiscal_id` carries the tax-id pattern, the regimes,
+     * the invoice uses and the identity documents the buyer can upload). Cacheable; `null` when the organization
+     * has no region configured.
+     */
+    region: (options) => getOrNull("/storefront/region", void 0, options),
     products: {
       list: (params, options) => get("/storefront/products", productListQuery(params), options),
       /** `null` when the product does not exist or is unpublished. */
@@ -338,6 +375,13 @@ function createStorefrontClient(config) {
       setDelivery: (id, delivery, options) => write("PUT", cartPath(id, "/delivery"), delivery, options),
       /** Order note (up to 1000 characters). `null` or empty clears it. */
       setNote: (id, note, options) => write("PUT", cartPath(id, "/note"), { note }, options),
+      /**
+       * Asks for an invoice for this cart (`null` or `{ requested: false }` withdraws it). The server validates the
+       * data against the region BEFORE any charge: `422` with `field: 'invoice.<field>'` (e.g. `invoice.tax_regime`)
+       * names what to fix. `409 already_checked_out` when the cart is already an order. Checkout uses it when
+       * `CheckoutInput.invoice` is omitted.
+       */
+      setInvoice: (id, invoice, options) => write("PUT", cartPath(id, "/invoice"), invoice ?? { requested: false }, options),
       /**
        * Cross-sell suggestions: only sellable variants, with `unlocks` when adding one reaches the next
        * discount tier. `first` 1-8 (default 4). `private, no-store`; ask on demand, not on every render.
@@ -380,7 +424,27 @@ function createStorefrontClient(config) {
       requestOtp: (identifier, options) => write("POST", "/storefront/customer/otp", identifier, options),
       /** Exchanges the code for a buyer session (`token` goes in `customerToken`). */
       createSession: (input, options) => write("POST", "/storefront/customer/session", input, options),
+      /** What the store supports (password login, email verification, OTP channels). Drives which forms to show. */
+      capabilities: (options) => get("/storefront/customer/capabilities", void 0, options),
+      /**
+       * Creates an account with email + password. `verification_required` (202): a code was emailed, finish with
+       * `verifyRegistration`. `created` (201): the account exists and `session` is ready. `409` when the email is taken.
+       */
+      register: async (input, options) => {
+        const res = await write("POST", "/storefront/customer/register", input, options);
+        return res && "token" in res ? { status: "created", session: res } : { status: "verification_required" };
+      },
+      /** Confirms the emailed registration code and returns the new buyer session. */
+      verifyRegistration: (input, options) => write("POST", "/storefront/customer/register/verify", input, options),
+      /** Email + password login. `401` for wrong credentials. */
+      loginWithPassword: (input, options) => write("POST", "/storefront/customer/login", input, options),
+      /** Sets or changes the password of the signed-in buyer (`options.customerToken`, or a `withCustomerToken` client). */
+      setPassword: (input, options) => write("PUT", "/storefront/customer/password", input, options),
+      /** Resets a forgotten password with the code from `requestOtp({ email })`. */
+      resetPassword: (input, options) => write("POST", "/storefront/customer/password/reset", input, options),
       get: (options) => get("/storefront/customer", void 0, options),
+      /** Updates the profile and the saved fiscal data; `fiscal: null` deletes the latter. `422` with `field: 'fiscal.<field>'`. */
+      update: (input, options) => write("PATCH", "/storefront/customer", input, options),
       orders: (params, options) => get("/storefront/customer/orders", params, options),
       /** `null` when the order does not exist or belongs to someone else. */
       order: (id, options) => getOrNull(`/storefront/customer/orders/${enc(id)}`, void 0, options),
@@ -412,6 +476,45 @@ function storefrontDomainHeader(domain, market) {
   return code && /^[a-z0-9_-]{1,32}$/.test(code) ? `${host}#${code}` : host;
 }
 
+// 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)}`;
+}
+function repairPath(connectionName) {
+  return `OPS \u2192 Conexiones y API \u2192 ${connectionName ?? "<conexi\xF3n>"} \u2192 Reparar permisos`;
+}
+async function diagnose(client, options = {}) {
+  const log = options.log ?? ((m) => console.warn(m));
+  const timeoutMs = options.timeoutMs ?? 3e3;
+  const raw = client.config.token;
+  let mask;
+  try {
+    mask = maskToken(typeof raw === "function" ? raw() : raw);
+  } catch {
+    mask = maskToken(null);
+  }
+  try {
+    const info = await client.token.introspect({ signal: AbortSignal.timeout(timeoutMs) });
+    const missing = Array.isArray(info?.missing_scopes) ? info.missing_scopes : [];
+    if (missing.length > 0) {
+      log(
+        `[@asteby/storefront] La credencial ${mask} no tiene permisos que la tienda necesita: ${missing.join(", ")}. Rep\xE1ralo en ${repairPath(options.connectionName)} (no hace falta cambiar la clave ni reiniciar).`
+      );
+    }
+    return info ?? null;
+  } catch (err) {
+    if (isStorefrontError(err) && err.status === 401) {
+      try {
+        log(`[@asteby/storefront] OPS rechaz\xF3 la credencial ${mask} (401): est\xE1 revocada o vencida. Vuelve a conectar la tienda en OPS \u2192 Conexiones y API.`);
+      } catch {
+      }
+    }
+    return null;
+  }
+}
+
 // src/payments.ts
 var ES = {
   "decline.insufficient_funds": "Tu tarjeta no tiene saldo suficiente. Prueba con otra tarjeta o paga en efectivo.",
@@ -917,6 +1020,6 @@ function deliveryNotices(delivery) {
   };
 }
 
-export { CLIENT_IP_HEADER, COUNTRY_HEADERS, MISSING_WEIGHT, NOTE_MAX_LENGTH, StorefrontError, appendParams, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productListQuery, promoProgressView, promotionMessages, rewardLabel, safeHttpsUrl, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+export { CLIENT_IP_HEADER, COUNTRY_HEADERS, MISSING_WEIGHT, NOTE_MAX_LENGTH, StorefrontError, appendParams, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productListQuery, promoProgressView, promotionMessages, repairPath, rewardLabel, safeHttpsUrl, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map