Reference

Classes

BoundBucketClient

A client bound with a specific user, company, and other context.

Constructors

new BoundBucketClient()

new BoundBucketClient(client: BucketClient, __namedParameters: ContextWithTracking): BoundBucketClient

Parameters

Parameter	Type
client	BucketClient
__namedParameters	ContextWithTracking

Returns

BoundBucketClient

Accessors

company

Get Signature

get company(): 
  | undefined
  | {
[k: string]: any;   id: undefined | string | number;
  name: string;
}

Gets the company associated with the client.

Returns

| undefined | { [k: string]: any; id: undefined | string | number; name: string; }

The company or undefined if it is not set.

otherContext

Get Signature

get otherContext(): undefined | Record<string, any>

Gets the "other" context associated with the client.

Returns

undefined | Record<string, any>

The "other" context or undefined if it is not set.

user

Get Signature

get user(): 
  | undefined
  | {
[k: string]: any;   email: string;
  id: undefined | string | number;
  name: string;
}

Gets the user associated with the client.

Returns

| undefined | { [k: string]: any; email: string; id: undefined | string | number; name: string; }

The user or undefined if it is not set.

Methods

bindClient()

bindClient(__namedParameters: Context & {
  enableTracking: boolean;
 }): BoundBucketClient

Create a new client bound with the additional context. Note: This performs a shallow merge for user/company/other individually.

Parameters

Parameter	Type
__namedParameters	Context & { enableTracking: boolean; }

Returns

BoundBucketClient

new client bound with the additional context

flush()

flush(): Promise<void>

Flushes the batch buffer.

Returns

Promise<void>

getFeature()

getFeature(key: string): Feature

Get a specific feature for the user/company/other context bound to this client. Using the isEnabled property sends a check event to Bucket.

Parameters

Parameter	Type
key	string

Returns

Feature

Features for the given user/company and whether each one is enabled or not

getFeatureRemote()

getFeatureRemote(key: string): Promise<Feature>

Get remotely evaluated feature for the user/company/other context bound to this client.

Parameters

Parameter	Type
key	string

Returns

Promise<Feature>

Feature for the given user/company and key and whether it's enabled or not

getFeatures()

getFeatures(): Record<string, Feature>

Get features for the user/company/other context bound to this client. Meant for use in serialization of features for transferring to the client-side/browser.

Returns

Record<string, Feature>

Features for the given user/company and whether each one is enabled or not

getFeaturesRemote()

getFeaturesRemote(): Promise<Record<string, Feature>>

Get remotely evaluated feature for the user/company/other context bound to this client.

Returns

Promise<Record<string, Feature>>

Features for the given user/company and whether each one is enabled or not

track()

track(event: string, opts?: TrackOptions & {
  companyId: string;
}): Promise<void>

Track an event in Bucket.

Parameters

Parameter	Type	Description
event	string	The event to track.
opts?	TrackOptions & { companyId: string; }	‐

Returns

Promise<void>

Throws

An error if the event is invalid or the options are invalid.

---

BucketClient

The SDK client.

Constructors

new BucketClient()

new BucketClient(options: ClientOptions): BucketClient

Creates a new SDK client. See README for configuration options.

Parameters

Parameter	Type	Description
options	ClientOptions	The options for the client or an existing client to clone.

Returns

BucketClient

Throws

An error if the options are invalid.

Accessors

featureOverrides

Set Signature

set featureOverrides(overrides: FeatureOverridesFn): void

Parameters

Parameter	Type
overrides	FeatureOverridesFn

Returns

void

logger

Get Signature

get logger(): undefined | Logger

Gets the logger associated with the client.

Returns

undefined | Logger

The logger or undefined if it is not set.

Methods

bindClient()

bindClient(__namedParameters: ContextWithTracking): BoundBucketClient

Returns a new BoundBucketClient with the user/company/otherContext set to be used in subsequent calls. For example, for evaluating feature targeting or tracking events.

Parameters

Parameter	Type
__namedParameters	ContextWithTracking

Returns

BoundBucketClient

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.

flush()

flush(): Promise<void>

Flushes the batch buffer.

Returns

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.

getFeature()

