# Reference ## Classes ### BoundReflagClient A client bound with a specific user, company, and other context. #### Constructors **new BoundReflagClient()** ```ts new BoundReflagClient(client: ReflagClient, options: ContextWithTracking): BoundReflagClient ``` **`Internal`** (Internal) Creates a new BoundReflagClient. Use `bindClient` to create a new client bound with a specific context. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | --------------------------- | | `client` | [`ReflagClient`](#reflagclient) | The `ReflagClient` to use. | | `options` | [`ContextWithTracking`](#contextwithtracking) | The options for the client. | **Returns** [`BoundReflagClient`](#boundreflagclient) #### Accessors **company** **Get Signature** ```ts get company(): | undefined | { [k: string]: any; avatar: string; id: undefined | string | number; name: string; } ``` Gets the company associated with the client. **Returns** \| `undefined` | { `[k: string]`: `any`; `avatar`: `string`; `id`: `undefined` | `string` | `number`; `name`: `string`; } The company or `undefined` if it is not set. **otherContext** **Get Signature** ```ts get otherContext(): | undefined | Record ``` Gets the "other" context associated with the client. **Returns** \| `undefined` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `any`> The "other" context or `undefined` if it is not set. **user** **Get Signature** ```ts get user(): | undefined | { [k: string]: any; avatar: string; email: string; id: undefined | string | number; name: string; } ``` Gets the user associated with the client. **Returns** \| `undefined` | { `[k: string]`: `any`; `avatar`: `string`; `email`: `string`; `id`: `undefined` | `string` | `number`; `name`: `string`; } The user or `undefined` if it is not set. #### Methods **bindClient()** ```ts bindClient(context: ContextWithTracking): BoundReflagClient ``` Create a new client bound with the additional context. Note: This performs a shallow merge for user/company/other individually. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------------- | | `context` | [`ContextWithTracking`](#contextwithtracking) | The context to bind the client to. | **Returns** [`BoundReflagClient`](#boundreflagclient) new client bound with the additional context **flush()** ```ts flush(): Promise ``` Flushes the batch buffer. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **getFlag()** ```ts getFlag(key: TKey): Flag ``` Get a specific flag for the user/company/other context bound to this client. Using the `isEnabled` property sends a `check` event to Reflag. **Type Parameters** | Type Parameter | | ------------------------- | | `TKey` *extends* `string` | **Parameters** | Parameter | Type | Description | | --------- | ------ | --------------------------- | | `key` | `TKey` | The key of the flag to get. | **Returns** [`Flag`](#flagtconfig) Flags for the given user/company and whether each one is enabled or not **getFlagRemote()** ```ts getFlagRemote(key: string): Promise ``` Get remotely evaluated flag for the user/company/other context bound to this client. **Parameters** | Parameter | Type | Description | | --------- | -------- | --------------------------- | | `key` | `string` | The key of the flag to get. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Flag`](#flagtconfig)> Flag for the given user/company and key and whether it's enabled or not **getFlags()** ```ts getFlags(): Record ``` Get flags for the user/company/other context bound to this client. Meant for use in serialization of flags for transferring to the client-side/browser. **Returns** [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)> Flags for the given user/company and whether each one is enabled or not **getFlagsForBootstrap()** ```ts getFlagsForBootstrap(): BootstrappedFlags ``` Get raw flags for the user/company/other context bound to this client without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications. **Returns** [`BootstrappedFlags`](#bootstrappedflags) Raw flags for the given user/company and whether each one is enabled or not **getFlagsRemote()** ```ts getFlagsRemote(): Promise> ``` Get remotely evaluated flag for the user/company/other context bound to this client. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)>> Flags for the given user/company and whether each one is enabled or not **refreshFlags()** ```ts refreshFlags(waitForVersion?: number): Promise ``` Refreshes the flag definitions from the server. Fetch starts are throttled to at most once per second. Outside `in-request` mode, a call to `refreshFlags(waitForVersion)` still waits until the cache has applied that version or newer. In `in-request` mode, a throttled call only records pending refresh work. The fetch then runs on the next request/access or `refreshFlags()` call after the throttle window expires. **Parameters** | Parameter | Type | Description | | ----------------- | -------- | ----------------------------------------------------------------------------- | | `waitForVersion`? | `number` | Optional flag state version to wait for before returning updated definitions. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **track()** ```ts track(event: string, options?: TrackOptions & { companyId: string; }): Promise ``` Track an event in Reflag. **Parameters** | Parameter | Type | Description | | ---------- | ------------------------------------------------------------ | -------------------------- | | `event` | `string` | The event to track. | | `options`? | [`TrackOptions`](#trackoptions) & { `companyId`: `string`; } | The options for the event. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the event is invalid or the options are invalid. *** ### EdgeClient The EdgeClient is ReflagClient pre-configured to be used in edge runtimes, like Cloudflare Workers. It always uses `flagsSyncMode: "in-request"`. Refresh fetch starts are throttled to at most once per second. A `refreshFlags()` call made during that throttle window only records pending refresh work, so the call may resolve before the fetch runs. That pending refresh is executed on the next request/access or `refreshFlags()` call after the window expires. #### Example ```ts // set the REFLAG_SECRET_KEY environment variable or pass the secret key in the constructor const client = new EdgeClient(); // evaluate a flag const context = { user: { id: "user-id" }, company: { id: "company-id" }, } const { isEnabled } = client.getFlag(context, "flag-key"); ``` #### Extends * [`ReflagClient`](#reflagclient) #### Constructors **new EdgeClient()** ```ts new EdgeClient(options: EdgeClientOptions): EdgeClient ``` **Parameters** | Parameter | Type | | --------- | ----------------------------------------- | | `options` | [`EdgeClientOptions`](#edgeclientoptions) | **Returns** [`EdgeClient`](#edgeclient) **Overrides** [`ReflagClient`](#reflagclient).[`constructor`](#constructors-2) #### Properties | Property | Modifier | Type | Description | | ------------ | ---------- | ----------------------------- | ------------------------------------------- | | `httpClient` | `public` | [`HttpClient`](#httpclient-2) | ‐ | | `logger` | `readonly` | [`Logger`](#logger-2) | Gets the logger associated with the client. | #### Accessors **flagOverrides** **Set Signature** ```ts set flagOverrides(overrides: | Partial> | FlagOverridesFn): void ``` **Deprecated** Use `setFlagOverrides()` for replacing the base override set. **Parameters** | Parameter | Type | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | **Returns** `void` **Inherited from** [`ReflagClient`](#reflagclient).[`flagOverrides`](#flagoverrides-1) #### Methods **bindClient()** ```ts bindClient(context: ContextWithTracking): BoundReflagClient ``` Returns a new BoundReflagClient with the user/company/otherContext set to be used in subsequent calls. For example, for evaluating flag targeting or tracking events. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------------- | | `context` | [`ContextWithTracking`](#contextwithtracking) | The context to bind the client to. | **Returns** [`BoundReflagClient`](#boundreflagclient) A new client bound with the arguments given. **Throws** An error if the user/company is given but their ID is not a string. **Remarks** The `updateUser` / `updateCompany` methods will automatically be called when the user/company is set respectively. **Inherited from** [`ReflagClient`](#reflagclient).[`bindClient`](#bindclient-2) **clearFlagOverrides()** ```ts clearFlagOverrides(): void ``` Clears the base flag overrides. **Returns** `void` **Remarks** This does not affect temporary layers added with `pushFlagOverrides()`. **Example** ```ts client.clearFlagOverrides(); ``` **Inherited from** [`ReflagClient`](#reflagclient).[`clearFlagOverrides`](#clearflagoverrides-1) **destroy()** ```ts destroy(): void ``` Destroys the client and cleans up all resources including timers and background processes. **Returns** `void` **Remarks** After calling this method, the client should not be used anymore. This is particularly useful in development environments with hot reloading to prevent multiple background processes from running simultaneously. **Inherited from** [`ReflagClient`](#reflagclient).[`destroy`](#destroy-1) **flush()** ```ts flush(): Promise ``` Flushes and completes any in-flight fetches in the flag cache. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** It is recommended to call this method when the application is shutting down to ensure all events are sent before the process exits. This method is automatically called when the process exits if `batchOptions.flushOnExit` is `true` in the options (default). **Inherited from** [`ReflagClient`](#reflagclient).[`flush`](#flush-2) **getFlag()** ```ts getFlag(__namedParameters: ContextWithTracking, key: TKey): Flag ``` Gets the evaluated flag for the current context which includes the user, company, and custom context. Using the `isEnabled` property sends a `check` event to Reflag. **Type Parameters** | Type Parameter | | ------------------------- | | `TKey` *extends* `string` | **Parameters** | Parameter | Type | Description | | ------------------- | --------------------------------------------- | --------------------------- | | `__namedParameters` | [`ContextWithTracking`](#contextwithtracking) | ‐ | | `key` | `TKey` | The key of the flag to get. | **Returns** [`Flag`](#flagtconfig) The evaluated flag. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. **Inherited from** [`ReflagClient`](#reflagclient).[`getFlag`](#getflag-2) **getFlagDefinitions()** ```ts getFlagDefinitions(): FlagDefinition[] ``` Gets the flag definitions, including all config values. To evaluate which flags are enabled for a given user/company, use `getFlags`. **Returns** [`FlagDefinition`](#flagdefinition)\[] The flags definitions. **Inherited from** [`ReflagClient`](#reflagclient).[`getFlagDefinitions`](#getflagdefinitions-1) **getFlagRemote()** ```ts getFlagRemote( key: TKey, userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise ``` Gets evaluated flag with the usage of remote context. This method triggers a network request every time it's called. **Type Parameters** | Type Parameter | | ------------------------- | | `TKey` *extends* `string` | **Parameters** | Parameter | Type | Description | | -------------------- | ----------------------- | ------------------------------------------------- | | `key` | `TKey` | The key of the flag to get. | | `userId`? | [`IdType`](#idtype) | The userId of the user to get the flag for. | | `companyId`? | [`IdType`](#idtype) | The companyId of the company to get the flag for. | | `additionalContext`? | [`Context`](#context-1) | The additional context to get the flag for. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Flag`](#flagtconfig)> evaluated flag **Inherited from** [`ReflagClient`](#reflagclient).[`getFlagRemote`](#getflagremote-2) **getFlags()** ```ts getFlags(options: ContextWithTracking): Record ``` Gets the evaluated flags for the current context which includes the user, company, and custom context. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------- | | `options` | [`ContextWithTracking`](#contextwithtracking) | The options for the context. | **Returns** [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)> The evaluated flags. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. **Inherited from** [`ReflagClient`](#reflagclient).[`getFlags`](#getflags-2) **getFlagsForBootstrap()** ```ts getFlagsForBootstrap(options: ContextWithTracking): BootstrappedFlags ``` Gets the evaluated flags for the current context without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------- | | `options` | [`ContextWithTracking`](#contextwithtracking) | The options for the context. | **Returns** [`BootstrappedFlags`](#bootstrappedflags) The evaluated raw flags and the context. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. This method returns RawFlag objects without wrapping them in getters, making them suitable for serialization. **Inherited from** [`ReflagClient`](#reflagclient).[`getFlagsForBootstrap`](#getflagsforbootstrap-2) **getFlagsRemote()** ```ts getFlagsRemote( userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise> ``` Gets evaluated flags with the usage of remote context. This method triggers a network request every time it's called. **Parameters** | Parameter | Type | Description | | -------------------- | ----------------------- | -------------------------------------------------- | | `userId`? | [`IdType`](#idtype) | The userId of the user to get the flags for. | | `companyId`? | [`IdType`](#idtype) | The companyId of the company to get the flags for. | | `additionalContext`? | [`Context`](#context-1) | The additional context to get the flags for. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)>> evaluated flags **Inherited from** [`ReflagClient`](#reflagclient).[`getFlagsRemote`](#getflagsremote-2) **initialize()** ```ts initialize(): Promise ``` Initializes the client by caching the flags definitions. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** Call this method before calling `getFlags` to ensure the flag definitions are cached. The client will ignore subsequent calls to this method. **Inherited from** [`ReflagClient`](#reflagclient).[`initialize`](#initialize-1) **pushFlagOverrides()** ```ts pushFlagOverrides(overrides: | Partial> | FlagOverridesFn): () => void ``` Temporarily layers flag overrides on top of the current overrides. **Parameters** | Parameter | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | The flag overrides to apply for the scoped period. | **Returns** `Function` A remove function that removes only this override layer. **Returns** `void` **Remarks** This is intended for tests or other short-lived local overrides. The remove function is idempotent and can safely be called multiple times. **Example** ```ts let remove: (() => void) | undefined; beforeEach(() => { remove = client.pushFlagOverrides({ "flag-1": true }); }); afterEach(() => { remove?.(); remove = undefined; }); ``` **Inherited from** [`ReflagClient`](#reflagclient).[`pushFlagOverrides`](#pushflagoverrides-1) **refreshFlags()** ```ts refreshFlags(waitForVersion?: number): Promise ``` Refreshes the flag definitions from the server. **Parameters** | Parameter | Type | Description | | ----------------- | -------- | ----------------------------------------------------------------------------- | | `waitForVersion`? | `number` | Optional flag state version to wait for before returning updated definitions. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** This triggers an on-demand refresh of the cached flag definitions. Useful when you know flags have changed and don't want to wait for the next automatic refresh cycle. Note: updated flag rules take a few seconds to propagate to all servers. Fetch starts are throttled to at most once per second. Outside `in-request` mode, throttling only delays when the next fetch begins: `refreshFlags(99)` still waits until the cache has applied flag definitions from version `99` or newer before the promise resolves. Concurrent callers are deduplicated and may share the same in-flight or scheduled follow-up refresh. In `in-request` mode, delayed follow-up refreshes are not scheduled. On edge runtimes like Cloudflare Workers, a call during the throttle window only records pending refresh work, and the promise may resolve before that fetch runs. The pending refresh is executed on the next request/access or `refreshFlags()` call after the throttle window expires. **Inherited from** [`ReflagClient`](#reflagclient).[`refreshFlags`](#refreshflags-2) **setFlagOverrides()** ```ts setFlagOverrides(overrides: | Partial> | FlagOverridesFn): void ``` Replaces the base flag overrides used by the client. **Parameters** | Parameter | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | The flag overrides. | **Returns** `void` **Remarks** Base overrides are always applied before any temporary layers added through `pushFlagOverrides()`. **Example** ```ts client.setFlagOverrides({ "flag-1": true, "flag-2": false, }); ``` **Inherited from** [`ReflagClient`](#reflagclient).[`setFlagOverrides`](#setflagoverrides-1) **track()** ```ts track( userId: IdType, event: string, options?: TrackOptions & { companyId: IdType; }): Promise ``` Tracks an event in Reflag. **Parameters** | Parameter | Type | | ---------- | ----------------------------------------------------------------------- | | `userId` | [`IdType`](#idtype) | | `event` | `string` | | `options`? | [`TrackOptions`](#trackoptions) & { `companyId`: [`IdType`](#idtype); } | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the user is not set or the event is invalid or the options are invalid. **Remarks** If the company is set, the event will be associated with the company. **Inherited from** [`ReflagClient`](#reflagclient).[`track`](#track-2) **updateCompany()** ```ts updateCompany(companyId: IdType, options?: TrackOptions & { userId: IdType; }): Promise ``` Updates the associated company in Reflag. **Parameters** | Parameter | Type | Description | | ----------- | -------------------------------------------------------------------- | --------------------------------------- | | `companyId` | [`IdType`](#idtype) | The companyId of the company to update. | | `options`? | [`TrackOptions`](#trackoptions) & { `userId`: [`IdType`](#idtype); } | The options for the company. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the company is not set or the options are invalid. **Remarks** The company must be set using `withCompany` before calling this method. If the user is set, the company will be associated with the user. **Inherited from** [`ReflagClient`](#reflagclient).[`updateCompany`](#updatecompany-1) **updateUser()** ```ts updateUser(userId: IdType, options?: TrackOptions): Promise ``` Updates the associated user in Reflag. **Parameters** | Parameter | Type | Description | | ---------- | ------------------------------- | --------------------------------- | | `userId` | [`IdType`](#idtype) | The userId of the user to update. | | `options`? | [`TrackOptions`](#trackoptions) | The options for the user. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the company is not set or the options are invalid. **Remarks** The company must be set using `withCompany` before calling this method. If the user is set, the company will be associated with the user. **Inherited from** [`ReflagClient`](#reflagclient).[`updateUser`](#updateuser-1) *** ### ReflagClient The SDK client. #### Remarks This is the main class for interacting with Reflag. It is used to evaluate flags, update user and company contexts, and track events. #### Example ```ts // set the REFLAG_SECRET_KEY environment variable or pass the secret key to the constructor const client = new ReflagClient(); // evaluate a flag const isFlagEnabled = client.getFlag("flag-key", { user: { id: "user-id" }, company: { id: "company-id" }, }); ``` #### Extended by * [`EdgeClient`](#edgeclient) #### Constructors **new ReflagClient()** ```ts new ReflagClient(options: ClientOptions): ReflagClient ``` Creates a new SDK client. See README for configuration options. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------- | ---------------------------------------------------------- | | `options` | [`ClientOptions`](#clientoptions) | The options for the client or an existing client to clone. | **Returns** [`ReflagClient`](#reflagclient) **Throws** An error if the options are invalid. #### Properties | Property | Modifier | Type | Description | | ------------ | ---------- | ----------------------------- | ------------------------------------------- | | `httpClient` | `public` | [`HttpClient`](#httpclient-2) | ‐ | | `logger` | `readonly` | [`Logger`](#logger-2) | Gets the logger associated with the client. | #### Accessors **flagOverrides** **Set Signature** ```ts set flagOverrides(overrides: | Partial> | FlagOverridesFn): void ``` **Deprecated** Use `setFlagOverrides()` for replacing the base override set. **Parameters** | Parameter | Type | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | **Returns** `void` #### Methods **bindClient()** ```ts bindClient(context: ContextWithTracking): BoundReflagClient ``` Returns a new BoundReflagClient with the user/company/otherContext set to be used in subsequent calls. For example, for evaluating flag targeting or tracking events. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------------- | | `context` | [`ContextWithTracking`](#contextwithtracking) | The context to bind the client to. | **Returns** [`BoundReflagClient`](#boundreflagclient) A new client bound with the arguments given. **Throws** An error if the user/company is given but their ID is not a string. **Remarks** The `updateUser` / `updateCompany` methods will automatically be called when the user/company is set respectively. **clearFlagOverrides()** ```ts clearFlagOverrides(): void ``` Clears the base flag overrides. **Returns** `void` **Remarks** This does not affect temporary layers added with `pushFlagOverrides()`. **Example** ```ts client.clearFlagOverrides(); ``` **destroy()** ```ts destroy(): void ``` Destroys the client and cleans up all resources including timers and background processes. **Returns** `void` **Remarks** After calling this method, the client should not be used anymore. This is particularly useful in development environments with hot reloading to prevent multiple background processes from running simultaneously. **flush()** ```ts flush(): Promise ``` Flushes and completes any in-flight fetches in the flag cache. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** It is recommended to call this method when the application is shutting down to ensure all events are sent before the process exits. This method is automatically called when the process exits if `batchOptions.flushOnExit` is `true` in the options (default). **getFlag()** ```ts getFlag(__namedParameters: ContextWithTracking, key: TKey): Flag ``` Gets the evaluated flag for the current context which includes the user, company, and custom context. Using the `isEnabled` property sends a `check` event to Reflag. **Type Parameters** | Type Parameter | | ------------------------- | | `TKey` *extends* `string` | **Parameters** | Parameter | Type | Description | | ------------------- | --------------------------------------------- | --------------------------- | | `__namedParameters` | [`ContextWithTracking`](#contextwithtracking) | ‐ | | `key` | `TKey` | The key of the flag to get. | **Returns** [`Flag`](#flagtconfig) The evaluated flag. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. **getFlagDefinitions()** ```ts getFlagDefinitions(): FlagDefinition[] ``` Gets the flag definitions, including all config values. To evaluate which flags are enabled for a given user/company, use `getFlags`. **Returns** [`FlagDefinition`](#flagdefinition)\[] The flags definitions. **getFlagRemote()** ```ts getFlagRemote( key: TKey, userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise ``` Gets evaluated flag with the usage of remote context. This method triggers a network request every time it's called. **Type Parameters** | Type Parameter | | ------------------------- | | `TKey` *extends* `string` | **Parameters** | Parameter | Type | Description | | -------------------- | ----------------------- | ------------------------------------------------- | | `key` | `TKey` | The key of the flag to get. | | `userId`? | [`IdType`](#idtype) | The userId of the user to get the flag for. | | `companyId`? | [`IdType`](#idtype) | The companyId of the company to get the flag for. | | `additionalContext`? | [`Context`](#context-1) | The additional context to get the flag for. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Flag`](#flagtconfig)> evaluated flag **getFlags()** ```ts getFlags(options: ContextWithTracking): Record ``` Gets the evaluated flags for the current context which includes the user, company, and custom context. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------- | | `options` | [`ContextWithTracking`](#contextwithtracking) | The options for the context. | **Returns** [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)> The evaluated flags. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. **getFlagsForBootstrap()** ```ts getFlagsForBootstrap(options: ContextWithTracking): BootstrappedFlags ``` Gets the evaluated flags for the current context without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications. **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------- | ---------------------------- | | `options` | [`ContextWithTracking`](#contextwithtracking) | The options for the context. | **Returns** [`BootstrappedFlags`](#bootstrappedflags) The evaluated raw flags and the context. **Remarks** Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. This method returns RawFlag objects without wrapping them in getters, making them suitable for serialization. **getFlagsRemote()** ```ts getFlagsRemote( userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise> ``` Gets evaluated flags with the usage of remote context. This method triggers a network request every time it's called. **Parameters** | Parameter | Type | Description | | -------------------- | ----------------------- | -------------------------------------------------- | | `userId`? | [`IdType`](#idtype) | The userId of the user to get the flags for. | | `companyId`? | [`IdType`](#idtype) | The companyId of the company to get the flags for. | | `additionalContext`? | [`Context`](#context-1) | The additional context to get the flags for. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Flag`](#flagtconfig)>> evaluated flags **initialize()** ```ts initialize(): Promise ``` Initializes the client by caching the flags definitions. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** Call this method before calling `getFlags` to ensure the flag definitions are cached. The client will ignore subsequent calls to this method. **pushFlagOverrides()** ```ts pushFlagOverrides(overrides: | Partial> | FlagOverridesFn): () => void ``` Temporarily layers flag overrides on top of the current overrides. **Parameters** | Parameter | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | The flag overrides to apply for the scoped period. | **Returns** `Function` A remove function that removes only this override layer. **Returns** `void` **Remarks** This is intended for tests or other short-lived local overrides. The remove function is idempotent and can safely be called multiple times. **Example** ```ts let remove: (() => void) | undefined; beforeEach(() => { remove = client.pushFlagOverrides({ "flag-1": true }); }); afterEach(() => { remove?.(); remove = undefined; }); ``` **refreshFlags()** ```ts refreshFlags(waitForVersion?: number): Promise ``` Refreshes the flag definitions from the server. **Parameters** | Parameter | Type | Description | | ----------------- | -------- | ----------------------------------------------------------------------------- | | `waitForVersion`? | `number` | Optional flag state version to wait for before returning updated definitions. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Remarks** This triggers an on-demand refresh of the cached flag definitions. Useful when you know flags have changed and don't want to wait for the next automatic refresh cycle. Note: updated flag rules take a few seconds to propagate to all servers. Fetch starts are throttled to at most once per second. Outside `in-request` mode, throttling only delays when the next fetch begins: `refreshFlags(99)` still waits until the cache has applied flag definitions from version `99` or newer before the promise resolves. Concurrent callers are deduplicated and may share the same in-flight or scheduled follow-up refresh. In `in-request` mode, delayed follow-up refreshes are not scheduled. On edge runtimes like Cloudflare Workers, a call during the throttle window only records pending refresh work, and the promise may resolve before that fetch runs. The pending refresh is executed on the next request/access or `refreshFlags()` call after the throttle window expires. **setFlagOverrides()** ```ts setFlagOverrides(overrides: | Partial> | FlagOverridesFn): void ``` Replaces the base flag overrides used by the client. **Parameters** | Parameter | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `overrides` | \| [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`FlagOverride`](#flagoverride)>> \| [`FlagOverridesFn`](#flagoverridesfn) | The flag overrides. | **Returns** `void` **Remarks** Base overrides are always applied before any temporary layers added through `pushFlagOverrides()`. **Example** ```ts client.setFlagOverrides({ "flag-1": true, "flag-2": false, }); ``` **track()** ```ts track( userId: IdType, event: string, options?: TrackOptions & { companyId: IdType; }): Promise ``` Tracks an event in Reflag. **Parameters** | Parameter | Type | | ---------- | ----------------------------------------------------------------------- | | `userId` | [`IdType`](#idtype) | | `event` | `string` | | `options`? | [`TrackOptions`](#trackoptions) & { `companyId`: [`IdType`](#idtype); } | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the user is not set or the event is invalid or the options are invalid. **Remarks** If the company is set, the event will be associated with the company. **updateCompany()** ```ts updateCompany(companyId: IdType, options?: TrackOptions & { userId: IdType; }): Promise ``` Updates the associated company in Reflag. **Parameters** | Parameter | Type | Description | | ----------- | -------------------------------------------------------------------- | --------------------------------------- | | `companyId` | [`IdType`](#idtype) | The companyId of the company to update. | | `options`? | [`TrackOptions`](#trackoptions) & { `userId`: [`IdType`](#idtype); } | The options for the company. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the company is not set or the options are invalid. **Remarks** The company must be set using `withCompany` before calling this method. If the user is set, the company will be associated with the user. **updateUser()** ```ts updateUser(userId: IdType, options?: TrackOptions): Promise ``` Updates the associated user in Reflag. **Parameters** | Parameter | Type | Description | | ---------- | ------------------------------- | --------------------------------- | | `userId` | [`IdType`](#idtype) | The userId of the user to update. | | `options`? | [`TrackOptions`](#trackoptions) | The options for the user. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> **Throws** An error if the company is not set or the options are invalid. **Remarks** The company must be set using `withCompany` before calling this method. If the user is set, the company will be associated with the user. ## Interfaces ### ContextWithTracking A context with tracking option. #### Extends * [`Context`](#context-1) #### Properties | Property | Type | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `company?` | { `[k: string]`: `any`; `avatar`: `string`; `id`: `undefined` \| `string` \| `number`; `name`: `string`; } | The company context. If no `id` key is set, the whole object is ignored. | | `company.avatar?` | `string` | The avatar URL of the company. | | `company.id` | `undefined` \| `string` \| `number` | The identifier of the company. | | `company.name?` | `string` | The name of the company. | | `enableTracking?` | `boolean` | Enable tracking for the context. If set to `false`, tracking will be disabled for the context. Default is `true`. | | `meta?` | [`TrackingMeta`](#trackingmeta) | The meta context used to update the user or company when syncing is required during feature retrieval. | | `other?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `any`> | The other context. This is used for any additional context that is not related to user or company. | | `user?` | { `[k: string]`: `any`; `avatar`: `string`; `email`: `string`; `id`: `undefined` \| `string` \| `number`; `name`: `string`; } | The user context. If no `id` key is set, the whole object is ignored. | | `user.avatar?` | `string` | The avatar URL of the user. | | `user.email?` | `string` | The email of the user. | | `user.id` | `undefined` \| `string` \| `number` | The identifier of the user. | | `user.name?` | `string` | The name of the user. | *** ### Flag\ Describes a feature #### Type Parameters | Type Parameter | Default type | | -------------------------------------------------------- | ------------------------------------------------- | | `TConfig` *extends* [`FlagType`](#flagtype)\[`"config"`] | [`EmptyFlagRemoteConfig`](#emptyflagremoteconfig) | #### Properties | Property | Type | Description | | ----------- | ---------------------------------------------------------------------------------------- | -------------------------- | | `config` | \| [`EmptyFlagRemoteConfig`](#emptyflagremoteconfig) \| { `key`: `string`; } & `TConfig` | ‐ | | `isEnabled` | `boolean` | If the feature is enabled. | | `key` | `string` | The key of the feature. | #### Methods **track()** ```ts track(): Promise ``` Track feature usage in Reflag. **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> *** ### Flags Describes a collection of evaluated features. #### Remarks You should extend the Flags interface to define the available features. *** ### FlagsFallbackProvider Provider used to load and save raw flag definition snapshots. #### Methods **load()** ```ts load(context: FlagsFallbackProviderContext): Promise ``` Load a previously saved snapshot. **Parameters** | Parameter | Type | | --------- | --------------------------------------------------------------- | | `context` | [`FlagsFallbackProviderContext`](#flagsfallbackprovidercontext) | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`undefined` | [`FlagsFallbackSnapshot`](#flagsfallbacksnapshot)> **save()** ```ts save(context: FlagsFallbackProviderContext, snapshot: FlagsFallbackSnapshot): Promise ``` Persist a snapshot after a successful live fetch. **Parameters** | Parameter | Type | | ---------- | --------------------------------------------------------------- | | `context` | [`FlagsFallbackProviderContext`](#flagsfallbackprovidercontext) | | `snapshot` | [`FlagsFallbackSnapshot`](#flagsfallbacksnapshot) | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> *** ### HttpClient Defines the interface for an HTTP client. #### Remarks This interface is used to abstract the HTTP client implementation from the SDK. Define your own implementation of this interface to use a different HTTP client. #### Methods **get()** ```ts get( url: string, headers: Record, timeoutMs: number): Promise> ``` Sends a GET request to the specified URL. **Type Parameters** | Type Parameter | | -------------- | | `TResponse` | **Parameters** | Parameter | Type | Description | | ----------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `url` | `string` | The URL to send the request to. | | `headers` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string`> | The headers to include in the request. | | `timeoutMs` | `number` | ‐ | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`HttpClientResponse`](#httpclientresponsetresponse)<`TResponse`>> The response from the server. **post()** ```ts post( url: string, headers: Record, body: TBody): Promise> ``` Sends a POST request to the specified URL. **Type Parameters** | Type Parameter | | -------------- | | `TBody` | | `TResponse` | **Parameters** | Parameter | Type | Description | | --------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `url` | `string` | The URL to send the request to. | | `headers` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string`> | The headers to include in the request. | | `body` | `TBody` | The body of the request. | **Returns** [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`HttpClientResponse`](#httpclientresponsetresponse)<`TResponse`>> The response from the server. *** ### Logger Logger interface for logging messages #### Properties | Property | Type | Description | | -------- | ----------------------------------------------- | ---------------------- | | `debug` | (`message`: `string`, `data`?: `any`) => `void` | Log a debug messages | | `error` | (`message`: `string`, `data`?: `any`) => `void` | Log an error messages | | `info` | (`message`: `string`, `data`?: `any`) => `void` | Log an info messages | | `warn` | (`message`: `string`, `data`?: `any`) => `void` | Log a warning messages | *** ### RawFlag Describes a feature. #### Properties | Property | Type | Description | | ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------- | | `config?` | [`RawFlagRemoteConfig`](#rawflagremoteconfig) | The remote configuration value for the feature. | | `isEnabled` | `boolean` | If the feature is enabled. | | `key` | `string` | The key of the feature. | | `missingContextFields?` | `string`\[] | The missing fields in the evaluation context (optional). | | `ruleEvaluationResults?` | `boolean`\[] | The rule results of the evaluation (optional). | | `targetingVersion?` | `number` | The version of the targeting used to evaluate if the feature is enabled (optional). | ## Type Aliases ### Attributes ```ts type Attributes = Record; ``` Describes the attributes of a user, company or event. *** ### BatchBufferOptions\ ```ts type BatchBufferOptions = { flushHandler: (items: T[]) => Promise; flushOnExit: boolean; intervalMs: number; logger: Logger; maxSize: number; }; ``` Options for configuring the BatchBuffer. #### Type Parameters | Type Parameter | Description | | -------------- | -------------------------------- | | `T` | The type of items in the buffer. | #### Type declaration | Name | Type | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `flushHandler` | (`items`: `T`\[]) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`> | A function that handles flushing the items in the buffer. | | `flushOnExit`? | `boolean` | Whether to flush the buffer on exit. | | `intervalMs`? | `number` |

