@schematichq/schematic-react 1.4.1 → 1.5.0

package/dist/schematic-react.d.ts

@@ -73,11 +73,11 @@ 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}
@@ -111,10 +111,10 @@ 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}
@@ -136,8 +136,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 */
@@ -198,6 +204,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>}
@@ -231,6 +245,62 @@ declare const CheckPlanReturnFromJSON: (json: any) => CheckPlanReturn;
 
 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;
+};
+
+declare type CreditBalanceListenerFn = CreditBalancesListenerFn | EmptyListenerFn;
+
+/** A company's lease-aware credit balances keyed by credit ID */
+export declare type CreditBalances = Record<string, CreditBalance>;
+
+declare const CreditBalancesFromJSON: (json: any) => CreditBalances;
+
+declare type CreditBalancesListenerFn = (value: CreditBalances) => void;
+
 /**
  *
  * @export
@@ -412,6 +482,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}
@@ -419,11 +495,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}
@@ -442,6 +530,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}
@@ -456,10 +550,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}
@@ -468,10 +562,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}
@@ -492,34 +586,36 @@ declare interface FeatureEntitlement {
     valueType: EntitlementValueType;
 }
 
+declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
+
+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];
-
-declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
-
-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];
 
 declare type PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
 
@@ -542,6 +638,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;
@@ -558,11 +670,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;
@@ -669,6 +787,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;
@@ -768,6 +893,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 */
@@ -775,11 +904,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 */
@@ -792,6 +924,14 @@ declare interface SchematicContextProps {
     client: SchematicJS.Schematic;
 }
 
+/** A company's credit balance for a single credit type, plus a loading flag */
+export declare type SchematicCreditBalance = {
+    /** The spendable balance; 0 while loading or when the company holds no balance in this credit */
+    balance: number;
+    /** True while the balance is still loading and no value has arrived yet */
+    isLoading: boolean;
+};
+
 export declare interface SchematicHookOpts {
     client?: SchematicJS.Schematic;
 }
@@ -811,6 +951,12 @@ declare namespace SchematicJS {
         CheckPlanReturn,
         CheckPlanReturnFromJSON,
         CheckPlanReturnListenerFn,
+        CompanyCreditBalance,
+        CreditBalance,
+        CreditBalanceListenerFn,
+        CreditBalances,
+        CreditBalancesFromJSON,
+        CreditBalancesListenerFn,
         EmptyListenerFn,
         Event_2 as Event,
         EventBody,
@@ -850,6 +996,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 */
@@ -929,6 +1081,16 @@ export declare const useSchematicContext: (opts?: SchematicHookOpts) => {
     setContext: (context: SchematicJS.SchematicContext) => Promise<void>;
 };
 
+/**
+ * Returns a company's live, lease-aware credit balance for a single credit type.
+ *
+ * Surfaces the spendable `settled` balance, sourced from the streamed
+ * `credit_balances` map (keyed by credit ID). It re-renders as partials arrive
+ * over the DataStream, so it stays accurate during an open lease — when the raw
+ * `remaining` would otherwise read stale / falsely "exhausted".
+ */
+export declare const useSchematicCreditBalance: (creditId: string, opts?: SchematicHookOpts) => SchematicCreditBalance;
+
 export declare const useSchematicEntitlement: (key: string, opts?: UseSchematicFlagOpts) => SchematicJS.CheckFlagReturn;
 
 export declare const useSchematicEvents: (opts?: SchematicHookOpts) => {