@drttix/drt-sdk 1.5.1 → 2.0.0

package/src/functions/sdkConfig.ts

@@ -1,169 +1,222 @@
-// SDK Configuration - allows initializing credentials once
-import { OpenAPI as ShopperAPI } from '../generated/shopper/core/OpenAPI';
-import { OpenAPI as ScannerAPI } from '../generated/scanner/core/OpenAPI';
-import { OpenAPI as PortalAPI } from '../generated/portal/core/OpenAPI';
-
-export type ShopperScope = 'singleton' | 'per-request';
-
-export interface SDKConfig {
-    apiKey: string;
-    /**
-     * Required when shopperScope is 'singleton' (the default). Optional when
-     * shopperScope is 'per-request' — in that mode these act only as a fallback
-     * default, and every shopper call may override them via a trailing
-     * `{ shopperGuid, accountId }` context argument.
-     */
-    shopperGuid?: string;
-    accountId?: string;
-    /**
-     * 'singleton' (default): shopperGuid/accountId are fixed for the lifetime of
-     * the process, exactly like today.
-     *
-     * 'per-request': shopperGuid/accountId become optional at init() time, and
-     * every shopper service method accepts an optional trailing context argument
-     * ({ shopperGuid, accountId }) so a single SDK instance can serve requests
-     * for many shoppers/accounts concurrently — the intended shape for a backend
-     * that proxies calls on behalf of arbitrary shoppers.
-     */
-    shopperScope?: ShopperScope;
-}
-
-let isInitialized = false;
-let currentConfig: SDKConfig | null = null;
-let currentShopperScope: ShopperScope = 'singleton';
-
-/**
- * Initialize the DRT SDK with credentials.
- * Once initialized, these credentials will be automatically included
- * in all API requests as headers.
- *
- * @param config - The SDK configuration containing shopperGuid, accountId, and apiKey
- *
- * @example
- * ```javascript
- * import { DRT } from '@drttix/drt-sdk';
- *
- * // Initialize once (default: singleton shopper scope)
- * DRT.init({
- *   shopperGuid: 'your-shopper-guid',
- *   accountId: 'your-account-id',
- *   apiKey: 'your-api-key'
- * });
- *
- * // Now make calls without passing credentials
- * const theme = await DRT.shopper.account.getTheme();
- * ```
- *
- * @example
- * ```javascript
- * // Backend serving many shoppers/accounts from a single SDK instance
- * DRT.init({ apiKey: 'your-api-key', shopperScope: 'per-request' });
- *
- * // Pass shopperGuid/accountId per call instead
- * await DRT.shopper.product.addProduct(body, {
- *   shopperGuid: req.shopperGuid,
- *   accountId: req.accountId,
- * });
- * ```
- */
-export function init(config: SDKConfig): void {
-    if (!config.apiKey) {
-        throw new Error('DRT SDK init requires apiKey');
-    }
-
-    const shopperScope = config.shopperScope ?? 'singleton';
-
-    if (shopperScope === 'singleton' && (!config.shopperGuid || !config.accountId)) {
-        throw new Error(
-            'DRT SDK init requires shopperGuid and accountId (or pass shopperScope: "per-request" to supply them per shopper call instead)',
-        );
-    }
-
-    currentConfig = config;
-    currentShopperScope = shopperScope;
-
-    // Portal and scanner are always singleton-scoped: one fixed set of
-    // credentials for every call, applied globally via OpenAPI.HEADERS.
-    const sharedHeaders: Record<string, string> = { apikey: config.apiKey };
-    if (config.shopperGuid && config.accountId) {
-        sharedHeaders.shopperguid = config.shopperGuid;
-        sharedHeaders.accountid = config.accountId;
-    }
-    ScannerAPI.HEADERS = sharedHeaders;
-    PortalAPI.HEADERS = sharedHeaders;
-
-    // Shopper credentials are resolved per-call by resolveShopperHeaders()
-    // (see generated shopper services), so no global header is set here —
-    // that's what lets shopperScope: 'per-request' override per call without
-    // a global value silently taking precedence.
-    ShopperAPI.HEADERS = undefined;
-
-    isInitialized = true;
-}
-
-/**
- * Check if the SDK has been initialized with credentials.
- */
-export function isReady(): boolean {
-    return isInitialized;
-}
-
-/**
- * Get the current SDK configuration (if initialized).
- */
-export function getConfig(): SDKConfig | null {
-    return currentConfig;
-}
-
-/**
- * Get the shopperScope the SDK was initialized with ('singleton' if not yet initialized).
- */
-export function getShopperScope(): ShopperScope {
-    return currentShopperScope;
-}
-
-/**
- * Reset the SDK configuration.
- */
-export function reset(): void {
-    currentConfig = null;
-    currentShopperScope = 'singleton';
-    isInitialized = false;
-    ShopperAPI.HEADERS = undefined;
-    ScannerAPI.HEADERS = undefined;
-    PortalAPI.HEADERS = undefined;
-}
-
-/**
- * Resolves the shopperguid/accountid/apikey headers for a single shopper API call.
- *
- * Used internally by every generated shopper service method. `context`, when
- * provided, overrides the shopperGuid/accountId set at DRT.init() — this is
- * what makes shopperScope: 'per-request' work. apiKey always comes from
- * DRT.init(), since it identifies the calling backend, not the shopper.
- */
-export function resolveShopperHeaders(context?: {
-    shopperGuid?: string;
-    accountId?: string;
-}): Record<string, string> {
-    if (!currentConfig) {
-        throw new Error('DRT SDK not initialized. Call DRT.init() first.');
-    }
-
-    const shopperGuid = context?.shopperGuid ?? currentConfig.shopperGuid;
-    const accountId = context?.accountId ?? currentConfig.accountId;
-
-    if (!shopperGuid || !accountId) {
-        throw new Error(
-            currentShopperScope === 'per-request'
-                ? 'No shopperGuid/accountId available for this call. DRT SDK was initialized with shopperScope: "per-request" without defaults — pass { shopperGuid, accountId } as the last argument to this call.'
-                : 'DRT SDK not initialized with shopperGuid/accountId. Call DRT.init() first.',
-        );
-    }
-
-    return {
-        shopperguid: shopperGuid,
-        accountid: accountId,
-        apikey: currentConfig.apiKey,
-    };
-}
+// SDK Configuration - allows initializing credentials once
+import { OpenAPI as ShopperAPI } from '../generated/shopper/core/OpenAPI';
+import { OpenAPI as ScannerAPI } from '../generated/scanner/core/OpenAPI';
+import { OpenAPI as PortalAPI } from '../generated/portal/core/OpenAPI';
+
+export type ShopperScope = 'singleton' | 'per-request';
+
+/**
+ * Header a non-browser caller uses to declare the domain it acts as. The
+ * shopper API matches it against the api key's allowed domains when no
+ * browser-set Origin/Referer is present.
+ */
+export const DOMAIN_HEADER = 'x-drt-domain';
+
+export interface SDKConfig {
+    /**
+     * A shopper API key issued by DRT ('drt_shopper_...'), sent as the `apikey`
+     * header on every call. The shopper API refuses any request without a live
+     * key, and only honours a key from the domains it was issued for: a browser
+     * is identified by the Origin header it sets itself; a server by `domain`.
+     *
+     * Read it from the DRT_API_KEY environment variable — never commit it.
+     */
+    apiKey: string;
+    /**
+     * The domain this caller acts as (e.g. 'tap-to-pay.drttix.com'), sent as
+     * `x-drt-domain`. REQUIRED for callers that are not browsers — a Node
+     * backend, a server-side script — because they send no Origin/Referer, so
+     * without it the shopper API sees an empty domain and refuses the key.
+     * Browsers leave it unset: the API trusts the Origin the browser sets and
+     * ignores this header whenever an Origin/Referer is present.
+     */
+    domain?: string;
+    /**
+     * Required when shopperScope is 'singleton' (the default). Optional when
+     * shopperScope is 'per-request' — in that mode these act only as a fallback
+     * default, and every shopper call may override them via a trailing
+     * `{ shopperGuid, accountId }` context argument.
+     */
+    shopperGuid?: string;
+    accountId?: string;
+    /**
+     * 'singleton' (default): shopperGuid/accountId are fixed for the lifetime of
+     * the process, exactly like today.
+     *
+     * 'per-request': shopperGuid/accountId become optional at init() time, and
+     * every shopper service method accepts an optional trailing context argument
+     * ({ shopperGuid, accountId }) so a single SDK instance can serve requests
+     * for many shoppers/accounts concurrently — the intended shape for a backend
+     * that proxies calls on behalf of arbitrary shoppers.
+     */
+    shopperScope?: ShopperScope;
+}
+
+let isInitialized = false;
+let currentConfig: SDKConfig | null = null;
+let currentShopperScope: ShopperScope = 'singleton';
+
+/**
+ * Initialize the DRT SDK with credentials.
+ * Once initialized, these credentials will be automatically included
+ * in all API requests as headers.
+ *
+ * @param config - The SDK configuration containing shopperGuid, accountId, and apiKey
+ *
+ * @example
+ * ```javascript
+ * import { DRT } from '@drttix/drt-sdk';
+ *
+ * // Initialize once (default: singleton shopper scope)
+ * DRT.init({
+ *   shopperGuid: 'your-shopper-guid',
+ *   accountId: 'your-account-id',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Now make calls without passing credentials
+ * const theme = await DRT.shopper.account.getTheme();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Backend serving many shoppers/accounts from a single SDK instance.
+ * // A backend is not a browser, so it must also say which domain it acts as.
+ * DRT.init({
+ *   apiKey: process.env.DRT_API_KEY,
+ *   domain: 'tap-to-pay.drttix.com',
+ *   shopperScope: 'per-request',
+ * });
+ *
+ * // Pass shopperGuid/accountId per call instead
+ * await DRT.shopper.product.addProduct(body, {
+ *   shopperGuid: req.shopperGuid,
+ *   accountId: req.accountId,
+ * });
+ * ```
+ */
+export function init(config: SDKConfig): void {
+    if (!config.apiKey) {
+        throw new Error('DRT SDK init requires apiKey');
+    }
+
+    const shopperScope = config.shopperScope ?? 'singleton';
+
+    if (shopperScope === 'singleton' && (!config.shopperGuid || !config.accountId)) {
+        throw new Error(
+            'DRT SDK init requires shopperGuid and accountId (or pass shopperScope: "per-request" to supply them per shopper call instead)',
+        );
+    }
+
+    currentConfig = config;
+    currentShopperScope = shopperScope;
+
+    // Portal and scanner are always singleton-scoped: one fixed set of
+    // credentials for every call, applied globally via OpenAPI.HEADERS.
+    const sharedHeaders: Record<string, string> = { apikey: config.apiKey };
+    if (config.domain) {
+        sharedHeaders[DOMAIN_HEADER] = config.domain;
+    }
+    if (config.shopperGuid && config.accountId) {
+        sharedHeaders.shopperguid = config.shopperGuid;
+        sharedHeaders.accountid = config.accountId;
+    }
+    ScannerAPI.HEADERS = sharedHeaders;
+    PortalAPI.HEADERS = sharedHeaders;
+
+    // Shopper credentials are resolved per-call by resolveShopperHeaders()
+    // (see generated shopper services), so no global header is set here —
+    // that's what lets shopperScope: 'per-request' override per call without
+    // a global value silently taking precedence.
+    ShopperAPI.HEADERS = undefined;
+
+    isInitialized = true;
+}
+
+/**
+ * Check if the SDK has been initialized with credentials.
+ */
+export function isReady(): boolean {
+    return isInitialized;
+}
+
+/**
+ * Called by the shared request layer before EVERY request, for every service
+ * (shopper, portal, scanner). The SDK is unusable until DRT.init() has been
+ * given an api key — there is no keyless mode. Throwing here, rather than
+ * letting the request go out and fail at the API, names the fix in the error.
+ */
+export function assertInitialized(baseUrl: string): void {
+    if (isInitialized) {
+        return;
+    }
+    throw new Error(
+        `DRT SDK not initialized — call DRT.init({ apiKey, ... }) before using it (request to ${baseUrl}). ` +
+            'The key comes from the DRT_API_KEY environment variable; a backend also passes ' +
+            "`domain`, and one that serves many shoppers passes shopperScope: 'per-request'.",
+    );
+}
+
+/**
+ * Get the current SDK configuration (if initialized).
+ */
+export function getConfig(): SDKConfig | null {
+    return currentConfig;
+}
+
+/**
+ * Get the shopperScope the SDK was initialized with ('singleton' if not yet initialized).
+ */
+export function getShopperScope(): ShopperScope {
+    return currentShopperScope;
+}
+
+/**
+ * Reset the SDK configuration.
+ */
+export function reset(): void {
+    currentConfig = null;
+    currentShopperScope = 'singleton';
+    isInitialized = false;
+    ShopperAPI.HEADERS = undefined;
+    ScannerAPI.HEADERS = undefined;
+    PortalAPI.HEADERS = undefined;
+}
+
+/**
+ * Resolves the shopperguid/accountid/apikey headers for a single shopper API call.
+ *
+ * Used internally by every generated shopper service method. `context`, when
+ * provided, overrides the shopperGuid/accountId set at DRT.init() — this is
+ * what makes shopperScope: 'per-request' work. apiKey always comes from
+ * DRT.init(), since it identifies the calling backend, not the shopper.
+ */
+export function resolveShopperHeaders(context?: {
+    shopperGuid?: string;
+    accountId?: string;
+}): Record<string, string> {
+    if (!currentConfig) {
+        throw new Error('DRT SDK not initialized. Call DRT.init() first.');
+    }
+
+    const shopperGuid = context?.shopperGuid ?? currentConfig.shopperGuid;
+    const accountId = context?.accountId ?? currentConfig.accountId;
+
+    if (!shopperGuid || !accountId) {
+        throw new Error(
+            currentShopperScope === 'per-request'
+                ? 'No shopperGuid/accountId available for this call. DRT SDK was initialized with shopperScope: "per-request" without defaults — pass { shopperGuid, accountId } as the last argument to this call.'
+                : 'DRT SDK not initialized with shopperGuid/accountId. Call DRT.init() first.',
+        );
+    }
+
+    const headers: Record<string, string> = {
+        shopperguid: shopperGuid,
+        accountid: accountId,
+        apikey: currentConfig.apiKey,
+    };
+    if (currentConfig.domain) {
+        headers[DOMAIN_HEADER] = currentConfig.domain;
+    }
+    return headers;
+}

