@cartbase/storefront 0.20.0 → 0.20.1

package/src/api/regions.ts

@@ -1,200 +1,200 @@
-/**
- * @cartbase/storefront/api/regions — regions, countries, currencies, locales.
- *
- * Catalog-context primitives every storefront resolves at boot: which
- * regions exist (→ `region_id` for the pricing context), which countries the
- * store sells to, which currencies it 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: Cartbase regions carry
- * NO embedded `countries` array on the store surface (divergence from
- * Medusa's Store API — tax scoping is by `tax_regions` server-side). The
- * countries are their own call, `listCountries`, and each row carries the
- * `region_id` it belongs to.
- */
-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
-}
-
-/**
- * A country a shopper may choose (`barter_commerce.countries` row, the store's
- * own tenant catalogue).
- */
-export interface StoreCountry {
-  /** Lowercase ISO-3166 alpha-2, e.g. "bg" — the value a cart address takes. */
-  iso_2: string
-  /** What a shopper reads, e.g. "Bulgaria". The code is never shown as copy. */
-  display_name: string
-  /** The catalogue's uppercase form, e.g. "BULGARIA". */
-  name: string
-  /** The region this country belongs to, null when the store has not placed it. */
-  region_id: string | null
-}
-
-export interface ListCountriesQuery extends PaginationQuery {
-  /** Case-insensitive substring match on the displayed name. */
-  q?: string
-}
-
-export interface CountryListResponse extends ListEnvelope {
-  countries: StoreCountry[]
-  /**
-   * True when this list IS the store's Markets declaration; false when the
-   * store has declared nothing and this is the whole ISO catalogue.
-   */
-  restricted: boolean
-}
-
-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 countries a shopper may choose at checkout, ordered by the name
- * they read.
- *
- * THE RULE IS THE PLATFORM'S, NOT THE STOREFRONT'S: the store's own Markets
- * decide where it sells, and a store that has decided nothing yet sells to
- * the whole world. So this answers with the countries the store's regions
- * declare, and with the whole 250-entry catalogue when it declares none;
- * `restricted` says which you got. A storefront therefore never hardcodes a
- * country list, and never has to invent a fallback of its own.
- *
- * `useCheckoutOrchestration` calls this for you when you do not pass it a
- * `countries` list, so a new store offers every country with no wiring at
- * all. Pass your own list only to override the store's answer.
- *
- * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
- * 400 `validation_failed`. Settings: Admin → Settings → Markets → Regions,
- * where a region owns its countries; `limit` 1–300 (default 300, so one
- * call carries the entire catalogue).
- */
-export async function listCountries(
-  client: StorefrontClient,
-  query?: ListCountriesQuery
-): Promise<CountryListResponse> {
-  return client.get("/api/store/countries", { query: { ...query } })
-}
-
-/**
- * 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")
-}
+/**
+ * @cartbase/storefront/api/regions — regions, countries, currencies, locales.
+ *
+ * Catalog-context primitives every storefront resolves at boot: which
+ * regions exist (→ `region_id` for the pricing context), which countries the
+ * store sells to, which currencies it 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: Cartbase regions carry
+ * NO embedded `countries` array on the store surface (divergence from
+ * Medusa's Store API — tax scoping is by `tax_regions` server-side). The
+ * countries are their own call, `listCountries`, and each row carries the
+ * `region_id` it belongs to.
+ */
+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
+}
+
+/**
+ * A country a shopper may choose (`barter_commerce.countries` row, the store's
+ * own tenant catalogue).
+ */
+export interface StoreCountry {
+  /** Lowercase ISO-3166 alpha-2, e.g. "bg" — the value a cart address takes. */
+  iso_2: string
+  /** What a shopper reads, e.g. "Bulgaria". The code is never shown as copy. */
+  display_name: string
+  /** The catalogue's uppercase form, e.g. "BULGARIA". */
+  name: string
+  /** The region this country belongs to, null when the store has not placed it. */
+  region_id: string | null
+}
+
+export interface ListCountriesQuery extends PaginationQuery {
+  /** Case-insensitive substring match on the displayed name. */
+  q?: string
+}
+
+export interface CountryListResponse extends ListEnvelope {
+  countries: StoreCountry[]
+  /**
+   * True when this list IS the store's Markets declaration; false when the
+   * store has declared nothing and this is the whole ISO catalogue.
+   */
+  restricted: boolean
+}
+
+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 countries a shopper may choose at checkout, ordered by the name
+ * they read.
+ *
+ * THE RULE IS THE PLATFORM'S, NOT THE STOREFRONT'S: the store's own Markets
+ * decide where it sells, and a store that has decided nothing yet sells to
+ * the whole world. So this answers with the countries the store's regions
+ * declare, and with the whole 250-entry catalogue when it declares none;
+ * `restricted` says which you got. A storefront therefore never hardcodes a
+ * country list, and never has to invent a fallback of its own.
+ *
+ * `useCheckoutOrchestration` calls this for you when you do not pass it a
+ * `countries` list, so a new store offers every country with no wiring at
+ * all. Pass your own list only to override the store's answer.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: Admin → Settings → Markets → Regions,
+ * where a region owns its countries; `limit` 1–300 (default 300, so one
+ * call carries the entire catalogue).
+ */
+export async function listCountries(
+  client: StorefrontClient,
+  query?: ListCountriesQuery
+): Promise<CountryListResponse> {
+  return client.get("/api/store/countries", { query: { ...query } })
+}
+
+/**
+ * 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")
+}