@cartbase/storefront 0.1.0

package/src/api/integrations.ts

@@ -0,0 +1,130 @@
+/**
+ * @cartbase/storefront/api/integrations — store-public integrations config
+ * (couriers-port + tracking-integrations cards).
+ *
+ * Ground truth: src/app/api/store/integrations/{route.ts,boxnow/lockers/
+ * route.ts} + src/lib/integrations/store-config.ts +
+ * src/lib/tracking/store-config-block.ts.
+ *
+ * The config payload is COMPOSED from an ordered block registry — each
+ * block owns distinct top-level keys (`carriers`, `cod`, `tracking` today;
+ * future blocks append). NOT wrapped in an envelope: the blocks ARE the
+ * top-level keys.
+ *
+ * SECURITY LAW: every block is an explicit allowlist — credentials
+ * (carrier API keys, CAPI access_token, GA4 api_secret, Klaviyo
+ * private_key) can NEVER appear in this payload; the contract tests assert
+ * it key-by-key.
+ */
+
+import type { StorefrontClient } from "./http"
+
+/** Public capability flags of one ENABLED carrier. */
+export interface PublicCarrierConfig {
+  enabled: true
+  /** Carrier supports cash-on-delivery collection. */
+  cod: boolean
+  /** Office/pickup-point delivery. */
+  pickup_points: boolean
+  /** Locker/APM network. */
+  lockers: boolean
+  /** Present only when lockers=true — the public locker-directory endpoint
+   * (path relative to the API base, e.g. `/api/store/integrations/boxnow/lockers`). */
+  lockers_url?: string
+}
+
+/** COD checkout block — null unless enabled AND fee_amount > 0 (the exact
+ * gate the totals engine applies, so the optimistic fee row never disagrees
+ * with the charged total). */
+export interface PublicCodConfig {
+  enabled: true
+  /** EUR major units. */
+  fee_amount: number
+  fee_currency: "eur"
+  fee_label: string
+  /** Admin's checkout note, or null. */
+  description: string | null
+}
+
+/** Public tag config — only ENABLED providers with a public id appear.
+ * Secrets can never appear here (explicit allowlist). */
+export interface StoreTrackingBlock {
+  facebookPixel?: { pixelId: string }
+  gtm?: { containerId: string }
+  ga4?: { measurementId: string }
+  klaviyo?: { publicKey: string }
+  googleAds?: { conversionId: string; conversionLabel?: string }
+  /** True when the store's consent CMP is enabled — mount tags ONLY through
+   * the consent gate (`_1c_consent` / Consent Mode v2). */
+  consent_required: boolean
+}
+
+/** The composed payload of GET /api/store/integrations. */
+export interface StoreIntegrationsConfig {
+  /** Keyed by provider slug (e.g. `boxnow`, `econt`). Disabled carriers are
+   * ABSENT, never `enabled: false`. */
+  carriers: Record<string, PublicCarrierConfig>
+  cod: PublicCodConfig | null
+  tracking: StoreTrackingBlock
+}
+
+/**
+ * GET /api/store/integrations — everything a storefront needs at render/
+ * checkout time about the store's integrations, secrets excluded by
+ * construction.
+ *
+ * Auth: anon (x-client-id); `x-publishable-api-key` is VALIDATED when the
+ * client sends one (unknown/revoked/foreign → 400 invalid_publishable_key)
+ * and may be omitted by single-channel storefronts.
+ * Errors: 400 missing_client_id · 400 invalid_publishable_key.
+ * Settings: admin → Settings → Integrations (per-provider enable/config);
+ * consent settings drive `tracking.consent_required`.
+ *
+ * Storefront wiring: mount tags from `tracking` + consent state; Purchase
+ * events MUST use `eventID = "purchase_" + order.display_id` so Meta
+ * dedupes browser Pixel vs server CAPI; write TrackingAttribution keys into
+ * `cart.metadata` (consent-gated) so server events inherit fbp/fbc/ga
+ * signals.
+ */
+export async function getIntegrationsConfig(
+  client: StorefrontClient
+): Promise<StoreIntegrationsConfig> {
+  return client.get("/api/store/integrations")
+}
+
+/** One BoxNow locker (APM) for the checkout picker. */
+export interface BoxNowLocker {
+  id: string
+  title: string
+  addressLine1: string
+  addressLine2: string
+  postalCode: string
+  country: string
+  /** Numbers or null — malformed carrier coordinates coerce to null, never NaN. */
+  lat: number | null
+  lng: number | null
+  note: string
+}
+
+export interface BoxNowLockersResponse {
+  lockers: BoxNowLocker[]
+}
+
+/**
+ * GET /api/store/integrations/boxnow/lockers — the BoxNow locker directory
+ * for the checkout locker picker. Cached hard (in-process 10-min TTL per
+ * store + `Cache-Control: public, max-age=600, stale-while-revalidate=3600`)
+ * — locker locations change on a weeks timescale.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 503 `{message, lockers: []}` when BoxNow is not configured/
+ * enabled for the store · 502 `{message, lockers: []}` when the carrier
+ * call fails. (Both carry the `lockers` key — a picker can always map over
+ * it.) Discover availability via `carriers.boxnow.lockers_url` on the
+ * integrations config instead of probing for the 503.
+ */
+export async function listBoxNowLockers(
+  client: StorefrontClient
+): Promise<BoxNowLockersResponse> {
+  return client.get("/api/store/integrations/boxnow/lockers")
+}