package/src/functions/setBaseURL.ts

@@ -1,47 +1,47 @@
-// Centralized base URL initialization for all services
-import { OpenAPI as ShopperAPI } from "../generated/shopper/core/OpenAPI";
-import { OpenAPI as ScannerAPI } from "../generated/scanner/core/OpenAPI";
-import { OpenAPI as PortalAPI } from "../generated/portal/core/OpenAPI";
-
-// Override fetch for the portal API client
-PortalAPI.WITH_CREDENTIALS = true;
-
-// Public API endpoints (default)
-const PUBLIC_API = {
-	shopper: "https://api.drttix.com/shopper",
-	scanner: "https://api.drttix.com/scanner-v3",
-	portal: "https://api.drttix.com/admin-portal",
-};
-
-// One-time base URL initialization guard
-let didSetBaseUrls = false;
-
-/**
- * Sets the base URLs for all API clients.
- *
- * By default, uses the public production API.
- *
- * For local development (developer only), set:
- *   DRT_API_LOCAL=true        (uses localhost:3000 for both services)
- *   DRT_API_BASE_URL=<url>    (uses custom base URL for both services)
- */
-export function setBaseUrlsOnce() {
-	if (didSetBaseUrls) return;
-	didSetBaseUrls = true;
-
-	// Browser-friendly environment detection:
-	// - If `globalThis.DRT_API_BASE_URL` is provided (e.g. window.DRT_API_BASE_URL), use it.
-	// - If `globalThis.DRT_API_LOCAL` is set to true (boolean) or "true" (string), use localhost.
-	// - Otherwise, fall back to PUBLIC_API defaults.
-	const globalEnv: any =
-		typeof globalThis !== "undefined" ? (globalThis as any) : {};
-	const customBase = globalEnv.DRT_API_BASE_URL ?? null;
-	const useLocal =
-		globalEnv.DRT_API_LOCAL === true || globalEnv.DRT_API_LOCAL === "true";
-
-	const base = customBase || (useLocal ? "http://localhost:3000" : null);
-
-	ShopperAPI.BASE = base ? `${base}/shopper` : PUBLIC_API.shopper;
-	ScannerAPI.BASE = base ? `${base}/scanner-v3` : PUBLIC_API.scanner;
-	PortalAPI.BASE = base ? `${base}/portal` : PUBLIC_API.portal;
-}
+// Centralized base URL initialization for all services
+import { OpenAPI as ShopperAPI } from "../generated/shopper/core/OpenAPI";
+import { OpenAPI as ScannerAPI } from "../generated/scanner/core/OpenAPI";
+import { OpenAPI as PortalAPI } from "../generated/portal/core/OpenAPI";
+
+// Override fetch for the portal API client
+PortalAPI.WITH_CREDENTIALS = true;
+
+// Public API endpoints (default)
+const PUBLIC_API = {
+	shopper: "https://api.drttix.com/shopper",
+	scanner: "https://api.drttix.com/scanner-v3",
+	portal: "https://api.drttix.com/admin-portal",
+};
+
+// One-time base URL initialization guard
+let didSetBaseUrls = false;
+
+/**
+ * Sets the base URLs for all API clients.
+ *
+ * By default, uses the public production API.
+ *
+ * For local development (developer only), set:
+ *   DRT_API_LOCAL=true        (uses localhost:3000 for both services)
+ *   DRT_API_BASE_URL=<url>    (uses custom base URL for both services)
+ */
+export function setBaseUrlsOnce() {
+	if (didSetBaseUrls) return;
+	didSetBaseUrls = true;
+
+	// Browser-friendly environment detection:
+	// - If `globalThis.DRT_API_BASE_URL` is provided (e.g. window.DRT_API_BASE_URL), use it.
+	// - If `globalThis.DRT_API_LOCAL` is set to true (boolean) or "true" (string), use localhost.
+	// - Otherwise, fall back to PUBLIC_API defaults.
+	const globalEnv: any =
+		typeof globalThis !== "undefined" ? (globalThis as any) : {};
+	const customBase = globalEnv.DRT_API_BASE_URL ?? null;
+	const useLocal =
+		globalEnv.DRT_API_LOCAL === true || globalEnv.DRT_API_LOCAL === "true";
+
+	const base = customBase || (useLocal ? "http://localhost:3000" : null);
+
+	ShopperAPI.BASE = base ? `${base}/shopper` : PUBLIC_API.shopper;
+	ScannerAPI.BASE = base ? `${base}/scanner-v3` : PUBLIC_API.scanner;
+	PortalAPI.BASE = base ? `${base}/portal` : PUBLIC_API.portal;
+}

