@schematichq/schematic-typescript-node 1.3.2 → 1.4.1

package/dist/api/types/index.d.ts

@@ -1,9 +1,10 @@
+export * from "./ActorType";
 export * from "./ApiError";
 export * from "./ApiKeyCreateResponseData";
-export * from "./ApiKeyRequestListResponseData";
-export * from "./ApiKeyRequestResponseData";
 export * from "./ApiKeyResponseData";
 export * from "./ApiKeyScope";
+export * from "./AuditLogListResponseData";
+export * from "./AuditLogResponseData";
 export * from "./BillingCouponResponseData";
 export * from "./BillingCreditBundleResponseData";
 export * from "./BillingCreditBundleStatus";
@@ -18,6 +19,7 @@ export * from "./BillingCreditGrantZeroedOutReason";
 export * from "./BillingCreditLedgerResponseData";
 export * from "./BillingCreditResponseData";
 export * from "./BillingCreditRolloverPolicy";
+export * from "./BillingCreditView";
 export * from "./BillingCustomerResponseData";
 export * from "./BillingCustomerSubscription";
 export * from "./BillingCustomerWithSubscriptionsResponseData";
@@ -67,7 +69,6 @@ export * from "./CompanyPlanInvalidReason";
 export * from "./CompanyPlanWithBillingSubView";
 export * from "./CompanyResponseData";
 export * from "./CompanySubscriptionResponseData";
-export * from "./CompanyViewWithFeatureUsageResponseData";
 export * from "./CompatiblePlans";
 export * from "./CompatiblePlansResponseData";
 export * from "./ComponentCapabilities";
@@ -82,9 +83,13 @@ export * from "./ComponentState";
 export * from "./Condition";
 export * from "./ConditionConditionType";
 export * from "./ConditionGroup";
+export * from "./ConditionGroupResponseData";
+export * from "./ConditionGroupView";
 export * from "./ConditionMetricPeriod";
 export * from "./ConditionMetricPeriodMonthReset";
 export * from "./ConditionOperator";
+export * from "./ConditionResponseData";
+export * from "./ConditionView";
 export * from "./CountResponse";
 export * from "./CouponRequestBody";
 export * from "./CreateBillingPlanCreditGrantRequestBody";
@@ -111,17 +116,22 @@ export * from "./CreatePriceTierRequestBody";
 export * from "./CreditAutoTopupAmountType";
 export * from "./CreditBundlePurchaseResponseData";
 export * from "./CreditCompanyGrantView";
+export * from "./CreditEventLedgerResponseData";
+export * from "./CreditEventType";
 export * from "./CreditGrantDetail";
 export * from "./CreditGrantExpiryRequestBody";
 export * from "./CreditGrantSortOrder";
 export * from "./CreditLedgerEnrichedEntryResponseData";
 export * from "./CreditLedgerPeriod";
+export * from "./CreditsAutoTopupCompanySummary";
+export * from "./CreditsAutoTopupCreditSummary";
+export * from "./CreditsAutoTopupHardFailure";
+export * from "./CreditsAutoTopupRetryFailure";
 export * from "./CreditTransferResponseData";
 export * from "./CreditTransferView";
 export * from "./CreditTriggerConfig";
 export * from "./CreditUsage";
 export * from "./CreditUsageAggregation";
-export * from "./CreditUsageResponseData";
 export * from "./CustomPlanConfig";
 export * from "./CustomPlanViewConfigResponseData";
 export * from "./DataExportOutputFileType";
@@ -160,21 +170,29 @@ export * from "./EventType";
 export * from "./FeatureCompanyResponseData";
 export * from "./FeatureCompanyUserResponseData";
 export * from "./FeatureDetailResponseData";
+export * from "./FeatureEntitlement";
+export * from "./FeatureEntitlementMetricPeriod";
+export * from "./FeatureEntitlementMonthReset";
 export * from "./FeatureLedgerResponseData";
 export * from "./FeatureLifecyclePhase";
 export * from "./FeatureResponseData";
 export * from "./FeatureType";
-export * from "./FeatureUsageDataResponseData";
 export * from "./FeatureUsageDetailResponseData";
+export * from "./FeatureUsageLegacyResponseData";
 export * from "./FeatureUsageResponseData";
+export * from "./FeatureUsageTimeSeriesResponseData";
+export * from "./FeatureView";
 export * from "./FlagDetailResponseData";
 export * from "./FlagResponseData";
 export * from "./FlagType";
+export * from "./FlagView";
 export * from "./GenericPreviewObject";
 export * from "./InvoiceRequestBody";
 export * from "./InvoiceResponseData";