package/src/api/menus.ts

@@ -0,0 +1,77 @@
+/**
+ * @cartbase/storefront/api/menus — backend-owned navigation
+ * (content-navigation card).
+ *
+ * Ground truth: src/app/api/store/menus/[handle]/route.ts +
+ * src/lib/content/menus.ts.
+ *
+ * Shopify Storefront `Menu` shape verbatim. Item `url`s are COMPUTED AT
+ * READ TIME from live resource handles (src/lib/content/paths.ts) — a
+ * handle rename never breaks a menu. Items whose referenced resource is
+ * deleted or not storefront-visible (draft page/post/product, inactive or
+ * internal category) are SKIPPED, subtree included — the payload only ever
+ * contains renderable links. 3-level nesting max.
+ *
+ * ## ETag / caching semantics
+ * The route serves `ETag` (sha1 of the payload) +
+ * `Cache-Control: public, s-maxage=60, stale-while-revalidate=3600`, and
+ * answers `If-None-Match` with `304` (empty body). Browser `fetch` handles
+ * this transparently; server-side callers on Next.js should instead lean on
+ * the RSC cache (`next: { revalidate }`) via `RequestOptions`. Note the SDK
+ * itself does NOT replay ETags — a 304 only occurs when the caller's fetch
+ * layer sends `If-None-Match`, in which case the platform serves the cached
+ * body before the SDK sees it. The `menu.updated` event fires on every menu
+ * mutation for future revalidation hooks.
+ */
+
+import type { StorefrontClient } from "./http"
+
+/** One navigation node — recursive, ≤ 3 levels total. */
+export interface MenuItem {
+  title: string
+  /** What the item points at. */
+  type:
+    | "frontpage"
+    | "collection"
+    | "product"
+    | "category"
+    | "page"
+    | "blog_post"
+    | "external"
+  /**
+   * Computed at read time: `/` for frontpage, the shared path convention
+   * (`/collections/<handle>`, `/products/<handle>`, `/categories/<handle>`,
+   * `/pages/<handle>`, `/blogs/<blog>/<post>`) for resources, and the
+   * stored URL verbatim for `external`.
+   */
+  url: string
+  /** Referenced resource id (`pcol_…`, `prod_…`); null for frontpage/external. */
+  resourceId: string | null
+  items: MenuItem[]
+}
+
+export interface Menu {
+  handle: string
+  title: string
+  items: MenuItem[]
+}
+
+export interface MenuResponse {
+  menu: Menu
+}
+
+/**
+ * GET /api/store/menus/:handle — one menu, renderable links only.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown/deleted handle — a store with zero menus
+ * 404s every handle; render no nav, never crash).
+ * Settings: menus are authored in admin → Content → Navigation; deleting a
+ * referenced resource silently drops its item (subtree included) here.
+ */
+export async function getMenu(
+  client: StorefrontClient,
+  handle: string
+): Promise<MenuResponse> {
+  return client.get(`/api/store/menus/${encodeURIComponent(handle)}`)
+}

package/src/api/metaobjects.ts