package/src/generated/portal/core/ApiError.ts

@@ -22,4 +22,4 @@ export class ApiError extends Error {
         this.body = response.body;
         this.request = request;
     }
-}
+}

package/src/generated/portal/core/ApiRequestOptions.ts

@@ -14,4 +14,4 @@ export type ApiRequestOptions = {
     readonly mediaType?: string;
     readonly responseHeader?: string;
     readonly errors?: Record<number, string>;
-};
+};

package/src/generated/portal/core/ApiResult.ts

@@ -8,4 +8,4 @@ export type ApiResult = {
     readonly status: number;
     readonly statusText: string;
     readonly body: any;
-};
+};

package/src/generated/portal/core/CancelablePromise.ts

@@ -128,4 +128,4 @@ export class CancelablePromise<T> implements Promise<T> {
     public get isCancelled(): boolean {
         return this.#isCancelled;
     }
-}
+}

package/src/generated/portal/core/OpenAPI.ts

@@ -21,7 +21,7 @@ export type OpenAPIConfig = {
 
 export const OpenAPI: OpenAPIConfig = {
     BASE: '',
-    VERSION: '20260831.1',
+    VERSION: '20260902.5',
     WITH_CREDENTIALS: false,
     CREDENTIALS: 'include',
     TOKEN: undefined,
@@ -29,4 +29,4 @@ export const OpenAPI: OpenAPIConfig = {
     PASSWORD: undefined,
     HEADERS: undefined,
     ENCODE_PATH: undefined,
-};
+};