@kasuvia/sdk 0.0.8 → 0.0.9

package/src/utils/guest-session.ts

@@ -0,0 +1,59 @@
+/**
+ * Guest Cart Session
+ *
+ * REAL BUG FIXED (2026-09-21): kasuvia-cart-management's real
+ * `POST /api/v1/cart/*` routes hard-require an `X-Guest-Session` header for
+ * any anonymous (unauthenticated) caller — confirmed against the live
+ * backend (cart.go's `resolveTenant`/guest-path branches): with no
+ * Authorization and no X-Guest-Session, add-to-cart returns 401
+ * "Authentication required. Please log in or provide a guest session."
+ * `useCart()` has always accepted a `guestSessionId` parameter for exactly
+ * this, but nothing anywhere in kasuvia-storefront ever generated or passed
+ * one — every real `useCart()` call site called it with zero arguments. That
+ * meant anonymous add-to-cart has never worked at all on the real storefront:
+ * `addToCartMutation` throws 'Cannot add to cart: no access token or guest
+ * session ID provided.' client-side before a request is even sent.
+ *
+ * This generates and persists one real guest session id per browser (via the
+ * existing tenant-isolated `localStore` — already prefixed per business_id,
+ * so multiple businesses tested on the same origin never collide), reused by
+ * `SdkProvider` to feed every `useCart()` call through context automatically
+ * (see sdk-context.tsx), the same way `config`/`accessToken` already are.
+ */
+import { localStore } from './storage'
+
+const GUEST_SESSION_KEY = 'guest_session_id'
+
+/**
+ * Returns the current browser's guest cart session id for this business,
+ * generating and persisting one on first call. SSR-safe: returns null on
+ * the server (no localStorage) — callers should only invoke this from a
+ * client-side effect, matching every other browser-storage read in this SDK.
+ */
+export function getOrCreateGuestSessionId(businessId: string): string | null {
+  if (typeof window === 'undefined') return null
+  try {
+    const existing = localStore.get(businessId, GUEST_SESSION_KEY)
+    if (existing) return existing
+    const generated = crypto.randomUUID()
+    localStore.set(businessId, GUEST_SESSION_KEY, generated)
+    return generated
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Clears the persisted guest session id — call after a successful guest
+ * cart merge into an authenticated customer's cart, so a subsequent logout
+ * on the same browser starts a fresh guest session rather than reusing one
+ * the backend has already deleted server-side.
+ */
+export function clearGuestSessionId(businessId: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    localStore.remove(businessId, GUEST_SESSION_KEY)
+  } catch {
+    // Best-effort cleanup — a failure here shouldn't surface to the caller.
+  }
+}

package/src/utils/http-client.ts

@@ -0,0 +1,147 @@
+import type { SdkConfig } from '../config'
+import { refreshAccessToken, hasRefreshHandler } from './token-refresh'
+
+/**
+ * Thrown by apiRequest on any non-2xx response. Carries the real HTTP status
+ * and parsed body so a caller that needs to branch on status (e.g. a 409
+ * "confirmation required" two-step flow) can catch this instead of the
+ * generic client special-casing every such flow.
+ */
+export class ApiError extends Error {
+  status: number
+  body: unknown
+  constructor(message: string, status: number, body: unknown) {
+    super(message)
+    this.name = 'ApiError'
+    this.status = status
+    this.body = body
+  }
+}
+
+/**
+ * Extract the real, specific error message from a Kasuvia backend's error
+ * body, whichever of the two real shapes this platform's services return:
+ *
+ *   - FastAPI/Pydantic (store-management, cart-management, cms, crm-go,
+ *     notification-go, payment-go): `{"detail": "plain string"}` for a
+ *     manually-raised HTTPException, or `{"detail": [{"loc": [...], "msg":
+ *     "...", "type": "..."}]}` for an automatic Pydantic validation failure.
+ *   - Django REST Framework (kasuvia-auth): `{"detail": "plain string"}` for
+ *     AuthenticationFailed/NotFound/PermissionDenied-style exceptions, or a
+ *     bare validation-error dict with no top-level `detail` at all -
+ *     `{"non_field_errors": [...]}` or `{"email": [...]}"` - when a
+ *     serializer's own `is_valid(raise_exception=True)` fires.
+ *
+ * Previously two separately-named, independently-adopted copies of this
+ * logic existed (`extractHttpErrorDetail`, `extractAuthErrorMessage`) - only
+ * 7 of 18 SDK service files used either one at all. Merged into one function
+ * every call site now goes through via apiRequest, so error quality no
+ * longer depends on which service function happens to have remembered to
+ * check for it.
+ */
+export function extractApiErrorMessage(body: unknown, fallback: string): string {
+  if (typeof body !== 'object' || body === null) return fallback
+  const record = body as Record<string, unknown>
+
+  if (typeof record.detail === 'string') return record.detail
+
+  if (Array.isArray(record.detail) && record.detail.length > 0) {
+    const first = record.detail[0] as Record<string, unknown> | undefined
+    if (first && typeof first.msg === 'string') {
+      const loc = first.loc
+      const field = Array.isArray(loc) ? loc[loc.length - 1] : undefined
+      return typeof field === 'string' || typeof field === 'number' ? `${field}: ${first.msg}` : first.msg
+    }
+  }
+
+  const firstStringOrArrayItem = (value: unknown): string | undefined => {
+    if (typeof value === 'string') return value
+    if (Array.isArray(value) && typeof value[0] === 'string') return value[0]
+    return undefined
+  }
+
+  const nonFieldMessage = firstStringOrArrayItem(record.non_field_errors)
+  if (nonFieldMessage) return nonFieldMessage
+
+  for (const [key, value] of Object.entries(record)) {
+    if (key === 'detail' || key === 'non_field_errors') continue
+    const message = firstStringOrArrayItem(value)
+    if (message) return message
+  }
+
+  return fallback
+}
+
+/** `{'X-Storefront-Key': ..., 'X-Business-ID': ...}` - every storefront-scoped call. */
+export function storefrontHeaders(config: SdkConfig): Record<string, string> {
+  return {
+    'X-Storefront-Key': config.storefrontApiKey,
+    'X-Business-ID': config.businessId,
+  }
+}
+
+/** storefrontHeaders plus `Authorization: Bearer <token>` - every authenticated customer call. */
+export function authHeaders(config: SdkConfig, accessToken: string): Record<string, string> {
+  return {
+    ...storefrontHeaders(config),
+    Authorization: `Bearer ${accessToken}`,
+  }
+}
+
+export const JSON_HEADERS: Record<string, string> = { 'Content-Type': 'application/json' }
+
+export interface ApiRequestOptions extends RequestInit {
+  /** Used when the response is a non-2xx status whose body carries nothing usable. */
+  fallbackErrorMessage?: string
+}
+
+/**
+ * The one real HTTP call path every REST SDK service function should use.
+ * Replaces each function independently doing fetch + response.ok check +
+ * error-body parsing (100 call sites across 18 files, only 7 of which
+ * consistently surfaced the real backend error before this existed).
+ *
+ * A 204/empty body resolves to `undefined` rather than throwing on the
+ * `response.json()` call - real for logout and a few other no-content
+ * responses on this platform.
+ *
+ * Silent-refresh-and-retry on 401 (see token-refresh.ts's own doc comment
+ * for the full real-world bug this fixes and the kasuvia/ pattern it
+ * ports): only triggers for a request that actually carried an
+ * `Authorization: Bearer` header AND has a refresh handler registered -
+ * a storefront-key-only public call's 401 means something else entirely
+ * (wrong key/business) and must never trigger a token refresh attempt.
+ * Retries at most once per call, mirroring withAuthInterceptors' own
+ * `_retry` guard - a fresh token that still 401s is a genuine, final
+ * failure, not something to loop on.
+ */
+export async function apiRequest<T>(url: string, options: ApiRequestOptions = {}): Promise<T> {
+  const { fallbackErrorMessage = 'Request failed', ...init } = options
+  const headers = new Headers(init.headers)
+  const hadBearerToken = headers.get('Authorization')?.startsWith('Bearer ') ?? false
+
+  const response = await fetch(url, { ...init, headers })
+
+  if (response.status === 401 && hadBearerToken && hasRefreshHandler()) {
+    const freshToken = await refreshAccessToken()
+    if (freshToken) {
+      const retryHeaders = new Headers(headers)
+      retryHeaders.set('Authorization', `Bearer ${freshToken}`)
+      const retryResponse = await fetch(url, { ...init, headers: retryHeaders })
+      if (retryResponse.ok) {
+        const retryText = await retryResponse.text()
+        return (retryText ? JSON.parse(retryText) : undefined) as T
+      }
+      const retryBody = await retryResponse.json().catch(() => ({}))
+      throw new ApiError(extractApiErrorMessage(retryBody, fallbackErrorMessage), retryResponse.status, retryBody)
+    }
+  }
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}))
+    throw new ApiError(extractApiErrorMessage(body, fallbackErrorMessage), response.status, body)
+  }
+
+  const text = await response.text()
+  return (text ? JSON.parse(text) : undefined) as T
+}