@@ -0,0 +1,136 @@
+/**
+ * @cartbase/storefront/api/metaobjects — merchant-defined content types
+ * (metaobjects card): size charts, brand profiles, FAQ blocks…
+ *
+ * Ground truth: src/app/api/store/metaobjects/** +
+ * src/lib/metaobjects/store.ts.
+ *
+ * ACTIVE entries only — drafts 404 (lib filter AND anon RLS). Capabilities
+ * per definition: `renderable` → `seo` present; `online_store` → `url`
+ * present (`/metaobjects/<type>/<handle>`; the storefront prepends its
+ * origin). References resolve at READ time: a target the storefront cannot
+ * see yields `reference: null` — never dropped, never a 500.
+ *
+ * `by-metafield` is a RESERVED type slug (the static route shadows /:type).
+ */
+
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, PaginationQuery } from "./types"
+
+/** One field of a metaobject entry. */
+export interface MetaobjectField {
+  key: string
+  /** Field kind from the definition (text, rich_text, reference kinds…). */
+  kind: string
+  /** Raw stored value (shape depends on `kind`). */
+  value: unknown
+  /**
+   * Reference kinds only (absent otherwise). Resolved target, or null when
+   * the target is deleted / not storefront-visible. NOT resolved on LIST
+   * payloads — only the by-handle read and by-metafield resolve references.
+   */
+  reference?: { id: string; title: string; handle: string; type?: string } | null
+}
+
+export interface Metaobject {
+  id: string
+  /** The definition's type slug. */
+  type: string
+  handle: string
+  displayName: string
+  fields: MetaobjectField[]
+  /** Present only when the definition has the `renderable` capability.
+   * title falls back to displayName; description to null. */
+  seo?: { title: string; description: string | null }
+  /** Present only with the `online_store` capability:
+   * `/metaobjects/<type>/<handle>`. */
+  url?: string
+  updatedAt: IsoDateString
+}
+
+export type ListMetaobjectsQuery = PaginationQuery
+
+export interface MetaobjectListResponse {
+  metaobjects: Metaobject[]
+  count: number
+  offset: number
+  limit: number
+}
+
+/**
+ * GET /api/store/metaobjects/:type — paginated ACTIVE entries of one type,
+ * newest-updated first. `limit` clamped to 1–100 (default 20; out-of-range
+ * values are clamped, not rejected). List payloads carry RAW field values —
+ * `reference` is NOT resolved here (use getMetaobject for the resolve path).
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown type).
+ */
+export async function listMetaobjects(
+  client: StorefrontClient,
+  type: string,
+  query?: ListMetaobjectsQuery
+): Promise<MetaobjectListResponse> {
+  return client.get(`/api/store/metaobjects/${encodeURIComponent(type)}`, {
+    query: { ...query },
+  })
+}
+
+export interface MetaobjectResponse {
+  metaobject: Metaobject
+}
+
+/**
+ * GET /api/store/metaobjects/:type/:handle — one ACTIVE entry, references
+ * RESOLVED (invisible targets → `reference: null`).
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown type, unknown handle, or draft entry).
+ */
+export async function getMetaobject(
+  client: StorefrontClient,
+  type: string,
+  handle: string
+): Promise<MetaobjectResponse> {
+  return client.get(
+    `/api/store/metaobjects/${encodeURIComponent(type)}/${encodeURIComponent(handle)}`
+  )
+}
+
+export interface ByMetafieldQuery {
+  /** Owning entity type, e.g. `product`. */
+  entity_type: string
+  /** Owning entity id, e.g. `prod_…`. */
+  entity_id: string
+  /** The metafield key — its definition MUST be `metaobject_reference`. */
+  key: string
+}
+
+/**
+ * Response of the by-metafield chain. `metaobjects` is always present in
+ * stored order. `metaobject` (first entry or null) is present ONLY when the
+ * metafield definition is single-valued — LIST definitions return
+ * `{metaobjects}` alone.
+ */
+export interface ByMetafieldResponse {
+  metaobject?: Metaobject | null
+  metaobjects: Metaobject[]
+}
+
+/**
+ * GET /api/store/metaobjects/by-metafield — the product→size-chart fetch
+ * chain: resolve an entity's `metaobject_reference` METAFIELD into full
+ * metaobject payload(s), references resolved. Deliberate leak boundary:
+ * only `metaobject_reference` definitions resolve here (any other key →
+ * 404), and only ACTIVE entries return.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 invalid_data (missing entity_type/entity_id/key) ·
+ * 404 not_found (no such definition, wrong field_type, or no stored value).
+ */
+export async function getMetaobjectsByMetafield(
+  client: StorefrontClient,
+  query: ByMetafieldQuery
+): Promise<ByMetafieldResponse> {
+  return client.get("/api/store/metaobjects/by-metafield", { query: { ...query } })
+}

package/src/api/orders.ts

@@ -0,0 +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)
+}