@cartbase/storefront 0.6.0 → 0.8.0

package/src/api/http.ts

@@ -4,9 +4,11 @@
  * Every SDK function in this package is a thin typed wrapper over
  * `storeFetch()` from a `StorefrontClient`. Auth model (store-api.md):
  *
- *  - `x-client-id`      — required for anon reads (RLS scope)
- *  - `x-publishable-api-key` — optional; scopes catalog/carts to the key's
- *                              sales channels when set
+ *  - `x-publishable-api-key` — THE store's key: names the store on its own
+ *                              (one key, 2026-09-07) and scopes catalog and
+ *                              carts to the key's sales channels
+ *  - `x-client-id`      — the platform's own door (hosted builds carry it);
+ *                          optional, wins over the key when both are sent
  *  - `authorization: Bearer <jwt>` — customer session (passwordless code
  *                              flow or supabase password login)
  *  - `x-locale`         — optional storefront locale hint
@@ -19,12 +21,16 @@
 import { StoreApiError } from "./types"
 
 export interface StorefrontClientConfig {
-  /** Deployment origin, e.g. `https://admin.mindpages.bg` */
+  /** Deployment origin, e.g. `https://admin.cartbase.ai` */
   baseUrl: string
-  /** Tenant id — required for anon reads. */
-  clientId: string
-  /** Publishable API key (channel scope). Optional for single-channel stores. */
+  /**
+   * The store's publishable key: names the store and scopes the catalog to
+   * the key's sales channels. The one input a merchant hands out; at least
+   * one of `publishableKey` and `clientId` is required.
+   */
   publishableKey?: string
+  /** Tenant id — the platform's own door. Optional when a key is given. */
+  clientId?: string
   /** Called per request; return the customer JWT or null for guests. */
   getAuthToken?: () => string | null | Promise<string | null>
   /** Called per request; return the active locale code or null. */
@@ -50,7 +56,9 @@ export interface RequestOptions {
 export class StorefrontClient {
   constructor(private readonly config: StorefrontClientConfig) {
     if (!config.baseUrl) throw new Error("StorefrontClient: baseUrl is required")
-    if (!config.clientId) throw new Error("StorefrontClient: clientId is required")
+    if (!config.publishableKey && !config.clientId) {
+      throw new Error("StorefrontClient: publishableKey (or clientId) is required")
+    }
   }
 
   /** The low-level typed request. Domain modules call this — apps rarely should. */
@@ -72,7 +80,7 @@ export class StorefrontClient {
     }
 
     const headers: Record<string, string> = {
-      "x-client-id": this.config.clientId,
+      ...(this.config.clientId ? { "x-client-id": this.config.clientId } : {}),
       ...(this.config.publishableKey
         ? { "x-publishable-api-key": this.config.publishableKey }
         : {}),

package/src/api/index.ts

@@ -13,6 +13,7 @@ export * as products from "./products"
 export * as collections from "./collections"
 export * as categories from "./categories"
 export * as regions from "./regions"
+export * as store from "./store"
 export * as carts from "./carts"
 export * as giftCards from "./gift-cards"
 export * as checkout from "./checkout"

package/src/api/integrations.ts

@@ -1,117 +1,118 @@
-/**
- * @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`, `tracking` today; future
- * blocks append). NOT wrapped in an envelope: the blocks ARE the top-level
- * keys. (The `cod` block died with the 'cod' integration, 2026-08-11 —
- * method fees now ride the payment listing entries themselves.)
- *
- * 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
-}
-
-/** 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>
-  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")
-}
+/**
+ * @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`, `tracking` today; future
+ * blocks append). NOT wrapped in an envelope: the blocks ARE the top-level
+ * keys. (The `cod` block died with the 'cod' integration, 2026-08-11 —
+ * method fees now ride the payment listing entries themselves.)
+ *
+ * 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
+}
+
+/** 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 }
+  tiktok?: { pixelId: 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>
+  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/store.ts

@@ -0,0 +1,35 @@
+/**
+ * @cartbase/storefront/api/store — the store's identity.
+ *
+ * Name, slug and brand (the merchant's Settings → Brand): what a
+ * storefront needs to title, head and foot itself without hardcoding a
+ * name. One anonymous read at layout level. Docs: docs/storefront/store.md.
+ */
+import type { StorefrontClient } from "./http"
+
+export interface StoreBrand {
+  /** Primary logo, public URL, or null. */
+  logo_url: string | null
+  /** Square mark, public URL, or null. */
+  logo_square_url: string | null
+  /** `#rrggbb` or null. */
+  color_primary: string | null
+  /** `#rrggbb` or null. */
+  color_secondary: string | null
+  slogan: string | null
+}
+
+export interface StoreIdentity {
+  /** The store's public id: what `<PlatformInit storeId>` mounts. */
+  id: string
+  /** The store's display name. */
+  name: string
+  /** The store's slug; its address is `{slug}.cartbase.net` until a custom domain. */
+  slug: string
+  brand: StoreBrand
+}
+
+/** GET /api/store/store — anon. */
+export function getStore(client: StorefrontClient): Promise<{ store: StoreIdentity }> {
+  return client.request<{ store: StoreIdentity }>("/api/store/store")
+}

package/src/checkout/geocode.ts

@@ -141,7 +141,7 @@ export async function geocodeAddress(
     url.searchParams.set("limit", "1")
 
     const res = await fetch(url.toString(), {
-      headers: { "User-Agent": "barter-storefront/1.0" },
+      headers: { "User-Agent": "cartbase-storefront/1.0" },
     })
     const data = await res.json()
     if (data?.[0]) {

package/src/lib/cookie-names.ts

@@ -39,3 +39,48 @@ export function readCartCookie(
 ): string | undefined {
   return get(CART_COOKIE) ?? get(LEGACY_CART_COOKIE)
 }
+
+/**
+ * THE VISITOR ID — our own per-browser id and the join key between browsing
+ * and money (ecommerce-analytics §3.1). It is OURS deliberately: the
+ * analytics engine is swappable, so a key owned by the engine would couple
+ * the whole platform to it.
+ *
+ * Written by the injected storefront proxy in a `Set-Cookie` header, never
+ * by `document.cookie`, and that is not a style preference: Safari's ITP
+ * caps JavaScript-written cookies at 7 days while server-set first-party
+ * cookies live up to 400. A JS-written id makes every returning Safari
+ * visitor read as new after a week.
+ */
+export const VISITOR_COOKIE = "_cartbase_visitor"
+
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_VISITOR_COOKIE = "_1c_anon"
+
+/** First-touch UTM tuple, written once, 365 days. */
+export const UTM_FIRST_COOKIE = "_cartbase_utm_first"
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_UTM_FIRST_COOKIE = "_1c_utm_first"
+
+/** Last-touch UTM tuple, rewritten on every UTM-bearing visit, 90 days. */
+export const UTM_LAST_COOKIE = "_cartbase_utm_last"
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_UTM_LAST_COOKIE = "_1c_utm_last"
+
+/** Known-visitor marker (localStorage, not a cookie). */
+export const KNOWN_VISITOR_KEY = "_cartbase_visitor_v1"
+/** @deprecated Pre-rename key — read-only compat, never written. */
+export const LEGACY_KNOWN_VISITOR_KEY = "_1c_visitor_v1"
+
+/**
+ * Read a value preferring the current name and falling back to the legacy
+ * one, so a visitor who arrived before the rename keeps their identity and
+ * their attribution instead of being counted as somebody new.
+ */
+export function readRenamedCookie(
+  get: (name: string) => string | undefined,
+  current: string,
+  legacy: string
+): string | undefined {
+  return get(current) ?? get(legacy)
+}

package/src/lib/platform.ts

@@ -0,0 +1,13 @@
+/**
+ * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
+ * a constant, not an input. Every Cartbase store's API lives here; a
+ * storefront overrides it only to point at a local or staging platform
+ * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
+ * publishable key does.
+ */
+export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
+
+/** The origin to call: the override when set, else the platform. */
+export function cartbaseApiOrigin(override?: string | null): string {
+  return (override && override.trim()) || CARTBASE_API_ORIGIN
+}

package/src/lib/visitor.ts

@@ -0,0 +1,74 @@
+import { VISITOR_COOKIE, LEGACY_VISITOR_COOKIE } from "./cookie-names"
+
+/**
+ * THE VISITOR'S TWO IDS. One module, because three copies of a cookie read
+ * had already appeared across the package and a fourth was about to.
+ *
+ *  - The VISITOR id is the durable one. It is written by the platform's
+ *    injected proxy as a `Set-Cookie` on the very first request, which is
+ *    what makes it survive: Safari caps a cookie written by JavaScript at
+ *    seven days, so a returning visitor read from a JS-written id looks new
+ *    every week. It is the join key between a browsing session and the cart
+ *    and order it becomes.
+ *  - The TAB SESSION id is per tab and dies with it. Two tabs are two
+ *    sessions, which is what a merchant counting live visitors sees on
+ *    their own screen.
+ */
+
+/**
+ * Reads the platform's first-party visitor cookie, preferring the current
+ * name and falling back to the pre-rename one. Server-side there is no
+ * document, and callers pass the value explicitly instead.
+ */
+export function readVisitorId(): string | undefined {
+  if (typeof document === "undefined") return undefined
+  for (const name of [VISITOR_COOKIE, LEGACY_VISITOR_COOKIE]) {
+    const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`))
+    if (match) return decodeURIComponent(match[1])
+  }
+  return undefined
+}
+
+const TAB_SESSION_KEY = "_cartbase_live_session"
+
+function randomId(): string {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * One id per tab, shared by the heartbeat and the pageview tracker so the
+ * live count and the traffic report are talking about the same sessions.
+ */
+export function getTabSessionId(): string {
+  try {
+    const existing = window.sessionStorage.getItem(TAB_SESSION_KEY)
+    if (existing) return existing
+    const id = randomId()
+    window.sessionStorage.setItem(TAB_SESSION_KEY, id)
+    return id
+  } catch {
+    // Private mode with storage blocked: a per-mount id still produces an
+    // honest count, it just does not survive a reload.
+    return randomId()
+  }
+}
+
+/**
+ * True when the platform's injected collector is already running on this
+ * page. It claims the flag synchronously, before hydration, so any React
+ * component that checks this on mount sees a settled answer.
+ *
+ * Why it exists: every deployed storefront gets the collector injected at
+ * deploy time, and the scaffold ALSO mounts <StorefrontTags>. Without this
+ * check every store built from the scaffold would count every pageview
+ * twice, which is the kind of defect that looks like growth.
+ */
+export function platformCollectorPresent(): boolean {
+  try {
+    return Boolean((window as unknown as { __cartbase_collector?: unknown }).__cartbase_collector)
+  } catch {
+    return false
+  }
+}