@schematichq/schematic-js 1.4.0 → 1.5.0

package/dist/schematic.d.ts

@@ -67,11 +67,11 @@ export declare interface CheckFlagResponseData {
     featureUsageEvent?: string | null;
     /**
      * Deprecated: Use Entitlement.MetricPeriod instead.
-     * @type {string}
+     * @type {MetricPeriod}
      * @memberof CheckFlagResponseData
      * @deprecated
      */
-    featureUsagePeriod?: string | null;
+    featureUsagePeriod?: MetricPeriod | null;
     /**
      * Deprecated: Use Entitlement.MetricResetAt instead.
      * @type {Date}
@@ -105,10 +105,10 @@ export declare interface CheckFlagResponseData {
     ruleId?: string | null;
     /**
      * If a rule was found, its type
-     * @type {string}
+     * @type {RuleType}
      * @memberof CheckFlagResponseData
      */
-    ruleType?: string | null;
+    ruleType?: RuleType_2 | null;
     /**
      * If user keys were provided and matched a user, its ID
      * @type {string}
@@ -130,8 +130,14 @@ export declare type CheckFlagReturn = {
     featureUsageExceeded?: boolean;
     /** If company keys were provided and matched a company, its ID */
     companyId?: string;
-    /** If the company has a credit-based entitlement for this feature, the remaining credit amount */
+    /** If the company has a credit-based entitlement for this feature, the ID of the credit */
+    creditId?: string;
+    /** If the company has a credit-based entitlement for this feature, the credit available to fund new consumption excluding any open lease hold (the value lease-holding SDKs gate on) */
     creditRemaining?: number;
+    /** If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease, 0 when none is open */
+    creditReserved?: number;
+    /** If the company has a credit-based entitlement for this feature, the spendable balance including any open lease hold (creditRemaining + creditReserved); the number to display to end users */
+    creditSettled?: number;
     /** If an error occurred while checking the flag, the error message */
     error?: string;
     /** If a numeric feature entitlement rule was matched, its allocation */
@@ -192,6 +198,14 @@ declare interface CheckFlagsResponse {
  * @interface CheckFlagsResponseData
  */
 declare interface CheckFlagsResponseData {
+    /**
+     * Lease-aware credit balances keyed by credit ID, covering every credit type the company holds a balance in
+     * @type {{ [key: string]: CompanyCreditBalance; }}
+     * @memberof CheckFlagsResponseData
+     */
+    creditBalances?: {
+        [key: string]: CompanyCreditBalance;
+    };
     /**
      *
      * @type {Array<CheckFlagResponseData>}
@@ -225,6 +239,62 @@ export declare const CheckPlanReturnFromJSON: (json: any) => CheckPlanReturn;
 
 export declare type CheckPlanReturnListenerFn = (value: CheckPlanReturn) => void;
 
+/**
+ * Schematic API
+ * Schematic API
+ *
+ * The version of the OpenAPI document: 0.1
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ *
+ * @export
+ * @interface CompanyCreditBalance
+ */
+export declare interface CompanyCreditBalance {
+    /**
+     * Remaining credit, excluding any open lease hold (the value SDKs gate on)
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    remaining: number;
+    /**
+     * Amount held by the company's open credit lease, 0 when none is open
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    reserved: number;
+    /**
+     * Spendable balance including the open lease hold (remaining + reserved)
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    settled: number;
+}
+
+/** A company's lease-aware balance for a single credit type */
+export declare type CreditBalance = {
+    /** Spendable balance including any open lease hold (remaining + reserved); the number to display to end users */
+    settled: number;
+    /** Remaining credit excluding any open lease hold (the value lease-holding SDKs gate on) */
+    remaining: number;
+    /** Amount held by the company's open credit lease, 0 when none is open */
+    reserved: number;
+};
+
+export declare type CreditBalanceListenerFn = CreditBalancesListenerFn | EmptyListenerFn;
+
+/** A company's lease-aware credit balances keyed by credit ID */
+export declare type CreditBalances = Record<string, CreditBalance>;
+
+export declare const CreditBalancesFromJSON: (json: any) => CreditBalances;
+
+export declare type CreditBalancesListenerFn = (value: CreditBalances) => void;
+
 /**
  *
  * @export
@@ -406,6 +476,12 @@ declare interface FeatureEntitlement {
      * @memberof FeatureEntitlement
      */
     allocation?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the credit cost per unit of usage
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    consumptionRate?: number | null;
     /**
      * If the company has a credit-based entitlement for this feature, the ID of the credit
      * @type {string}
@@ -413,11 +489,23 @@ declare interface FeatureEntitlement {
      */
     creditId?: string | null;
     /**
-     * If the company has a credit-based entitlement for this feature, the remaining credit amount
+     * If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead
      * @type {number}
      * @memberof FeatureEntitlement
      */
     creditRemaining?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditReserved?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditSettled?: number | null;
     /**
      * If the company has a credit-based entitlement for this feature, the total credit amount
      * @type {number}
@@ -436,6 +524,12 @@ declare interface FeatureEntitlement {
      * @memberof FeatureEntitlement
      */
     eventName?: string | null;
+    /**
+     * For event-based or credit-metered feature entitlements, the event subtype whose usage is tracked
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    eventSubtype?: string | null;
     /**
      * The ID of the feature
      * @type {string}
@@ -450,10 +544,10 @@ declare interface FeatureEntitlement {
     featureKey: string;
     /**
      * For event-based feature entitlements, the period over which usage is tracked
-     * @type {string}
+     * @type {MetricPeriod}
      * @memberof FeatureEntitlement
      */
-    metricPeriod?: FeatureEntitlementMetricPeriodEnum | null;
+    metricPeriod?: MetricPeriod | null;
     /**
      * For event-based feature entitlements, when the usage period will reset
      * @type {Date}
@@ -462,10 +556,10 @@ declare interface FeatureEntitlement {
     metricResetAt?: Date | null;
     /**
      * For event-based feature entitlements that have a monthly period, whether that monthly reset is based on the calendar month or a billing cycle
-     * @type {string}
+     * @type {MetricPeriodMonthReset}
      * @memberof FeatureEntitlement
      */
-    monthReset?: FeatureEntitlementMonthResetEnum | null;
+    monthReset?: MetricPeriodMonthReset | null;
     /**
      * For usage-based pricing, the soft limit for overage charges or the next tier boundary
      * @type {number}
@@ -486,34 +580,36 @@ declare interface FeatureEntitlement {
     valueType: EntitlementValueType;
 }
 
+export declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
+
+export declare type FlagValueListenerFn = BooleanListenerFn | EmptyListenerFn;
+
+/** A record of unique key-value pairs used for identifying a company or user */
+export declare type Keys = Record<string, string>;
+
 /**
+ *
  * @export
  */
-declare const FeatureEntitlementMetricPeriodEnum: {
+declare const MetricPeriod: {
     readonly AllTime: "all_time";
     readonly CurrentDay: "current_day";
     readonly CurrentMonth: "current_month";
     readonly CurrentWeek: "current_week";
 };
 
-declare type FeatureEntitlementMetricPeriodEnum = (typeof FeatureEntitlementMetricPeriodEnum)[keyof typeof FeatureEntitlementMetricPeriodEnum];
+declare type MetricPeriod = (typeof MetricPeriod)[keyof typeof MetricPeriod];
 
 /**
+ *
  * @export
  */
-declare const FeatureEntitlementMonthResetEnum: {
-    readonly FirstOfMonth: "first_of_month";
+declare const MetricPeriodMonthReset: {
     readonly BillingCycle: "billing_cycle";
+    readonly FirstOfMonth: "first_of_month";
 };
 
-declare type FeatureEntitlementMonthResetEnum = (typeof FeatureEntitlementMonthResetEnum)[keyof typeof FeatureEntitlementMonthResetEnum];
-
-export declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
-
-export declare type FlagValueListenerFn = BooleanListenerFn | EmptyListenerFn;
-
-/** A record of unique key-value pairs used for identifying a company or user */
-export declare type Keys = Record<string, string>;
+declare type MetricPeriodMonthReset = (typeof MetricPeriodMonthReset)[keyof typeof MetricPeriodMonthReset];
 
 export declare type PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
 
@@ -536,6 +632,22 @@ export declare enum RuleType {
     DEFAULT = "default"
 }
 
+/**
+ *
+ * @export
+ */
+declare const RuleType_2: {
+    readonly CompanyOverride: "company_override";
+    readonly CompanyOverrideUsageExceeded: "company_override_usage_exceeded";
+    readonly Default: "default";
+    readonly GlobalOverride: "global_override";
+    readonly PlanEntitlement: "plan_entitlement";
+    readonly PlanEntitlementUsageExceeded: "plan_entitlement_usage_exceeded";
+    readonly Standard: "standard";
+};
+
+declare type RuleType_2 = (typeof RuleType_2)[keyof typeof RuleType_2];
+
 export declare class Schematic {
     private additionalHeaders;
     private apiKey;
@@ -552,11 +664,17 @@ export declare class Schematic {
     private isPending;
     private isPendingListeners;
     private planListeners;
+    private creditBalanceListeners;
     private storage;
+    private persistFlagState;
+    private flagStateCacheKey;
+    private flagStateCacheMaxAgeMs;
+    private cachedFlagState;
     private useWebSocket;
     private checks;
     private featureUsageEventMap;
     private planChecks;
+    private creditBalances;
     private webSocketUrl;
     private webSocketConnectionTimeout;
     private webSocketReconnect;
@@ -663,6 +781,13 @@ export declare class Schematic {
     private stopRetryTimer;
     private flushEventQueue;
     private getAnonymousId;
+    private hasCachedValuesForContext;
+    private readFlagStateCache;
+    private reviveCachedCheck;
+    private reviveCachedPlan;
+    private reviveCachedCreditBalances;
+    private hydrateFlagStateFromCache;
+    private persistContextToCache;
     private handleEvent;
     private sendEvent;
     private storeEvent;
@@ -762,6 +887,10 @@ export declare class Schematic {
     addIsPendingListener: (listener: PendingListenerFn) => () => void;
     private setIsPending;
     getPlan: () => CheckPlanReturn | undefined;
+    /** Get the company's lease-aware credit balances for the current context, keyed by credit ID */
+    getCreditBalances: () => CreditBalances;
+    /** Get the company's lease-aware balance for a single credit type in the current context */
+    getCreditBalance: (creditId: string) => CreditBalance | undefined;
     getFlagCheck: (flagKey: string) => CheckFlagReturn | undefined;
     getFlagValue: (flagKey: string) => boolean | undefined;
     /** Register an event listener that will be notified with the boolean value for a given flag when this value changes */
@@ -769,11 +898,14 @@ export declare class Schematic {
     /** Register an event listener that will be notified with the full flag check response for a given flag whenever this value changes */
     addFlagCheckListener: (flagKey: string, listener: FlagCheckListenerFn) => () => void;
     addPlanListener: (listener: PlanListenerFn) => () => void;
+    /** Register an event listener that will be notified with the company's credit balances (keyed by credit ID) whenever they change */
+    addCreditBalanceListener: (listener: CreditBalanceListenerFn) => () => void;
     private notifyFlagCheckListeners;
     /** Add or update a CheckFlagReturn in the featureUsageEventMap */
     private updateFeatureUsageEventMap;
     private notifyFlagValueListeners;
     private notifyPlanListeners;
+    private notifyCreditBalanceListeners;
 }
 
 /** Context for checking flags and sending events */
@@ -798,6 +930,12 @@ export declare type SchematicOptions = {
     offline?: boolean;
     /** Optionally provide a custom storage persister for client-side storage */
     storage?: StoragePersister;
+    /** Persist flag check results (and plan) keyed by context to the storage persister so subsequent page loads can boot with last-known values rather than fallbacks. Defaults to true; set false to disable.
+     *
+     * When a cache hit is found on `setContext`, `isPending` flips to false synchronously even if the cache only contains a subset of the flags the app subscribes to — uncached flags will resolve via configured fallbacks (`flagCheckDefaults`/`flagValueDefaults`) until the WebSocket reconciles. */
+    persistFlagState?: boolean;
+    /** Maximum age (ms) of a persisted cache entry before it is treated as stale on hydration. Per-context; older entries are dropped at construction time and on the next persist. Defaults to 7 days. */
+    flagStateCacheMaxAgeMs?: number;
     /** Use a WebSocket connection for real-time flag checks; if using this, run the cleanup function to close the connection */
     useWebSocket?: boolean;
     /** Optionally provide a custom WebSocket URL */