@asteby/storefront 0.5.0 → 0.7.0

package/dist/{types-BmC-RDo8.d.ts → types-iGGZ9EiC.d.ts}

@@ -38,6 +38,30 @@ type SelectedOption = {
     name: string;
     value: string;
 };
+/**
+ * Server-resolved availability state (stock policy of the market x `show_stock`).
+ * The storefront never computes it. Treat an unknown value as `out_of_stock`.
+ */
+type AvailabilityStatus = 'in_stock' | 'low_stock' | 'out_of_stock' | 'backorder' | 'preorder';
+/**
+ * Availability of a variant (or the summary of a product). `quantity` and
+ * `max_per_order` are already filtered by the shop's `show_stock`: with `none`
+ * or `in_stock_label` the quantity is always `null`. Never infer a number from
+ * any other field.
+ */
+type Availability = {
+    status: AvailabilityStatus;
+    /** Units the buyer may see; `null` when hidden. With `low_stock_threshold:N` it only comes when `status` is `low_stock`. */
+    quantity: number | null;
+    /** Max per order: min(max line quantity, visible quantity). `null` = no cap to show. */
+    max_per_order: number | null;
+    /** `YYYY-MM-DD`, only `backorder` / `preorder`, when OPS knows it. */
+    restock_eta: string | null;
+    /** RFC 3339, release of a `preorder`. */
+    preorder_release_at: string | null;
+    /** The buyer can subscribe to "notify me when it is back" (`restock.subscribe`). */
+    notify_available: boolean;
+};
 type ProductVariant = {
     id: string;
     sku: string;
@@ -45,8 +69,12 @@ type ProductVariant = {
     selected_options: SelectedOption[];
     price: Money;
     compare_at_price: Money | null;
+    /** Derived from `availability.status` when the server sends it. */
     available_for_sale: boolean;
+    /** `null` when the stock is not tracked. Derived from `availability.quantity` when the server sends it. */
     quantity_available: number | null;
+    /** Absent on servers older than contract 1.1: use `resolveAvailability` to polyfill it. */
+    availability?: Availability;
     image: Image | null;
     barcode: string | null;
 };
@@ -81,6 +109,8 @@ type Product = {
     price_range: MoneyRange;
     compare_at_price_range: MoneyRange | null;
     available_for_sale: boolean;
+    /** Summary: the best state among the variants. Absent on servers older than contract 1.1. */
+    availability?: Availability;
     seo: SEO;
     /** RFC 3339. */
     updated_at: string;
@@ -113,6 +143,7 @@ type ProductConnection = Connection<Product> & {
 type StockLevel = {
     sku: string;
     quantity_available: number | null;
+    availability?: Availability;
 };
 type ShopContact = {
     email: string | null;
@@ -220,10 +251,17 @@ type AddressInput = Partial<Omit<Address, 'id' | 'address1' | 'city' | 'zip' | '
 type CartLineMerchandise = ProductVariant & {
     product: Pick<Product, 'handle' | 'title' | 'featured_image'>;
 };
+/** Why a cart line cannot be bought as it is. `max_quantity` is `null` when `show_stock` hides it. */
+type CartLineProblem = {
+    code: 'out_of_stock' | 'insufficient_stock';
+    max_quantity: number | null;
+};
 type CartLine = {
     id: string;
     quantity: number;
     merchandise: CartLineMerchandise;
+    /** Computed when the cart is read, before checkout. `null`/absent = fine. */
+    problem?: CartLineProblem | null;
     cost: {
         total: Money;
         unit: Money;
@@ -256,7 +294,10 @@ type CartDelivery = {
 };
 type CartCost = {
     subtotal: Money;
+    /** Total discount (automatic tiers + codes). Use `discounts` to label each one. */
     discount: Money;
+    /** One entry per applied discount (contract 1.2). Absent on older servers. */
+    discounts?: CartDiscountLine[];
     shipping: Money | null;
     tax: Money | null;
     total: Money;
@@ -275,6 +316,8 @@ type Cart = {
     delivery: CartDelivery;
     cost: CartCost;
     note?: string | null;
+    /** Automatic-discount tiers and free-shipping progress (contract 1.2); `null`/absent without the promotions addon. */
+    promotions?: CartPromotions | null;
     updated_at: string;
 };
 type CartLineInput = {
@@ -337,6 +380,10 @@ type PaymentMethod = {
     /** `builtin` (manual transfer/cash) or `provider` (a payment addon). */
     kind: 'builtin' | 'provider';
     default: boolean;
+    /** Embedded-payment options the provider offers (contract 1.2). Absent: fall back to a redirect. */
+    options?: PaymentOption[];
+    /** Public data to mount the provider form in the browser (contract 1.2). */
+    client?: PaymentClient;
 };
 type PaymentMethods = {
     methods: PaymentMethod[];
@@ -371,6 +418,12 @@ type CheckoutInput = {
     /** Absolute URL; the API appends `?checkout=<id>` to it. */
     return_url: string;
     note?: string;
+    /** `embedded` pays in the page (`checkouts.pay`); `redirect` (default) sends the buyer to the provider. */
+    payment_flow?: PaymentFlow;
+    /** The option the buyer chose; one of `PaymentMethod.options[].key`. */
+    payment_option?: PaymentOptionKey;
+    /** The total the buyer saw. A different server total answers `422 price_mismatch`. */
+    expected_total?: Money;
 };
 type CheckoutPayment = {
     provider: string;
@@ -385,6 +438,12 @@ type CheckoutPayment = {
     instructions_data?: Record<string, unknown>;
     /** Offline payment instructions (OXXO reference, SPEI CLABE, manual transfer data) as text; `null` when none. */
     instructions?: string | null;
+    /** `embedded` when the buyer pays in the page (contract 1.2). */
+    flow?: PaymentFlow;
+    /** Public data to mount the provider form. */
+    client?: PaymentClient;
+    /** Pending action of the last attempt (voucher, 3DS challenge). */
+    action?: PaymentAction | null;
 };
 type CheckoutInfo = {
     /** Checkout session id; use it with `payment.instructions`. */
@@ -504,12 +563,273 @@ type Article = {
     seo: SEO;
 };
 type StorefrontErrorCode = 'validation' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'insufficient_stock' | 'price_mismatch' | 'invalid_state' | 'rate_limited' | 'not_modified' | 'server_error' | 'network' | 'timeout' | 'aborted' | 'invalid_response' | (string & {});
+/** One affected line of a `409 insufficient_stock`. `line_id` is `null` when the line did not exist yet (add). */
+type InsufficientStockLine = {
+    line_id: string | null;
+    variant_id: string;
+    sku: string;
+    status: AvailabilityStatus;
+    max_quantity: number | null;
+};
+type InsufficientStockDetails = {
+    lines: InsufficientStockLine[];
+};
 type StorefrontErrorBody = {
     error: {
         code: StorefrontErrorCode;
         message: string;
         field?: string;
+        details?: unknown;
+    };
+};
+type RestockSubscriptionInput = {
+    sku: string;
+    /** At least one of `email` / `phone`. */
+    email?: string;
+    phone?: string;
+    /** Language of the notice, e.g. `es-MX`. */
+    locale: string;
+    market?: string;
+    /** Explicit consent to receive the notice. */
+    consent: true;
+};
+type RestockSubscriptionResult = {
+    status: 'pending';
+};
+type PaymentFlow = 'redirect' | 'embedded';
+/** `card` and `cash` are paid in the page; `wallet` and `credits` always leave it (provider account). */
+type PaymentOptionKey = 'card' | 'cash' | 'wallet' | 'credits';
+/** A cash point (OXXO, 7 Eleven...). The list comes from the provider, never from the shop code. */
+type PaymentPoint = {
+    id: string;
+    payment_method_id: string;
+    payment_point?: string | null;
+    label: string;
+    logo_url?: string | null;
+    group: 'main' | 'more';
+};
+type PaymentOption = {
+    key: PaymentOptionKey;
+    family?: string;
+    /** Provider label, e.g. "Tarjeta de crédito o débito". */
+    label?: string;
+    /** `true`: choosing it sends the buyer to the provider. */
+    redirect: boolean;
+    max_installments?: number;
+    points?: PaymentPoint[];
+    /** Provider-supplied promo text, e.g. "up to 12 payments". */
+    label_max?: string | null;
+};
+/** Origins the provider needs in the page's CSP, declared by the provider. */
+type PaymentClientCsp = {
+    script?: string[];
+    frame?: string[];
+    connect?: string[];
+    img?: string[];
+    form?: string[];
+};
+/** Public data to mount a provider form. `public_key` is public by design; never a secret. */
+type PaymentClient = {
+    /** Adapter key, e.g. `mercadopago_bricks`. */
+    kind: string;
+    sdk_url: string;
+    public_key: string;
+    locale?: string;
+    market?: string;
+    options?: PaymentOption[];
+    csp?: PaymentClientCsp;
+    test_mode?: boolean;
+};
+/** Neutral reasons for a rejected payment (provider codes are translated server-side). */
+type DeclineCode = 'insufficient_funds' | 'invalid_cvc' | 'invalid_expiry' | 'invalid_card_data' | 'call_issuer' | 'card_disabled' | 'duplicate' | 'max_attempts' | 'authentication_failed' | 'declined';
+type PaymentVoucher = {
+    payment_point: string;
+    reference: string;
+    /** https page with the printable voucher. */
+    voucher_url?: string | null;
+    barcode?: string | null;
+    clabe?: string | null;
+    /** The exact amount to pay. The cart sends a decimal string plus `currency`; a `Money` object is also accepted. */
+    amount?: Money | string | number;
+    currency?: string;
+    /** RFC 3339. */
+    expires_at?: string | null;
+};
+type PaymentAction = {
+    type: 'none' | 'challenge' | 'voucher' | 'redirect';
+    challenge?: {
+        url?: string;
+        creq?: string;
+    } | null;
+    voucher?: PaymentVoucher | null;
+    redirect_url?: string | null;
+};
+type PaymentAttemptStatus = 'paid' | 'pending' | 'requires_action' | 'failed' | 'expired' | 'cancelled';
+/** What the buyer should do next after a rejection (stable enum from the cart). */
+type PaymentNextStep = 'retry' | 'fix_card_data' | 'use_other_card' | 'pay_cash' | 'contact_issuer' | 'check_email' | 'rebuild_cart';
+/** `POST /storefront/checkouts/:id/payment`. The amount is the server's; the browser only brings `provider_data`. */
+type PaymentSubmitInput = {
+    method: 'card' | 'cash' | 'bank_transfer';
+    /** What the provider SDK gave the browser (token, payment_method_id...). Never logged or stored. */
+    provider_data: Record<string, unknown>;
+    device_session_id?: string;
+    /** The total the buyer saw. */
+    expected_total?: Money;
+};
+type PaymentAttemptResult = {
+    payment: {
+        provider: string;
+        status: PaymentAttemptStatus;
+        /** Server classification: `approved | pending | rejected | redirect | challenge`. */
+        outcome?: string;
+        decline_code?: DeclineCode | null;
+        next_step?: PaymentNextStep | null;
+        retryable?: boolean;
+        /** Server-written texts (es / en). The helpers prefer the shop's own catalog but fall back to these. */
+        message?: string | null;
+        message_en?: string | null;
+        action?: PaymentAction | null;
+    };
+    checkout?: CheckoutInfo;
+    order?: {
+        id?: string;
+        number?: string | null;
+    };
+    attempt?: {
+        n: number;
+    };
+    attempts_left?: number;
+};
+/** `GET /storefront/checkouts/:id/payment-config`: what to mount for an embedded checkout. */
+type PaymentConfig = {
+    provider: string;
+    flow: PaymentFlow;
+    option: PaymentOptionKey | null;
+    payable: boolean;
+    /** Why it is not payable: `not_embedded | paid | closed | expired | too_many_attempts | payment_in_progress`. */
+    reason: string | null;
+    amount: Money;
+    currency: string;
+    public_key: string | null;
+    methods: string[];
+    options: PaymentOption[];
+    client: PaymentClient | null;
+    checkout: CheckoutInfo;
+    /** Pending voucher / challenge / redirect of an earlier attempt, to show again after a reload. */
+    action: PaymentAction | null;
+    attempts_left: number;
+};
+type PromotionReward = {
+    kind: 'percent';
+    percent: string;
+} | {
+    kind: 'fixed';
+    amount: Money;
+} | {
+    kind: 'free_shipping';
+};
+type PromotionTier = {
+    id: string;
+    threshold: Money;
+    reward: PromotionReward;
+    reached: boolean;
+    /** Position of the milestone on the bar (0-100), computed by OPS. */
+    percent_of_max: number;
+};
+type CartPromotions = {
+    version: 1;
+    promotion_id: string;
+    title: string;
+    basis: Money;
+    tiers: PromotionTier[];
+    applied: {
+        tier_id: string;
+        reward: PromotionReward;
+        amount: Money;
+    } | null;
+    next_tier: {
+        tier_id: string;
+        threshold: Money;
+        remaining: Money;
+        reward: PromotionReward;
+        percent: number;
+    } | null;
+    max_reached: boolean;
+    percent_of_max: number;
+    combines_with_codes: boolean;
+    ends_at: string | null;
+    excluded_line_ids: string[];
+    suppressed: {
+        reason: 'code_better' | 'list_final' | 'limit_reached';
+    } | null;
+    free_shipping: {
+        /** `0.00` = no minimum. */
+        threshold: Money;
+        basis: Money;
+        remaining: Money;
+        reached: boolean;
+        percent: number;
+    } | null;
+};
+type CartDiscountLine = {
+    kind: 'automatic' | 'code';
+    id: string;
+    title: string;
+    code: string | null;
+    amount: Money;
+};
+type CartRecommendation = {
+    product: Pick<Product, 'id' | 'handle' | 'title' | 'featured_image' | 'options' | 'vendor'>;
+    /** Only sellable variants, with the server price. */
+    variants: ProductVariant[];
+    default_variant_id: string;
+    source: 'curated' | 'bought_together' | 'bestseller' | 'similar';
+    unlocks: {
+        tier_id: string;
+        reward: PromotionReward;
+        remaining_after: Money;
+    } | null;
+};
+type CartRecommendations = {
+    nodes: CartRecommendation[];
+    promotions: CartPromotions | null;
+};
+type RecommendationPlacement = 'checkout_upsell' | 'cart' | 'drawer';
+/** Public announcement behind the entry pop-up (`GET /storefront/promotions`). Amounts come from the engine. */
+type PromotionAnnouncement = {
+    id: string;
+    version: number;
+    placement: 'entry_popup';
+    headline: string;
+    subheadline?: string | null;
+    cta_label?: string | null;
+    /** Internal path. */
+    cta_url?: string | null;
+    image?: {
+        url: string;
+        alt: string;
+    } | null;
+    tiers: {
+        threshold: Money;
+        reward: PromotionReward;
+    }[];
+    free_shipping_threshold: Money | null;
+    /** Server-generated fine print. */
+    legal_text: string;
+    combines_with_codes: boolean;
+    starts_at: string | null;
+    ends_at: string | null;
+    frequency?: 'session' | 'days' | 'campaign';
+    frequency_days?: number;
+    trigger?: {
+        delay_ms?: number;
+        pageviews?: number;
+        scroll_percent?: number;
     };
 };
+type PromotionsList = {
+    nodes: unknown[];
+    announcements: PromotionAnnouncement[];
+};
 
-export type { ProductSort as $, Address as A, LocationContacts as B, Cart as C, DeliveryInput as D, LocationKind as E, Facet as F, LocationListParams as G, LocationPickup as H, Image as I, MenuItem as J, Money as K, Location as L, Menu as M, MoneyRange as N, NearestLocation as O, Order as P, OrderLine as Q, Page as R, PageInfo as S, PaymentMethod as T, PaymentMethods as U, PickupOption as V, Product as W, ProductAttributeValue as X, ProductCategory as Y, ProductConnection as Z, ProductOption as _, AddressInput as a, ProductVariant as a0, ReturnRequest as a1, ReturnRequestInput as a2, SEO as a3, Section as a4, SelectedOption as a5, ShippingRate as a6, Shop as a7, ShopBranch as a8, ShopContact as a9, ShopPolicies as aa, StockLevel as ab, StorefrontErrorBody as ac, StorefrontErrorCode as ad, Theme as ae, UnavailableRateProvider as af, Article as b, CartBuyer as c, CartBuyerInput as d, CartCost as e, CartDelivery as f, CartDiscountCode as g, CartLine as h, CartLineInput as i, CartLineMerchandise as j, CartLineUpdateInput as k, CheckoutInfo as l, CheckoutInput as m, CheckoutPayment as n, CheckoutResult as o, Collection as p, Connection as q, Customer as r, CustomerIdentifier as s, CustomerSession as t, CustomerSessionInput as u, DeliveryMethod as v, DeliveryOptions as w, FacetValue as x, InvoiceRequest as y, InvoiceResult as z };
+export type { Page as $, Address as A, CustomerSession as B, Cart as C, CustomerSessionInput as D, DeclineCode as E, DeliveryInput as F, DeliveryMethod as G, DeliveryOptions as H, Facet as I, FacetValue as J, Image as K, InsufficientStockDetails as L, InsufficientStockLine as M, InvoiceRequest as N, InvoiceResult as O, Location as P, LocationContacts as Q, LocationKind as R, LocationListParams as S, LocationPickup as T, Menu as U, MenuItem as V, Money as W, MoneyRange as X, NearestLocation as Y, Order as Z, OrderLine as _, AddressInput as a, PageInfo as a0, PaymentAction as a1, PaymentAttemptResult as a2, PaymentAttemptStatus as a3, PaymentClient as a4, PaymentClientCsp as a5, PaymentConfig as a6, PaymentFlow as a7, PaymentMethod as a8, PaymentMethods as a9, ShippingRate as aA, Shop as aB, ShopBranch as aC, ShopContact as aD, ShopPolicies as aE, StockLevel as aF, StorefrontErrorBody as aG, StorefrontErrorCode as aH, Theme as aI, UnavailableRateProvider as aJ, PaymentNextStep as aa, PaymentOption as ab, PaymentOptionKey as ac, PaymentPoint as ad, PaymentSubmitInput as ae, PaymentVoucher as af, PickupOption as ag, Product as ah, ProductAttributeValue as ai, ProductCategory as aj, ProductConnection as ak, ProductOption as al, ProductSort as am, ProductVariant as an, PromotionAnnouncement as ao, PromotionReward as ap, PromotionTier as aq, PromotionsList as ar, RecommendationPlacement as as, RestockSubscriptionInput as at, RestockSubscriptionResult as au, ReturnRequest as av, ReturnRequestInput as aw, SEO as ax, Section as ay, SelectedOption as az, Article as b, Availability as c, AvailabilityStatus as d, CartBuyer as e, CartBuyerInput as f, CartCost as g, CartDelivery as h, CartDiscountCode as i, CartDiscountLine as j, CartLine as k, CartLineInput as l, CartLineMerchandise as m, CartLineProblem as n, CartLineUpdateInput as o, CartPromotions as p, CartRecommendation as q, CartRecommendations as r, CheckoutInfo as s, CheckoutInput as t, CheckoutPayment as u, CheckoutResult as v, Collection as w, Connection as x, Customer as y, CustomerIdentifier as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/storefront",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Typed client for the Storefront API v1 (catalog, cart, checkout, customer, content) using only global fetch — Node 20+, edge runtimes and browsers — plus an in-memory mock of the whole contract.",
   "license": "Apache-2.0",
   "repository": {