package/src/utils/index.ts

@@ -1,10 +1,17 @@
-/**
- * Utils Barrel Export
- */
-
 export * from './cache'
 export * from './logger'
+export * from './storage'
 export * from './sanitize-url'
 export * from './customer'
 export * from './checkout'
 export * from './error-handler'
+export * from './http-client'
+export * from './token-refresh'
+export * from './format'
+export * from './geolocation'
+export * from './status-colors'
+export * from './youtube'
+export * from './cookieConsent'
+export * from './validators'
+export * from './graphql-url'
+export * from './guest-session'

package/src/utils/status-colors.ts

@@ -0,0 +1,79 @@
+/**
+ * Status colour mappings for Kasuvia entity statuses.
+ * These are Tailwind CSS class strings; consuming apps must have Tailwind configured.
+ * Migrated from kasuvia-storefront to kasuvia-sdk for shared use.
+ */
+
+import type { ServiceBookingStatus, MilestoneStatus } from "../types/services";
+import type { OrderStatus } from "../types/store";
+
+// REAL BUG FIXED (2026-09-20): keyed on a fictional `AppointmentStatus`
+// ("pending" as the initial state) that never matched the real backend enum
+// (kasuvia-store-management's ServiceBookingStatus — the initial state is
+// "scheduled", not "pending"). Renamed/rekeyed to match reality.
+export const appointmentStatusColors: Record<ServiceBookingStatus, string> = {
+  scheduled: "bg-yellow-100 text-yellow-800 hover:bg-yellow-200",
+  confirmed: "bg-green-100 text-green-800 hover:bg-green-200",
+  in_progress: "bg-blue-100 text-blue-800 hover:bg-blue-200",
+  completed: "bg-gray-100 text-gray-800 hover:bg-gray-200",
+  voided: "bg-red-100 text-red-800 hover:bg-red-200",
+  no_show: "bg-red-100 text-red-800 hover:bg-red-200",
+};
+
+// REAL BUG FIXED (2026-09-20): the "deliverable" concept these colors were
+// keyed on (pending/in_progress/review/approved/rejected) has no backend
+// counterpart at all — the real analogous feature is the service booking's
+// milestone/escrow sub-resource (MilestoneStatus), a different status set.
+export const milestoneStatusColors: Record<MilestoneStatus, string> = {
+  pending: "bg-gray-100 text-gray-800",
+  funded: "bg-blue-100 text-blue-800",
+  submitted: "bg-yellow-100 text-yellow-800",
+  approved: "bg-green-100 text-green-800",
+  released: "bg-green-100 text-green-800",
+  disputed: "bg-red-100 text-red-800",
+  refunded: "bg-gray-100 text-gray-800",
+};
+
+/**
+ * REAL GAP FIXED (2026-09-22): no shared order-status mapping existed at
+ * all (only appointments/milestones did) — kasuvia-storefront's
+ * `OrderStatusCard.tsx` and `DashboardOrders.tsx` each independently
+ * rendered order status differently (one a hand-rolled ternary chain with
+ * friendlier labels like "Preparing"/"On the way", the other the raw
+ * backend enum value capitalized, no color at all) — the same order shows
+ * two different things depending which page the customer is on. Keyed on
+ * the real `OrderStatus` union (types/store/index.ts).
+ */
+export const orderStatusColors: Record<OrderStatus, string> = {
+  pending: "bg-gray-100 text-gray-800",
+  confirmed: "bg-blue-100 text-blue-800",
+  processing: "bg-yellow-100 text-yellow-800",
+  packed: "bg-yellow-100 text-yellow-800",
+  picked_up: "bg-blue-100 text-blue-800",
+  ready_for_pickup: "bg-blue-100 text-blue-800",
+  picked_up_by_customer: "bg-green-100 text-green-800",
+  in_transit: "bg-blue-100 text-blue-800",
+  shipped: "bg-blue-100 text-blue-800",
+  delivered: "bg-green-100 text-green-800",
+  voided: "bg-red-100 text-red-800",
+  refunded: "bg-gray-100 text-gray-800",
+  failed: "bg-red-100 text-red-800",
+};
+
+/** Human-friendly order status labels — the single source every page should use instead of its own ternary chain or the raw enum value. */
+export const orderStatusLabels: Record<OrderStatus, string> = {
+  pending: "Order Placed",
+  confirmed: "Confirmed",
+  processing: "Preparing",
+  packed: "Packed",
+  picked_up: "Picked Up",
+  ready_for_pickup: "Ready for Pickup",
+  picked_up_by_customer: "Collected",
+  in_transit: "In Transit",
+  shipped: "On the Way",
+  delivered: "Delivered",
+  voided: "Voided",
+  refunded: "Refunded",
+  failed: "Failed",
+};
+