The interval in milliseconds at which the buffer is flushed.

Remarks

If 0, the buffer is flushed only when maxSize is reached.

| | `logger`? | [`Logger`](#logger-2) | The logger to use for logging (optional). | | `maxSize`? | `number` | The maximum size of the buffer before it is flushed. | *** ### BootstrappedFlags ```ts type BootstrappedFlags = { context: Context; flags: RawFlags; }; ``` Describes a collection of evaluated raw flags and the context for bootstrapping. #### Type declaration | Name | Type | | --------- | ----------------------- | | `context` | [`Context`](#context-1) | | `flags` | [`RawFlags`](#rawflags) | *** ### CacheStrategy ```ts type CacheStrategy = "periodically-update" | "in-request"; ``` *** ### ClientOptions ```ts type ClientOptions = { apiBaseUrl: string; batchOptions: Omit, "flushHandler" | "logger">; cacheStrategy: CacheStrategy; configFile: string; emitEvaluationEvents: boolean; fallbackFlags: | TypedFlagKey[] | Record>; fetchTimeoutMs: number; flagOverrides: | FlagOverrides | (context: Context) => FlagOverrides; flagsFallbackProvider: FlagsFallbackProvider; flagsFetchRetries: number; flagsPushUrl: string; flagsSyncMode: FlagsSyncMode; host: string; httpClient: HttpClient; logger: Logger; logLevel: LogLevel; offline: boolean; secretKey: string; }; ``` Defines the options for the SDK client. #### Type declaration | Name | Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiBaseUrl`? | `string` | The host to send requests to (optional). | | `batchOptions`? | [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)<[`BatchBufferOptions`](#batchbufferoptionst)<`any`>, `"flushHandler"` \| `"logger"`> | The options for the batch buffer (optional). If not provided, the default options are used. | | `cacheStrategy`? | [`CacheStrategy`](#cachestrategy) |

Deprecated

Use flagsSyncMode.

| | `configFile`? | `string` | The path to the config file. If supplied, the config file will be loaded. Defaults to `reflag.config.json` when NODE\_ENV is not production. Can also be set through the environment variable REFLAG\_CONFIG\_FILE. | | `emitEvaluationEvents`? | `boolean` | If set to `false`, no evaluation events will be emitted. | | `fallbackFlags`? | \| [`TypedFlagKey`](#typedflagkey)\[] \| [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<[`TypedFlagKey`](#typedflagkey), [`Exclude`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludeuniontype-excludedmembers)<[`FlagOverride`](#flagoverride), `false`>> |

The features to "enable" as fallbacks when the API is unavailable (optional). Can be an array of feature keys, or a record of feature keys and boolean or object values.

If a record is supplied instead of array, the values of each key are either the configuration values or the boolean value true.

Deprecated

Use flagsFallbackProvider instead.

| | `fetchTimeoutMs`? | `number` | The timeout in milliseconds for fetching feature targeting data (optional). Default is 10000 ms. | | `flagOverrides`? | \| [`FlagOverrides`](#flagoverrides-3) \| (`context`: [`Context`](#context-1)) => [`FlagOverrides`](#flagoverrides-3) |

Local flag overrides for testing or development.

If a function is specified, the function will be called with the context and should return a record of flag keys and boolean or object values.

| | `flagsFallbackProvider`? | [`FlagsFallbackProvider`](#flagsfallbackprovider) | Optional provider used to load and save raw flag definitions for fallback startup. Ignored in offline mode. | | `flagsFetchRetries`? | `number` | Number of times to retry fetching feature definitions (optional). Default is 3 times. | | `flagsPushUrl`? | `string` | Push endpoint used when `flagsSyncMode` is `"push"`. | | `flagsSyncMode`? | [`FlagsSyncMode`](#flagssyncmode-1) |

How flag definitions are synchronized.

  • polling (default): periodic background refresh.
  • in-request: stale refresh is triggered during request handling.
  • push: live updates over SSE keep flag definitions up to date.
| | `host`? | `string` |

Deprecated

Use apiBaseUrl instead.

| | `httpClient`? | [`HttpClient`](#httpclient-2) | The HTTP client to use for sending requests (optional). Default is the built-in fetch client. | | `logger`? | [`Logger`](#logger-2) | The logger to use for logging (optional). Default is info level logging to console. | | `logLevel`? | [`LogLevel`](#loglevel-1) | Use the console logger, but set a log level. Ineffective if a custom logger is provided. | | `offline`? | `boolean` | In offline mode, no data is sent or fetched from the the Reflag API, and `flagsFallbackProvider` is not used. This is useful for testing or development. | | `secretKey`? | `string` | The secret key used to authenticate with the Reflag API. | *** ### Context ```ts type Context = { company: { [k: string]: any; avatar: string; id: string | number | undefined; name: string; }; other: Record; user: { [k: string]: any; avatar: string; email: string; id: string | number | undefined; name: string; }; }; ``` Describes the current user context, company context, and other context. This is used to determine if feature targeting matches and to track events. #### Type declaration | Name | Type | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `company`? | { `[k: string]`: `any`; `avatar`: `string`; `id`: `string` \| `number` \| `undefined`; `name`: `string`; } | The company context. If no `id` key is set, the whole object is ignored. | | `company.avatar`? | `string` | The avatar URL of the company. | | `company.id` | `string` \| `number` \| `undefined` | The identifier of the company. | | `company.name`? | `string` | The name of the company. | | `other`? | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `any`> | The other context. This is used for any additional context that is not related to user or company. | | `user`? | { `[k: string]`: `any`; `avatar`: `string`; `email`: `string`; `id`: `string` \| `number` \| `undefined`; `name`: `string`; } | The user context. If no `id` key is set, the whole object is ignored. | | `user.avatar`? | `string` | The avatar URL of the user. | | `user.email`? | `string` | The email of the user. | | `user.id` | `string` \| `number` \| `undefined` | The identifier of the user. | | `user.name`? | `string` | The name of the user. | *** ### EdgeClientOptions ```ts type EdgeClientOptions = Omit; ``` *** ### EmptyFlagRemoteConfig ```ts type EmptyFlagRemoteConfig = { key: undefined; payload: undefined; }; ``` #### Type declaration | Name | Type | | --------- | ----------- | | `key` | `undefined` | | `payload` | `undefined` | *** ### FileFallbackProviderOptions ```ts type FileFallbackProviderOptions = { directory: string; }; ``` #### Type declaration | Name | Type | Description | | ------------ | -------- | ----------------------------------------------------- | | `directory`? | `string` | Directory where per-environment snapshots are stored. | *** ### FlagAPIResponse ```ts type FlagAPIResponse = { config: { variants: FlagConfigVariant[]; version: number; }; description: string | null; key: string; targeting: { rules: { filter: RuleFilter; }[]; version: number; }; }; ``` **`Internal`** (Internal) Describes a specific feature in the API response. #### Type declaration | Name | Type | Description | | ------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | | `config`? | { `variants`: [`FlagConfigVariant`](#flagconfigvariant)\[]; `version`: `number`; } | The remote configuration for the feature. | | `config.variants` | [`FlagConfigVariant`](#flagconfigvariant)\[] | The variants of the remote configuration. | | `config.version` | `number` | The version of the remote configuration. | | `description` | `string` \| `null` | Description of the feature. | | `key` | `string` | The key of the feature. | | `targeting` | { `rules`: { `filter`: `RuleFilter`; }\[]; `version`: `number`; } | The targeting rules for the feature. | | `targeting.rules` | { `filter`: `RuleFilter`; }\[] | The targeting rules. | | `targeting.version` | `number` | The version of the targeting rules. | *** ### FlagConfigVariant ```ts type FlagConfigVariant = { filter: RuleFilter; key: string; payload: any; }; ``` Describes a remote feature config variant. #### Type declaration | Name | Type | Description | | --------- | ------------ | ---------------------------------------- | | `filter` | `RuleFilter` | The filter for the variant. | | `key` | `string` | The key of the variant. | | `payload` | `any` | The optional user-supplied payload data. | *** ### FlagDefinition ```ts type FlagDefinition = { config: { variants: FlagConfigVariant[]; version: number; }; description: string | null; flag: { rules: { filter: RuleFilter; }[]; version: number; }; key: string; }; ``` Describes a feature definition. #### Type declaration | Name | Type | Description | | ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | | `config`? | { `variants`: [`FlagConfigVariant`](#flagconfigvariant)\[]; `version`: `number`; } | The remote configuration for the feature. | | `config.variants` | [`FlagConfigVariant`](#flagconfigvariant)\[] | The variants of the remote configuration. | | `config.version` | `number` | The version of the remote configuration. | | `description` | `string` \| `null` | Description of the feature. | | `flag` | { `rules`: { `filter`: `RuleFilter`; }\[]; `version`: `number`; } | The targeting rules for the feature. | | `flag.rules` | { `filter`: `RuleFilter`; }\[] | The targeting rules. | | `flag.version` | `number` | The version of the targeting rules. | | `key` | `string` | The key of the feature. | *** ### FlagOverride ```ts type FlagOverride = | FlagType & { config: { key: string; }; isEnabled: boolean; } | boolean; ``` *** ### FlagOverrides ```ts type FlagOverrides = Partial : { [FlagKey in keyof Flags]: Flags[FlagKey] extends FlagOverride ? Flags[FlagKey] : Exclude }>; ``` Describes the feature overrides. *** ### FlagOverridesFn() ```ts type FlagOverridesFn = (context: Context) => FlagOverrides; ``` #### Parameters | Parameter | Type | | --------- | ----------------------- | | `context` | [`Context`](#context-1) | #### Returns [`FlagOverrides`](#flagoverrides-3) *** ### FlagRemoteConfig ```ts type FlagRemoteConfig = | { key: string; payload: any; } | EmptyFlagRemoteConfig; ``` A remotely managed configuration value for a feature. #### Type declaration { `key`: `string`; `payload`: `any`; } | Name | Type | Description | | --------- | -------- | ------------------------------------------- | | `key` | `string` | The key of the matched configuration value. | | `payload` | `any` | The optional user-supplied payload data. | [`EmptyFlagRemoteConfig`](#emptyflagremoteconfig) *** ### FlagsAPIResponse ```ts type FlagsAPIResponse = { features: FlagAPIResponse[]; flagStateVersion: number; }; ``` **`Internal`** (Internal) Describes the response of the features endpoint. #### Type declaration | Name | Type | Description | | ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `features` | [`FlagAPIResponse`](#flagapiresponse)\[] | The feature definitions. | | `flagStateVersion`? | `number` | Optional for backward compatibility; when absent, the snapshot version should be treated as unknown by consumers. | *** ### FlagsFallbackProviderContext ```ts type FlagsFallbackProviderContext = { secretKeyHash: string; }; ``` Non-secret context passed to fallback providers so they can derive storage keys without access to the raw secret key. #### Type declaration | Name | Type | Description | | --------------- | -------- | ------------------------------------------------ | | `secretKeyHash` | `string` | Deterministic hash of the configured secret key. | *** ### FlagsFallbackSnapshot ```ts type FlagsFallbackSnapshot = { flags: FlagAPIResponse[]; savedAt: string; version: number; }; ``` Snapshot of flag definitions used for fallback initialization. #### Type declaration | Name | Type | Description | | --------- | ---------------------------------------- | ----------------------------------------------------- | | `flags` | [`FlagAPIResponse`](#flagapiresponse)\[] | Raw flag definitions as returned by the API. | | `savedAt` | `string` | ISO timestamp indicating when the snapshot was saved. | | `version` | `number` | Snapshot schema version. | *** ### FlagsSyncMode ```ts type FlagsSyncMode = "polling" | "in-request" | "push"; ``` *** ### FlagType ```ts type FlagType = { config: { payload: any; }; }; ``` #### Type declaration | Name | Type | | ---------------- | --------------------- | | `config`? | { `payload`: `any`; } | | `config.payload` | `any` | *** ### GCSFallbackProviderClient ```ts type GCSFallbackProviderClient = | GCSLegacyClient | GCSGoogleApisClient; ``` *** ### GCSFallbackProviderOptions ```ts type GCSFallbackProviderOptions = { bucket: string; client: GCSFallbackProviderClient; keyPrefix: string; }; ``` #### Type declaration | Name | Type | Description | | ------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bucket` | `string` | Bucket where snapshots are stored. | | `client`? | [`GCSFallbackProviderClient`](#gcsfallbackproviderclient) |

Optional GCS client. A default client is created when omitted.

Accepts either a legacy bucket().file() client or a generated @googleapis/storage client.

TODO(next major): Replace this with a simpler object-store interface.

| | `keyPrefix`? | `string` | Prefix for generated per-environment keys. | *** ### GCSGoogleApisClient ```ts type GCSGoogleApisClient = { objects: { get: Promise<{ data: unknown; }>; insert: Promise; }; }; ``` #### Type declaration | Name | Type | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `objects` | { `get`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{ `data`: `unknown`; }>; `insert`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`>; } | | `get()` | [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{ `data`: `unknown`; }> | | `insert()` | [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`> | *** ### GCSLegacyClient ```ts type GCSLegacyClient = { bucket: { file: { download: Promise<[Uint8Array]>; exists: Promise<[boolean]>; save: Promise; }; }; }; ``` #### Type declaration | Name | Type | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `bucket()` | { `file`: { `download`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<\[[`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)]>; `exists`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<\[`boolean`]>; `save`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`>; }; } | *** ### HttpClientResponse\ ```ts type HttpClientResponse = { body: TResponse | undefined; ok: boolean; status: number; }; ``` Describes the response of a HTTP client. #### Type Parameters | Type Parameter | Description | | -------------- | ------------------------------ | | `TResponse` | The type of the response body. | #### Type declaration | Name | Type | Description | | -------- | -------------------------- | -------------------------------------- | | `body` | `TResponse` \| `undefined` | The body of the response if available. | | `ok` | `boolean` | Indicates that the request succeeded. | | `status` | `number` | The status code of the response. | *** ### IdType ```ts type IdType = string | number; ``` *** ### LogLevel ```ts type LogLevel = typeof LOG_LEVELS[number]; ``` *** ### RawFlagRemoteConfig ```ts type RawFlagRemoteConfig = { key: string; missingContextFields: string[]; payload: any; ruleEvaluationResults: boolean[]; targetingVersion: number; }; ``` A remotely managed configuration value for a feature. #### Type declaration | Name | Type | Description | | ------------------------ | ------------ | ------------------------------------------------------------------- | | `key` | `string` | The key of the matched configuration value. | | `missingContextFields`? | `string`\[] | The missing fields in the evaluation context (optional). | | `payload` | `any` | The optional user-supplied payload data. | | `ruleEvaluationResults`? | `boolean`\[] | The rule results of the evaluation (optional). | | `targetingVersion`? | `number` | The version of the targeting rules used to select the config value. | *** ### RawFlags ```ts type RawFlags = Record; ``` Describes a collection of evaluated raw flags. *** ### RedisFallbackProviderOptions ```ts type RedisFallbackProviderOptions = { client: { get: Promise; set: Promise; }; keyPrefix: string; }; ``` #### Type declaration | Name | Type | Description | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `client`? | { `get`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`undefined` \| `null` \| `string`>; `set`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`>; } | Optional Redis client. When omitted, a client is created using `REDIS_URL`. | | `get()` | [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`undefined` \| `null` \| `string`> | ‐ | | `set()` | [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`> | ‐ | | `keyPrefix`? | `string` | Prefix for generated per-environment keys. | *** ### S3FallbackProviderOptions ```ts type S3FallbackProviderOptions = { bucket: string; client: { send: Promise; }; keyPrefix: string; }; ``` #### Type declaration | Name | Type | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `bucket` | `string` | Bucket where snapshots are stored. | | `client`? | { `send`: [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`any`>; } | Optional S3 client. A default client is created when omitted. | | `send()` | [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`any`> | ‐ | | `keyPrefix`? | `string` | Prefix for generated per-environment keys. | *** ### StaticFallbackProviderOptions ```ts type StaticFallbackProviderOptions = { flags: Record; }; ``` #### Type declaration | Name | Type | Description | | ------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `flags` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `boolean`> | Static fallback flags keyed by flag key. | *** ### TrackingMeta ```ts type TrackingMeta = { active: boolean; }; ``` Describes the meta context associated with tracking. #### Type declaration | Name | Type | Description | | --------- | --------- | -------------------------------------- | | `active`? | `boolean` | Whether the user or company is active. | *** ### TrackOptions ```ts type TrackOptions = { attributes: Attributes; meta: TrackingMeta; }; ``` Defines the options for tracking of entities. #### Type declaration | Name | Type | Description | | ------------- | ------------------------------- | ------------------------------------------- | | `attributes`? | [`Attributes`](#attributes) | The attributes associated with the event. | | `meta`? | [`TrackingMeta`](#trackingmeta) | The meta context associated with the event. | *** ### TypedFlagKey ```ts type TypedFlagKey = keyof TypedFlags; ``` *** ### TypedFlags ```ts type TypedFlags = keyof Flags extends never ? Record : { [FlagKey in keyof Flags]: Flags[FlagKey] extends FlagType ? Flag : Flag }; ``` Describes a collection of evaluated feature. #### Remarks This types falls back to a generic Record\ if the Flags interface has not been extended. ## Variables ### fallbackProviders ```ts const fallbackProviders: { file: (__namedParameters: FileFallbackProviderOptions) => FlagsFallbackProvider; gcs: (__namedParameters: GCSFallbackProviderOptions) => FlagsFallbackProvider; redis: (__namedParameters: RedisFallbackProviderOptions) => FlagsFallbackProvider; s3: (__namedParameters: S3FallbackProviderOptions) => FlagsFallbackProvider; static: (__namedParameters: StaticFallbackProviderOptions) => FlagsFallbackProvider; }; ``` #### Type declaration | Name | Type | Default value | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `file` | (`__namedParameters`: [`FileFallbackProviderOptions`](#filefallbackprovideroptions)) => [`FlagsFallbackProvider`](#flagsfallbackprovider) | createFileFallbackProvider | | `gcs` | (`__namedParameters`: [`GCSFallbackProviderOptions`](#gcsfallbackprovideroptions)) => [`FlagsFallbackProvider`](#flagsfallbackprovider) | createGCSFallbackProvider | | `redis` | (`__namedParameters`: [`RedisFallbackProviderOptions`](#redisfallbackprovideroptions)) => [`FlagsFallbackProvider`](#flagsfallbackprovider) | createRedisFallbackProvider | | `s3` | (`__namedParameters`: [`S3FallbackProviderOptions`](#s3fallbackprovideroptions)) => [`FlagsFallbackProvider`](#flagsfallbackprovider) | createS3FallbackProvider | | `static` | (`__namedParameters`: [`StaticFallbackProviderOptions`](#staticfallbackprovideroptions)) => [`FlagsFallbackProvider`](#flagsfallbackprovider) | createStaticFallbackProvider | *** ### LOG\_LEVELS ```ts const LOG_LEVELS: readonly ["DEBUG", "INFO", "WARN", "ERROR"]; ```