@schematichq/schematic-js 1.2.1 → 1.2.3

package/dist/schematic.d.ts

@@ -61,6 +61,12 @@ export declare interface CheckFlagResponseData {
      * @memberof CheckFlagResponseData
      */
     featureUsage?: number | null;
+    /**
+     * If an event-based numeric feature entitlement rule was matched, the event used to track its usage
+     * @type {string}
+     * @memberof CheckFlagResponseData
+     */
+    featureUsageEvent?: string | null;
     /**
      * For event-based feature entitlement rules, the period over which usage is tracked (current_month, current_day, current_week, all_time)
      * @type {string}
@@ -130,6 +136,8 @@ export declare type CheckFlagReturn = {
     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 */
@@ -208,7 +216,92 @@ declare type Event_2 = {
 };
 export { Event_2 as Event }
 
-export declare type EventBody = EventBodyIdentify | EventBodyTrack;
+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
+ */
+export 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;
+}
+
+export declare function EventBodyFlagCheckToJSON(json: any): EventBodyFlagCheck;
 
 export declare type EventBodyIdentify = {
     company?: {
@@ -227,7 +320,7 @@ export declare type EventBodyTrack = SchematicContext & {
     traits?: Traits;
 };
 
-export declare type EventType = "identify" | "track";
+export declare type EventType = "identify" | "track" | "flag_check";
 
 export declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
 
@@ -261,6 +354,8 @@ export declare class Schematic {
     private apiUrl;
     private conn;
     private context;
+    private debugEnabled;
+    private offlineEnabled;
     private eventQueue;
     private eventUrl;
     private flagCheckListeners;
@@ -270,6 +365,7 @@ export declare class Schematic {
     private storage;
     private useWebSocket;
     private checks;
+    private featureUsageEventMap;
     private webSocketUrl;
     constructor(apiKey: string, options?: SchematicOptions);
     /**
@@ -280,6 +376,20 @@ export declare class Schematic {
      * 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
+     */
+    private debug;
+    /**
+     * 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;
     /**
      * Helper method for falling back to REST API when WebSocket connection fails
      */
@@ -287,6 +397,7 @@ export declare class Schematic {
     /**
      * 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>>;
     /**
@@ -302,13 +413,21 @@ export declare class Schematic {
      * 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
      */
@@ -322,6 +441,7 @@ export declare class Schematic {
      */
     /**
      * If using websocket mode, close the connection when done.
+     * In offline mode, this is a no-op.
      */
     cleanup: () => Promise<void>;
     private wsConnect;
@@ -332,13 +452,15 @@ export declare class Schematic {
     getIsPending: () => boolean;
     addIsPendingListener: (listener: PendingListenerFn) => () => void;
     private setIsPending;
-    getFlagCheck: (flagKey: string) => CheckFlagReturn;
-    getFlagValue: (flagKey: string) => boolean;
+    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;
     private notifyFlagCheckListeners;
+    /** Add or update a CheckFlagReturn in the featureUsageEventMap */
+    private updateFeatureUsageEventMap;
     private notifyFlagValueListeners;
 }
 
@@ -353,8 +475,15 @@ export declare type SchematicOptions = {
     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 */