@reflag/node-sdk 1.0.0-alpha.1

package/dist/src/utils.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = void 0;
+exports.ok = ok;
+exports.idOk = idOk;
+exports.isObject = isObject;
+exports.decorate = decorate;
+exports.applyLogLevel = applyLogLevel;
+exports.decorateLogger = decorateLogger;
+exports.mergeSkipUndefined = mergeSkipUndefined;
+exports.hashObject = hashObject;
+exports.once = once;
+exports.withTimeout = withTimeout;
+const crypto_1 = require("crypto");
+/**
+ * Assert that the given condition is `true`.
+ *
+ * @param condition - The condition to check.
+ * @param message - The error message to throw.
+ **/
+function ok(condition, message) {
+    if (!condition) {
+        throw new Error(`validation failed: ${message}`);
+    }
+}
+/**
+ * Assert that the given values is a valid user/company id
+ **/
+function idOk(id, entity) {
+    ok((typeof id === "string" && id.length > 0) || typeof id === "number", `${entity} must be a string or number if given`);
+}
+/**
+ * Check if the given item is an object.
+ *
+ * @param item - The item to check.
+ * @returns `true` if the item is an object, `false` otherwise.
+ **/
+function isObject(item) {
+    return (item && typeof item === "object" && !Array.isArray(item)) || false;
+}
+function decorate(prefix, fn) {
+    return (message, ...args) => {
+        fn(`${prefix} ${message}`, ...args);
+    };
+}
+function applyLogLevel(logger, logLevel) {
+    switch (logLevel === null || logLevel === void 0 ? void 0 : logLevel.toLocaleUpperCase()) {
+        case "DEBUG":
+            return {
+                debug: decorate("[debug]", logger.debug),
+                info: decorate("[info]", logger.info),
+                warn: decorate("[warn]", logger.warn),
+                error: decorate("[error]", logger.error),
+            };
+        case "INFO":
+            return {
+                debug: () => void 0,
+                info: decorate("[info]", logger.info),
+                warn: decorate("[warn]", logger.warn),
+                error: decorate("[error]", logger.error),
+            };
+        case "WARN":
+            return {
+                debug: () => void 0,
+                info: () => void 0,
+                warn: decorate("[warn]", logger.warn),
+                error: decorate("[error]", logger.error),
+            };
+        case "ERROR":
+            return {
+                debug: () => void 0,
+                info: () => void 0,
+                warn: () => void 0,
+                error: decorate("[error]", logger.error),
+            };
+        default:
+            throw new Error(`invalid log level: ${logLevel}`);
+    }
+}
+/**
+ * Decorate the messages of a given logger with the given prefix.
+ *
+ * @param prefix - The prefix to add to log messages.
+ * @param logger - The logger to decorate.
+ * @returns The decorated logger.
+ **/
+function decorateLogger(prefix, logger) {
+    ok(typeof prefix === "string", "prefix must be a string");
+    ok(typeof logger === "object", "logger must be an object");
+    return {
+        debug: decorate(prefix, logger.debug),
+        info: decorate(prefix, logger.info),
+        warn: decorate(prefix, logger.warn),
+        error: decorate(prefix, logger.error),
+    };
+}
+/** Merge two objects, skipping `undefined` values.
+ *
+ * @param target - The target object.
+ * @param source - The source object.
+ * @returns The merged object.
+ **/
+function mergeSkipUndefined(target, source) {
+    const newTarget = Object.assign({}, target);
+    for (const key in source) {
+        if (source[key] === undefined) {
+            continue;
+        }
+        newTarget[key] = source[key];
+    }
+    return newTarget;
+}
+function updateSha1Hash(hash, value) {
+    if (value === null) {
+        hash.update("null");
+    }
+    else {
+        switch (typeof value) {
+            case "object":
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        updateSha1Hash(hash, item);
+                    }
+                }
+                else {
+                    for (const key of Object.keys(value).sort()) {
+                        hash.update(key);
+                        updateSha1Hash(hash, value[key]);
+                    }
+                }
+                break;
+            case "string":
+                hash.update(value);
+                break;
+            case "number":
+            case "boolean":
+            case "symbol":
+            case "bigint":
+            case "function":
+                hash.update(value.toString());
+                break;
+            case "undefined":
+            default:
+                break;
+        }
+    }
+}
+/** Hash an object using SHA1.
+ *
+ * @param obj - The object to hash.
+ *
+ * @returns The SHA1 hash of the object.
+ **/
+function hashObject(obj) {
+    ok(isObject(obj), "obj must be an object");
+    const hash = (0, crypto_1.createHash)("sha1");
+    updateSha1Hash(hash, obj);
+    return hash.digest("base64");
+}
+function once(fn) {
+    let called = false;
+    let returned;
+    return function () {
+        if (called) {
+            return returned;
+        }
+        returned = fn();
+        called = true;
+        return returned;
+    };
+}
+class TimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Operation timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Wraps a promise with a timeout. If the promise doesn't resolve within the specified
+ * timeout, it will reject with a timeout error. The original promise will still
+ * continue to execute but its result will be ignored.
+ *
+ * @param promise - The promise to wrap with a timeout
+ * @param timeoutMs - The timeout in milliseconds
+ * @returns A promise that resolves with the original promise result or rejects with a timeout error
+ * @throws {Error} If the timeout is reached before the promise resolves
+ **/
+function withTimeout(promise, timeoutMs) {
+    ok(timeoutMs > 0, "timeout must be a positive number");
+    return new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(new TimeoutError(timeoutMs));
+        }, timeoutMs);
+        promise
+            .then((result) => {
+            resolve(result);
+        })
+            .catch((error) => {
+            reject(error);
+        })
+            .finally(() => {
+            clearTimeout(timeoutId);
+        });
+    });
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/types/src/batch-buffer.d.ts