getFeature(__namedParameters: ContextWithTracking, key: string): Feature

Gets the evaluated feature for the current context which includes the user, company, and custom context. Using the isEnabled property sends a check event to Bucket.

Parameters

Parameter	Type
__namedParameters	ContextWithTracking
key	string

Returns

Feature

The evaluated features.

Remarks

Call initialize before calling this method to ensure the feature definitions are cached, no features will be returned otherwise.

getFeatureRemote()

getFeatureRemote(
   key: string, 
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Feature>

Gets evaluated feature with the usage of remote context. This method triggers a network request every time it's called.

Parameters

Parameter	Type
key	string
userId?	IdType
companyId?	IdType
additionalContext?	Context

Returns

Promise<Feature>

evaluated feature

getFeatures()

getFeatures(__namedParameters: ContextWithTracking): Record<string, Feature>

Gets the evaluated feature for the current context which includes the user, company, and custom context.

Parameters

Parameter	Type
__namedParameters	ContextWithTracking

Returns

Record<string, Feature>

The evaluated features.

Remarks

Call initialize before calling this method to ensure the feature definitions are cached, no features will be returned otherwise.

getFeaturesRemote()

getFeaturesRemote(
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Record<string, Feature>>

Gets evaluated features with the usage of remote context. This method triggers a network request every time it's called.

Parameters

Parameter	Type
userId?	IdType
companyId?	IdType
additionalContext?	Context

Returns

Promise<Record<string, Feature>>

evaluated features

initialize()

initialize(): Promise<void>

Initializes the client by caching the features definitions.

Returns

Promise<void>

void

Remarks

Call this method before calling getFeatures to ensure the feature definitions are cached. The client will ignore subsequent calls to this method.

track()

track(
   userId: IdType, 
   event: string, 
   opts?: TrackOptions & {
  companyId: IdType;
}): Promise<void>

Tracks an event in Bucket.

Parameters

Parameter	Type	Description
userId	IdType	The userId of the user who performed the event
event	string	The event to track.
opts?	TrackOptions & { companyId: IdType; }	The options.

Returns

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()

updateCompany(companyId: IdType, opts?: TrackOptions & {
  userId: IdType;
}): Promise<void>

Updates the associated company in Bucket.

Parameters

Parameter	Type
companyId	IdType
opts?	TrackOptions & { userId: IdType; }

Returns

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()

updateUser(userId: IdType, opts?: TrackOptions): Promise<void>

Updates the associated user in Bucket.

Parameters

Parameter	Type
userId	IdType
opts?	TrackOptions

Returns

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

Properties

Property	Type	Description
company?	{ [k: string]: any; id: undefined | string | number; name: string; }	The company context. If no id key is set, the whole object is ignored.
company.id	undefined | string | number	‐
company.name?	string	‐
enableTracking?	boolean	Enable tracking for the context. If set to false, tracking will be disabled for the context. Default is true.
other?	Record<string, any>	The other context. This is used for any additional context that is not related to user or company.
user?	{ [k: string]: any; email: string; id: undefined | string | number; name: string; }	The user context. If no id key is set, the whole object is ignored.
user.email?	string	‐
user.id	undefined | string | number	‐
user.name?	string	‐

---

Feature

Describes a feature

Properties

Property	Type	Description
isEnabled	boolean	If the feature is enabled.
key	string	The key of the feature.

Methods

track()

track(): Promise<void>

Track feature usage in Bucket.

Returns

Promise<void>

---

Features

Describes a collection of evaluated features.

Remarks

You should extend the Features interface to define the available features.

---

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()

get<TResponse>(url: string, headers: Record<string, string>): Promise<HttpClientResponse<TResponse>>

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<string, string>	The headers to include in the request.

Returns

Promise<HttpClientResponse<TResponse>>

The response from the server.

post()

post<TBody, TResponse>(
   url: string, 
   headers: Record<string, string>, 
body: TBody): Promise<HttpClientResponse<TResponse>>

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<string, string>	The headers to include in the request.
body	TBody	The body of the request.

Returns

Promise<HttpClientResponse<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

---

RawFeature

Describes a feature

Properties

Property	Type	Description
isEnabled	boolean	If the feature is enabled.
key	string	The key of the feature.
missingContextFields?	string[]	The missing fields in the evaluation context (optional).
targetingVersion?	number	The version of the targeting used to evaluate if the feature is enabled (optional).

Type Aliases

Attributes

type Attributes = Record<string, any>;

Describes the attributes of a user, company or event.

---

BatchBufferOptions<T>

type BatchBufferOptions<T> = {
  flushHandler: (items: T[]) => Promise<void>;
  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<void>	A function that handles flushing the items in the buffer.
intervalMs?	number	The interval in milliseconds at which the buffer is flushed.
logger?	Logger	The logger to use for logging (optional).
maxSize?	number	The maximum size of the buffer before it is flushed.

---

ClientOptions

type ClientOptions = {
  apiBaseUrl: string;
  batchOptions: Omit<BatchBufferOptions<any>, "flushHandler" | "logger">;
  configFile: string;
  fallbackFeatures: keyof TypedFeatures[];
  featureOverrides:   | string
     | (context: Context) => Partial<Record<keyof TypedFeatures, boolean>>;
  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<BatchBufferOptions<any>, "flushHandler" | "logger">	The options for the batch buffer (optional). If not provided, the default options are used.
configFile?	string	The path to the config file. If supplied, the config file will be loaded. Defaults to bucket.json when NODE_ENV is not production. Can also be set through the environment variable BUCKET_CONFIG_FILE.
fallbackFeatures?	keyof TypedFeatures[]	The features to "enable" as fallbacks when the API is unavailable (optional).
featureOverrides?	| string | (context: Context) => Partial<Record<keyof TypedFeatures, boolean>>	If a filename is specified, feature targeting results be overridden with the values from this file. The file should be a JSON object with feature keys as keys and boolean values as values. If a function is specified, the function will be called with the context and should return a record of feature keys and boolean values. Defaults to "bucketFeatures.json".
host?	string	Deprecated Use apiBaseUrl instead.
httpClient?	HttpClient	The HTTP client to use for sending requests (optional). Default is the built-in fetch client.
logger?	Logger	The logger to use for logging (optional). Default is info level logging to console.
logLevel?	LogLevel	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 Bucket API. This is useful for testing or development.
secretKey?	string	The secret key used to authenticate with the Bucket API.

---

Context

type Context = {
  company: {
   [k: string]: any;   id: string | number | undefined;
     name: string;
    };
  other: Record<string, any>;
  user: {
   [k: string]: any;   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; id: string | number | undefined; name: string; }	The company context. If no id key is set, the whole object is ignored.
company.id	string | number | undefined	‐
company.name?	string	‐
other?	Record<string, any>	The other context. This is used for any additional context that is not related to user or company.
user?	{ [k: string]: any; email: string; id: string | number | undefined; name: string; }	The user context. If no id key is set, the whole object is ignored.
user.email?	string	‐
user.id	string | number | undefined	‐
user.name?	string	‐

---

FeatureOverrides

type FeatureOverrides = Partial<Record<keyof TypedFeatures, boolean>>;

Describes the feature overrides.

---

FeatureOverridesFn()

type FeatureOverridesFn = (context: Context) => FeatureOverrides;

Parameters

Parameter	Type
context	Context

Returns

FeatureOverrides

---

HttpClientResponse<TResponse>

type HttpClientResponse<TResponse> = {
  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

type IdType = string | number;

---

LogLevel

type LogLevel = typeof LOG_LEVELS[number];

---

TrackingMeta

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

type TrackOptions = {
  attributes: Attributes;
  meta: TrackingMeta;
};

Defines the options for tracking of entities.

Type declaration

Name	Type	Description
attributes?	Attributes	The attributes associated with the event.
meta?	TrackingMeta	The meta context associated with the event.

---

TypedFeatures

type TypedFeatures = keyof Features extends never ? Record<string, Feature> : Record<keyof Features, Feature>;

Describes a collection of evaluated feature.

Remarks

This types falls back to a generic Record<string, Feature> if the Features interface has not been extended.

Variables

LOG_LEVELS

const LOG_LEVELS: readonly ["DEBUG", "INFO", "WARN", "ERROR"];