flags/dist/index.d.ts

Flags SDK by Vercel - The feature flags toolkit for Next.js and SvelteKit

import { TracerProvider } from '@opentelemetry/api';
import { F as FlagOverridesType, a as FlagValuesType, b as FlagDefinitionsType, P as ProviderData } from './types-CisDd6Kq.js';
export { A as Adapter, c as ApiData, D as Decide, f as FlagDeclaration, e as FlagDefinitionType, d as FlagOptionType, G as GenerousOption, H as HeadersAdapter, I as Identify, J as JsonValue, O as Origin, R as ReadonlyHeaders, g as ReadonlyRequestCookies, h as RequestCookiesAdapter } from './types-CisDd6Kq.js';
import 'http';
import '@edge-runtime/cookies';

var version = "4.0.1";

/**
 * Allows setting the `@opentelemetry/api` tracer provider to generate traces
 * for `flags` operations.
 */
declare function setTracerProvider(tracer: TracerProvider): void;

/**
 * Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
 *
 * This function is just like JSON.stringify but also escapes the resulting string to prevent XSS.
 *
 * @see https://pragmaticwebsecurity.com/articles/spasecurity/json-stringify-xss
 * @param value A JavaScript value, usually an object or array, to be converted.
 * @param replacer A function that transforms the results.
 * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
 */
declare function safeJsonStringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
/**
 * Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
 *
 * This function is just like JSON.stringify but also escapes the resulting string to prevent XSS.
 *
 * @see https://pragmaticwebsecurity.com/articles/spasecurity/json-stringify-xss
 * @param value A JavaScript value, usually an object or array, to be converted.
 * @param replacer An array of strings and numbers that acts as an approved list for selecting the object properties that will be stringified.
 * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
 */
declare function safeJsonStringify(value: any, replacer?: (number | string)[] | null, space?: string | number): string;

type ExpirationTime = string | number | Date;
/**
 * Encrypts flag overrides data.
 *
 * @param overrides - The flag overrides to encrypt
 * @param secret - The encryption secret (defaults to FLAGS_SECRET env var)
 * @param expirationTime - When the encrypted data should expire (defaults to 1 year)
 * @returns A promise resolving to the encrypted JWE string
 * @throws Error if the secret is missing or invalid
 */
declare function encryptOverrides(overrides: FlagOverridesType, secret?: string | undefined, expirationTime?: ExpirationTime): Promise<string>;
/**
 * Decrypts and validates flag overrides data.
 *
 * @param encryptedData - The encrypted JWE token string
 * @param secret - The decryption secret (defaults to FLAGS_SECRET env var)
 * @returns A promise resolving to the decrypted flag overrides or undefined if invalid
 * @throws Error if the secret is missing or invalid
 */
declare function decryptOverrides(encryptedData: string, secret?: string | undefined): Promise<FlagOverridesType | undefined>;
/**
 * Encrypts flag values data.
 *
 * @param flagValues - The flag values to encrypt
 * @param secret - The encryption secret (defaults to FLAGS_SECRET env var)
 * @param expirationTime - When the encrypted data should expire (defaults to 1 year)
 * @returns A promise resolving to the encrypted JWE string
 * @throws Error if the secret is missing or invalid
 */
declare function encryptFlagValues(flagValues: FlagValuesType, secret?: string | undefined, expirationTime?: ExpirationTime): Promise<string>;
/**
 * Decrypts and validates flag values data.
 *
 * @param encryptedData - The encrypted JWE token string
 * @param secret - The decryption secret (defaults to FLAGS_SECRET env var)
 * @returns A promise resolving to the decrypted flag values or undefined if invalid
 * @throws Error if the secret is missing or invalid
 */
