@cartbase/storefront 0.17.0 → 0.18.0

package/src/api/orders.ts

@@ -1,290 +1,290 @@
-/**
- * @cartbase/storefront/api/orders — the authenticated customer's orders.
- *
- * EVERY function here requires a customer session
- * (`authorization: Bearer <jwt>` via the client's `getAuthToken`) — there
- * is no anonymous order read; a guest's only order handle is the
- * `completeCart()` response. Missing/invalid JWT → 401 `unauthenticated`.
- *
- * Route ground truth: src/app/api/store/orders/**. Doc:
- * docs/storefront/orders.md.
- *
- * `GET /api/store/orders/display/:displayId` was contract-listed but
- * missing from the codebase when this module was first written; the route
- * was built at the batch-9 merge and `retrieveOrderByDisplayId` wraps it.
- */
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, ListEnvelope, MajorUnitAmount } from "./types"
-
-// ---------------------------------------------------------------------------
-// DTOs — ground truth: orders/route.ts (list select `*`), orders/[id]/route.ts
-// (STORE_ORDER_DETAIL_SELECT), orders/[id]/transfer/*.
-// ---------------------------------------------------------------------------
-
-/** Order row as listed (plain `orders` columns, no embeds). */
-export interface StoreOrderSummaryRow {
-  id: string
-  /** Human-facing autoincrement. */
-  display_id: number
-  status: string
-  email: string | null
-  currency_code: string
-  customer_id: string | null
-  sales_channel_id: string | null
-  region_id: string | null
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  [key: string]: unknown
-}
-
-/** `order_line_items` row (title/prices/product snapshot at purchase time). */
-export interface StoreOrderLineItem {
-  id: string
-  title: string | null
-  subtitle: string | null
-  product_title: string | null
-  product_handle: string | null
-  thumbnail: string | null
-  variant_id: string | null
-  variant_title: string | null
-  variant_sku: string | null
-  unit_price: MajorUnitAmount
-  is_giftcard?: boolean
-  requires_shipping?: boolean
-  metadata: Record<string, unknown> | null
-  [key: string]: unknown
-}
-
-/** Version pivot row: quantity + the embedded line item. */
-export interface StoreOrderItem {
-  id: string
-  order_id: string
-  quantity: number
-  line_item: StoreOrderLineItem | null
-  [key: string]: unknown
-}
-
-export interface StoreFulfillmentLabel {
-  tracking_number: string | null
-  tracking_url: string | null
-}
-
-/** Store-safe fulfillment subset: lifecycle timestamps + tracking labels. */
-export interface StoreOrderFulfillment {
-  fulfillment: {
-    id: string
-    packed_at: IsoDateString | null
-    shipped_at: IsoDateString | null
-    delivered_at: IsoDateString | null
-    canceled_at: IsoDateString | null
-    labels: StoreFulfillmentLabel[]
-  } | null
-}
-
-/** `order_addresses` row. */
-export interface StoreOrderAddress {
-  id: string
-  first_name: string | null
-  last_name: string | null
-  company: string | null
-  address_1: string | null
-  address_2: string | null
-  city: string | null
-  country_code: string | null
-  province: string | null
-  postal_code: string | null
-  phone: string | null
-  [key: string]: unknown
-}
-
-/**
- * Order detail — a store-safe subset of the admin select: items (with
- * embedded line_item), fulfillments with tracking, both addresses. No
- * internal joins (customer row, payment internals) and NO internal staff
- * notes (timeline comments never cross this surface).
- */
-export interface StoreOrderDetail extends StoreOrderSummaryRow {
-  items: StoreOrderItem[]
-  fulfillments: StoreOrderFulfillment[]
-  shipping_address: StoreOrderAddress | null
-  billing_address: StoreOrderAddress | null
-}
-
-export interface ListOrdersQuery {
-  /** 1–200, default 20. */
-  limit?: number
-  /** Default 0. */
-  offset?: number
-  /** Exact-match filter on `orders.status` (e.g. `pending`, `completed`, `canceled`). */
-  status?: string
-}
-
-export interface OrderListResponse extends ListEnvelope {
-  orders: StoreOrderSummaryRow[]
-}
-
-export interface OrderResponse {
-  order: StoreOrderDetail
-}
-
-// ---------------------------------------------------------------------------
-// Reads
-// ---------------------------------------------------------------------------
-
-/**
- * List MY orders (newest first). → 200 `{orders, count, offset, limit}` —
- * plain order rows, no embeds (fetch the detail for items/tracking).
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`). Scoped to the session
- * customer — another customer's orders are invisible, not 403.
- * Errors: 401 `unauthenticated`, 400 `validation_failed` (bad
- * limit/offset).
- */
-export async function listOrders(
-  client: StorefrontClient,
-  query: ListOrdersQuery = {}
-): Promise<OrderListResponse> {
-  return client.get("/api/store/orders", { query: { ...query } })
-}
-
-/**
- * Retrieve MY order with items, fulfillments (+ tracking labels) and
- * addresses. → 200 `{order}`.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found` (unknown id OR an order
- * belonging to another customer — ownership is part of the lookup, so
- * cross-customer reads are indistinguishable from missing).
- */
-export async function retrieveOrder(
-  client: StorefrontClient,
-  orderId: string
-): Promise<OrderResponse> {
-  return client.get(`/api/store/orders/${orderId}`)
-}
-
-/**
- * Retrieve MY order by its human number: the autoincrement `display_id`
- * (numeric segment) or a `custom_display_id` (any segment; a numeric
- * custom id wins over a colliding display_id — it is the number the store
- * showed the customer). Same detail embeds + ownership scope as
- * `retrieveOrder`.
- * → 200 `{order}`.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found` (unknown number OR another
- * customer's order — indistinguishable by design).
- */
-export async function retrieveOrderByDisplayId(
-  client: StorefrontClient,
-  displayId: string | number
-): Promise<OrderResponse> {
-  return client.get(`/api/store/orders/display/${displayId}`)
-}
-
-// ---------------------------------------------------------------------------
-// Transfers — move a (guest) order to the authenticated customer.
-// Flow: the CLAIMING customer calls request → a token is issued for the
-// order's email holder → the claimer (whose email must match the order's)
-// calls accept with the token; decline/cancel end a pending transfer.
-// ---------------------------------------------------------------------------
-
-export interface RequestOrderTransferInput {
-  /** Free-text shown to the recipient; stored on the transfer action. */
-  description?: string
-}
-
-/**
- * request → `{order:{id, transfer:{requested:true}}}` — ALWAYS this shape,
- * for the first request and for duplicates alike. The transfer token is
- * email-delivered only and never crosses the store surface.
- */
-export interface RequestOrderTransferResponse {
-  order: {
-    id: string
-    transfer: { requested: true }
-  }
-}
-
-/**
- * Request the order be transferred to ME (the authenticated customer).
- * Idempotent: an existing pending transfer is returned, not duplicated.
- * → 200.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found`, 400 `already_owned`
- * (the order already belongs to this customer).
- */
-export async function requestOrderTransfer(
-  client: StorefrontClient,
-  orderId: string,
-  input: RequestOrderTransferInput = {}
-): Promise<RequestOrderTransferResponse> {
-  return client.post(`/api/store/orders/${orderId}/transfer/request`, input)
-}
-
-export interface CancelOrderTransferResponse {
-  order: { id: string; transfer: { canceled: true } }
-}
-
-/**
- * Cancel MY pending transfer request (only the requester may cancel).
- * → 200.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found` (order or no pending
- * transfer), 403 `forbidden` (not the requester).
- */
-export async function cancelOrderTransfer(
-  client: StorefrontClient,
-  orderId: string
-): Promise<CancelOrderTransferResponse> {
-  return client.post(`/api/store/orders/${orderId}/transfer/cancel`)
-}
-
-export interface AcceptOrderTransferInput {
-  /** The transfer token received by email (≥16 chars). */
-  token: string
-}
-
-/** accept → the full updated order row (now owned by the caller). */
-export interface AcceptOrderTransferResponse {
-  order: StoreOrderSummaryRow
-}
-
-/**
- * Accept a pending transfer with the emailed token — assigns the order to
- * the authenticated customer. The caller's email must equal the order's
- * original email (a leaked token alone is not enough). → 200 `{order}`.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found` (order / no pending
- * transfer), 403 `invalid_token` | `email_mismatch`, 400
- * `validation_failed`.
- */
-export async function acceptOrderTransfer(
-  client: StorefrontClient,
-  orderId: string,
-  input: AcceptOrderTransferInput
-): Promise<AcceptOrderTransferResponse> {
-  return client.post(`/api/store/orders/${orderId}/transfer/accept`, input)
-}
-
-export interface DeclineOrderTransferInput {
-  /** The transfer token received by email (≥16 chars). */
-  token: string
-}
-
-export interface DeclineOrderTransferResponse {
-  order: { id: string; transfer: { declined: true } }
-}
-
-/**
- * Decline a pending transfer (the order's original email holder rejects
- * it) — validates the token, then removes the pending action. → 200.
- * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
- * Errors: 401 `unauthenticated`, 404 `not_found`, 403 `invalid_token`,
- * 400 `validation_failed`.
- */
-export async function declineOrderTransfer(
-  client: StorefrontClient,
-  orderId: string,
-  input: DeclineOrderTransferInput
-): Promise<DeclineOrderTransferResponse> {
-  return client.post(`/api/store/orders/${orderId}/transfer/decline`, input)
-}
+/**
+ * @cartbase/storefront/api/orders — the authenticated customer's orders.
+ *
+ * EVERY function here requires a customer session
+ * (`authorization: Bearer <jwt>` via the client's `getAuthToken`) — there
+ * is no anonymous order read; a guest's only order handle is the
+ * `completeCart()` response. Missing/invalid JWT → 401 `unauthenticated`.
+ *
+ * Route ground truth: src/app/api/store/orders/**. Doc:
+ * docs/storefront/orders.md.
+ *
+ * `GET /api/store/orders/display/:displayId` was contract-listed but
+ * missing from the codebase when this module was first written; the route
+ * was built at the batch-9 merge and `retrieveOrderByDisplayId` wraps it.
+ */
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, ListEnvelope, MajorUnitAmount } from "./types"
+
+// ---------------------------------------------------------------------------
+// DTOs — ground truth: orders/route.ts (list select `*`), orders/[id]/route.ts
+// (STORE_ORDER_DETAIL_SELECT), orders/[id]/transfer/*.
+// ---------------------------------------------------------------------------
+
+/** Order row as listed (plain `orders` columns, no embeds). */
+export interface StoreOrderSummaryRow {
+  id: string
+  /** Human-facing autoincrement. */
+  display_id: number
+  status: string
+  email: string | null
+  currency_code: string
+  customer_id: string | null
+  sales_channel_id: string | null
+  region_id: string | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  [key: string]: unknown
+}
+
+/** `order_line_items` row (title/prices/product snapshot at purchase time). */
+export interface StoreOrderLineItem {
+  id: string
+  title: string | null
+  subtitle: string | null
+  product_title: string | null
+  product_handle: string | null
+  thumbnail: string | null
+  variant_id: string | null
+  variant_title: string | null
+  variant_sku: string | null
+  unit_price: MajorUnitAmount
+  is_giftcard?: boolean
+  requires_shipping?: boolean
+  metadata: Record<string, unknown> | null
+  [key: string]: unknown
+}
+
+/** Version pivot row: quantity + the embedded line item. */
+export interface StoreOrderItem {
+  id: string
+  order_id: string
+  quantity: number
+  line_item: StoreOrderLineItem | null
+  [key: string]: unknown
+}
+
+export interface StoreFulfillmentLabel {
+  tracking_number: string | null
+  tracking_url: string | null
+}
+
+/** Store-safe fulfillment subset: lifecycle timestamps + tracking labels. */
+export interface StoreOrderFulfillment {
+  fulfillment: {
+    id: string
+    packed_at: IsoDateString | null
+    shipped_at: IsoDateString | null
+    delivered_at: IsoDateString | null
+    canceled_at: IsoDateString | null
+    labels: StoreFulfillmentLabel[]
+  } | null
+}
+
+/** `order_addresses` row. */
+export interface StoreOrderAddress {
+  id: string
+  first_name: string | null
+  last_name: string | null
+  company: string | null
+  address_1: string | null
+  address_2: string | null
+  city: string | null
+  country_code: string | null
+  province: string | null
+  postal_code: string | null
+  phone: string | null
+  [key: string]: unknown
+}
+
+/**
+ * Order detail — a store-safe subset of the admin select: items (with
+ * embedded line_item), fulfillments with tracking, both addresses. No
+ * internal joins (customer row, payment internals) and NO internal staff
+ * notes (timeline comments never cross this surface).
+ */
+export interface StoreOrderDetail extends StoreOrderSummaryRow {
+  items: StoreOrderItem[]
+  fulfillments: StoreOrderFulfillment[]
+  shipping_address: StoreOrderAddress | null
+  billing_address: StoreOrderAddress | null
+}
+
+export interface ListOrdersQuery {
+  /** 1–200, default 20. */
+  limit?: number
+  /** Default 0. */
+  offset?: number
+  /** Exact-match filter on `orders.status` (e.g. `pending`, `completed`, `canceled`). */
+  status?: string
+}
+
+export interface OrderListResponse extends ListEnvelope {
+  orders: StoreOrderSummaryRow[]
+}
+
+export interface OrderResponse {
+  order: StoreOrderDetail
+}
+
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+
+/**
+ * List MY orders (newest first). → 200 `{orders, count, offset, limit}` —
+ * plain order rows, no embeds (fetch the detail for items/tracking).
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`). Scoped to the session
+ * customer — another customer's orders are invisible, not 403.
+ * Errors: 401 `unauthenticated`, 400 `validation_failed` (bad
+ * limit/offset).
+ */
+export async function listOrders(
+  client: StorefrontClient,
+  query: ListOrdersQuery = {}
+): Promise<OrderListResponse> {
+  return client.get("/api/store/orders", { query: { ...query } })
+}
+
+/**
+ * Retrieve MY order with items, fulfillments (+ tracking labels) and
+ * addresses. → 200 `{order}`.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found` (unknown id OR an order
+ * belonging to another customer — ownership is part of the lookup, so
+ * cross-customer reads are indistinguishable from missing).
+ */
+export async function retrieveOrder(
+  client: StorefrontClient,
+  orderId: string
+): Promise<OrderResponse> {
+  return client.get(`/api/store/orders/${orderId}`)
+}
+
+/**
+ * Retrieve MY order by its human number: the autoincrement `display_id`
+ * (numeric segment) or a `custom_display_id` (any segment; a numeric
+ * custom id wins over a colliding display_id — it is the number the store
+ * showed the customer). Same detail embeds + ownership scope as
+ * `retrieveOrder`.
+ * → 200 `{order}`.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found` (unknown number OR another
+ * customer's order — indistinguishable by design).
+ */
+export async function retrieveOrderByDisplayId(
+  client: StorefrontClient,
+  displayId: string | number
+): Promise<OrderResponse> {
+  return client.get(`/api/store/orders/display/${displayId}`)
+}
+
+// ---------------------------------------------------------------------------
+// Transfers — move a (guest) order to the authenticated customer.
+// Flow: the CLAIMING customer calls request → a token is issued for the
+// order's email holder → the claimer (whose email must match the order's)
+// calls accept with the token; decline/cancel end a pending transfer.
+// ---------------------------------------------------------------------------
+
+export interface RequestOrderTransferInput {
+  /** Free-text shown to the recipient; stored on the transfer action. */
+  description?: string
+}
+
+/**
+ * request → `{order:{id, transfer:{requested:true}}}` — ALWAYS this shape,
+ * for the first request and for duplicates alike. The transfer token is
+ * email-delivered only and never crosses the store surface.
+ */
+export interface RequestOrderTransferResponse {
+  order: {
+    id: string
+    transfer: { requested: true }
+  }
+}
+
+/**
+ * Request the order be transferred to ME (the authenticated customer).
+ * Idempotent: an existing pending transfer is returned, not duplicated.
+ * → 200.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found`, 400 `already_owned`
+ * (the order already belongs to this customer).
+ */
+export async function requestOrderTransfer(
+  client: StorefrontClient,
+  orderId: string,
+  input: RequestOrderTransferInput = {}
+): Promise<RequestOrderTransferResponse> {
+  return client.post(`/api/store/orders/${orderId}/transfer/request`, input)
+}
+
+export interface CancelOrderTransferResponse {
+  order: { id: string; transfer: { canceled: true } }
+}
+
+/**
+ * Cancel MY pending transfer request (only the requester may cancel).
+ * → 200.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found` (order or no pending
+ * transfer), 403 `forbidden` (not the requester).
+ */
+export async function cancelOrderTransfer(
+  client: StorefrontClient,
+  orderId: string
+): Promise<CancelOrderTransferResponse> {
+  return client.post(`/api/store/orders/${orderId}/transfer/cancel`)
+}
+
+export interface AcceptOrderTransferInput {
+  /** The transfer token received by email (≥16 chars). */
+  token: string
+}
+
+/** accept → the full updated order row (now owned by the caller). */
+export interface AcceptOrderTransferResponse {
+  order: StoreOrderSummaryRow
+}
+
+/**
+ * Accept a pending transfer with the emailed token — assigns the order to
+ * the authenticated customer. The caller's email must equal the order's
+ * original email (a leaked token alone is not enough). → 200 `{order}`.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found` (order / no pending
+ * transfer), 403 `invalid_token` | `email_mismatch`, 400
+ * `validation_failed`.
+ */
+export async function acceptOrderTransfer(
+  client: StorefrontClient,
+  orderId: string,
+  input: AcceptOrderTransferInput
+): Promise<AcceptOrderTransferResponse> {
+  return client.post(`/api/store/orders/${orderId}/transfer/accept`, input)
+}
+
+export interface DeclineOrderTransferInput {
+  /** The transfer token received by email (≥16 chars). */
+  token: string
+}
+
+export interface DeclineOrderTransferResponse {
+  order: { id: string; transfer: { declined: true } }
+}
+
+/**
+ * Decline a pending transfer (the order's original email holder rejects
+ * it) — validates the token, then removes the pending action. → 200.
+ * Auth: REQUIRED Bearer JWT (+ `x-client-id`).
+ * Errors: 401 `unauthenticated`, 404 `not_found`, 403 `invalid_token`,
+ * 400 `validation_failed`.
+ */
+export async function declineOrderTransfer(
+  client: StorefrontClient,
+  orderId: string,
+  input: DeclineOrderTransferInput
+): Promise<DeclineOrderTransferResponse> {
+  return client.post(`/api/store/orders/${orderId}/transfer/decline`, input)
+}

