@kasuvia/sdk 0.0.8 → 0.0.9

package/src/config/index.ts

@@ -1,21 +1,39 @@
 /**
  * Kasuvia SDK Configuration
- * 
+ *
  * Stateless configuration - no module-scoped state.
  * All configuration is passed as parameters to SDK functions.
- * 
- * SECURITY NOTE: Backend URLs should never be exposed to the browser.
- * They should only be used on the server side or in Next.js API routes.
+ *
+ * SECURITY NOTE: `backendUrls` must resolve to real backend hosts (e.g. https://kasuvia-auth-...
+ * .onrender.com/api/v1) ONLY in a config instance built for server-side use - never pass that
+ * instance into SdkProvider or any other client-rendered code. A consuming app should build TWO
+ * SdkConfig instances of this exact same shape: a server one (real URLs, for Next.js API routes /
+ * Server Components) and a client one (same-origin proxy paths like /api/proxy/store, safe for
+ * SdkProvider and any "use client" component).
+ *
+ * REAL GAP CLOSED (2026-09-17): this plain interface alone couldn't enforce that distinction -
+ * getting it backwards used to compile fine and fail at runtime instead (confirmed: kasuvia-storefront's
+ * ProductsListing.tsx imported the server instance into a "use client" file, which silently
+ * resolved backendUrls.store to '' in the browser bundle rather than erroring loudly - fixed
+ * 2026-09-03, but nothing here caught the next occurrence of the same mistake). Build the SERVER
+ * instance via `createServerSdkConfig` from '@kasuvia/sdk/config/server' instead of a plain object
+ * literal - that module is tagged `import 'server-only'` on its own isolated build entry, so
+ * Next.js's bundler refuses at BUILD TIME to include it in any "use client" file's module graph,
+ * closing this exact incident class instead of just documenting it. The client instance needs no
+ * such guard (proxy paths carry no secret/real-host material) - a plain object literal is fine.
  */
 
 export interface SdkConfig {
   businessId: string
   storefrontApiKey: string
+  authToken?: string
   backendUrls: {
     auth: string
     store: string
+    cart: string
     payment: string
     notifications: string
     cms: string
+    crm: string
   }
 }

package/src/config/server.ts

@@ -0,0 +1,45 @@
+// REAL GAP CLOSED (2026-09-17): SdkConfig's own file documents a real
+// incident (kasuvia-storefront's ProductsListing.tsx importing the SERVER
+// config instance — real backend URLs — into a "use client" file, silently
+// resolving to '' in the browser bundle rather than failing loudly) and
+// admits "This type alone can't enforce that distinction". A plain
+// TypeScript interface can't — but `server-only` (the same sentinel package
+// Next.js's own docs recommend for exactly this problem) can, at BUILD
+// TIME: this file's mere existence as a leaf module, isolated on its own
+// tsup entry/exports subpath (never re-exported from the main '@kasuvia/sdk'
+// or '@kasuvia/sdk/config' entry, which would taint that whole module graph
+// as server-only for every consumer), means importing it from a "use client"
+// file makes Next.js's build fail immediately with a clear, actionable
+// error — not a silent empty string discovered in production.
+import 'server-only'
+import type { SdkConfig } from './index'
+
+export interface ServerBackendUrls {
+  auth: string
+  store: string
+  cart: string
+  payment: string
+  notifications: string
+  cms: string
+  crm: string
+}
+
+/**
+ * Build the SERVER-side SdkConfig instance — real backend URLs, for Next.js
+ * API route handlers / Server Components only. Importing this function (or
+ * this module at all) from a "use client" file is a build error by design.
+ * For the client-safe instance (same-origin proxy paths), just construct a
+ * plain SdkConfig object directly — no factory needed, nothing to guard
+ * against, since there's no secret/real-host material in it.
+ */
+export function createServerSdkConfig(params: {
+  businessId: string
+  storefrontApiKey: string
+  backendUrls: ServerBackendUrls
+}): SdkConfig {
+  return {
+    businessId: params.businessId,
+    storefrontApiKey: params.storefrontApiKey,
+    backendUrls: params.backendUrls,
+  }
+}

package/src/context/sdk-context.tsx

@@ -23,6 +23,8 @@ import type { SdkConfig } from '../config';
 export interface SdkContextValue {
   config: SdkConfig;
   accessToken: string | null;
+  /** Current browser's guest cart session id (see utils/guest-session.ts) — null when unauthenticated context hasn't resolved one yet, or when the caller is authenticated and doesn't need one. */
+  guestSessionId?: string | null;
 }
 
 const SdkContext = createContext<SdkContextValue | null>(null);
@@ -30,12 +32,13 @@ const SdkContext = createContext<SdkContextValue | null>(null);
 export interface SdkProviderProps {
   config: SdkConfig;
   accessToken: string | null;
+  guestSessionId?: string | null;
   children: ReactNode;
 }
 
-export function SdkProvider({ config, accessToken, children }: SdkProviderProps) {
+export function SdkProvider({ config, accessToken, guestSessionId, children }: SdkProviderProps) {
   return (
-    <SdkContext.Provider value={{ config, accessToken }}>
+    <SdkContext.Provider value={{ config, accessToken, guestSessionId }}>
       {children}
     </SdkContext.Provider>
   );