+export * from "./InvoiceStatus";
 export * from "./IssueTemporaryAccessTokenResponseData";
 export * from "./KeysRequestBody";
+export * from "./LimitTimeSeriesPointResponseData";
 export * from "./ManagePlanPreviewResponseResponseData";
 export * from "./ManagePlanRequest";
 export * from "./ManagePlanResponseResponseData";
@@ -187,7 +205,6 @@ export * from "./PlanBundleCreditGrantRequestBody";
 export * from "./PlanBundleEntitlementRequestBody";
 export * from "./PlanBundleResponseData";
 export * from "./PlanChangeAction";
-export * from "./PlanChangeActorType";
 export * from "./PlanChangeBasePlanAction";
 export * from "./PlanChangeResponseData";
 export * from "./PlanChangeSubscriptionAction";
@@ -207,14 +224,21 @@ export * from "./PlanSelection";
 export * from "./PlanSnapshotView";
 export * from "./PlanTraitResponseData";
 export * from "./PlanType";
+export * from "./PlanVersionCompanyMigrationResponseData";
+export * from "./PlanVersionCompanyMigrationStatus";
+export * from "./PlanVersionMigrationResponseData";
+export * from "./PlanVersionMigrationStatus";
+export * from "./PlanVersionMigrationStrategy";
 export * from "./PlanVersionResponseData";
 export * from "./PlanVersionStatus";
+export * from "./PlanViewPublicResponseData";
 export * from "./PreviewObject";
 export * from "./PreviewObjectResponseData";
 export * from "./PreviewSubscriptionChangeResponseData";
 export * from "./PreviewSubscriptionFinanceResponseData";
 export * from "./PreviewSubscriptionUpcomingInvoiceLineItems";
 export * from "./ProrationBehavior";
+export * from "./PublicPlansResponseData";
 export * from "./QuickstartResp";
 export * from "./RawEventBatchResponseData";
 export * from "./RawEventResponseData";
@@ -241,7 +265,11 @@ export * from "./RulesengineConditionGroup";
 export * from "./RulesengineConditionMetricPeriod";
 export * from "./RulesengineConditionMetricPeriodMonthReset";
 export * from "./RulesengineConditionOperator";
+export * from "./RulesengineEntitlementValueType";
 export * from "./RulesengineEntityType";
+export * from "./RulesengineFeatureEntitlement";
+export * from "./RulesengineFeatureEntitlementMetricPeriod";
+export * from "./RulesengineFeatureEntitlementMonthReset";
 export * from "./RulesengineFlag";
 export * from "./RulesengineRule";
 export * from "./RulesengineRuleRuleType";
@@ -250,6 +278,11 @@ export * from "./RulesengineTrait";
 export * from "./RulesengineTraitDefinition";
 export * from "./RulesengineTraitDefinitionComparableType";
 export * from "./RulesengineUser";
+export * from "./RuleView";
+export * from "./ScheduledCheckoutResponseData";
+export * from "./ScheduledCheckoutStatus";
+export * from "./ScheduledDowngradeConfigBehavior";
+export * from "./ScheduledDowngradeResponseData";
 export * from "./SegmentStatusResp";
 export * from "./SkippedEntitlementErrorResponseData";
 export * from "./SkippedEntitlementResponseData";
@@ -260,6 +293,7 @@ export * from "./SubscriptionTraitUpdate";
 export * from "./SubscriptionType";
 export * from "./TemporaryAccessTokenResourceType";
 export * from "./TemporaryAccessTokenResponseData";
+export * from "./TimeSeriesGranularity";
 export * from "./TraitDefinition";
 export * from "./TraitDefinitionComparableType";
 export * from "./TraitType";
@@ -280,11 +314,14 @@ export * from "./UpsertUserRequestBody";
 export * from "./UpsertUserSubRequestBody";
 export * from "./UsageBasedEntitlementRequestBody";
 export * from "./UsageBasedEntitlementResponseData";
+export * from "./UsageTimeSeriesPointResponseData";
 export * from "./UserDetailResponseData";
 export * from "./UserResponseData";
+export * from "./WebFeatureUsageWebhookOutput";
 export * from "./WebhookEventDetailResponseData";
 export * from "./WebhookEventResponseData";
 export * from "./WebhookEventStatus";
 export * from "./WebhookRequestType";
 export * from "./WebhookResponseData";
 export * from "./WebhookStatus";
+export * from "./WhoAmIResponseData";

package/dist/cache/index.d.ts