package/src/utils/token-refresh.ts

@@ -0,0 +1,115 @@
+/**
+ * Silent-refresh registry for apiRequest's automatic 401 retry.
+ *
+ * REAL GAP FIXED (2026-09-28), live-reported ("authentication in
+ * kasuvia-storefront is terrible, sometimes it gets cut off while using
+ * the app"): AuthProvider only ever called /api/auth/refresh once, in a
+ * useEffect on mount (restoreSession()) — every one of apiRequest's ~100+
+ * real call sites had zero awareness of token expiry at all. The moment a
+ * customer's access token expired mid-session (JWT_ACCESS_TOKEN_LIFETIME_
+ * MINUTES defaults to 30 on kasuvia-auth — see common/utils/tokens.py),
+ * every subsequent authenticated call 401'd and stayed broken for the rest
+ * of that browser tab, with no recovery short of a full page reload
+ * (which re-runs restoreSession() exactly once more, then the cycle
+ * repeats). This is a fundamentally different failure mode than "signed
+ * out on refresh" (investigated exhaustively earlier this session and
+ * found structurally sound) - it only shows up while actively using the
+ * app between page loads, matching the user's own description exactly.
+ *
+ * Compared directly against kasuvia/ (the merchant dashboard)'s own proven
+ * architecture (lib/api/interceptors.ts's withAuthInterceptors): every
+ * axios instance there has a response interceptor that, on any 401 from a
+ * non-refresh endpoint, transparently calls the refresh endpoint once
+ * (coalescing concurrent 401s into a single in-flight refresh via a
+ * pending-request queue - never a stampede of parallel refresh calls),
+ * updates the in-memory access token, and retries the original request
+ * with the new token - completely invisible to the calling code and the
+ * user. kasuvia/ can do this because its access token lives in a plain,
+ * synchronously-readable/writable module-level variable
+ * (lib/api/auth/axios.ts's tokenStore), not React state - exactly what
+ * makes an imperative, outside-the-render-cycle interceptor possible.
+ *
+ * This module ports that same pattern into kasuvia-sdk's fetch-based
+ * apiRequest, which every one of the storefront's ~100+ authenticated SDK
+ * calls already funnels through - fixing it once here reaches every call
+ * site with zero changes to any of them. A consumer (AuthProvider) calls
+ * registerRefreshHandler() once with a function that knows how to obtain a
+ * fresh token (POST /api/auth/refresh, in the storefront's case) and keeps
+ * its own React state in sync; apiRequest below calls it automatically
+ * whenever a request carrying an Authorization header gets a real 401,
+ * with the same in-flight-coalescing guarantee kasuvia/'s interceptor has.
+ * If no handler is registered (e.g. a server-side call, or a consumer that
+ * never opts in), behavior is completely unchanged - a 401 throws
+ * immediately, exactly as before this module existed.
+ *
+ * REAL BUG FOUND AND FIXED while live-verifying this exact mechanism
+ * (2026-09-28): kasuvia-sdk's tsup config builds each package entry point
+ * (`.` / `./services` / `./hooks` / `./components`) as a fully independent
+ * bundle with no shared chunk - confirmed by grepping the built output,
+ * every one of the 3 real dist files contains its OWN separate copy of this
+ * file's code. A plain module-level `let refreshHandler` therefore gave
+ * each entry point its own invisible-to-each-other copy of this state:
+ * registering via `@kasuvia/sdk` (the root entry, what AuthProvider
+ * imports from) silently did nothing for any authenticated call made
+ * through `@kasuvia/sdk/hooks` (a different physical bundle, and the one
+ * real hooks like useWalletBalance/useCart actually route through) - the
+ * exact majority-of-real-traffic case this whole fix exists for. Storing
+ * the registry on `globalThis` under a fixed key instead makes it a true
+ * process/tab-wide singleton no matter how many separate bundle copies of
+ * this module end up loaded side by side in the same browser tab - the
+ * standard fix for this exact "multiple bundled copies of one logical
+ * module" bug class, without needing to change the package's build/
+ * splitting setup (out of scope for an auth fix, wider blast radius).
+ */
+
+export type RefreshHandler = () => Promise<string | null>
+
+interface RefreshRegistry {
+  handler: RefreshHandler | null
+  inFlight: Promise<string | null> | null
+}
+
+const GLOBAL_KEY = '__kasuviaSdkTokenRefreshRegistry__'
+
+function getRegistry(): RefreshRegistry {
+  const g = globalThis as unknown as Record<string, RefreshRegistry | undefined>
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = { handler: null, inFlight: null }
+  }
+  return g[GLOBAL_KEY]!
+}
+
+/**
+ * Registers the function apiRequest calls to obtain a fresh access token
+ * after a 401. Call this once, e.g. in AuthProvider's top-level mount
+ * effect - not tied to login state, since the handler itself is stateless
+ * (it always attempts a real refresh call and returns null on failure,
+ * which is exactly correct behavior whether or not a customer happens to be
+ * logged in right now). `null` is accepted for a consumer that genuinely
+ * unmounts its provider (e.g. route-level teardown) and wants to stop
+ * apiRequest from calling a handler whose closure is about to go stale.
+ */
+export function registerRefreshHandler(handler: RefreshHandler | null): void {
+  getRegistry().handler = handler
+}
+
+/**
+ * Runs the registered refresh handler, coalescing concurrent callers into
+ * the single in-flight attempt (mirrors withAuthInterceptors' `_isRefreshing`
+ * / `_pendingQueue` exactly - several requests failing with a 401 at once
+ * must never each independently call the refresh endpoint).
+ */
+export async function refreshAccessToken(): Promise<string | null> {
+  const registry = getRegistry()
+  if (!registry.handler) return null
+  if (registry.inFlight) return registry.inFlight
+
+  registry.inFlight = registry.handler().finally(() => {
+    registry.inFlight = null
+  })
+  return registry.inFlight
+}
+
+export function hasRefreshHandler(): boolean {
+  return getRegistry().handler !== null
+}

