@cartbase/storefront 0.19.0 → 0.20.1

package/src/api/menus.ts

@@ -1,77 +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)}`)
-}
+/**
+ * @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

@@ -1,136 +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 } })
-}
+/**
+ * @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 } })
+}