package/src/api/products.ts

@@ -125,6 +125,37 @@ export interface StoreProductVariant {
    * when absent, components fall back to the optimistic legacy behavior.
    */
   in_stock?: boolean
+  /**
+   * The variant's links to stock items, Medusa's inventory kit, present only
+   * when the read asked for them with `fields: SET_FIELDS`
+   * (`products/sets.ts`). A set's variant has one link per product inside
+   * it; a product sold on its own stock has one link to its own item.
+   */
+  inventory_items?: StoreInventoryItemLink[]
+}
+
+/** A variant drawing on a stock item, as a kit link names it. */
+export interface StoreInventoryLinkedVariant {
+  id: string
+  product_id: string
+  title: string | null
+  sku: string | null
+  product: { id: string; title: string; handle: string; thumbnail: string | null } | null
+}
+
+/** One link from a variant to a stock item, with how many units it takes. */
+export interface StoreInventoryItemLink {
+  inventory_item_id: string
+  required_quantity: number
+  inventory: {
+    id: string
+    /** Every stock item is born with its own variant's SKU. */
+    sku: string | null
+    title: string | null
+    thumbnail: string | null
+    /** Every live variant of a published product drawing on this item. */
+    variants: StoreInventoryLinkedVariant[]
+  } | null
 }
 
 export interface StoreProduct {
@@ -197,6 +228,17 @@ export interface ListProductsQuery extends PricingContextQuery, PaginationQuery
    * the default).
    */
   order?: string
+  /**
+   * Medusa's field selection. Only the kit links change the answer: pass
+   * `SET_FIELDS` (`products/sets.ts`) to receive `variants[].inventory_items`.
+   */
+  fields?: string
+}
+
+/** The one product read's query: the pricing context and the field selection. */
+export interface RetrieveProductQuery extends PricingContextQuery {
+  /** As on the list: `SET_FIELDS` adds `variants[].inventory_items`. */
+  fields?: string
 }
 
 export interface ProductListResponse extends ListEnvelope {
@@ -254,7 +296,7 @@ export async function listProducts(
 export async function retrieveProduct(
   client: StorefrontClient,
   idOrHandle: string,
-  query?: PricingContextQuery
+  query?: RetrieveProductQuery
 ): Promise<ProductResponse> {
   return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}`, {
     query: { ...query },