package/src/utils/validators.ts

@@ -83,3 +83,16 @@ export function validateMessage(message: string): string | null {
   }
   return null;
 }
+
+/**
+ * Validates that a country code is a proper 2-letter ISO 3166-1 alpha-2 code.
+ * Defensive guard against backend or session data that might send full country names.
+ *
+ * @param code - The country code string to validate
+ * @returns true when the code is a valid 2-uppercase-letter ISO code
+ */
+export function isValidCountryCode(code: string | undefined): code is string {
+  if (!code) return false;
+  // Must be exactly 2 uppercase letters (valid ISO 3166-1 alpha-2)
+  return /^[A-Z]{2}$/.test(code) && code.length === 2;
+}

package/src/utils/youtube.ts

@@ -0,0 +1,18 @@
+/**
+ * YouTube utility functions
+ */
+
+/**
+ * Extract YouTube video ID from various URL formats.
+ * Supports:
+ * - youtube.com/watch?v=VIDEO_ID
+ * - youtu.be/VIDEO_ID
+ * - youtube.com/embed/VIDEO_ID
+ * - youtube.com/v/VIDEO_ID
+ * - youtube.com/u/USERNAME/watch?v=VIDEO_ID
+ */
+export function getYouTubeID(url: string): string | null {
+    const regExp = /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|&v=)([^#&?]*).*/;
+    const match = url.match(regExp);
+    return (match && match[2].length === 11) ? match[2] : null;
+}