@schematichq/schematic-react 1.3.1 → 1.4.1

package/README.md

@@ -136,6 +136,45 @@ const MyComponent = () => {
 
 *Note: `useSchematicIsPending` is checking if entitlement data has been loaded, typically via `identify`. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to `identify`.*
 
+### Company plan information
+
+To access the current company's plan and trial status, you can use the `useSchematicPlan` hook:
+
+```tsx
+import { useSchematicPlan } from "@schematichq/schematic-react";
+
+const MyComponent = () => {
+    const plan = useSchematicPlan();
+
+    if (!plan) {
+        return <div>No plan assigned</div>;
+    }
+
+    return (
+        <div>
+            <p>Current plan: {plan.name}</p>
+
+            {plan.trialStatus === "active" && (
+                <p>Trial ends: {plan.trialEndDate?.toLocaleDateString()}</p>
+            )}
+
+            {plan.trialStatus === "expired" && (
+                <p>Your trial has ended. <a href="/upgrade">Upgrade now</a></p>
+            )}
+        </div>
+    );
+};
+```
+
+The hook returns an object with the following properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The plan ID |
+| `name` | `string` | The plan name |
+| `trialEndDate` | `Date \| undefined` | The trial end date, if the company has or had a trial |
+| `trialStatus` | `"active" \| "expired" \| "converted" \| undefined` | The company's trial status: `active` if the trial is ongoing, `expired` if the trial ended without conversion, `converted` if the company converted to a paid plan, or `undefined` if the company has never trialed |
+
 ## Fallback Behavior
 
 The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

package/dist/schematic-react.cjs.js

@@ -809,6 +809,7 @@ var UsagePeriod = /* @__PURE__ */ ((UsagePeriod2) => {
 var CheckFlagReturnFromJSON = (json) => {
   const {
     companyId,
+    entitlement,
     error,
     featureAllocation,
     featureUsage,
@@ -826,20 +827,27 @@ var CheckFlagReturnFromJSON = (json) => {
   const featureUsageExceeded = !value && // if flag is not false, then we haven't exceeded usage
   (ruleType == "company_override_usage_exceeded" || // if the rule type is one of these, then we have exceeded usage
   ruleType == "plan_entitlement_usage_exceeded");
+  const resolvedAllocation = entitlement?.allocation ?? featureAllocation;
+  const resolvedUsage = entitlement?.usage ?? featureUsage;
+  const resolvedEvent = entitlement?.eventName ?? featureUsageEvent;
+  const resolvedPeriod = entitlement?.metricPeriod ?? featureUsagePeriod;
+  const resolvedResetAt = entitlement?.metricResetAt ?? featureUsageResetAt;
   return {
     featureUsageExceeded,
     companyId: companyId == null ? void 0 : companyId,
+    creditRemaining: entitlement?.creditRemaining == null ? void 0 : entitlement.creditRemaining,
     error: error == null ? void 0 : error,
-    featureAllocation: featureAllocation == null ? void 0 : featureAllocation,
-    featureUsage: featureUsage == null ? void 0 : featureUsage,
-    featureUsageEvent: featureUsageEvent === null ? void 0 : featureUsageEvent,
-    featureUsagePeriod: featureUsagePeriod == null ? void 0 : featureUsagePeriod,
-    featureUsageResetAt: featureUsageResetAt == null ? void 0 : featureUsageResetAt,
+    featureAllocation: resolvedAllocation == null ? void 0 : resolvedAllocation,
+    featureUsage: resolvedUsage == null ? void 0 : resolvedUsage,
+    featureUsageEvent: resolvedEvent == null ? void 0 : resolvedEvent,
+    featureUsagePeriod: resolvedPeriod == null ? void 0 : resolvedPeriod,
+    featureUsageResetAt: resolvedResetAt == null ? void 0 : resolvedResetAt,
     flag,
     flagId: flagId == null ? void 0 : flagId,
     reason,
     ruleId: ruleId == null ? void 0 : ruleId,
     ruleType: ruleType == null ? void 0 : ruleType,
+    softLimit: entitlement?.softLimit == null ? void 0 : entitlement.softLimit,
     userId: userId == null ? void 0 : userId,
     value
   };
@@ -867,7 +875,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.3.1";
+var version = "1.4.0";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -2304,7 +2312,7 @@ var notifyPlanListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.3.1";
+var version2 = "1.4.1";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.d.ts

@@ -1,47 +1,792 @@
-import { CheckFlagReturn } from '@schematichq/schematic-js';
-import { CheckPlanReturn } from '@schematichq/schematic-js';
-import { Event as Event_2 } from '@schematichq/schematic-js';
-import { EventBody } from '@schematichq/schematic-js';
-import { EventBodyIdentify } from '@schematichq/schematic-js';
-import { EventBodyTrack } from '@schematichq/schematic-js';
-import { EventType } from '@schematichq/schematic-js';
-import { Keys } from '@schematichq/schematic-js';
 import { default as React_2 } from 'react';
-import { RuleType } from '@schematichq/schematic-js';
-import { Schematic } from '@schematichq/schematic-js';
-import { SchematicContext } from '@schematichq/schematic-js';
-import * as SchematicJS from '@schematichq/schematic-js';
-import { SchematicOptions } from '@schematichq/schematic-js';
-import { StoragePersister } from '@schematichq/schematic-js';
-import { Traits } from '@schematichq/schematic-js';
-import { TrialStatus } from '@schematichq/schematic-js';
-import { UsagePeriod } from '@schematichq/schematic-js';
 
 declare type BaseSchematicProviderProps = Omit<SchematicJS.SchematicOptions, "client" | "publishableKey" | "useWebSocket"> & {
     children: React_2.ReactNode;
 };
 
-export { CheckFlagReturn }
+declare type BooleanListenerFn = (value: boolean) => void;
+
+/**
+ *
+ * @export
+ * @interface CheckFlagResponse
+ */
+declare interface CheckFlagResponse {
+    /**
+     *
+     * @type {CheckFlagResponseData}
+     * @memberof CheckFlagResponse
+     */
+    data: CheckFlagResponseData;
+    /**
+     * Input parameters
+     * @type {object}
+     * @memberof CheckFlagResponse
+     */
+    params: object;
+}
+
+/**
+ *
+ * @export
+ * @interface CheckFlagResponseData
+ */
+declare interface CheckFlagResponseData {
+    /**
+     * If company keys were provided and matched a company, its ID
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    companyId?: string | null;
+    /**
+     * If a feature entitlement rule was matched, its entitlement details
+     * @type {FeatureEntitlement}
+     * @memberof CheckFlagResponseData
+     */
+    entitlement?: FeatureEntitlement;
+    /**
+     * If an error occurred while checking the flag, the error message
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    error?: string | null;
+    /**
+     * Deprecated: Use Entitlement.Allocation instead.
+     * @type {number}
+     * @memberof CheckFlagResponseData
+     * @deprecated
+     */
+    featureAllocation?: number | null;
+    /**
+     * Deprecated: Use Entitlement.Usage instead.
+     * @type {number}
+     * @memberof CheckFlagResponseData
+     * @deprecated
+     */
+    featureUsage?: number | null;
+    /**
+     * Deprecated: Use Entitlement.EventName instead.
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     * @deprecated
+     */
+    featureUsageEvent?: string | null;
+    /**
+     * Deprecated: Use Entitlement.MetricPeriod instead.
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     * @deprecated
+     */
+    featureUsagePeriod?: string | null;
+    /**
+     * Deprecated: Use Entitlement.MetricResetAt instead.
+     * @type {Date}
+     * @memberof CheckFlagResponseData
+     * @deprecated
+     */
+    featureUsageResetAt?: Date | null;
+    /**
+     * The key used to check the flag
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    flag: string;
+    /**
+     * If a flag was found, its ID
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    flagId?: string | null;
+    /**
+     * A human-readable explanation of the result
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    reason: string;
+    /**
+     * If a rule was found, its ID
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    ruleId?: string | null;
+    /**
+     * If a rule was found, its type
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    ruleType?: string | null;
+    /**
+     * If user keys were provided and matched a user, its ID
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    userId?: string | null;
+    /**
+     * A boolean flag check result; for feature entitlements, this represents whether further consumption of the feature is permitted
+     * @type {boolean}
+     * @memberof CheckFlagResponseData
+     */
+    value: boolean;
+}
 
-export { CheckPlanReturn }
+declare function CheckFlagResponseFromJSON(json: any): CheckFlagResponse;
+
+export declare type CheckFlagReturn = {
+    /** The company has access to the feature, but has exceeded the usage limit */
+    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 */
+    creditRemaining?: number;
+    /** If an error occurred while checking the flag, the error message */
+    error?: string;
+    /** If a numeric feature entitlement rule was matched, its allocation */
+    featureAllocation?: number;
+    /** If a numeric feature entitlement rule was matched, the company's usage */
+    featureUsage?: number;
+    /** Event representing the feature usage */
+    featureUsageEvent?: string;
+    /** For event-based feature entitlement rules, the period over which usage is tracked (current_month, current_day, current_week, all_time) */
+    featureUsagePeriod?: UsagePeriod;
+    /** For event-based feature entitlement rules, when the usage period will reset */
+    featureUsageResetAt?: Date;
+    /** The key used to check the flag */
+    flag: string;
+    /** If a flag was found, its ID */
+    flagId?: string;
+    /** A human-readable explanation of the result */
+    reason: string;
+    /** If a rule was found, its ID */
+    ruleId?: string;
+    /** If a rule was found, its type  */
+    ruleType?: RuleType;
+    /** For usage-based pricing, the soft limit for overage charges or the next tier boundary */
+    softLimit?: number;
+    /** If user keys were provided and matched a user, its ID */
+    userId?: string;
+    /** A boolean flag check result; for feature entitlements, this represents whether further consumption of the feature is permitted */
+    value: boolean;
+};
+
+declare const CheckFlagReturnFromJSON: (json: any) => CheckFlagReturn;
+
+declare type CheckFlagReturnListenerFn = (value: CheckFlagReturn) => void;
+
+/**
+ *
+ * @export
+ * @interface CheckFlagsResponse
+ */
+declare interface CheckFlagsResponse {
+    /**
+     *
+     * @type {CheckFlagsResponseData}
+     * @memberof CheckFlagsResponse
+     */
+    data: CheckFlagsResponseData;
+    /**
+     * Input parameters
+     * @type {object}
+     * @memberof CheckFlagsResponse
+     */
+    params: object;
+}
 
+/**
+ *
+ * @export
+ * @interface CheckFlagsResponseData
+ */
+declare interface CheckFlagsResponseData {
+    /**
+     *
+     * @type {Array<CheckFlagResponseData>}
+     * @memberof CheckFlagsResponseData
+     */
+    flags: Array<CheckFlagResponseData>;
+    /**
+     *
+     * @type {DatastreamCompanyPlan}
+     * @memberof CheckFlagsResponseData
+     */
+    plan?: DatastreamCompanyPlan;
+}
+
+declare function CheckFlagsResponseFromJSON(json: any): CheckFlagsResponse;
+
+declare type CheckOptions = {
+    context?: SchematicContext;
+    fallback?: boolean;
+    key: string;
+};
+
+export declare type CheckPlanReturn = {
+    id: string;
+    name: string;
+    trialEndDate?: Date;
+    trialStatus?: TrialStatus;
+};
+
+declare const CheckPlanReturnFromJSON: (json: any) => CheckPlanReturn;
+
+declare type CheckPlanReturnListenerFn = (value: CheckPlanReturn) => void;
+
+/**
+ *
+ * @export
+ * @interface DatastreamCompanyPlan
+ */
+declare interface DatastreamCompanyPlan {
+    /**
+     *
+     * @type {string}
+     * @memberof DatastreamCompanyPlan
+     */
+    id: string;
+    /**
+     *
+     * @type {string}
+     * @memberof DatastreamCompanyPlan
+     */
+    name: string;
+    /**
+     *
+     * @type {Date}
+     * @memberof DatastreamCompanyPlan
+     */
+    trialEndDate?: Date | null;
+    /**
+     *
+     * @type {TrialStatus}
+     * @memberof DatastreamCompanyPlan
+     */
+    trialStatus?: TrialStatus | null;
+}
+
+declare function DatastreamCompanyPlanFromJSON(json: any): DatastreamCompanyPlan;
+
+declare type EmptyListenerFn = () => void;
+
+/**
+ *
+ * @export
+ */
+declare const EntitlementValueType: {
+    readonly Boolean: "boolean";
+    readonly Credit: "credit";
+    readonly Numeric: "numeric";
+    readonly Trait: "trait";
+    readonly Unknown: "unknown";
+    readonly Unlimited: "unlimited";
+};
+
+declare type EntitlementValueType = (typeof EntitlementValueType)[keyof typeof EntitlementValueType];
+
+declare type Event_2 = {
+    api_key: string;
+    body: EventBody;
+    sent_at: string;
+    tracker_event_id: string;
+    tracker_user_id: string;
+    type: EventType;
+    retry_count?: number;
+    next_retry_at?: number;
+};
 export { Event_2 as Event }
 
-export { EventBody }
+export declare type EventBody = EventBodyIdentify | EventBodyTrack | EventBodyFlagCheck;
+
+/**
+ * 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 EventBodyFlagCheck
+ */
+declare interface EventBodyFlagCheck {
+    /**
+     * Schematic company ID (starting with 'comp_') of the company evaluated, if any
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    companyId?: string | null;
+    /**
+     * Report an error that occurred during the flag check
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    error?: string | null;
+    /**
+     * Schematic flag ID (starting with 'flag_') for the flag matching the key, if any
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    flagId?: string | null;
+    /**
+     * The key of the flag being checked
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    flagKey: string;
+    /**
+     * The reason why the value was returned
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    reason: string;
+    /**
+     * Key-value pairs used to to identify company for which the flag was checked
+     * @type {{ [key: string]: string; }}
+     * @memberof EventBodyFlagCheck
+     */
+    reqCompany?: {
+        [key: string]: string;
+    } | null;
+    /**
+     * Key-value pairs used to to identify user for which the flag was checked
+     * @type {{ [key: string]: string; }}
+     * @memberof EventBodyFlagCheck
+     */
+    reqUser?: {
+        [key: string]: string;
+    } | null;
+    /**
+     * Schematic rule ID (starting with 'rule_') of the rule that matched for the flag, if any
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    ruleId?: string | null;
+    /**
+     * Schematic user ID (starting with 'user_') of the user evaluated, if any
+     * @type {string}
+     * @memberof EventBodyFlagCheck
+     */
+    userId?: string | null;
+    /**
+     * The value of the flag for the given company and/or user
+     * @type {boolean}
+     * @memberof EventBodyFlagCheck
+     */
+    value: boolean;
+}
+
+declare function EventBodyFlagCheckToJSON(json: any): EventBodyFlagCheck;
+
+export declare type EventBodyIdentify = {
+    company?: {
+        keys?: Keys;
+        name?: string;
+        traits?: Traits;
+    };
+    keys?: Keys;
+    name?: string;
+    traits?: Traits;
+};
+
+export declare type EventBodyTrack = SchematicContext & {
+    event: string;
+    quantity?: number;
+    traits?: Traits;
+};
 
-export { EventBodyIdentify }
+export declare type EventType = "identify" | "track" | "flag_check";
+
+/**
+ *
+ * @export
+ * @interface FeatureEntitlement
+ */
+declare interface FeatureEntitlement {
+    /**
+     * If the company has a numeric entitlement for this feature, the allocated amount
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    allocation?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the ID of the credit
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    creditId?: string | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the remaining credit amount
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditRemaining?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the total credit amount
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditTotal?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the amount of credit used
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditUsed?: number | null;
+    /**
+     * If the feature is event-based, the name of the event tracked for usage
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    eventName?: string | null;
+    /**
+     * The ID of the feature
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    featureId: string;
+    /**
+     * The key of the flag associated with the feature
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    featureKey: string;
+    /**
+     * For event-based feature entitlements, the period over which usage is tracked
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    metricPeriod?: FeatureEntitlementMetricPeriodEnum | null;
+    /**
+     * For event-based feature entitlements, when the usage period will reset
+     * @type {Date}
+     * @memberof 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}
+     * @memberof FeatureEntitlement
+     */
+    monthReset?: FeatureEntitlementMonthResetEnum | null;
+    /**
+     * For usage-based pricing, the soft limit for overage charges or the next tier boundary
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    softLimit?: number | null;
+    /**
+     * If the company has a numeric entitlement for this feature, the current usage amount
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    usage?: number | null;
+    /**
+     * The type of the entitlement value
+     * @type {EntitlementValueType}
+     * @memberof FeatureEntitlement
+     */
+    valueType: EntitlementValueType;
+}
 
-export { EventBodyTrack }
+/**
+ * @export
+ */
+declare const FeatureEntitlementMetricPeriodEnum: {
+    readonly AllTime: "all_time";
+    readonly CurrentDay: "current_day";
+    readonly CurrentMonth: "current_month";
+    readonly CurrentWeek: "current_week";
+};
 
-export { EventType }
+declare type FeatureEntitlementMetricPeriodEnum = (typeof FeatureEntitlementMetricPeriodEnum)[keyof typeof FeatureEntitlementMetricPeriodEnum];
 
-export { Keys }
+/**
+ * @export
+ */
+declare const FeatureEntitlementMonthResetEnum: {
+    readonly FirstOfMonth: "first_of_month";
+    readonly BillingCycle: "billing_cycle";
+};
 
-export { RuleType }
+declare type FeatureEntitlementMonthResetEnum = (typeof FeatureEntitlementMonthResetEnum)[keyof typeof FeatureEntitlementMonthResetEnum];
 
-export { Schematic }
+declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
 
-export { SchematicContext }
+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 PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
+
+declare type PlanListenerFn = CheckPlanReturnListenerFn | EmptyListenerFn;
+
+export declare enum RuleType {
+    /** A global rule that, if present, will override all other rules for a flag */
+    GLOBAL_OVERRIDE = "global_override",
+    /** Rule type indicating feature access provisioned to a company via an override */
+    COMPANY_OVERRIDE = "company_override",
+    /** Rule type indicating that feature access has been provisione to a company via an override, but the usage limit has been reached or exceeded */
+    COMPANY_OVERRIDE_USAGE_EXCEEDED = "company_override_usage_exceeded",
+    /** Rule type indicating feature access provisioned to a company via its base plan or add-ons */
+    PLAN_ENTITLEMENT = "plan_entitlement",
+    /** Rule type indicating that feature access has been provisione to a company via base plan or add-ons, but the usage limit has been reached or exceeded */
+    PLAN_ENTITLEMENT_USAGE_EXCEEDED = "plan_entitlement_usage_exceeded",
+    /** General-purpose targeting rule */
+    STANDARD = "standard",
+    /** Default rule type that will be used if no other rules are matched */
+    DEFAULT = "default"
+}
+
+export declare class Schematic {
+    private additionalHeaders;
+    private apiKey;
+    private apiUrl;
+    private conn;
+    private context;
+    private debugEnabled;
+    private offlineEnabled;
+    private eventQueue;
+    private contextDependentEventQueue;
+    private eventUrl;
+    private flagCheckListeners;
+    private flagValueListeners;
+    private isPending;
+    private isPendingListeners;
+    private planListeners;
+    private storage;
+    private useWebSocket;
+    private checks;
+    private featureUsageEventMap;
+    private planChecks;
+    private webSocketUrl;
+    private webSocketConnectionTimeout;
+    private webSocketReconnect;
+    private webSocketMaxReconnectAttempts;
+    private webSocketMaxConnectionAttempts;
+    private webSocketInitialRetryDelay;
+    private webSocketMaxRetryDelay;
+    private wsReconnectAttempts;
+    private wsReconnectTimer;
+    private wsIntentionalDisconnect;
+    private currentWebSocket;
+    private isConnecting;
+    private maxEventQueueSize;
+    private maxEventRetries;
+    private eventRetryInitialDelay;
+    private eventRetryMaxDelay;
+    private retryTimer;
+    private flagValueDefaults;
+    private flagCheckDefaults;
+    private fallbackCheckCache;
+    constructor(apiKey: string, options?: SchematicOptions);
+    /**
+     * Resolve fallback value according to priority order:
+     * 1. Callsite fallback value (if provided)
+     * 2. Boolean value from flagCheckDefaults initialization option
+     * 3. Boolean value from flagValueDefaults initialization option
+     * 4. Default to false
+     */
+    private resolveFallbackValue;
+    /**
+     * Resolve complete CheckFlagReturn object according to priority order:
+     * 1. Use callsite fallback for boolean value, construct CheckFlagReturn
+     * 2. Use flagCheckDefaults if available for this flag
+     * 3. Use flagValueDefaults if available for this flag, construct CheckFlagReturn
+     * 4. Default CheckFlagReturn with value: false
+     */
+    private resolveFallbackCheckFlagReturn;
+    /**
+     * Get value for a single flag.
+     * In WebSocket mode, returns cached values if connection is active, otherwise establishes
+     * new connection and then returns the requested value. Falls back to preconfigured fallback
+     * values if WebSocket connection fails.
+     * In REST mode, makes an API call for each check.
+     */
+    checkFlag(options: CheckOptions): Promise<boolean>;
+    /**
+     * Helper function to log debug messages
+     * Only logs if debug mode is enabled
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Create a persistent message handler for websocket flag updates
+     */
+    private createPersistentMessageHandler;
+    /**
+     * Helper function to check if client is in offline mode
+     */
+    private isOffline;
+    /**
+     * Submit a flag check event
+     * Records data about a flag check for analytics
+     */
+    private submitFlagCheckEvent;
+    /**
+     * Make an API call to fetch all flag values for a given context.
+     * Recommended for use in REST mode only.
+     * In offline mode, returns an empty object.
+     */
+    checkFlags: (context?: SchematicContext) => Promise<Record<string, boolean>>;
+    /**
+     * Send an identify event.
+     * This will set the context for subsequent flag evaluation and events, and will also
+     * send an identify event to the Schematic API which will upsert a user and company.
+     */
+    identify: (body: EventBodyIdentify) => Promise<void>;
+    /**
+     * Set the flag evaluation context.
+     * In WebSocket mode, this will:
+     * 1. Open a websocket connection if not already open
+     * 2. Send the context to the server
+     * 3. Wait for initial flag values to be returned
+     * The promise resolves when initial flag values are received.
+     * In offline mode, this will just set the context locally without connecting.
+     */
+    setContext: (context: SchematicContext) => Promise<void>;
+    /**
+     * Send a track event
+     * Track usage for a company and/or user.
+     * Optimistically updates feature usage flags if tracking a featureUsageEvent.
+     */
+    track: (body: EventBodyTrack) => Promise<void>;
+    /**
+     * Optimistically update feature usage flags associated with a tracked event
+     * This updates flags in memory with updated usage counts and value/featureUsageExceeded flags
+     * before the network request completes
+     */
+    private optimisticallyUpdateFeatureUsage;
+    /**
+     * Event processing
+     */
+    private hasContext;
+    private flushContextDependentEventQueue;
+    private startRetryTimer;
+    private stopRetryTimer;
+    private flushEventQueue;
+    private getAnonymousId;
+    private handleEvent;
+    private sendEvent;
+    private storeEvent;
+    /**
+     * Websocket management
+     */
+    /**
+     * Force an immediate WebSocket reconnection.
+     * This is useful when the application returns from a background state (e.g., mobile app
+     * coming back to foreground) and wants to immediately re-establish the connection
+     * rather than waiting for the exponential backoff timer.
+     *
+     * This method will:
+     * - Cancel any pending reconnection timer
+     * - Reset the reconnection attempt counter
+     * - Close any existing connection
+     * - Immediately attempt to reconnect
+     * - Re-send the current context to get fresh flag values
+     *
+     * Use this when you need guaranteed fresh values (e.g., after an in-app purchase).
+     *
+     * @example
+     * ```typescript
+     * // React Native example: reconnect when app comes to foreground
+     * useEffect(() => {
+     *   const subscription = AppState.addEventListener("change", (state) => {
+     *     if (state === "active") {
+     *       client.forceReconnect();
+     *     }
+     *   });
+     *   return () => subscription.remove();
+     * }, [client]);
+     * ```
+     */
+    forceReconnect: () => Promise<void>;
+    /**
+     * Reconnect the WebSocket connection only if the current connection is unhealthy.
+     * This is useful when the application returns from a background state and wants to
+     * ensure a healthy connection exists, but doesn't need to force a reconnection if
+     * the connection is still active.
+     *
+     * This method will:
+     * - Check if an existing connection is healthy (readyState === OPEN)
+     * - If healthy, return immediately without reconnecting
+     * - If unhealthy, perform the same reconnection logic as forceReconnect()
+     *
+     * Use this when you want efficient reconnection that avoids unnecessary disconnects.
+     *
+     * @example
+     * ```typescript
+     * // React Native example: reconnect only if needed when app comes to foreground
+     * useEffect(() => {
+     *   const subscription = AppState.addEventListener("change", (state) => {
+     *     if (state === "active") {
+     *       client.reconnectIfNeeded();
+     *     }
+     *   });
+     *   return () => subscription.remove();
+     * }, [client]);
+     * ```
+     */
+    reconnectIfNeeded: () => Promise<void>;
+    /**
+     * Internal method to handle reconnection logic for both forceReconnect and reconnectIfNeeded.
+     */
+    private reconnect;
+    /**
+     * If using websocket mode, close the connection when done.
+     * In offline mode, this is a no-op.
+     */
+    cleanup: () => Promise<void>;
+    /**
+     * Calculate the delay for the next reconnection attempt using exponential backoff with jitter.
+     * This helps prevent dogpiling when the server recovers from an outage.
+     */
+    private calculateReconnectDelay;
+    /**
+     * Handle browser going offline
+     */
+    private handleNetworkOffline;
+    /**
+     * Handle browser coming back online
+     */
+    private handleNetworkOnline;
+    /**
+     * Attempt to reconnect the WebSocket connection with exponential backoff.
+     * Called automatically when the connection closes unexpectedly.
+     */
+    private attemptReconnect;
+    private wsConnect;
+    private wsConnectOnce;
+    private wsSendMessage;
+    /**
+     * State management
+     */
+    getIsPending: () => boolean;
+    addIsPendingListener: (listener: PendingListenerFn) => () => void;
+    private setIsPending;
+    getPlan: () => CheckPlanReturn | 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 */
+    addFlagValueListener: (flagKey: string, listener: FlagValueListenerFn) => () => void;
+    /** 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;
+    private notifyFlagCheckListeners;
+    /** Add or update a CheckFlagReturn in the featureUsageEventMap */
+    private updateFeatureUsageEventMap;
+    private notifyFlagValueListeners;
+    private notifyPlanListeners;
+}
+
+/** Context for checking flags and sending events */
+export declare type SchematicContext = {
+    company?: Keys;
+    user?: Keys;
+};
 
 declare interface SchematicContextProps {
     client: SchematicJS.Schematic;
@@ -51,7 +796,87 @@ export declare interface SchematicHookOpts {
     client?: SchematicJS.Schematic;
 }
 
-export { SchematicOptions }
+declare namespace SchematicJS {
+    export {
+        CheckFlagResponseFromJSON,
+        CheckFlagsResponseFromJSON,
+        DatastreamCompanyPlanFromJSON,
+        EventBodyFlagCheckToJSON,
+        BooleanListenerFn,
+        CheckFlagResponseData,
+        CheckFlagReturn,
+        CheckFlagReturnFromJSON,
+        CheckFlagReturnListenerFn,
+        CheckOptions,
+        CheckPlanReturn,
+        CheckPlanReturnFromJSON,
+        CheckPlanReturnListenerFn,
+        EmptyListenerFn,
+        Event_2 as Event,
+        EventBody,
+        EventBodyFlagCheck,
+        EventBodyIdentify,
+        EventBodyTrack,
+        EventType,
+        FlagCheckListenerFn,
+        FlagValueListenerFn,
+        Keys,
+        PendingListenerFn,
+        PlanListenerFn,
+        RuleType,
+        Schematic,
+        SchematicContext,
+        SchematicOptions,
+        StoragePersister,
+        Traits,
+        TrialStatus,
+        UsagePeriod
+    }
+}
+
+export declare type SchematicOptions = {
+    /** Optionally provide any additional headers to include in the request */
+    additionalHeaders?: Record<string, string>;
+    /** Optionally provide a custom API URL */
+    apiUrl?: string;
+    /** Enable debug mode to log flag check results and events to the console.
+     * Can also be enabled at runtime via URL query parameter "schematic_debug=true" */
+    debug?: boolean;
+    /** Optionally provide a custom event URL */
+    eventUrl?: string;
+    /** Enable offline mode to prevent all network requests.
+     * When enabled, events are only logged not sent, and flag checks return fallback values.
+     * Can also be enabled at runtime via URL query parameter "schematic_offline=true" */
+    offline?: boolean;
+    /** Optionally provide a custom storage persister for client-side storage */
+    storage?: StoragePersister;
+    /** 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 */
+    webSocketUrl?: string;
+    /** WebSocket connection timeout in milliseconds (default: 10000) */
+    webSocketConnectionTimeout?: number;
+    /** Enable automatic reconnection on WebSocket disconnect (default: true) */
+    webSocketReconnect?: boolean;
+    /** Maximum number of reconnection attempts (default: 7, set to Infinity for unlimited) */
+    webSocketMaxReconnectAttempts?: number;
+    /** Initial retry delay in milliseconds for exponential backoff (default: 1000) */
+    webSocketInitialRetryDelay?: number;
+    /** Maximum retry delay in milliseconds for exponential backoff (default: 30000) */
+    webSocketMaxRetryDelay?: number;
+    /** Maximum number of events to queue for retry when network is down (default: 100) */
+    maxEventQueueSize?: number;
+    /** Maximum number of retry attempts for failed events (default: 5) */
+    maxEventRetries?: number;
+    /** Initial retry delay in milliseconds for failed events (default: 1000) */
+    eventRetryInitialDelay?: number;
+    /** Maximum retry delay in milliseconds for failed events (default: 30000) */
+    eventRetryMaxDelay?: number;
+    /** Default boolean values for flags when Schematic API cannot be reached and no callsite fallback is provided */
+    flagValueDefaults?: Record<string, boolean>;
+    /** Default CheckFlagReturn objects for flags when Schematic API cannot be reached and no callsite fallback is provided */
+    flagCheckDefaults?: Record<string, CheckFlagReturn>;
+};
 
 export declare const SchematicProvider: React_2.FC<SchematicProviderProps>;
 
@@ -67,13 +892,36 @@ declare type SchematicProviderPropsWithPublishableKey = BaseSchematicProviderPro
     publishableKey: string;
 };
 
-export { StoragePersister }
+/** Optional type for implementing custom client-side storage */
+export declare type StoragePersister = {
+    setItem(key: string, value: any): void;
+    getItem(key: string): any;
+    removeItem(key: string): void;
+};
 
-export { Traits }
+/**
+ * A flexible key/value type that can store any type of value on a company or user.
+ */
+export declare type Traits = Record<string, any>;
+
+/**
+ *
+ * @export
+ */
+export declare const TrialStatus: {
+    readonly Active: "active";
+    readonly Converted: "converted";
+    readonly Expired: "expired";
+};
 
-export { TrialStatus }
+export declare type TrialStatus = (typeof TrialStatus)[keyof typeof TrialStatus];
 
-export { UsagePeriod }
+export declare enum UsagePeriod {
+    ALL_TIME = "all_time",
+    CURRENT_DAY = "current_day",
+    CURRENT_MONTH = "current_month",
+    CURRENT_WEEK = "current_week"
+}
 
 export declare const useSchematic: () => SchematicContextProps;
 

package/dist/schematic-react.esm.js

@@ -762,6 +762,7 @@ var UsagePeriod = /* @__PURE__ */ ((UsagePeriod2) => {
 var CheckFlagReturnFromJSON = (json) => {
   const {
     companyId,
+    entitlement,
     error,
     featureAllocation,
     featureUsage,
@@ -779,20 +780,27 @@ var CheckFlagReturnFromJSON = (json) => {
   const featureUsageExceeded = !value && // if flag is not false, then we haven't exceeded usage
   (ruleType == "company_override_usage_exceeded" || // if the rule type is one of these, then we have exceeded usage
   ruleType == "plan_entitlement_usage_exceeded");
+  const resolvedAllocation = entitlement?.allocation ?? featureAllocation;
+  const resolvedUsage = entitlement?.usage ?? featureUsage;
+  const resolvedEvent = entitlement?.eventName ?? featureUsageEvent;
+  const resolvedPeriod = entitlement?.metricPeriod ?? featureUsagePeriod;
+  const resolvedResetAt = entitlement?.metricResetAt ?? featureUsageResetAt;
   return {
     featureUsageExceeded,
     companyId: companyId == null ? void 0 : companyId,
+    creditRemaining: entitlement?.creditRemaining == null ? void 0 : entitlement.creditRemaining,
     error: error == null ? void 0 : error,
-    featureAllocation: featureAllocation == null ? void 0 : featureAllocation,
-    featureUsage: featureUsage == null ? void 0 : featureUsage,
-    featureUsageEvent: featureUsageEvent === null ? void 0 : featureUsageEvent,
-    featureUsagePeriod: featureUsagePeriod == null ? void 0 : featureUsagePeriod,
-    featureUsageResetAt: featureUsageResetAt == null ? void 0 : featureUsageResetAt,
+    featureAllocation: resolvedAllocation == null ? void 0 : resolvedAllocation,
+    featureUsage: resolvedUsage == null ? void 0 : resolvedUsage,
+    featureUsageEvent: resolvedEvent == null ? void 0 : resolvedEvent,
+    featureUsagePeriod: resolvedPeriod == null ? void 0 : resolvedPeriod,
+    featureUsageResetAt: resolvedResetAt == null ? void 0 : resolvedResetAt,
     flag,
     flagId: flagId == null ? void 0 : flagId,
     reason,
     ruleId: ruleId == null ? void 0 : ruleId,
     ruleType: ruleType == null ? void 0 : ruleType,
+    softLimit: entitlement?.softLimit == null ? void 0 : entitlement.softLimit,
     userId: userId == null ? void 0 : userId,
     value
   };
@@ -820,7 +828,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.3.1";
+var version = "1.4.0";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -2257,7 +2265,7 @@ var notifyPlanListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.3.1";
+var version2 = "1.4.1";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -30,12 +30,10 @@
     "tsc": "npx tsc",
     "prepare": "husky"
   },
-  "dependencies": {
-    "@schematichq/schematic-js": "^1.3.1"
-  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@microsoft/api-extractor": "^7.58.1",
+    "@microsoft/api-extractor": "^7.58.2",
+    "@schematichq/schematic-js": "^1.4.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
@@ -45,16 +43,16 @@
     "eslint": "^10.2.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "globals": "^17.4.0",
-    "happy-dom": "^20.8.9",
+    "eslint-plugin-react-hooks": "^7.1.0",
+    "globals": "^17.5.0",
+    "happy-dom": "^20.9.0",
     "husky": "^9.1.7",
-    "jsdom": "^29.0.1",
-    "prettier": "^3.8.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.0",
+    "jsdom": "^29.0.2",
+    "prettier": "^3.8.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.58.2",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {