@cartbase/storefront 0.1.0

package/src/api/products.ts

@@ -0,0 +1,303 @@
+/**
+ * @cartbase/storefront/api/products — products + product variants.
+ *
+ * The catalog read surface. Response shapes are the canonical store product
+ * object every discovery endpoint reuses (search results, collection
+ * membership pages, related products) — build ONE product-card renderer
+ * against `StoreProduct` and reuse it everywhere.
+ *
+ * Pricing: pass `currency_code` (or `region_id`) to receive
+ * `variant.calculated_price` (group-aware when a customer JWT is attached).
+ * Raw `prices` embeds contain BASE rows only — price-list rows are stripped
+ * server-side (leak rule) and surface exclusively through
+ * `calculated_price`. Docs: docs/storefront/products.md.
+ */
+import type { StorefrontClient } from "./http"
+import type {
+  CalculatedPrice,
+  IsoDateString,
+  ListEnvelope,
+  PaginationQuery,
+  PricingContextQuery,
+} from "./types"
+
+/** Raw base price row (`prices` table). Amounts are EUR-style major units. */
+export interface StorePriceRow {
+  id: string
+  amount: number
+  currency_code: string
+  min_quantity: number | null
+  max_quantity: number | null
+  price_set_id: string
+  /** Always null on the store surface — price-list rows are stripped. */
+  price_list_id: string | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+/**
+ * The wire shape of `variant.prices`: a price-set LINK embed, not a flat
+ * array. Base rows live at `prices[].price_set.prices[]`.
+ */
+export interface StoreVariantPriceSetLink {
+  price_set: { prices: StorePriceRow[] | null } | null
+}
+
+/** `variant.options[]` — the option VALUE with its parent option embedded. */
+export interface StoreVariantOptionValueLink {
+  value: {
+    id: string
+    value: string
+    option_id: string
+    metadata: Record<string, unknown> | null
+    option: StoreProductOption | null
+  } | null
+}
+
+export interface StoreProductOptionValue {
+  id: string
+  value: string
+  option_id: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface StoreProductOption {
+  id: string
+  title: string
+  product_id: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  /** Present on `product.options[]`; absent inside variant option links. */
+  values?: StoreProductOptionValue[]
+}
+
+export interface StoreProductImage {
+  id: string
+  url: string
+  rank: number
+  product_id: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface StoreProductVariant {
+  id: string
+  title: string
+  product_id: string
+  sku: string | null
+  barcode: string | null
+  ean: string | null
+  upc: string | null
+  thumbnail: string | null
+  allow_backorder: boolean
+  manage_inventory: boolean
+  variant_rank: number
+  weight: number | null
+  length: number | null
+  height: number | null
+  width: number | null
+  hs_code: string | null
+  origin_country: string | null
+  mid_code: string | null
+  material: string | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  options: StoreVariantOptionValueLink[]
+  /** Base-price rows via the price-set link embed (leak rule applied). */
+  prices: StoreVariantPriceSetLink[]
+  /**
+   * Present when a pricing context was resolvable (`currency_code` or
+   * `region_id` given); null otherwise, and null when no price matches the
+   * context. Varies by customer group — never cache shared.
+   */
+  calculated_price: CalculatedPrice | null
+}
+
+export interface StoreProduct {
+  id: string
+  title: string
+  subtitle: string | null
+  description: string | null
+  handle: string
+  status: "published"
+  thumbnail: string | null
+  is_giftcard: boolean
+  discountable: boolean
+  collection_id: string | null
+  type_id: string | null
+  external_id: string | null
+  weight: number | null
+  length: number | null
+  height: number | null
+  width: number | null
+  hs_code: string | null
+  origin_country: string | null
+  mid_code: string | null
+  material: string | null
+  /** SEO override; null = fall back to `title`. */
+  seo_title: string | null
+  /** SEO override; null = fall back to the plain-text `description`. */
+  seo_description: string | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  variants: StoreProductVariant[]
+  images: StoreProductImage[]
+  options: StoreProductOption[]
+  collection: { id: string; title: string; handle: string } | null
+  categories: Array<{ category: { id: string; name: string; handle: string } | null }>
+  tags: Array<{ tag: { id: string; value: string } | null }>
+  type: { id: string; value: string } | null
+}
+
+export interface ListProductsQuery extends PricingContextQuery, PaginationQuery {
+  /** Case-insensitive substring match on title (full search: use /search). */
+  q?: string
+  /** Product ids (joined as CSV on the wire). */
+  id?: string[]
+  handle?: string
+  collection_id?: string[]
+  category_id?: string[]
+  tag_id?: string[]
+  type_id?: string[]
+  /**
+   * Sort column; prefix with `-` for descending (e.g. `-created_at`,
+   * the default).
+   */
+  order?: string
+}
+
+export interface ProductListResponse extends ListEnvelope {
+  products: StoreProduct[]
+}
+
+export interface ProductResponse {
+  product: StoreProduct
+}
+
+export interface ListProductVariantsQuery extends PricingContextQuery, PaginationQuery {
+  /** Variant ids as CSV in ONE string (wire format of the route). */
+  id?: string
+  product_id?: string
+  sku?: string
+}
+
+export interface ProductVariantListResponse extends ListEnvelope {
+  variants: StoreProductVariant[]
+}
+
+export interface ProductVariantResponse {
+  variant: StoreProductVariant
+}
+
+/**
+ * List published products (newest first by default).
+ *
+ * Auth: anon (`x-client-id`); optional `x-publishable-api-key` restricts the
+ * catalog to products linked to the key's sales channels (a channel-scoped
+ * key with no matching products returns an empty list). Optional Bearer JWT
+ * makes `calculated_price` customer-group-aware.
+ *
+ * Errors: 400 `missing_client_id`, 400 `validation_failed`,
+ * 400 `invalid_publishable_key`, 400 `invalid_region`.
+ * Settings: price lists (B2B pricing), sales-channel product links,
+ * publishable-key channel bindings.
+ */
+export async function listProducts(
+  client: StorefrontClient,
+  query?: ListProductsQuery
+): Promise<ProductListResponse> {
+  return client.get("/api/store/products", { query: { ...query } })
+}
+
+/**
+ * Retrieve one product by id (`prod_…`) or handle — storefronts deep-link by
+ * handle.
+ *
+ * Auth: anon (`x-client-id`); optional publishable key + Bearer JWT as on
+ * the list. Errors: 404 `not_found` (unknown, draft — RLS-hidden — or
+ * outside the key's channels: invisible, not forbidden),
+ * 400 `invalid_publishable_key`, 400 `invalid_region`.
+ */
+export async function retrieveProduct(
+  client: StorefrontClient,
+  idOrHandle: string,
+  query?: PricingContextQuery
+): Promise<ProductResponse> {
+  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}`, {
+    query: { ...query },
+  })
+}
+
+/**
+ * List product variants (cart-line hydration). `id` accepts a CSV of variant
+ * ids for multi-lookup. Ordered by `variant_rank`.
+ *
+ * Auth: anon (`x-client-id`); optional Bearer JWT for group-aware
+ * `calculated_price`. NOTE: this listing is NOT publishable-key
+ * channel-scoped (scope applies to product reads). Errors:
+ * 400 `missing_client_id`, 400 `validation_failed`, 400 `invalid_region`.
+ */
+export async function listProductVariants(
+  client: StorefrontClient,
+  query?: ListProductVariantsQuery
+): Promise<ProductVariantListResponse> {
+  return client.get("/api/store/product-variants", { query: { ...query } })
+}
+
+/**
+ * Retrieve one variant by id, options + base prices hydrated,
+ * `calculated_price` when a pricing context is given.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`, 400 `invalid_region`.
+ */
+export async function retrieveProductVariant(
+  client: StorefrontClient,
+  variantId: string,
+  query?: PricingContextQuery
+): Promise<ProductVariantResponse> {
+  return client.get(`/api/store/product-variants/${encodeURIComponent(variantId)}`, {
+    query: { ...query },
+  })
+}
+
+/** A subscription offer on a product (PDP purchase options). */
+export interface StoreSellingPlan {
+  id: string
+  name: string
+  interval: "day" | "week" | "month" | "year"
+  interval_count: number
+  /** null = catalog price (the plan only sets the cadence). */
+  pricing_type: "percent" | "fixed" | null
+  pricing_value: number | null
+  min_cycles: number | null
+  max_cycles: number | null
+}
+
+export interface SellingPlanListResponse {
+  selling_plans: StoreSellingPlan[]
+  count: number
+}
+
+/**
+ * The subscription plans a product can be purchased with — render as PDP
+ * purchase options (one-time vs each plan). The chosen plan id goes on the
+ * cart line (`carts.addLineItem` `selling_plan_id`); the server applies the
+ * plan price. Empty list = product is one-time only.
+ *
+ * Auth: anon (`x-client-id`); publishable-key channel scope applies (same
+ * rule as the product read). Errors: 404 `not_found`.
+ */
+export async function listSellingPlans(
+  client: StorefrontClient,
+  idOrHandle: string
+): Promise<SellingPlanListResponse> {
+  return client.get(
+    `/api/store/products/${encodeURIComponent(idOrHandle)}/selling-plans`
+  )
+}

package/src/api/redirects.ts

@@ -0,0 +1,37 @@
+/**
+ * @cartbase/storefront/api/redirects — 404-path URL redirect lookup
+ * (seo-listings card 21).
+ *
+ * Ground truth: src/app/api/store/url-redirects/route.ts +
+ * src/lib/content/url-redirects.ts.
+ *
+ * HOT-PATH RULE: call this ONLY from the storefront's not-found handler
+ * (the 404 path) — never on regular page loads. Exact-match lookup,
+ * index-covered on (client_id, from_path). When `to_path` is non-null the
+ * storefront issues a 301 to it.
+ */
+
+import type { StorefrontClient } from "./http"
+
+export interface RedirectLookupResponse {
+  /** The path you asked about (echoed). */
+  path: string
+  /** Redirect target, or null when no redirect exists — render the 404. */
+  to_path: string | null
+}
+
+/**
+ * GET /api/store/url-redirects?path=… — look up a redirect for a missed
+ * pathname (e.g. `/products/old-handle`).
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 validation_failed (missing/empty path) · 400 missing_client_id.
+ * Settings: redirects are created in admin (and automatically on handle
+ * renames of products/collections/pages/posts).
+ */
+export async function lookupRedirect(
+  client: StorefrontClient,
+  path: string
+): Promise<RedirectLookupResponse> {
+  return client.get("/api/store/url-redirects", { query: { path } })
+}

package/src/api/regions.ts

@@ -0,0 +1,141 @@
+/**
+ * @cartbase/storefront/api/regions — regions, currencies, locales.
+ *
+ * Catalog-context primitives every storefront resolves at boot: which
+ * regions exist (→ `region_id` for the pricing context), which currencies
+ * the store has enabled, which locales it serves. All endpoints are anon
+ * reads (`x-client-id` scoping via RLS). Docs: docs/storefront/regions.md.
+ */
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
+
+/**
+ * A store region (`barter_commerce.regions` row). NOTE: barter regions carry
+ * NO embedded `countries` array on the store surface (divergence from
+ * Medusa's Store API — tax scoping is by `tax_regions` server-side).
+ */
+export interface StoreRegion {
+  id: string
+  name: string
+  /** Lowercase ISO currency, e.g. "eur" — feeds the pricing context. */
+  currency_code: string
+  automatic_taxes: boolean
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+/** Shared-catalog currency row, scoped to the store's enabled set on list. */
+export interface StoreCurrency {
+  /** Lowercase ISO code, e.g. "eur". */
+  code: string
+  name: string
+  symbol: string
+  symbol_native: string | null
+  decimal_digits: number
+  rounding: number
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface ListRegionsQuery extends PaginationQuery {
+  /** Case-insensitive substring match on region name. */
+  q?: string
+  /** Exact match (lowercased server-side). */
+  currency_code?: string
+}
+
+export interface RegionListResponse extends ListEnvelope {
+  regions: StoreRegion[]
+}
+
+export interface RegionResponse {
+  region: StoreRegion
+}
+
+export interface ListCurrenciesQuery extends PaginationQuery {
+  /** Exact code match (lowercased server-side). */
+  code?: string
+}
+
+export interface CurrencyListResponse extends ListEnvelope {
+  currencies: StoreCurrency[]
+}
+
+export interface CurrencyResponse {
+  currency: StoreCurrency
+}
+
+export interface LocaleListResponse {
+  /** Locale codes, store default first, then alphabetical (e.g. ["en","bg"]). */
+  locales: string[]
+}
+
+/**
+ * List the store's regions, ordered by name.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: regions are created in
+ * Admin → Settings → Regions; `limit` 1–200 (default 50).
+ */
+export async function listRegions(
+  client: StorefrontClient,
+  query?: ListRegionsQuery
+): Promise<RegionListResponse> {
+  return client.get("/api/store/regions", { query: { ...query } })
+}
+
+/**
+ * Retrieve one region by id.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found` (unknown id,
+ * soft-deleted, or another tenant's region — invisible, not forbidden).
+ */
+export async function retrieveRegion(
+  client: StorefrontClient,
+  regionId: string
+): Promise<RegionResponse> {
+  return client.get(`/api/store/regions/${encodeURIComponent(regionId)}`)
+}
+
+/**
+ * List the currencies ENABLED on this store (the `store_currencies` link
+ * filters the shared currency catalog). A store with none enabled returns an
+ * empty list, ordered by code.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: Admin → Settings → Store → currencies.
+ */
+export async function listCurrencies(
+  client: StorefrontClient,
+  query?: ListCurrenciesQuery
+): Promise<CurrencyListResponse> {
+  return client.get("/api/store/currencies", { query: { ...query } })
+}
+
+/**
+ * Retrieve one currency by code (case-insensitive).
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`.
+ *
+ * CODE-TRUTH NOTE: unlike the list, the single read is NOT filtered by the
+ * store's enabled set — any currency in the shared catalog resolves. Treat
+ * the list as the authority on what the store supports.
+ */
+export async function retrieveCurrency(
+  client: StorefrontClient,
+  code: string
+): Promise<CurrencyResponse> {
+  return client.get(`/api/store/currencies/${encodeURIComponent(code)}`)
+}
+
+/**
+ * List the store's supported locale codes (default locale first). Use to
+ * build the storefront language switcher and to set the client's `x-locale`.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`.
+ * Settings: Admin → Settings → Store → locales (per-store store_locales).
+ */
+export async function listLocales(client: StorefrontClient): Promise<LocaleListResponse> {
+  return client.get("/api/store/locales")
+}