@forgecart/sdk 1.2.7 → 1.202606151453.0

package/src/client.generated.d.ts

@@ -0,0 +1,249 @@
+/**
+ * AUTO-GENERATED FILE — DO NOT EDIT
+ *
+ * This file was generated by @forgecart/client-sdk-generators.
+ * Any manual changes will be overwritten on the next generation run.
+ */
+import { Observable } from 'rxjs';
+import type { HookSubscription } from './sdk-hook-subscription.generated';
+import type { AdminHookPoint, AdminHookHandler } from './hook-event-map.generated';
+import { AdminNamespace } from './admin.generated';
+import type * as Admin from './admin.generated';
+import { ShopNamespace } from './shop.generated';
+import type * as Shop from './shop.generated';
+export interface ForgeCartAdminClientConfig {
+    endpoint: string;
+    channelToken: string;
+    adminSecret?: string;
+    uploadEndpoint?: string;
+    headers?: Record<string, string>;
+}
+export interface ForgeCartShopClientConfig {
+    endpoint: string;
+    channelToken: string;
+    uploadEndpoint?: string;
+    headers?: Record<string, string>;
+}
+export interface ForgeCartClientConfig {
+    endpoint: string;
+    channelToken: string;
+    adminSecret?: string;
+    uploadEndpoint?: string;
+    headers?: Record<string, string>;
+}
+export declare class SDKLogger {
+    private readonly prefix;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export interface GraphQLErrorResponse {
+    errors: Array<{
+        message: string;
+        extensions?: Record<string, unknown>;
+    }>;
+}
+export declare class ClientError extends Error {
+    readonly response: GraphQLErrorResponse;
+    constructor(response: GraphQLErrorResponse, message: string);
+}
+export type ErrorHandler = (error: ClientError) => void;
+/**
+ * An Observable that is also PromiseLike, so `await` resolves the first emitted value.
+ * Use `.subscribe()` for streaming, `await` for single-shot request-response.
+ */
+export declare class QueryObservable<T> extends Observable<T> implements PromiseLike<T> {
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+export interface LoginSessionChannel {
+    id: string;
+    token: string;
+    code: string;
+    permissions: string[];
+}
+export interface LoginSession {
+    id: string;
+    token: string;
+    channels: LoginSessionChannel[];
+}
+export interface AdminLoginAdministrator {
+    id: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    avatarUrl: string | null;
+}
+export interface AdminExternalAuthResult {
+    session: LoginSession;
+    administrator: AdminLoginAdministrator;
+    requiresOnboarding: boolean;
+}
+export declare class BaseGraphQLClient {
+    private readonly baseHeaders;
+    private readonly uploadEndpoint?;
+    private readonly logger;
+    private readonly endpoint;
+    private wsClient;
+    private ownsWsClient;
+    private wsClientStale;
+    private authToken;
+    private transactionToken;
+    private errorHandler;
+    constructor(endpoint: string, baseHeaders: Record<string, string>, uploadEndpoint?: string | undefined);
+    private getWsClient;
+    private getHeaders;
+    setAuthToken(token: string): void;
+    getAuthToken(): string | null;
+    clearAuthToken(): void;
+    setTransactionToken(token: string): void;
+    clearTransactionToken(): void;
+    setErrorHandler(handler: ErrorHandler): void;
+    private notifyErrorHandler;
+    query<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    mutate<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    subscribe<T>(document: string, variables?: Record<string, unknown>): Observable<T>;
+    upload<T>(document: string, variables: Record<string, unknown>): QueryObservable<T>;
+    private getPerOperationExtensions;
+    private captureSessionToken;
+    private captureSessionTokenFromUpload;
+    private containsFiles;
+    private resolveUploadEndpoint;
+    private disposeWsClient;
+    dispose(): void;
+    fork(transactionToken: string): BaseGraphQLClient;
+}
+export declare function setAuthToken(client: BaseGraphQLClient, token: string): void;
+export declare function clearAuthToken(client: BaseGraphQLClient): void;
+export declare function setTransactionToken(client: BaseGraphQLClient, token: string): void;
+export declare function clearTransactionToken(client: BaseGraphQLClient): void;
+export declare class TransactionContext {
+    private readonly _admin;
+    private readonly _shop;
+    constructor(admin: AdminNamespace, shop?: ShopNamespace);
+    get admin(): AdminNamespace;
+    get shop(): ShopNamespace;
+}
+export declare class ForgeCartAdminClient {
+    private readonly client;
+    private readonly _namespace;
+    constructor(config: ForgeCartAdminClientConfig);
+    setAuthToken(token: string): void;
+    getAuthToken(): string | null;
+    clearAuthToken(): void;
+    setTransactionToken(token: string): void;
+    clearTransactionToken(): void;
+    setErrorHandler(handler: ErrorHandler): void;
+    dispose(): void;
+    query<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    mutate<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    private shopPeer;
+    setShopPeer(shop: ForgeCartShopClient): void;
+    createScopedNamespace(transactionToken: string): AdminNamespace;
+    withTransaction<T>(fn: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+    private hookManager;
+    on<K extends AdminHookPoint>(hookPoints: K[], handler: AdminHookHandler<K>): HookSubscription;
+    login(emailAddress: string, password: string): Promise<LoginSession>;
+    loginWithExternalStrategy(strategyCode: string, data: Record<string, unknown>): Promise<AdminExternalAuthResult>;
+    logout(): Promise<void>;
+    get entry(): Admin.EntryCategory;
+    get fieldDefinition(): Admin.FieldDefinitionCategory;
+    get publish(): Admin.PublishCategory;
+    get acfSchema(): Admin.AcfSchemaCategory;
+    get acf(): Admin.AcfCategory;
+    get administrator(): Admin.AdministratorCategory;
+    get analyticsGateway(): Admin.AnalyticsGatewayCategory;
+    get asset(): Admin.AssetCategory;
+    get audienceMembership(): Admin.AudienceMembershipCategory;
+    get audienceSegment(): Admin.AudienceSegmentCategory;
+    get auth(): Admin.AuthCategory;
+    get settings(): Admin.SettingsCategory;
+    get channel(): Admin.ChannelCategory;
+    get chat(): Admin.ChatCategory;
+    get collection(): Admin.CollectionCategory;
+    get country(): Admin.CountryCategory;
+    get address(): Admin.AddressCategory;
+    get group(): Admin.GroupCategory;
+    get customerGroup(): Admin.CustomerGroupCategory;
+    get customer(): Admin.CustomerCategory;
+    get deployment(): Admin.DeploymentCategory;
+    get facet(): Admin.FacetCategory;
+    get fulfillmentRequest(): Admin.FulfillmentRequestCategory;
+    get fulfillment(): Admin.FulfillmentCategory;
+    get hookDispatch(): Admin.HookDispatchCategory;
+    get hook(): Admin.HookCategory;
+    get marketingAttribution(): Admin.MarketingAttributionCategory;
+    get marketingEvent(): Admin.MarketingEventCategory;
+    get marketingIdentity(): Admin.MarketingIdentityCategory;
+    get onboarding(): Admin.OnboardingCategory;
+    get coupon(): Admin.CouponCategory;
+    get draft(): Admin.DraftCategory;
+    get modification(): Admin.ModificationCategory;
+    get note(): Admin.NoteCategory;
+    get orderModification(): Admin.OrderModificationCategory;
+    get order(): Admin.OrderCategory;
+    get payment(): Admin.PaymentCategory;
+    get manageable(): Admin.ManageableCategory;
+    get plugin(): Admin.PluginCategory;
+    get optionGroup(): Admin.OptionGroupCategory;
+    get option(): Admin.OptionCategory;
+    get productOption(): Admin.ProductOptionCategory;
+    get productVariant(): Admin.ProductVariantCategory;
+    get product(): Admin.ProductCategory;
+    get promotion(): Admin.PromotionCategory;
+    get role(): Admin.RoleCategory;
+    get scheduledJob(): Admin.ScheduledJobCategory;
+    get search(): Admin.SearchCategory;
+    get seller(): Admin.SellerCategory;
+    get shipping(): Admin.ShippingCategory;
+    get stock(): Admin.StockCategory;
+    get subscription(): Admin.SubscriptionCategory;
+    get tax(): Admin.TaxCategory;
+    get transaction(): Admin.TransactionCategory;
+    get zone(): Admin.ZoneCategory;
+}
+export declare class ForgeCartShopClient {
+    private readonly client;
+    private readonly _namespace;
+    constructor(config: ForgeCartShopClientConfig);
+    setAuthToken(token: string): void;
+    getAuthToken(): string | null;
+    clearAuthToken(): void;
+    setTransactionToken(token: string): void;
+    clearTransactionToken(): void;
+    setErrorHandler(handler: ErrorHandler): void;
+    dispose(): void;
+    query<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    mutate<T>(document: string, variables?: Record<string, unknown>): QueryObservable<T>;
+    createScopedNamespace(transactionToken: string): ShopNamespace;
+    login(emailAddress: string, password: string): Promise<LoginSession>;
+    loginWithExternalStrategy(strategyCode: string, data: Record<string, unknown>): Promise<LoginSession>;
+    logout(): Promise<void>;
+    get acf(): Shop.AcfCategory;
+    get auth(): Shop.AuthCategory;
+    get cart(): Shop.CartCategory;
+    get checkout(): Shop.CheckoutCategory;
+    get collection(): Shop.CollectionCategory;
+    get customer(): Shop.CustomerCategory;
+    get facet(): Shop.FacetCategory;
+    get hookDispatch(): Shop.HookDispatchCategory;
+    get hook(): Shop.HookCategory;
+    get marketingEvent(): Shop.MarketingEventCategory;
+    get marketingIdentity(): Shop.MarketingIdentityCategory;
+    get order(): Shop.OrderCategory;
+    get payment(): Shop.PaymentCategory;
+    get product(): Shop.ProductCategory;
+    get search(): Shop.SearchCategory;
+    get shipping(): Shop.ShippingCategory;
+    get subscription(): Shop.SubscriptionCategory;
+}
+export declare class ForgeCartClient {
+    private readonly _admin;
+    private readonly _shop;
+    constructor(config: ForgeCartClientConfig);
+    setAuthToken(token: string): void;
+    clearAuthToken(): void;
+    setTransactionToken(token: string): void;
+    clearTransactionToken(): void;
+    get admin(): ForgeCartAdminClient;
+    get shop(): ForgeCartShopClient;
+}

package/src/client.generated.ts

@@ -24,6 +24,11 @@ export interface ForgeCartAdminClientConfig {
   adminSecret?: string;
   uploadEndpoint?: string;
   headers?: Record<string, string>;
+  // Session preferences sent as forgecart-currency / forgecart-language
+  // headers on every request. Override later via setCurrencyCode() /
+  // setLanguageCode().
+  currencyCode?: string;
+  languageCode?: string;
 }
 
 export interface ForgeCartShopClientConfig {
@@ -31,6 +36,11 @@ export interface ForgeCartShopClientConfig {
   channelToken: string;
   uploadEndpoint?: string;
   headers?: Record<string, string>;
+  // Session preferences sent as forgecart-currency / forgecart-language
+  // headers on every request. Override later via setCurrencyCode() /
+  // setLanguageCode().
+  currencyCode?: string;
+  languageCode?: string;
 }
 
 export interface ForgeCartClientConfig {
@@ -39,6 +49,11 @@ export interface ForgeCartClientConfig {
   adminSecret?: string;
   uploadEndpoint?: string;
   headers?: Record<string, string>;
+  // Session preferences sent as forgecart-currency / forgecart-language
+  // headers on every request. Override later via setCurrencyCode() /
+  // setLanguageCode().
+  currencyCode?: string;
+  languageCode?: string;
 }
 
 export class SDKLogger {
@@ -120,14 +135,33 @@ export class BaseGraphQLClient {
   private wsClientStale = false;
   private authToken: string | null = null;
   private transactionToken: string | null = null;
+  private currencyCode: string | null = null;
+  private languageCode: string | null = null;
   private errorHandler: ErrorHandler | null = null;
+  private readonly persistSession: boolean;
+  private readonly tokenStorageKey: string;
 
   constructor(
     endpoint: string,
     private readonly baseHeaders: Record<string, string>,
     private readonly uploadEndpoint?: string,
+    options?: { persistSession?: boolean; currencyCode?: string; languageCode?: string },
   ) {
     this.endpoint = endpoint.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+    // Cross-tab session continuity: each new tab or reload builds a fresh
+    // client instance, so without a shared store every one would mint a new
+    // anonymous session server-side — and be counted as a new active user.
+    // Persist the captured token in localStorage (shared across same-origin
+    // tabs), keyed per endpoint + channel so separate stores never collide.
+    // Opt out with `{ persistSession: false }` when the host app owns token
+    // storage (e.g. the admin dashboard).
+    this.persistSession = options?.persistSession ?? true;
+    this.currencyCode = options?.currencyCode ?? null;
+    this.languageCode = options?.languageCode ?? null;
+    this.tokenStorageKey = `forgecart:auth:${this.endpoint}:${this.baseHeaders["forgecart-token"] ?? ""}`;
+    if (this.persistSession) {
+      this.authToken = this.readPersistedToken();
+    }
   }
 
   private getWsClient(): WsClient {
@@ -158,12 +192,19 @@ export class BaseGraphQLClient {
     if (this.transactionToken) {
       headers["forgecart-transaction-token"] = this.transactionToken;
     }
+    if (this.currencyCode) {
+      headers["forgecart-currency"] = this.currencyCode;
+    }
+    if (this.languageCode) {
+      headers["forgecart-language"] = this.languageCode;
+    }
     return headers;
   }
 
   setAuthToken(token: string): void {
     if (this.authToken === token) return;
     this.authToken = token;
+    this.persistToken(token);
     this.disposeWsClient();
     this.logger.info("Auth token set");
   }
@@ -174,10 +215,42 @@ export class BaseGraphQLClient {
 
   clearAuthToken(): void {
     this.authToken = null;
+    this.persistToken(null);
     this.disposeWsClient();
     this.logger.info("Auth token cleared");
   }
 
+  // Currency/language preferences ride the WebSocket connection params,
+  // so changing one disposes the connection — the next request reconnects
+  // with the new forgecart-currency / forgecart-language headers.
+  setCurrencyCode(currencyCode: string): void {
+    if (this.currencyCode === currencyCode) return;
+    this.currencyCode = currencyCode;
+    this.disposeWsClient();
+    this.logger.info("Currency code set");
+  }
+
+  clearCurrencyCode(): void {
+    if (this.currencyCode === null) return;
+    this.currencyCode = null;
+    this.disposeWsClient();
+    this.logger.info("Currency code cleared");
+  }
+
+  setLanguageCode(languageCode: string): void {
+    if (this.languageCode === languageCode) return;
+    this.languageCode = languageCode;
+    this.disposeWsClient();
+    this.logger.info("Language code set");
+  }
+
+  clearLanguageCode(): void {
+    if (this.languageCode === null) return;
+    this.languageCode = null;
+    this.disposeWsClient();
+    this.logger.info("Language code cleared");
+  }
+
   setTransactionToken(token: string): void {
     this.transactionToken = token;
     this.logger.info("Transaction token set");
@@ -281,6 +354,7 @@ export class BaseGraphQLClient {
     const token = result.extensions["forgecart-auth-token"] as string | undefined;
     if (token && !this.authToken) {
       this.authToken = token;
+      this.persistToken(token);
       this.wsClientStale = true;
       this.logger.info("Session token captured from extensions");
     }
@@ -291,11 +365,37 @@ export class BaseGraphQLClient {
     const token = result.extensions["forgecart-auth-token"] as string | undefined;
     if (token && !this.authToken) {
       this.authToken = token;
+      this.persistToken(token);
       this.wsClientStale = true;
       this.logger.info("Session token captured from upload response");
     }
   }
 
+  private readPersistedToken(): string | null {
+    if (typeof localStorage === "undefined") return null;
+    try {
+      return localStorage.getItem(this.tokenStorageKey);
+    } catch {
+      // Storage can throw (Safari private mode, disabled cookies, quota).
+      // Falling back to an in-memory session keeps the SDK functional.
+      return null;
+    }
+  }
+
+  private persistToken(token: string | null): void {
+    if (!this.persistSession || typeof localStorage === "undefined") return;
+    try {
+      if (token === null) {
+        localStorage.removeItem(this.tokenStorageKey);
+      } else {
+        localStorage.setItem(this.tokenStorageKey, token);
+      }
+    } catch {
+      // Persistence is best-effort; a storage failure must never break a
+      // request. The in-memory token still serves the current page.
+    }
+  }
+
   private containsFiles(obj: unknown): boolean {
     if (obj === null || obj === undefined) return false;
     if (typeof obj !== "object") return false;
@@ -326,6 +426,8 @@ export class BaseGraphQLClient {
     const forked = new BaseGraphQLClient(this.endpoint, this.baseHeaders, this.uploadEndpoint);
     forked.authToken = this.authToken;
     forked.transactionToken = transactionToken;
+    forked.currencyCode = this.currencyCode;
+    forked.languageCode = this.languageCode;
     forked.wsClient = this.wsClient;
     forked.ownsWsClient = false;
     return forked;
@@ -378,7 +480,10 @@ export class ForgeCartAdminClient {
     if (config.adminSecret) {
       headers['forgecart-secret'] = config.adminSecret;
     }
-    this.client = new BaseGraphQLClient(config.endpoint, headers, config.uploadEndpoint);
+    this.client = new BaseGraphQLClient(config.endpoint, headers, config.uploadEndpoint, {
+      currencyCode: config.currencyCode,
+      languageCode: config.languageCode,
+    });
     this._namespace = new AdminNamespace(this.client);
   }
 
@@ -394,6 +499,22 @@ export class ForgeCartAdminClient {
     this.client.clearAuthToken();
   }
 
+  setCurrencyCode(currencyCode: string): void {
+    this.client.setCurrencyCode(currencyCode);
+  }
+
+  clearCurrencyCode(): void {
+    this.client.clearCurrencyCode();
+  }
+
+  setLanguageCode(languageCode: string): void {
+    this.client.setLanguageCode(languageCode);
+  }
+
+  clearLanguageCode(): void {
+    this.client.clearLanguageCode();
+  }
+
   setTransactionToken(token: string): void {
     this.client.setTransactionToken(token);
   }
@@ -574,6 +695,9 @@ export class ForgeCartAdminClient {
   get hook(): Admin.HookCategory {
     return this._namespace.hook;
   }
+  get market(): Admin.MarketCategory {
+    return this._namespace.market;
+  }
   get marketingAttribution(): Admin.MarketingAttributionCategory {
     return this._namespace.marketingAttribution;
   }
@@ -583,6 +707,9 @@ export class ForgeCartAdminClient {
   get marketingIdentity(): Admin.MarketingIdentityCategory {
     return this._namespace.marketingIdentity;
   }
+  get mission(): Admin.MissionCategory {
+    return this._namespace.mission;
+  }
   get onboarding(): Admin.OnboardingCategory {
     return this._namespace.onboarding;
   }
@@ -669,7 +796,10 @@ export class ForgeCartShopClient {
 
   constructor(config: ForgeCartShopClientConfig) {
     const headers: Record<string, string> = { 'forgecart-token': config.channelToken, ...config.headers };
-    this.client = new BaseGraphQLClient(config.endpoint, headers, config.uploadEndpoint);
+    this.client = new BaseGraphQLClient(config.endpoint, headers, config.uploadEndpoint, {
+      currencyCode: config.currencyCode,
+      languageCode: config.languageCode,
+    });
     this._namespace = new ShopNamespace(this.client);
   }
 
@@ -685,6 +815,22 @@ export class ForgeCartShopClient {
     this.client.clearAuthToken();
   }
 
+  setCurrencyCode(currencyCode: string): void {
+    this.client.setCurrencyCode(currencyCode);
+  }
+
+  clearCurrencyCode(): void {
+    this.client.clearCurrencyCode();
+  }
+
+  setLanguageCode(languageCode: string): void {
+    this.client.setLanguageCode(languageCode);
+  }
+
+  clearLanguageCode(): void {
+    this.client.clearLanguageCode();
+  }
+
   setTransactionToken(token: string): void {
     this.client.setTransactionToken(token);
   }
@@ -742,6 +888,9 @@ export class ForgeCartShopClient {
   get cart(): Shop.CartCategory {
     return this._namespace.cart;
   }
+  get channel(): Shop.ChannelCategory {
+    return this._namespace.channel;
+  }
   get checkout(): Shop.CheckoutCategory {
     return this._namespace.checkout;
   }
@@ -791,8 +940,8 @@ export class ForgeCartClient {
   private readonly _shop: ForgeCartShopClient;
 
   constructor(config: ForgeCartClientConfig) {
-    this._admin = new ForgeCartAdminClient({ endpoint: config.endpoint + '/admin-api', channelToken: config.channelToken, adminSecret: config.adminSecret, uploadEndpoint: config.uploadEndpoint ? config.uploadEndpoint + '/admin-api' : undefined, headers: config.headers });
-    this._shop = new ForgeCartShopClient({ endpoint: config.endpoint + '/shop-api', channelToken: config.channelToken, uploadEndpoint: config.uploadEndpoint ? config.uploadEndpoint + '/shop-api' : undefined, headers: config.headers });
+    this._admin = new ForgeCartAdminClient({ endpoint: config.endpoint + '/admin-api', channelToken: config.channelToken, adminSecret: config.adminSecret, uploadEndpoint: config.uploadEndpoint ? config.uploadEndpoint + '/admin-api' : undefined, headers: config.headers, currencyCode: config.currencyCode, languageCode: config.languageCode });
+    this._shop = new ForgeCartShopClient({ endpoint: config.endpoint + '/shop-api', channelToken: config.channelToken, uploadEndpoint: config.uploadEndpoint ? config.uploadEndpoint + '/shop-api' : undefined, headers: config.headers, currencyCode: config.currencyCode, languageCode: config.languageCode });
     this._admin.setShopPeer(this._shop);
   }
 
@@ -806,6 +955,26 @@ export class ForgeCartClient {
     this._shop.clearAuthToken();
   }
 
+  setCurrencyCode(currencyCode: string): void {
+    this._admin.setCurrencyCode(currencyCode);
+    this._shop.setCurrencyCode(currencyCode);
+  }
+
+  clearCurrencyCode(): void {
+    this._admin.clearCurrencyCode();
+    this._shop.clearCurrencyCode();
+  }
+
+  setLanguageCode(languageCode: string): void {
+    this._admin.setLanguageCode(languageCode);
+    this._shop.setLanguageCode(languageCode);
+  }
+
+  clearLanguageCode(): void {
+    this._admin.clearLanguageCode();
+    this._shop.clearLanguageCode();
+  }
+
   setTransactionToken(token: string): void {
     this._admin.setTransactionToken(token);
     this._shop.setTransactionToken(token);