@@ -0,0 +1,3 @@
+export { type CacheProvider, type CacheOptions } from "./types";
+export { LocalCache } from "./local";
+export { RedisCacheProvider, type RedisClient } from "./redis";

package/dist/cache/local.d.ts

@@ -0,0 +1,21 @@
+import { CacheProvider, CacheOptions } from "./types";
+/**
+ * In-memory cache implementation with LRU eviction and TTL support
+ */
+declare class LocalCache<T> implements CacheProvider<T> {
+    private cache;
+    private maxItems;
+    private accessCounter;
+    private defaultTTL;
+    constructor({ maxItems, ttl }?: CacheOptions);
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T, ttlOverride?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMissing(keysToKeep: string[], _?: {
+        scanPattern?: string;
+    }): Promise<void>;
+    private evictItem;
+    private evictExpiredItems;
+    private evictLRUItems;
+}
+export { type CacheProvider, LocalCache };

package/dist/cache/redis.d.ts

@@ -0,0 +1,38 @@
+import { CacheProvider, CacheOptions } from "./types";
+/**
+ * Minimal interface describing the redis client methods used by RedisCacheProvider.
+ * Compatible with the 'redis' package's RedisClientType.
+ */
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    setEx(key: string, seconds: number, value: string): Promise<unknown>;
+    del(key: string | string[]): Promise<unknown>;
+    scanIterator(options: {
+        MATCH: string;
+        COUNT: number;
+    }): AsyncIterable<string>;
+}
+export interface RedisOptions extends CacheOptions {
+    /** Pre-created, connected redis client */
+    client: RedisClient;
+    /** Redis key prefix for all cache keys (default: 'schematic:') */
+    keyPrefix?: string;
+}
+/**
+ * Redis-based cache provider implementation
+ * Accepts a pre-created redis client (e.g. from the 'redis' package)
+ */
+export declare class RedisCacheProvider<T> implements CacheProvider<T> {
+    private client;
+    private defaultTTL;
+    private keyPrefix;
+    constructor(options: RedisOptions);
+    private getFullKey;
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMissing(keysToKeep: string[], options?: {
+        scanPattern?: string;
+    }): Promise<void>;
+}

package/dist/cache/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cache provider interface for storing and retrieving entities
+ */
+export interface CacheProvider<T> {
+    /** Get a value from cache */
+    get(key: string): Promise<T | null>;
+    /** Set a value in cache */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /** Delete a value from cache */
+    delete(key: string): Promise<void>;
+    /** Delete all keys not in the keysToKeep array (optional, for bulk operations) */
+    deleteMissing?(keysToKeep: string[], options?: {
+        scanPattern?: string;
+    }): Promise<void>;
+}
+export interface CacheOptions {
+    maxItems?: number;
+    ttl?: number;
+}

package/dist/datastream/datastream-client.d.ts