@@ -0,0 +1,27 @@
+import { BatchBufferOptions } from "./types";
+/**
+ * A buffer that accumulates items and flushes them in batches.
+ * @typeparam T - The type of items to buffer.
+ */
+export default class BatchBuffer<T> {
+    private buffer;
+    private flushHandler;
+    private logger?;
+    private maxSize;
+    private intervalMs;
+    private timer;
+    /**
+     * Creates a new `BatchBuffer` instance.
+     * @param options - The options to configure the buffer.
+     * @throws If the options are invalid.
+     */
+    constructor(options: BatchBufferOptions<T>);
+    /**
+     * Adds an item to the buffer.
+     *
+     * @param item - The item to add.
+     */
+    add(item: T): Promise<void>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=batch-buffer.d.ts.map

package/dist/types/src/batch-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-buffer.d.ts","sourceRoot":"","sources":["../../../src/batch-buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAU,MAAM,SAAS,CAAC;AAGrD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAA+B;IAE5C;;;;OAIG;gBACS,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAwB1C;;;;OAIG;IACU,GAAG,CAAC,IAAI,EAAE,CAAC;IAUX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA2BpC"}

package/dist/types/src/cache.d.ts

@@ -0,0 +1,16 @@
+import { Cache, Logger } from "./types";
+/**
+ * Create a cached function that updates the value asynchronously.
+ *
+ * The value is updated every `ttl` milliseconds.
+ * If the value is older than `staleTtl` milliseconds, a warning is logged.
+ *
+ * @typeParam T - The type of the value.
+ * @param ttl - The time-to-live in milliseconds.
+ * @param staleTtl - The time-to-live after which a warning is logged.
+ * @param logger - The logger to use.
+ * @param fn - The function to call to get the value.
+ * @returns The cache object.
+ **/
+export default function cache<T>(ttl: number, staleTtl: number, logger: Logger | undefined, fn: () => Promise<T | undefined>): Cache<T>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/types/src/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;;IAYI;AACJ,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAC/B,KAAK,CAAC,CAAC,CAAC,CAkDV"}

package/dist/types/src/client.d.ts

@@ -0,0 +1,410 @@
+import type { FlagDefinition, FlagOverrides, FlagOverridesFn, IdType, TypedFlagKey } from "./types";
+import { ClientOptions, Context, ContextWithTracking, HttpClient, Logger, TrackOptions, TypedFlags } from "./types";
+/**
+ * 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" },
+ * });
+ * ```
+ **/
+export declare class ReflagClient {
+    private _config;
+    httpClient: HttpClient;
+    private flagsCache;
+    private batchBuffer;
+    private rateLimiter;
+    /**
+     * Gets the logger associated with the client.
+     */
+    readonly logger: Logger;
+    private initializationFinished;
+    private _initialize;
+    /**
+     * Creates a new SDK client.
+     * See README for configuration options.
+     *
+     * @param options - The options for the client or an existing client to clone.
+     * @param options.secretKey - The secret key to use for the client.
+     * @param options.apiBaseUrl - The base URL to send requests to (optional).
+     * @param options.logger - The logger to use for logging (optional).
+     * @param options.httpClient - The HTTP client to use for sending requests (optional).
+     * @param options.logLevel - The log level to use for logging (optional).
+     * @param options.offline - Whether to run in offline mode (optional).
+     * @param options.fallbackFlags - The fallback flags to use if the flag is not found (optional).
+     * @param options.batchOptions - The options for the batch buffer (optional).
+     * @param options.flagOverrides - The flag overrides to use for the client (optional).
+     * @param options.configFile - The path to the config file (optional).
+     * @param options.flagsFetchRetries - Number of retries for fetching flags (optional, defaults to 3).
+     * @param options.fetchTimeoutMs - Timeout for fetching flags (optional, defaults to 10000ms).
+     * @param options.cacheStrategy - The cache strategy to use for the client (optional, defaults to "periodically-update").
+     *
+     * @throws An error if the options are invalid.
+     **/
+    constructor(options?: ClientOptions);
+    /**
+     * Sets the flag overrides.
+     *
+     * @param overrides - The flag overrides.
+     *
+     * @remarks
+     * The flag overrides are used to override the flag definitions.
+     * This is useful for testing or development.
+     *
+     * @example
+     * ```ts
+     * client.flagOverrides = {
+     *   "flag-1": true,
+     *   "flag-2": false,
+     * };
+     * ```
+     **/
+    set flagOverrides(overrides: FlagOverridesFn | FlagOverrides);
+    /**
+     * Clears the flag overrides.
+     *
+     * @remarks
+     * This is useful for testing or development.
+     *
+     * @example
+     * ```ts
+     * afterAll(() => {
+     *   client.clearFlagOverrides();
+     * });
+     * ```
+     **/
+    clearFlagOverrides(): void;
+    /**
+     * 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.
+     *
+     * @param context - The context to bind the client to.
+     * @param context.enableTracking - Whether to enable tracking for the context.
+     * @param context.user - The user context.
+     * @param context.company - The company context.
+     * @param context.other - The other context.
+     *
+     * @returns 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.
+     **/
+    bindClient({ enableTracking, ...context }: ContextWithTracking): BoundReflagClient;
+    /**
+     * Updates the associated user in Reflag.
+     *
+     * @param userId - The userId of the user to update.
+     * @param options - The options for the user.
+     * @param options.attributes - The additional attributes of the user (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     *
+     * @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(userId: IdType, options?: TrackOptions): Promise<void>;
+    /**
+     * Updates the associated company in Reflag.
+     *
+     * @param companyId - The companyId of the company to update.
+     * @param options - The options for the company.
+     * @param options.attributes - The additional attributes of the company (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     * @param options.userId - The userId of the user to associate with the company (optional).
+     *
+     * @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.
+     **/
+    updateCompany(companyId: IdType, options?: TrackOptions & {
+        userId?: IdType;
+    }): Promise<void>;
+    /**
+     * Tracks an event in Reflag.
+  
+     * @param options.companyId - Optional company ID for the event (optional).
+     *
+     * @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.
+     **/
+    track(userId: IdType, event: string, options?: TrackOptions & {
+        companyId?: IdType;
+    }): Promise<void>;
+    /**
+     * Initializes the client by caching the flags definitions.
+     *
+     * @remarks
+     * Call this method before calling `getFlags` to ensure the flag definitions are cached.
+     * The client will ignore subsequent calls to this method.
+     **/
+    initialize(): Promise<void>;
+    /**
+     * Flushes and completes any in-flight fetches in the flag cache.
+     *
+     * @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).
+     */
+    flush(): Promise<void>;
+    /**
+     * Gets the flag definitions, including all config values.
+     * To evaluate which flags are enabled for a given user/company, use `getFlags`.
+     *
+     * @returns The flags definitions.
+     */
+    getFlagDefinitions(): FlagDefinition[];
+    /**
+     * Gets the evaluated flags for the current context which includes the user, company, and custom context.
+     *
+     * @param options - The options for the context.
+     * @param options.enableTracking - Whether to enable tracking for the context.
+     * @param options.meta - The meta context associated with the context.
+     * @param options.user - The user context.
+     * @param options.company - The company context.
+     * @param options.other - The other context.
+     *
+     * @returns The evaluated flags.
+     *
+     * @remarks
+     * Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.
+     **/
+    getFlags({ enableTracking, ...context }: ContextWithTracking): TypedFlags;
+    /**
+     * 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.
+     *
+     * @param key - The key of the flag to get.
+     * @returns The evaluated flag.
+     *
+     * @remarks
+     * Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.
+     **/
+    getFlag<TKey extends TypedFlagKey>({ enableTracking, ...context }: ContextWithTracking, key: TKey): TypedFlags[TKey];
+    /**
+     * Gets evaluated flags with the usage of remote context.
+     * This method triggers a network request every time it's called.
+     *
+     * @param userId - The userId of the user to get the flags for.
+     * @param companyId - The companyId of the company to get the flags for.
+     * @param additionalContext - The additional context to get the flags for.
+     *
+     * @returns evaluated flags
+     */
+    getFlagsRemote(userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise<TypedFlags>;
+    /**
+     * Gets evaluated flag with the usage of remote context.
+     * This method triggers a network request every time it's called.
+     *
+     * @param key - The key of the flag to get.
+     * @param userId - The userId of the user to get the flag for.
+     * @param companyId - The companyId of the company to get the flag for.
+     * @param additionalContext - The additional context to get the flag for.
+     *
+     * @returns evaluated flag
+     */
+    getFlagRemote<TKey extends TypedFlagKey>(key: TKey, userId?: IdType, companyId?: IdType, additionalContext?: Context): Promise<TypedFlags[TKey]>;
+    private buildUrl;
+    /**
+     * Sends a POST request to the specified path.
+     *
+     * @param path - The path to send the request to.
+     * @param body - The body of the request.
+     *
+     * @returns A boolean indicating if the request was successful.
+     *
+     * @throws An error if the path or body is invalid.
+     **/
+    private post;
+    /**
+     * Sends a GET request to the specified path.
+     *
+     * @param path - The path to send the request to.
+     * @param retries - Optional number of retries for the request.
+     *
+     * @returns The response from the server.
+     * @throws An error if the path is invalid.
+     **/
+    private get;
+    /**
+     * Sends a batch of events to the Reflag API.
+     *
+     * @param events - The events to send.
+     *
+     * @throws An error if the send fails.
+     **/
+    private sendBulkEvents;
+    /**
+     * Sends a flag event to the Reflag API.
+     *
+     * Flag events are used to track the evaluation of flag targeting rules.
+     * "check" events are sent when a flag's `isEnabled` property is checked.
+     * "evaluate" events are sent when a flag's targeting rules are matched against
+     * the current context.
+     *
+     * @param event - The event to send.
+     * @param event.action - The action to send.
+     * @param event.key - The key of the flag to send.
+     * @param event.targetingVersion - The targeting version of the flag to send.
+     * @param event.evalResult - The evaluation result of the flag to send.
+     * @param event.evalContext - The evaluation context of the flag to send.
+     * @param event.evalRuleResults - The evaluation rule results of the flag to send.
+     * @param event.evalMissingFields - The evaluation missing fields of the flag to send.
+     *
+     * @throws An error if the event is invalid.
+     *
+     * @remarks
+     * This method is rate-limited to prevent too many events from being sent.
+     **/
+    private sendFlagEvent;
+    /**
+     * Updates the context in Reflag (if needed).
+     * This method should be used before requesting flags or binding a client.
+     *
+     * @param options - The options for the context.
+     * @param options.enableTracking - Whether to enable tracking for the context.
+     * @param options.meta - The meta context associated with the context.
+     * @param options.user - The user context.
+     * @param options.company - The company context.
+     * @param options.other - The other context.
+     */
+    private syncContext;
+    /**
+     * Warns if a flag has targeting rules that require context fields that are missing.
+     *
+     * @param context - The context.
+     * @param flag - The flag to check.
+     */
+    private _warnMissingFlagContextFields;
+    private _getFlags;
+    private _wrapRawFlag;
+    private _getFlagsRemote;
+}
+/**
+ * A client bound with a specific user, company, and other context.
+ */
+export declare class BoundReflagClient {
+    private readonly _client;
+    private readonly _options;
+    /**
+     * (Internal) Creates a new BoundReflagClient. Use `bindClient` to create a new client bound with a specific context.
+     *
+     * @param client - The `ReflagClient` to use.
+     * @param options - The options for the client.
+     * @param options.enableTracking - Whether to enable tracking for the client.
+     *
+     * @internal
+     */
+    constructor(client: ReflagClient, { enableTracking, ...context }: ContextWithTracking);
+    /**
+     * Gets the "other" context associated with the client.
+     *
+     * @returns The "other" context or `undefined` if it is not set.
+     **/
+    get otherContext(): Record<string, any> | undefined;
+    /**
+     * Gets the user associated with the client.
+     *
+     * @returns The user or `undefined` if it is not set.
+     **/
+    get user(): {
+        [k: string]: any;
+        id: string | number | undefined;
+        name?: string | undefined;
+        email?: string | undefined;
+        avatar?: string | undefined;
+    } | undefined;
+    /**
+     * Gets the company associated with the client.
+     *
+     * @returns The company or `undefined` if it is not set.
+     **/
+    get company(): {
+        [k: string]: any;
+        id: string | number | undefined;
+        name?: string | undefined;
+        avatar?: string | undefined;
+    } | undefined;
+    /**
+     * 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 Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlags(): TypedFlags;
+    /**
+     * Get a specific flag for the user/company/other context bound to this client.
+     * Using the `isEnabled` property sends a `check` event to Reflag.
+     *
+     * @param key - The key of the flag to get.
+     *
+     * @returns Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlag<TKey extends TypedFlagKey>(key: TKey): TypedFlags[TKey];
+    /**
+     * Get remotely evaluated flag for the user/company/other context bound to this client.
+     *
+     * @returns Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlagsRemote(): Promise<Record<string, import("./types").Flag<import("./types").EmptyFlagRemoteConfig>>>;
+    /**
+     * Get remotely evaluated flag for the user/company/other context bound to this client.
+     *
+     * @param key - The key of the flag to get.
+     *
+     * @returns Flag for the given user/company and key and whether it's enabled or not
+     */
+    getFlagRemote(key: string): Promise<import("./types").Flag<import("./types").EmptyFlagRemoteConfig>>;
+    /**
+     * Track an event in Reflag.
+     *
+     * @param event - The event to track.
+     * @param options - The options for the event.
+     * @param options.attributes - The attributes of the event (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     * @param options.companyId - Optional company ID for the event (optional).
+     *
+     * @throws An error if the event is invalid or the options are invalid.
+     */
+    track(event: string, options?: TrackOptions & {
+        companyId?: string;
+    }): Promise<void>;
+    /**
+     * Create a new client bound with the additional context.
+     * Note: This performs a shallow merge for user/company/other individually.
+     *
+     * @param context - The context to bind the client to.
+     * @param context.user - The user to bind the client to.
+     * @param context.company - The company to bind the client to.
+     * @param context.other - The other context to bind the client to.
+     * @param context.enableTracking - Whether to enable tracking for the client.
+     * @param context.meta - The meta context to bind the client to.
+     *
+     * @returns new client bound with the additional context
+     */
+    bindClient({ user, company, other, enableTracking, meta, }: ContextWithTracking): BoundReflagClient;
+    /**
+     * Flushes the batch buffer.
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client.ts"],"names":[],"mappings":"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"}