@asteby/storefront 0.1.0 → 0.3.0

package/dist/{types-BdaQ9Pxq.d.cts → types-CTXB8Dnl.d.cts}

@@ -106,9 +106,10 @@ type ProductSort = 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'title_
 type ProductConnection = Connection<Product> & {
     facets: Facet[];
 };
+/** `quantity_available` is `null` when the variant's stock is not tracked (always sellable). */
 type StockLevel = {
     sku: string;
-    quantity_available: number;
+    quantity_available: number | null;
 };
 type ShopContact = {
     email: string | null;
@@ -159,6 +160,11 @@ type Address = {
     zip: string;
     country_code: string;
     phone: string | null;
+    /** Colonia. Sent and echoed by the cart API. */
+    neighborhood?: string | null;
+    province_code?: string | null;
+    /** Delivery reference ("between streets", gate code...). */
+    reference?: string | null;
 };
 type AddressInput = Partial<Omit<Address, 'id' | 'address1' | 'city' | 'zip' | 'country_code'>> & Pick<Address, 'address1' | 'city' | 'zip' | 'country_code'>;
 type CartLineMerchandise = ProductVariant & {
@@ -172,11 +178,14 @@ type CartLine = {
         total: Money;
         unit: Money;
         compare_at_unit: Money | null;
+        discount?: Money;
     };
 };
 type CartDiscountCode = {
     code: string;
     applicable: boolean;
+    /** Why an inapplicable code was not applied. */
+    reason?: string;
 };
 type CartBuyer = {
     email: string | null;
@@ -188,6 +197,12 @@ type CartDelivery = {
     method: DeliveryMethod | null;
     rate_id: string | null;
     branch_id: string | null;
+    /** Present when the chosen option is no longer valid (e.g. the quote expired). */
+    problem?: string;
+    /** Description of the chosen carrier rate (carrier addons only). */
+    title?: string | null;
+    carrier?: string | null;
+    eta?: string | null;
 };
 type CartCost = {
     subtotal: Money;
@@ -199,6 +214,9 @@ type CartCost = {
 };
 type Cart = {
     id: string;
+    /** `active` while it can be edited; anything else is a cart already turned into an order. */
+    status?: string;
+    currency_code?: string;
     lines: CartLine[];
     total_quantity: number;
     discount_codes: CartDiscountCode[];
@@ -206,6 +224,7 @@ type Cart = {
     shipping_address: Address | null;
     delivery: CartDelivery;
     cost: CartCost;
+    note?: string | null;
     updated_at: string;
 };
 type CartLineInput = {
@@ -220,19 +239,59 @@ type CartBuyerInput = {
     email?: string | null;
     phone?: string | null;
 };
+/**
+ * A delivery rate. `id`, `title`, `cost` and `eta` are always present. The rest only
+ * comes from carrier addons (`commerce.shipping.rates`); `cost` already reflects a
+ * free-shipping code. Show it as is; never recompute.
+ */
 type ShippingRate = {
     id: string;
     title: string;
     cost: Money;
     eta: string | null;
+    /** Addon key of the rate provider. */
+    provider?: string;
+    carrier?: string | null;
+    service_code?: string | null;
+    eta_days_min?: number;
+    eta_days_max?: number;
+    /** e.g. `home`, `pickup_point`. */
+    delivery_type?: string | null;
+    pickup?: boolean;
+    taxes_included?: boolean | null;
+    /** RFC 3339: the quote is valid until then. */
+    expires_at?: string | null;
 };
 type PickupOption = {
     branch_id: string;
     name: string;
+    address?: string | null;
+    city?: string | null;
+};
+/** A rate provider that did not answer in time. */
+type UnavailableRateProvider = {
+    provider: string;
+    code: string;
 };
 type DeliveryOptions = {
+    /** Empty until the cart has a shipping address. Cheapest first. */
     rates: ShippingRate[];
     pickup: PickupOption[];
+    /** `true` when some provider failed: `rates` holds only what arrived. */
+    partial?: boolean;
+    unavailable?: UnavailableRateProvider[];
+};
+/** One way to pay (`GET /storefront/carts/:id/payment-methods`). `key` is sent as `payment_method` at checkout. */
+type PaymentMethod = {
+    key: string;
+    /** `builtin` (manual transfer/cash) or `provider` (a payment addon). */
+    kind: 'builtin' | 'provider';
+    default: boolean;
+};
+type PaymentMethods = {
+    methods: PaymentMethod[];
+    /** Market the request acted in; `null` when none. */
+    market: string | null;
 };
 type DeliveryInput = {
     method: DeliveryMethod;
@@ -240,31 +299,62 @@ type DeliveryInput = {
     branch_id?: string;
 };
 type InvoiceRequest = {
-    rfc?: string;
+    requested?: boolean;
+    tax_id?: string;
     legal_name?: string;
     tax_regime?: string;
-    zip?: string;
-    cfdi_use?: string;
-    email?: string;
+    /** CFDI use. */
+    use?: string;
+    postal_code?: string;
+    /** Spanish aliases the API also accepts. */
+    rfc?: string;
+    razon_social?: string;
+    regimen?: string;
+    uso_cfdi?: string;
+    cp?: string;
     [key: string]: unknown;
 };
 type CheckoutInput = {
+    /** `manual` or the `key` of a method from `carts.paymentMethods`. */
     payment_method: string;
     invoice?: InvoiceRequest;
+    /** Absolute URL; the API appends `?checkout=<id>` to it. */
     return_url: string;
+    note?: string;
 };
 type CheckoutPayment = {
     provider: string;
     status: string;
     redirect_url?: string | null;
     client_secret?: string | null;
+    /** What to do next (provider addons): `redirect`, `embed`, `voucher` or `none`. */
+    action_type?: string | null;
+    /** Isolated iframe URL of an embedded payment widget. */
+    embed_url?: string | null;
+    /** Offline instructions as data (OXXO reference, SPEI CLABE, deadline...). */
+    instructions_data?: Record<string, unknown>;
+    /** Offline payment instructions (OXXO reference, SPEI CLABE, manual transfer data) as text; `null` when none. */
+    instructions?: string | null;
+};
+type CheckoutInfo = {
+    /** Checkout session id; use it with `payment.instructions`. */
+    id: string;
+    /** e.g. `pending`, `paid`, `failed`, `cancelled`, `converted`. */
+    status: string;
+    external_order_id: string;
+    /** Amount to charge, computed by OPS (includes shipping and taxes). */
+    total: Money;
+    /** RFC 3339. Stock is held until then; `null` when nothing is held. */
+    stock_hold_expires_at: string | null;
 };
 type CheckoutResult = {
+    /** `number` is `null` until the order exists in OPS (it is created asynchronously after checkout). */
     order: {
         id: string;
-        number: string;
+        number: string | null;
     };
     payment: CheckoutPayment;
+    checkout: CheckoutInfo;
 };
 type Customer = {
     id: string;
@@ -372,4 +462,4 @@ type StorefrontErrorBody = {
     };
 };
 
-export type { ShopBranch as $, Address as A, Money as B, Cart as C, DeliveryInput as D, MoneyRange as E, Facet as F, OrderLine as G, PageInfo as H, Image as I, PickupOption as J, Product as K, ProductAttributeValue as L, Menu as M, ProductCategory as N, Order as O, Page as P, ProductConnection as Q, ProductOption as R, ProductSort as S, ProductVariant as T, ReturnRequest as U, ReturnRequestInput as V, SEO as W, Section as X, SelectedOption as Y, ShippingRate as Z, Shop as _, AddressInput as a, ShopContact as a0, ShopPolicies as a1, StockLevel as a2, StorefrontErrorBody as a3, StorefrontErrorCode as a4, Theme as a5, 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, CheckoutInput as l, CheckoutPayment as m, CheckoutResult as n, Collection as o, Connection as p, Customer as q, CustomerIdentifier as r, CustomerSession as s, CustomerSessionInput as t, DeliveryMethod as u, DeliveryOptions as v, FacetValue as w, InvoiceRequest as x, InvoiceResult as y, MenuItem as z };
+export type { SelectedOption as $, Address as A, MenuItem as B, Cart as C, DeliveryInput as D, Money as E, Facet as F, MoneyRange as G, OrderLine as H, Image as I, PageInfo as J, PaymentMethod as K, PaymentMethods as L, Menu as M, PickupOption as N, Order as O, Page as P, Product as Q, ProductAttributeValue as R, ProductCategory as S, ProductConnection as T, ProductOption as U, ProductSort as V, ProductVariant as W, ReturnRequest as X, ReturnRequestInput as Y, SEO as Z, Section as _, AddressInput as a, ShippingRate as a0, Shop as a1, ShopBranch as a2, ShopContact as a3, ShopPolicies as a4, StockLevel as a5, StorefrontErrorBody as a6, StorefrontErrorCode as a7, Theme as a8, UnavailableRateProvider as a9, 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 };

package/dist/{types-BdaQ9Pxq.d.ts → types-CTXB8Dnl.d.ts}

@@ -106,9 +106,10 @@ type ProductSort = 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'title_
 type ProductConnection = Connection<Product> & {
     facets: Facet[];
 };
+/** `quantity_available` is `null` when the variant's stock is not tracked (always sellable). */
 type StockLevel = {
     sku: string;
-    quantity_available: number;
+    quantity_available: number | null;
 };
 type ShopContact = {
     email: string | null;
@@ -159,6 +160,11 @@ type Address = {
     zip: string;
     country_code: string;
     phone: string | null;
+    /** Colonia. Sent and echoed by the cart API. */
+    neighborhood?: string | null;
+    province_code?: string | null;
+    /** Delivery reference ("between streets", gate code...). */
+    reference?: string | null;
 };
 type AddressInput = Partial<Omit<Address, 'id' | 'address1' | 'city' | 'zip' | 'country_code'>> & Pick<Address, 'address1' | 'city' | 'zip' | 'country_code'>;
 type CartLineMerchandise = ProductVariant & {
@@ -172,11 +178,14 @@ type CartLine = {
         total: Money;
         unit: Money;
         compare_at_unit: Money | null;
+        discount?: Money;
     };
 };
 type CartDiscountCode = {
     code: string;
     applicable: boolean;
+    /** Why an inapplicable code was not applied. */
+    reason?: string;
 };
 type CartBuyer = {
     email: string | null;
@@ -188,6 +197,12 @@ type CartDelivery = {
     method: DeliveryMethod | null;
     rate_id: string | null;
     branch_id: string | null;
+    /** Present when the chosen option is no longer valid (e.g. the quote expired). */
+    problem?: string;
+    /** Description of the chosen carrier rate (carrier addons only). */
+    title?: string | null;
+    carrier?: string | null;
+    eta?: string | null;
 };
 type CartCost = {
     subtotal: Money;
@@ -199,6 +214,9 @@ type CartCost = {
 };
 type Cart = {
     id: string;
+    /** `active` while it can be edited; anything else is a cart already turned into an order. */
+    status?: string;
+    currency_code?: string;
     lines: CartLine[];
     total_quantity: number;
     discount_codes: CartDiscountCode[];
@@ -206,6 +224,7 @@ type Cart = {
     shipping_address: Address | null;
     delivery: CartDelivery;
     cost: CartCost;
+    note?: string | null;
     updated_at: string;
 };
 type CartLineInput = {
@@ -220,19 +239,59 @@ type CartBuyerInput = {
     email?: string | null;
     phone?: string | null;
 };
+/**
+ * A delivery rate. `id`, `title`, `cost` and `eta` are always present. The rest only
+ * comes from carrier addons (`commerce.shipping.rates`); `cost` already reflects a
+ * free-shipping code. Show it as is; never recompute.
+ */
 type ShippingRate = {
     id: string;
     title: string;
     cost: Money;
     eta: string | null;
+    /** Addon key of the rate provider. */
+    provider?: string;
+    carrier?: string | null;
+    service_code?: string | null;
+    eta_days_min?: number;
+    eta_days_max?: number;
+    /** e.g. `home`, `pickup_point`. */
+    delivery_type?: string | null;
+    pickup?: boolean;
+    taxes_included?: boolean | null;
+    /** RFC 3339: the quote is valid until then. */
+    expires_at?: string | null;
 };
 type PickupOption = {
     branch_id: string;
     name: string;
+    address?: string | null;
+    city?: string | null;
+};
+/** A rate provider that did not answer in time. */
+type UnavailableRateProvider = {
+    provider: string;
+    code: string;
 };
 type DeliveryOptions = {
+    /** Empty until the cart has a shipping address. Cheapest first. */
     rates: ShippingRate[];
     pickup: PickupOption[];
+    /** `true` when some provider failed: `rates` holds only what arrived. */
+    partial?: boolean;
+    unavailable?: UnavailableRateProvider[];
+};
+/** One way to pay (`GET /storefront/carts/:id/payment-methods`). `key` is sent as `payment_method` at checkout. */
+type PaymentMethod = {
+    key: string;
+    /** `builtin` (manual transfer/cash) or `provider` (a payment addon). */
+    kind: 'builtin' | 'provider';
+    default: boolean;
+};
+type PaymentMethods = {
+    methods: PaymentMethod[];
+    /** Market the request acted in; `null` when none. */
+    market: string | null;
 };
 type DeliveryInput = {
     method: DeliveryMethod;
@@ -240,31 +299,62 @@ type DeliveryInput = {
     branch_id?: string;
 };
 type InvoiceRequest = {
-    rfc?: string;
+    requested?: boolean;
+    tax_id?: string;
     legal_name?: string;
     tax_regime?: string;
-    zip?: string;
-    cfdi_use?: string;
-    email?: string;
+    /** CFDI use. */
+    use?: string;
+    postal_code?: string;
+    /** Spanish aliases the API also accepts. */
+    rfc?: string;
+    razon_social?: string;
+    regimen?: string;
+    uso_cfdi?: string;
+    cp?: string;
     [key: string]: unknown;
 };
 type CheckoutInput = {
+    /** `manual` or the `key` of a method from `carts.paymentMethods`. */
     payment_method: string;
     invoice?: InvoiceRequest;
+    /** Absolute URL; the API appends `?checkout=<id>` to it. */
     return_url: string;
+    note?: string;
 };
 type CheckoutPayment = {
     provider: string;
     status: string;
     redirect_url?: string | null;
     client_secret?: string | null;
+    /** What to do next (provider addons): `redirect`, `embed`, `voucher` or `none`. */
+    action_type?: string | null;
+    /** Isolated iframe URL of an embedded payment widget. */
+    embed_url?: string | null;
+    /** Offline instructions as data (OXXO reference, SPEI CLABE, deadline...). */
+    instructions_data?: Record<string, unknown>;
+    /** Offline payment instructions (OXXO reference, SPEI CLABE, manual transfer data) as text; `null` when none. */
+    instructions?: string | null;
+};
+type CheckoutInfo = {
+    /** Checkout session id; use it with `payment.instructions`. */
+    id: string;
+    /** e.g. `pending`, `paid`, `failed`, `cancelled`, `converted`. */
+    status: string;
+    external_order_id: string;
+    /** Amount to charge, computed by OPS (includes shipping and taxes). */
+    total: Money;
+    /** RFC 3339. Stock is held until then; `null` when nothing is held. */
+    stock_hold_expires_at: string | null;
 };
 type CheckoutResult = {
+    /** `number` is `null` until the order exists in OPS (it is created asynchronously after checkout). */
     order: {
         id: string;
-        number: string;
+        number: string | null;
     };
     payment: CheckoutPayment;
+    checkout: CheckoutInfo;
 };
 type Customer = {
     id: string;
@@ -372,4 +462,4 @@ type StorefrontErrorBody = {
     };
 };
 
-export type { ShopBranch as $, Address as A, Money as B, Cart as C, DeliveryInput as D, MoneyRange as E, Facet as F, OrderLine as G, PageInfo as H, Image as I, PickupOption as J, Product as K, ProductAttributeValue as L, Menu as M, ProductCategory as N, Order as O, Page as P, ProductConnection as Q, ProductOption as R, ProductSort as S, ProductVariant as T, ReturnRequest as U, ReturnRequestInput as V, SEO as W, Section as X, SelectedOption as Y, ShippingRate as Z, Shop as _, AddressInput as a, ShopContact as a0, ShopPolicies as a1, StockLevel as a2, StorefrontErrorBody as a3, StorefrontErrorCode as a4, Theme as a5, 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, CheckoutInput as l, CheckoutPayment as m, CheckoutResult as n, Collection as o, Connection as p, Customer as q, CustomerIdentifier as r, CustomerSession as s, CustomerSessionInput as t, DeliveryMethod as u, DeliveryOptions as v, FacetValue as w, InvoiceRequest as x, InvoiceResult as y, MenuItem as z };
+export type { SelectedOption as $, Address as A, MenuItem as B, Cart as C, DeliveryInput as D, Money as E, Facet as F, MoneyRange as G, OrderLine as H, Image as I, PageInfo as J, PaymentMethod as K, PaymentMethods as L, Menu as M, PickupOption as N, Order as O, Page as P, Product as Q, ProductAttributeValue as R, ProductCategory as S, ProductConnection as T, ProductOption as U, ProductSort as V, ProductVariant as W, ReturnRequest as X, ReturnRequestInput as Y, SEO as Z, Section as _, AddressInput as a, ShippingRate as a0, Shop as a1, ShopBranch as a2, ShopContact as a3, ShopPolicies as a4, StockLevel as a5, StorefrontErrorBody as a6, StorefrontErrorCode as a7, Theme as a8, UnavailableRateProvider as a9, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/storefront",
-  "version": "0.1.0",
+  "version": "0.3.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": {