@@ -0,0 +1,239 @@
+import * as Schematic from '../api/types';
+import { Logger } from '../logger';
+import { LazyEmitter } from './emitter';
+import type { CacheProvider } from '../cache/types';
+import { type RedisClient } from '../cache/redis';
+/**
+ * Options for configuring the DataStream client
+ */
+export interface DataStreamClientOptions {
+    /** Schematic API key for authentication */
+    apiKey: string;
+    /** Base URL for the API (will be converted to WebSocket URL) */
+    baseURL?: string;
+    /** Logger for debug/info/error messages */
+    logger: Logger;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTTL?: number;
+    /** Pre-created, connected redis client for all cache providers (if not provided, uses memory cache) */
+    redisClient?: RedisClient;
+    /** Redis key prefix for all cache keys (default: 'schematic:') */
+    redisKeyPrefix?: string;
+    /** Custom cache provider for company entities (overrides Redis config if provided) */
+    companyCache?: CacheProvider<Schematic.RulesengineCompany>;
+    /** Custom cache provider for user entities (overrides Redis config if provided) */
+    userCache?: CacheProvider<Schematic.RulesengineUser>;
+    /** Custom cache provider for flag entities (overrides Redis config if provided) */
+    flagCache?: CacheProvider<Schematic.RulesengineFlag>;
+    /** Enable replicator mode for external data synchronization */
+    replicatorMode?: boolean;
+    /** Health check URL for replicator mode */
+    replicatorHealthURL?: string;
+    /** Health check interval for replicator mode in milliseconds */
+    replicatorHealthCheck?: number;
+}
+/**
+ * DataStreamClient provides a comprehensive client for Schematic's datastream
+ * with caching, flag evaluation, and entity management matching the Go implementation
+ */
+export declare class DataStreamClient extends LazyEmitter {
+    private readonly apiKey;
+    private readonly baseURL?;
+    private readonly logger;
+    private readonly cacheTTL;
+    private readonly companyCacheProvider;
+    private readonly userCacheProvider;
+    private readonly flagsCacheProvider;
+    private readonly companyKeyCacheProvider;
+    private readonly userKeyCacheProvider;
+    private wsClient?;
+    private rulesEngine;
+    private readonly replicatorMode;
+    private readonly replicatorHealthURL?;
+    private readonly replicatorHealthCheck;
+    private replicatorReady;
+    private replicatorHealthInterval?;
+    private replicatorCacheVersion?;
+    private pendingCompanyRequests;
+    private pendingUserRequests;
+    private pendingFlagRequest?;
+    constructor(options: DataStreamClientOptions);
+    /**
+     * Creates cache providers based on configuration options
+     * Priority: custom cache provider > Redis client > memory cache
+     * Flag cache uses special TTL logic matching Go implementation
+     */
+    private createCacheProvider;
+    /**
+     * Creates a key→ID mapping cache provider (always string values)
+     * Uses Redis if available, otherwise memory cache
+     */
+    private createKeyCacheProvider;
+    /**
+     * Calculates cache TTL based on cache type, matching Go implementation
+     * - Flag cache: use the greater of maxCacheTTL (30 days) or configured cacheTTL
+     * - Other caches: use configured cacheTTL (defaults to 24 hours)
+     */
+    private calculateCacheTTL;
+    /**
+     * Start initializes and starts the datastream client
+     */
+    start(): Promise<void>;
+    /**
+     * IsConnected returns whether the client is connected to the datastream
+     * In replicator mode, returns true if the external replicator is ready
+     */
+    isConnected(): boolean;
+    /**
+     * GetCompany retrieves a company by keys, using cache or datastream
+     */
+    getCompany(keys: Record<string, string>): Promise<Schematic.RulesengineCompany>;
+    /**
+     * GetUser retrieves a user by keys, using cache or datastream
+     */
+    getUser(keys: Record<string, string>): Promise<Schematic.RulesengineUser>;
+    /**
+     * GetFlag retrieves a flag by key from cache
+     */
+    getFlag(flagKey: string): Promise<Schematic.RulesengineFlag | null>;
+    /**
+     * GetAllFlags requests a refresh of all flags from the datastream
+     */
+    getAllFlags(): Promise<void>;
+    /**
+     * CheckFlag evaluates a flag for a company and/or user context
+     */
+    checkFlag(evalCtx: {
+        company?: Record<string, string>;
+        user?: Record<string, string>;
+    }, flagKey: string): Promise<Schematic.RulesengineCheckFlagResult>;
+    /**
+     * UpdateCompanyMetrics updates company metrics locally (for track events)
+     */
+    updateCompanyMetrics(keys: Record<string, string>, event: string, quantity: number): Promise<void>;
+    /**
+     * Close gracefully closes the datastream client
+     */
+    close(): void;
+    /**
+     * IsReplicatorReady returns whether the external replicator is ready
+     */
+    isReplicatorReady(): boolean;
+    /**
+     * IsReplicatorMode returns whether the client is running in replicator mode
+     */
+    isReplicatorMode(): boolean;
+    /**
+     * GetReplicatorCacheVersion returns the current cache version from the replicator
+     */
+    getReplicatorCacheVersion(): string | undefined;
+    /**
+     * GetReplicatorCacheVersionAsync attempts to fetch cache version immediately if not available
+     */
+    getReplicatorCacheVersionAsync(timeoutMs?: number): Promise<string | undefined>;
+    /**
+     * handleMessage processes incoming datastream messages
+     */
+    private handleMessage;
+    /**
+     * handleCompanyMessage processes company-specific datastream messages
+     */
+    private handleCompanyMessage;
+    /**
+     * handleUserMessage processes user-specific datastream messages
+     */
+    private handleUserMessage;
+    /**
+     * handleFlagsMessage processes bulk flags messages
+     */
+    private handleFlagsMessage;
+    /**
+     * handleFlagMessage processes single flag messages
+     */
+    private handleFlagMessage;
+    /**
+     * handleErrorMessage processes error messages
+     */
+    private handleErrorMessage;
+    /**
+     * handleConnectionReady is called when the WebSocket connection is ready
+     */
+    private handleConnectionReady;
+    /**
+     * sendDataStreamRequest sends a request to the datastream
+     */
+    private sendDataStreamRequest;
+    /**
+     * getCompanyFromCache attempts to retrieve a company from cache using any of the provided keys
+     */
+    private getCompanyFromCache;
+    /**
+     * getUserFromCache attempts to retrieve a user from cache using any of the provided keys
+     */
+    private getUserFromCache;
+    /**
+     * cacheCompanyForKeys caches a company for all of its keys
+     */
+    private cacheCompanyForKeys;
+    /**
+     * cacheUserForKeys caches a user for all of its keys using two-level indirection
+     */
+    private cacheUserForKeys;
+    /**
+     * generateCacheKeysForCompany generates all cache keys for a company's keys
+     */
+    private generateCacheKeysForCompany;
+    /**
+     * generateCacheKeysForUser generates all cache keys for a user's keys
+     */
+    private generateCacheKeysForUser;
+    /**
+     * notifyPendingCompanyRequests notifies all pending company requests
+     */
+    private notifyPendingCompanyRequests;
+    /**
+     * notifyPendingUserRequests notifies all pending user requests
+     */
+    private notifyPendingUserRequests;
+    /**
+     * cleanupPendingCompanyRequests removes a specific handler from pending company requests
+     */
+    private cleanupPendingCompanyRequests;
+    /**
+     * cleanupPendingUserRequests removes a specific handler from pending user requests
+     */
+    private cleanupPendingUserRequests;
+    /**
+     * clearPendingRequests clears all pending requests
+     */
+    private clearPendingRequests;
+    /**
+     * startReplicatorHealthCheck starts periodic health checks for replicator mode
+     */
+    private startReplicatorHealthCheck;
+    /**
+     * checkReplicatorHealth performs a single health check against the external replicator
+     */
+    private checkReplicatorHealth;
+    /**
+     * flagCacheKey generates a cache key for a flag
+     */
+    private flagCacheKey;
+    /**
+     * resourceIdCacheKey generates a cache key for an ID-based resource lookup
+     */
+    private resourceIdCacheKey;
+    /**
+     * resourceKeyToCacheKey generates a cache key for a resource
+     */
+    private resourceKeyToCacheKey;
+    /**
+     * deepCopyCompany creates a complete deep copy of a Company struct
+     */
+    private deepCopyCompany;
+    private evaluateFlag;
+    /**
+     * getRulesEngineVersionKey gets the version key from the rules engine
+     */
+    private getRulesEngineVersionKey;
+}