declare function decryptFlagValues(encryptedData: string, secret?: string | undefined): Promise<FlagValuesType | undefined>;
/**
 * Encrypts flag definitions data.
 *
 * @param flagDefinitions - The flag definitions to encrypt
 * @param secret - The encryption secret (defaults to FLAGS_SECRET env var)
 * @param expirationTime - When the encrypted data should expire (defaults to 1 year)
 * @returns A promise resolving to the encrypted JWE string
 * @throws Error if the secret is missing or invalid
 */
declare function encryptFlagDefinitions(flagDefinitions: FlagDefinitionsType, secret?: string | undefined, expirationTime?: ExpirationTime): Promise<string>;
/**
 * Decrypts and validates flag definitions data.
 *
 * @param encryptedData - The encrypted JWE token string
 * @param secret - The decryption secret (defaults to FLAGS_SECRET env var)
 * @returns A promise resolving to the decrypted flag definitions or undefined if invalid
 * @throws Error if the secret is missing or invalid
 */
declare function decryptFlagDefinitions(encryptedData: string, secret?: string | undefined): Promise<FlagDefinitionsType | undefined>;
/**
 * Creates an access proof token.
 *
 * @param secret - The encryption secret (defaults to FLAGS_SECRET env var)
 * @param expirationTime - When the token should expire (defaults to 1 year)
 * @returns A promise resolving to the encrypted access proof token
 * @throws Error if the secret is missing or invalid
 */
declare function createAccessProof(secret?: string | undefined, expirationTime?: ExpirationTime): Promise<string>;
/**
 * Verifies an access proof token is valid.
 *
 * @param encryptedData - The encrypted access proof token
 * @param secret - The decryption secret (defaults to FLAGS_SECRET env var)
 * @returns A promise resolving to a boolean indicating if the token is valid
 * @throws Error if the secret is missing or invalid
 */
declare function verifyAccessProof(encryptedData: string, secret?: string | undefined): Promise<boolean>;

/**
 * This function lets you verify whether a request to your application's .well-known/vercel/flags endpoint was made by the toolbar.
 * You can use verifyAccess to keep this endpoint private, to avoid public access of your feature flag definitions through that endpoint.
 *
 * @example Using verifyAccess in .well-known/vercel/flags to verify access and respond with unencrypted data.
 * ```
 *  import { type NextRequest, NextResponse } from "next/server";
 *  import { verifyAccess } from "flags";
 *
 *  export async function GET(request: NextRequest) {
 *    const access = await verifyAccess(request.headers.get("Authorization"));
 *    if (!access) return NextResponse.json(null, { status: 401 });
 *
 *    return NextResponse.json({ definitions: {} })
 *  }
 * ```
 * @param authHeader the Authorization header to check
 * @param secret the FLAGS_SECRET
 * @returns True when the authorization header was valid
 */
declare const verifyAccess: (authHeader: string | null | undefined, secret?: string | undefined) => Promise<boolean>;

/**
 * This function lets you report the value of a resolved flag, which will make it available when viewing Monitoring, Logs, Analytics and Speed Insights on Vercel.
 * It's important to note that this only has effects when running on Vercel in a preview or production environments, but not during local development.
 *
 * @example Using `reportValue` to report a flag value.
 * ```
 *  import { type NextRequest, NextResponse } from "next/server";
 *  import { reportValue } from 'flags';
 *
 *  export async function GET(request: NextRequest) {
 *    reportValue('my-flag', true);
 *    return NextResponse.json({});
 *  }
 * ```
 *
 * @param key the name of the flag
 * @param value the resolved value of the flag
 */
declare function reportValue(key: string, value: unknown): void;

declare function mergeProviderData(itemsPromises: (Promise<ProviderData> | ProviderData)[]): Promise<ProviderData>;

export { FlagDefinitionsType, FlagOverridesType, FlagValuesType, ProviderData, createAccessProof, decryptFlagDefinitions, decryptFlagValues, decryptOverrides, encryptFlagDefinitions, encryptFlagValues, encryptOverrides, mergeProviderData, reportValue, safeJsonStringify, setTracerProvider, verifyAccess, verifyAccessProof, version };