@cartbase/storefront 0.17.0 → 0.18.1

package/src/api/customers.ts

@@ -1,303 +1,303 @@
-/**
- * @cartbase/storefront/api/customers — customer profile, addresses, documents.
- *
- * Ground truth: src/app/api/store/customers/** + src/app/api/_lib/customer.ts.
- *
- * Auth model: every endpoint here except none is CUSTOMER-authenticated —
- * `authorization: Bearer <supabase jwt>` (minted by the passwordless code
- * flow in ./auth or a client-side supabase password sign-in) PLUS the anon
- * `x-client-id` tenant header the client always sends. Missing/invalid JWT →
- * `401 unauthenticated`.
- *
- * Lazy registration: `/customers/me` resolves the customer row by
- * (client_id, JWT email) and CREATES it on first authenticated call
- * (has_account=true, account_status per the store's approval policy) — a
- * fresh login never 404s on "me".
- */
-
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, PaginationQuery } from "./types"
-
-/** One row of `customer.addresses` (barter_commerce.customer_addresses), as the store serves it. */
-export interface CustomerAddress {
-  id: string
-  customer_id: string
-  address_name: string | null
-  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
-  is_default_billing: boolean
-  is_default_shipping: boolean
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-/**
- * The customer payload: the customer's own row as the store serves it, plus
- * addresses. Named columns since 2026-09-14: no tenant id, no soft-delete
- * stamp, no staff identity, no provider account id, and no merchant tags
- * (the labels a merchant puts on a customer are staff knowledge and never
- * reach the shopper).
- * `account_status` (`pending` | `approved`) gates B2B storefront content
- * when the store's approval policy is on (b2b-v1).
- */
-export interface StoreCustomer {
-  id: string
-  email: string | null
-  first_name: string | null
-  last_name: string | null
-  phone: string | null
-  company_name: string | null
-  /** Bulgarian company id (ЕИК) — feeds invoice-required checkout. */
-  company_eik: string | null
-  vat_number: string | null
-  has_account: boolean
-  /** `pending` | `approved` — store approval policy (customer-accounts card). */
-  account_status: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  addresses: CustomerAddress[]
-}
-
-export interface CustomerResponse {
-  customer: StoreCustomer
-}
-
-export interface CreateCustomerInput {
-  /** Must equal the session JWT's email — mismatch → 403 email_mismatch. */
-  email: string
-  first_name?: string
-  last_name?: string
-  phone?: string
-  company_name?: string
-}
-
-/**
- * POST /api/store/customers — guest-to-registered conversion (password
- * sign-up flow): call `supabase.auth.signUp({email, password})` client-side
- * first, then this with the same email. Upserts the (client_id, email)
- * customer row with has_account=true. NOT needed for the passwordless code
- * flow — verify already lazy-creates the customer.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 403 email_mismatch (body email ≠ JWT email)
- * · 400 validation_failed.
- * Settings: store approval policy decides account_status of a NEW row.
- */
-export async function createCustomer(
-  client: StorefrontClient,
-  input: CreateCustomerInput
-): Promise<CustomerResponse> {
-  return client.post("/api/store/customers", input)
-}
-
-/**
- * GET /api/store/customers/me — the signed-in customer, addresses embedded.
- * Lazy-creates the customer row on first call for this (tenant, email).
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 400 missing_client_id.
- */
-export async function getMe(client: StorefrontClient): Promise<CustomerResponse> {
-  return client.get("/api/store/customers/me")
-}
-
-export interface UpdateCustomerInput {
-  first_name?: string | null
-  last_name?: string | null
-  phone?: string | null
-  company_name?: string | null
-  /** ЕИК / VAT (customer-master-data) — loose format, never shape-blocked. */
-  company_eik?: string | null
-  vat_number?: string | null
-  metadata?: Record<string, unknown>
-}
-
-/**
- * POST /api/store/customers/me — update own profile. Unknown keys are
- * stripped server-side; returns the refreshed customer.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 400 validation_failed.
- */
-export async function updateMe(
-  client: StorefrontClient,
-  input: UpdateCustomerInput
-): Promise<CustomerResponse> {
-  return client.post("/api/store/customers/me", input)
-}
-
-export interface AddressListResponse {
-  addresses: CustomerAddress[]
-  /** Not truly paginated: offset is always 0 and limit === count. */
-  count: number
-  offset: number
-  limit: number
-}
-
-/**
- * GET /api/store/customers/me/addresses — all of the customer's addresses
- * (created_at asc). The list envelope is nominal — the route returns EVERY
- * address (offset 0, limit = count); no query params are read.
- *
- * Auth: Bearer JWT (+ x-client-id). Errors: 401 unauthenticated.
- */
-export async function listAddresses(
-  client: StorefrontClient
-): Promise<AddressListResponse> {
-  return client.get("/api/store/customers/me/addresses")
-}
-
-export interface CreateAddressInput {
-  address_name?: string
-  first_name?: string
-  last_name?: string
-  company?: string
-  address_1?: string
-  address_2?: string
-  city?: string
-  /** Lower-cased server-side. */
-  country_code?: string
-  province?: string
-  postal_code?: string
-  phone?: string
-  /** true clears the flag on every sibling first (one default per kind). */
-  is_default_billing?: boolean
-  is_default_shipping?: boolean
-  metadata?: Record<string, unknown>
-}
-
-/**
- * POST /api/store/customers/me/addresses — create an address. Returns the
- * FULL refreshed customer (`{customer}`, addresses embedded) — not the
- * created address alone; find it in `customer.addresses`.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 400 validation_failed.
- */
-export async function createAddress(
-  client: StorefrontClient,
-  input: CreateAddressInput
-): Promise<CustomerResponse> {
-  return client.post("/api/store/customers/me/addresses", input)
-}
-
-export interface AddressResponse {
-  address: CustomerAddress
-}
-
-/**
- * GET /api/store/customers/me/addresses/:id — one owned address.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 404 not_found (unknown OR another
- * customer's address — ownership 404s, it never 403s).
- */
-export async function getAddress(
-  client: StorefrontClient,
-  addressId: string
-): Promise<AddressResponse> {
-  return client.get(`/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`)
-}
-
-export interface UpdateAddressInput {
-  address_name?: string | null
-  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
-  is_default_billing?: boolean
-  is_default_shipping?: boolean
-  metadata?: Record<string, unknown>
-}
-
-/**
- * POST /api/store/customers/me/addresses/:id — partial update; default
- * flags clear siblings. Returns the FULL refreshed customer.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 404 not_found · 400 validation_failed.
- */
-export async function updateAddress(
-  client: StorefrontClient,
-  addressId: string,
-  input: UpdateAddressInput
-): Promise<CustomerResponse> {
-  return client.post(
-    `/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`,
-    input
-  )
-}
-
-/**
- * DELETE /api/store/customers/me/addresses/:id — soft-delete an owned
- * address. Returns the FULL refreshed customer (the address gone from
- * `customer.addresses`).
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 404 not_found.
- */
-export async function deleteAddress(
-  client: StorefrontClient,
-  addressId: string
-): Promise<CustomerResponse> {
-  return client.delete(
-    `/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`
-  )
-}
-
-/** One issued (non-void) order document — the account "Invoices" row. */
-export interface CustomerDocument {
-  id: string
-  order_id: string
-  order_display_id: number | null
-  doc_type: string
-  number: string
-  issued_at: IsoDateString
-  pdf_url: string | null
-  due_date: IsoDateString | null
-  paid_at: IsoDateString | null
-}
-
-export interface ListDocumentsQuery extends PaginationQuery {
-  /** Filter by document type (e.g. `invoice`). */
-  doc_type?: string
-}
-
-export interface DocumentListResponse {
-  documents: CustomerDocument[]
-  count: number
-  offset: number
-  limit: number
-}
-
-/**
- * GET /api/store/customers/me/documents — the customer's issued order
- * documents, newest first (issued_at desc). Voided documents excluded.
- * Ownership is INNER-join enforced (session customer id AND client_id) —
- * cross-customer reads are impossible. `limit` ≤ 200, default 20.
- *
- * Auth: Bearer JWT (+ x-client-id).
- * Errors: 401 unauthenticated · 400 validation_failed.
- */
-export async function listMyDocuments(
-  client: StorefrontClient,
-  query?: ListDocumentsQuery
-): Promise<DocumentListResponse> {
-  return client.get("/api/store/customers/me/documents", { query: { ...query } })
-}
+/**
+ * @cartbase/storefront/api/customers — customer profile, addresses, documents.
+ *
+ * Ground truth: src/app/api/store/customers/** + src/app/api/_lib/customer.ts.
+ *
+ * Auth model: every endpoint here except none is CUSTOMER-authenticated —
+ * `authorization: Bearer <supabase jwt>` (minted by the passwordless code
+ * flow in ./auth or a client-side supabase password sign-in) PLUS the anon
+ * `x-client-id` tenant header the client always sends. Missing/invalid JWT →
+ * `401 unauthenticated`.
+ *
+ * Lazy registration: `/customers/me` resolves the customer row by
+ * (client_id, JWT email) and CREATES it on first authenticated call
+ * (has_account=true, account_status per the store's approval policy) — a
+ * fresh login never 404s on "me".
+ */
+
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, PaginationQuery } from "./types"
+
+/** One row of `customer.addresses` (barter_commerce.customer_addresses), as the store serves it. */
+export interface CustomerAddress {
+  id: string
+  customer_id: string
+  address_name: string | null
+  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
+  is_default_billing: boolean
+  is_default_shipping: boolean
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+/**
+ * The customer payload: the customer's own row as the store serves it, plus
+ * addresses. Named columns since 2026-09-14: no tenant id, no soft-delete
+ * stamp, no staff identity, no provider account id, and no merchant tags
+ * (the labels a merchant puts on a customer are staff knowledge and never
+ * reach the shopper).
+ * `account_status` (`pending` | `approved`) gates B2B storefront content
+ * when the store's approval policy is on (b2b-v1).
+ */
+export interface StoreCustomer {
+  id: string
+  email: string | null
+  first_name: string | null
+  last_name: string | null
+  phone: string | null
+  company_name: string | null
+  /** Bulgarian company id (ЕИК) — feeds invoice-required checkout. */
+  company_eik: string | null
+  vat_number: string | null
+  has_account: boolean
+  /** `pending` | `approved` — store approval policy (customer-accounts card). */
+  account_status: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  addresses: CustomerAddress[]
+}
+
+export interface CustomerResponse {
+  customer: StoreCustomer
+}
+
+export interface CreateCustomerInput {
+  /** Must equal the session JWT's email — mismatch → 403 email_mismatch. */
+  email: string
+  first_name?: string
+  last_name?: string
+  phone?: string
+  company_name?: string
+}
+
+/**
+ * POST /api/store/customers — guest-to-registered conversion (password
+ * sign-up flow): call `supabase.auth.signUp({email, password})` client-side
+ * first, then this with the same email. Upserts the (client_id, email)
+ * customer row with has_account=true. NOT needed for the passwordless code
+ * flow — verify already lazy-creates the customer.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 403 email_mismatch (body email ≠ JWT email)
+ * · 400 validation_failed.
+ * Settings: store approval policy decides account_status of a NEW row.
+ */
+export async function createCustomer(
+  client: StorefrontClient,
+  input: CreateCustomerInput
+): Promise<CustomerResponse> {
+  return client.post("/api/store/customers", input)
+}
+
+/**
+ * GET /api/store/customers/me — the signed-in customer, addresses embedded.
+ * Lazy-creates the customer row on first call for this (tenant, email).
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 400 missing_client_id.
+ */
+export async function getMe(client: StorefrontClient): Promise<CustomerResponse> {
+  return client.get("/api/store/customers/me")
+}
+
+export interface UpdateCustomerInput {
+  first_name?: string | null
+  last_name?: string | null
+  phone?: string | null
+  company_name?: string | null
+  /** ЕИК / VAT (customer-master-data) — loose format, never shape-blocked. */
+  company_eik?: string | null
+  vat_number?: string | null
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * POST /api/store/customers/me — update own profile. Unknown keys are
+ * stripped server-side; returns the refreshed customer.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 400 validation_failed.
+ */
+export async function updateMe(
+  client: StorefrontClient,
+  input: UpdateCustomerInput
+): Promise<CustomerResponse> {
+  return client.post("/api/store/customers/me", input)
+}
+
+export interface AddressListResponse {
+  addresses: CustomerAddress[]
+  /** Not truly paginated: offset is always 0 and limit === count. */
+  count: number
+  offset: number
+  limit: number
+}
+
+/**
+ * GET /api/store/customers/me/addresses — all of the customer's addresses
+ * (created_at asc). The list envelope is nominal — the route returns EVERY
+ * address (offset 0, limit = count); no query params are read.
+ *
+ * Auth: Bearer JWT (+ x-client-id). Errors: 401 unauthenticated.
+ */
+export async function listAddresses(
+  client: StorefrontClient
+): Promise<AddressListResponse> {
+  return client.get("/api/store/customers/me/addresses")
+}
+
+export interface CreateAddressInput {
+  address_name?: string
+  first_name?: string
+  last_name?: string
+  company?: string
+  address_1?: string
+  address_2?: string
+  city?: string
+  /** Lower-cased server-side. */
+  country_code?: string
+  province?: string
+  postal_code?: string
+  phone?: string
+  /** true clears the flag on every sibling first (one default per kind). */
+  is_default_billing?: boolean
+  is_default_shipping?: boolean
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * POST /api/store/customers/me/addresses — create an address. Returns the
+ * FULL refreshed customer (`{customer}`, addresses embedded) — not the
+ * created address alone; find it in `customer.addresses`.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 400 validation_failed.
+ */
+export async function createAddress(
+  client: StorefrontClient,
+  input: CreateAddressInput
+): Promise<CustomerResponse> {
+  return client.post("/api/store/customers/me/addresses", input)
+}
+
+export interface AddressResponse {
+  address: CustomerAddress
+}
+
+/**
+ * GET /api/store/customers/me/addresses/:id — one owned address.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 404 not_found (unknown OR another
+ * customer's address — ownership 404s, it never 403s).
+ */
+export async function getAddress(
+  client: StorefrontClient,
+  addressId: string
+): Promise<AddressResponse> {
+  return client.get(`/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`)
+}
+
+export interface UpdateAddressInput {
+  address_name?: string | null
+  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
+  is_default_billing?: boolean
+  is_default_shipping?: boolean
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * POST /api/store/customers/me/addresses/:id — partial update; default
+ * flags clear siblings. Returns the FULL refreshed customer.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 404 not_found · 400 validation_failed.
+ */
+export async function updateAddress(
+  client: StorefrontClient,
+  addressId: string,
+  input: UpdateAddressInput
+): Promise<CustomerResponse> {
+  return client.post(
+    `/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`,
+    input
+  )
+}
+
+/**
+ * DELETE /api/store/customers/me/addresses/:id — soft-delete an owned
+ * address. Returns the FULL refreshed customer (the address gone from
+ * `customer.addresses`).
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 404 not_found.
+ */
+export async function deleteAddress(
+  client: StorefrontClient,
+  addressId: string
+): Promise<CustomerResponse> {
+  return client.delete(
+    `/api/store/customers/me/addresses/${encodeURIComponent(addressId)}`
+  )
+}
+
+/** One issued (non-void) order document — the account "Invoices" row. */
+export interface CustomerDocument {
+  id: string
+  order_id: string
+  order_display_id: number | null
+  doc_type: string
+  number: string
+  issued_at: IsoDateString
+  pdf_url: string | null
+  due_date: IsoDateString | null
+  paid_at: IsoDateString | null
+}
+
+export interface ListDocumentsQuery extends PaginationQuery {
+  /** Filter by document type (e.g. `invoice`). */
+  doc_type?: string
+}
+
+export interface DocumentListResponse {
+  documents: CustomerDocument[]
+  count: number
+  offset: number
+  limit: number
+}
+
+/**
+ * GET /api/store/customers/me/documents — the customer's issued order
+ * documents, newest first (issued_at desc). Voided documents excluded.
+ * Ownership is INNER-join enforced (session customer id AND client_id) —
+ * cross-customer reads are impossible. `limit` ≤ 200, default 20.
+ *
+ * Auth: Bearer JWT (+ x-client-id).
+ * Errors: 401 unauthenticated · 400 validation_failed.
+ */
+export async function listMyDocuments(
+  client: StorefrontClient,
+  query?: ListDocumentsQuery
+): Promise<DocumentListResponse> {
+  return client.get("/api/store/customers/me/documents", { query: { ...query } })
+}