package/dist/datastream/emitter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal interface for the subset of EventEmitter we use.
+ * Avoids importing the Node.js `events` module at the top level
+ * so that edge runtimes (Cloudflare Workers, etc.) can load the
+ * module graph without error.
+ */
+export interface Emitter {
+    on(event: string, listener: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): void;
+}
+/**
+ * Mixin base class that provides lazy-loaded EventEmitter composition.
+ * The Node.js `events` module is only required the first time a listener
+ * is registered or an event is emitted, keeping the import out of the
+ * module-level dependency graph.
+ */
+export declare class LazyEmitter {
+    private _emitter;
+    private ensureEmitter;
+    on(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+}

package/dist/datastream/index.d.ts

@@ -0,0 +1,2 @@
+export { DataStreamClient } from './datastream-client';
+export type { DataStreamClientOptions, } from './datastream-client';

package/dist/datastream/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Datastream message types for WebSocket communication
+ */
+export type Action = "start" | "stop";
+export declare enum EntityType {
+    COMPANY = "rulesengine.Company",
+    COMPANIES = "rulesengine.Companies",
+    USER = "rulesengine.User",
+    USERS = "rulesengine.Users",
+    FLAG = "rulesengine.Flag",
+    FLAGS = "rulesengine.Flags"
+}
+export declare enum MessageType {
+    FULL = "full",
+    PARTIAL = "partial",
+    DELETE = "delete",
+    ERROR = "error",
+    UNKNOWN = "unknown"
+}
+/**
+ * DataStreamReq represents a request message to the datastream
+ */
+export interface DataStreamReq {
+    entity_type: EntityType;
+    keys?: Record<string, string>;
+}
+/**
+ * DataStreamBaseReq wraps the request data
+ */
+export interface DataStreamBaseReq {
+    data: DataStreamReq;
+}
+/**
+ * DataStreamResp represents a response message from the datastream
+ */
+export interface DataStreamResp {
+    data: unknown;
+    entity_type: string;
+    message_type: string;
+}
+/**
+ * DataStreamError represents an error message from the datastream
+ */
+export interface DataStreamError {
+    error: string;
+    keys?: Record<string, string>;
+    entity_type?: EntityType;
+}