@cloudflare/flagship 0.0.0 → 0.0.1

package/dist/server.mjs

@@ -0,0 +1,290 @@
+import { a as FlagshipErrorCode, i as FlagshipError, n as ContextTransformer, r as FLAGSHIP_DEFAULT_BASE_URL, t as FlagshipClient } from "./src-CiVDWmng.mjs";
+import { ErrorCode, OpenFeatureEventEmitter, ProviderEvents, ProviderStatus } from "@openfeature/server-sdk";
+//#region src/server-provider.ts
+const _noop = () => {};
+/**
+* OpenFeature provider for Flagship (server-side / dynamic context).
+*
+* Use this provider with `@openfeature/server-sdk` for Node.js,
+* Cloudflare Workers, and other server-side JavaScript environments.
+*
+* @example
+* ```typescript
+* import { OpenFeature } from '@openfeature/server-sdk';
+* import { FlagshipServerProvider } from '@cloudflare/flagship/server';
+*
+* await OpenFeature.setProviderAndWait(
+*   new FlagshipServerProvider({
+*     appId: 'app-abc123',
+*     accountId: 'your-account-id',
+*     authToken: 'your-token',
+*   })
+* );
+*
+* const client = OpenFeature.getClient();
+* const value = await client.getBooleanValue('my-flag', false, {
+*   targetingKey: 'user-123',
+*   email: 'user@example.com',
+* });
+* ```
+*/
+var FlagshipServerProvider = class {
+	constructor(options) {
+		this.runsOn = "server";
+		this.events = new OpenFeatureEventEmitter();
+		this.currentStatus = ProviderStatus.NOT_READY;
+		this.metadata = { name: "Flagship Server Provider" };
+		this.client = new FlagshipClient(options);
+		this.logging = options.logging ?? false;
+	}
+	/**
+	* Returns the provided logger when logging is enabled, or a no-op logger
+	* when `logging` is `false`. Using this in every resolve method ensures
+	* the SDK produces no console output unless the caller opts in.
+	*/
+	logger(logger) {
+		if (this.logging) return logger;
+		return {
+			debug: _noop,
+			info: _noop,
+			warn: _noop,
+			error: _noop
+		};
+	}
+	/**
+	* Probes the evaluation endpoint with a health-check request. A 404 response
+	* is treated as success — it means the endpoint is reachable but the
+	* health-check flag simply doesn't exist, which is expected. Any network
+	* failure or timeout sets the status to ERROR.
+	*/
+	async initialize(_context) {
+		try {
+			await this.client.evaluate("_flagship_health_check", {});
+			this.currentStatus = ProviderStatus.READY;
+			this.events.emit(ProviderEvents.Ready);
+		} catch (error) {
+			if (error instanceof FlagshipError && error.cause instanceof Response && error.cause.status === 404) {
+				this.currentStatus = ProviderStatus.READY;
+				this.events.emit(ProviderEvents.Ready);
+				return;
+			}
+			this.currentStatus = ProviderStatus.ERROR;
+			this.events.emit(ProviderEvents.Error, { message: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	async onClose() {
+		this.currentStatus = ProviderStatus.NOT_READY;
+	}
+	get status() {
+		return this.currentStatus;
+	}
+	async resolveBooleanEvaluation(flagKey, defaultValue, context, logger) {
+		return this.resolve(flagKey, defaultValue, context, "boolean", logger);
+	}
+	async resolveStringEvaluation(flagKey, defaultValue, context, logger) {
+		return this.resolve(flagKey, defaultValue, context, "string", logger);
+	}
+	async resolveNumberEvaluation(flagKey, defaultValue, context, logger) {
+		return this.resolve(flagKey, defaultValue, context, "number", logger);
+	}
+	async resolveObjectEvaluation(flagKey, defaultValue, context, logger) {
+		return this.resolve(flagKey, defaultValue, context, "object", logger);
+	}
+	async resolve(flagKey, defaultValue, context, expectedType, logger) {
+		const log = this.logger(logger);
+		try {
+			log.debug(`[Flagship] Evaluating flag "${flagKey}" (expected: ${expectedType})`);
+			const result = await this.client.evaluate(flagKey, context);
+			const actualType = this.getValueType(result.value);
+			if (actualType !== expectedType) {
+				const msg = `Flag "${flagKey}" type mismatch: expected ${expectedType}, got ${actualType}`;
+				log.warn(`[Flagship] ${msg}`);
+				return {
+					value: defaultValue,
+					errorCode: ErrorCode.TYPE_MISMATCH,
+					errorMessage: msg,
+					reason: "ERROR"
+				};
+			}
+			log.debug(`[Flagship] Flag "${flagKey}" resolved: value=${String(result.value)} reason=${result.reason} variant=${result.variant}`);
+			return {
+				value: result.value,
+				variant: result.variant,
+				reason: result.reason,
+				flagMetadata: {}
+			};
+		} catch (error) {
+			return this.handleError(flagKey, defaultValue, error, log);
+		}
+	}
+	/**
+	* Maps a runtime value to one of the four OpenFeature flag types.
+	* `null` maps to `'object'` (typeof null === 'object'), treating it as a
+	* JSON null which belongs to the object/structure category.
+	*/
+	getValueType(value) {
+		if (typeof value === "boolean") return "boolean";
+		if (typeof value === "string") return "string";
+		if (typeof value === "number") return "number";
+		return "object";
+	}
+	handleError(flagKey, defaultValue, error, logger) {
+		if (error instanceof FlagshipError) {
+			let errorCode;
+			switch (error.code) {
+				case FlagshipErrorCode.NETWORK_ERROR:
+					errorCode = error.cause instanceof Response && error.cause.status === 404 ? ErrorCode.FLAG_NOT_FOUND : ErrorCode.GENERAL;
+					break;
+				case FlagshipErrorCode.TIMEOUT_ERROR:
+					errorCode = ErrorCode.GENERAL;
+					break;
+				case FlagshipErrorCode.PARSE_ERROR:
+					errorCode = ErrorCode.PARSE_ERROR;
+					break;
+				case FlagshipErrorCode.INVALID_CONTEXT:
+					errorCode = ErrorCode.INVALID_CONTEXT;
+					break;
+				default: errorCode = ErrorCode.GENERAL;
+			}
+			logger.error(`[Flagship] Flag "${flagKey}" evaluation failed (${errorCode}): ${error.message}`);
+			return {
+				value: defaultValue,
+				errorCode,
+				errorMessage: error.message,
+				reason: "ERROR"
+			};
+		}
+		const errorMessage = String(error);
+		logger.error(`[Flagship] Flag "${flagKey}" evaluation failed (GENERAL): ${errorMessage}`);
+		return {
+			value: defaultValue,
+			errorCode: ErrorCode.GENERAL,
+			errorMessage,
+			reason: "ERROR"
+		};
+	}
+};
+//#endregion
+//#region src/hooks/logging-hook.ts
+/**
+* Logging hook for debugging flag evaluations
+*
+* @example
+* ```typescript
+* import { OpenFeature } from '@openfeature/server-sdk';
+* import { FlagshipServerProvider, LoggingHook } from '@cloudflare/flagship/server';
+*
+* const provider = new FlagshipServerProvider({ appId: 'your-app-id', accountId: 'your-account-id' });
+* await OpenFeature.setProviderAndWait(provider);
+*
+* // Add logging hook
+* OpenFeature.addHooks(new LoggingHook());
+* ```
+*/
+var LoggingHook = class {
+	constructor(logger = console.log) {
+		this.logger = logger;
+	}
+	before(hookContext, _hookHints) {
+		this.logger(`[Flagship] Evaluating flag: ${hookContext.flagKey}`, {
+			defaultValue: hookContext.defaultValue,
+			context: hookContext.context
+		});
+	}
+	after(hookContext, evaluationDetails, _hookHints) {
+		this.logger(`[Flagship] Flag ${hookContext.flagKey} evaluated`, {
+			value: evaluationDetails.value,
+			reason: evaluationDetails.reason,
+			variant: evaluationDetails.variant,
+			errorCode: evaluationDetails.errorCode
+		});
+	}
+	error(hookContext, error, _hookHints) {
+		const message = error instanceof Error ? error.message : String(error);
+		this.logger(`[Flagship] Error evaluating flag ${hookContext.flagKey}:`, message);
+	}
+	finally(_hookContext, _evaluationDetails, _hookHints) {}
+};
+//#endregion
+//#region src/hooks/telemetry-hook.ts
+/**
+* Telemetry hook for tracking flag evaluations
+*
+* @example
+* ```typescript
+* import { OpenFeature } from '@openfeature/server-sdk';
+* import { FlagshipServerProvider, TelemetryHook } from '@cloudflare/flagship/server';
+*
+* const telemetryHook = new TelemetryHook((event) => {
+*   // Send to your analytics service
+*   analytics.track('flag_evaluated', event);
+* });
+*
+* OpenFeature.addHooks(telemetryHook);
+* ```
+*/
+var TelemetryHook = class {
+	constructor(onEvent) {
+		this.startTimes = /* @__PURE__ */ new Map();
+		this.contextKeys = /* @__PURE__ */ new WeakMap();
+		this.hints = /* @__PURE__ */ new WeakMap();
+		this.onEvent = onEvent;
+	}
+	before(hookContext, hookHints) {
+		const now = Date.now();
+		const key = `${hookContext.flagKey}-${now}-${Math.random()}`;
+		this.startTimes.set(key, now);
+		this.contextKeys.set(hookContext, key);
+		if (hookHints !== void 0) this.hints.set(hookContext, hookHints);
+	}
+	after(hookContext, evaluationDetails, _hookHints) {
+		const telemetryKey = this.contextKeys.get(hookContext);
+		const startTime = telemetryKey ? this.startTimes.get(telemetryKey) : void 0;
+		const duration = startTime !== void 0 ? Date.now() - startTime : void 0;
+		if (telemetryKey !== void 0) {
+			this.startTimes.delete(telemetryKey);
+			this.contextKeys.delete(hookContext);
+		}
+		this.onEvent({
+			type: "evaluation",
+			flagKey: hookContext.flagKey,
+			timestamp: Date.now(),
+			duration,
+			value: evaluationDetails.value,
+			reason: evaluationDetails.reason,
+			variant: evaluationDetails.variant,
+			errorCode: evaluationDetails.errorCode,
+			context: hookContext.context,
+			hints: this.hints.get(hookContext)
+		});
+	}
+	error(hookContext, error, _hookHints) {
+		const telemetryKey = this.contextKeys.get(hookContext);
+		const startTime = telemetryKey ? this.startTimes.get(telemetryKey) : void 0;
+		const duration = startTime !== void 0 ? Date.now() - startTime : void 0;
+		if (telemetryKey !== void 0) {
+			this.startTimes.delete(telemetryKey);
+			this.contextKeys.delete(hookContext);
+		}
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		this.onEvent({
+			type: "error",
+			flagKey: hookContext.flagKey,
+			timestamp: Date.now(),
+			duration,
+			errorMessage,
+			context: hookContext.context,
+			hints: this.hints.get(hookContext)
+		});
+	}
+	finally(hookContext, _evaluationDetails, _hookHints) {
+		const telemetryKey = this.contextKeys.get(hookContext);
+		if (telemetryKey !== void 0) {
+			this.startTimes.delete(telemetryKey);
+			this.contextKeys.delete(hookContext);
+		}
+		this.hints.delete(hookContext);
+	}
+};
+//#endregion
+export { ContextTransformer, FLAGSHIP_DEFAULT_BASE_URL, FlagshipClient, FlagshipError, FlagshipErrorCode, FlagshipServerProvider, LoggingHook, TelemetryHook };

package/dist/src-CiVDWmng.mjs

@@ -0,0 +1,202 @@
+//#region src/types.ts
+/** Default base URL for the Flagship API. */
+const FLAGSHIP_DEFAULT_BASE_URL = "https://api.cloudflare.com";
+/**
+* Internal error codes produced by `FlagshipClient`.
+* These are mapped to OpenFeature `ErrorCode` values by the providers.
+*/
+let FlagshipErrorCode = /* @__PURE__ */ function(FlagshipErrorCode) {
+	/** HTTP or fetch-level failure (non-404/400 status, connection refused, etc.) */
+	FlagshipErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+	/** The request was aborted because the configured timeout elapsed. */
+	FlagshipErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+	/** The response body was not a valid evaluation response. */
+	FlagshipErrorCode["PARSE_ERROR"] = "PARSE_ERROR";
+	/** The evaluation context contained complex values that cannot be serialized to query parameters. */
+	FlagshipErrorCode["INVALID_CONTEXT"] = "INVALID_CONTEXT";
+	return FlagshipErrorCode;
+}({});
+/**
+* Error thrown by `FlagshipClient` for all abnormal conditions.
+* Carries a `code` for programmatic handling and an optional `cause` which
+* is the underlying `Response` object for HTTP errors, allowing callers to
+* inspect the status code (e.g. to distinguish 404 → `FLAG_NOT_FOUND`).
+*/
+var FlagshipError = class extends Error {
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		this.name = "FlagshipError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+//#endregion
+//#region src/context.ts
+/**
+* Utility for transforming OpenFeature evaluation context
+*/
+var ContextTransformer = class {
+	/**
+	* Transform OpenFeature evaluation context to query parameters
+	* for the Flagship API.
+	*
+	* Primitive values (`string`, `number`, `boolean`) and `Date` objects are
+	* serialized directly. Nested objects and arrays cannot be expressed as query
+	* parameters and are skipped.
+	*
+	* When a `droppedKeys` collector array is provided, skipped key names are
+	* pushed into it and **no** console warning is emitted — the caller is
+	* expected to handle the situation (e.g. throw `INVALID_CONTEXT`).
+	* When no collector is provided, a `console.warn` is emitted for each
+	* skipped key so the issue is still surfaced in development.
+	*
+	* @param context - OpenFeature evaluation context
+	* @param droppedKeys - Optional collector array; skipped key names are pushed here
+	*/
+	static toQueryParams(context, droppedKeys) {
+		const params = {};
+		for (const [key, value] of Object.entries(context)) {
+			if (value === void 0 || value === null) continue;
+			if (value instanceof Date) {
+				params[key] = value.toISOString();
+				continue;
+			}
+			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+				params[key] = String(value);
+				continue;
+			}
+			if (typeof value === "object") {
+				if (droppedKeys) droppedKeys.push(key);
+				else console.warn(`[Flagship] Context key "${key}" is a complex object/array and cannot be serialized to a query parameter. This value will be ignored during flag evaluation.`);
+				continue;
+			}
+		}
+		return params;
+	}
+	/**
+	* Build URL with query parameters from context.
+	*
+	* @param baseUrl - The base evaluation endpoint URL
+	* @param flagKey - The flag key to evaluate
+	* @param context - OpenFeature evaluation context
+	* @param droppedKeys - Optional collector array; skipped context key names are pushed here
+	*/
+	static buildUrl(baseUrl, flagKey, context, droppedKeys) {
+		const url = new URL(baseUrl);
+		url.searchParams.set("flagKey", flagKey);
+		const params = this.toQueryParams(context, droppedKeys);
+		for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+		return url.toString();
+	}
+};
+//#endregion
+//#region src/client.ts
+var FlagshipClient = class {
+	constructor(options) {
+		this.options = {
+			endpoint: resolveEndpoint(options),
+			fetchOptions: buildFetchOptions(options),
+			timeout: options.timeout || 5e3,
+			retries: Math.min(options.retries !== void 0 ? options.retries : 1, 10),
+			retryDelay: Math.min(options.retryDelay !== void 0 ? options.retryDelay : 1e3, 3e4)
+		};
+	}
+	/**
+	* Evaluate a flag with the given context.
+	*
+	* Throws a `FlagshipError` with `FlagshipErrorCode.INVALID_CONTEXT` if the
+	* evaluation context contains complex values (objects or arrays) that cannot
+	* be serialized to query parameters.
+	*/
+	async evaluate(flagKey, context) {
+		const droppedKeys = [];
+		const url = ContextTransformer.buildUrl(this.options.endpoint, flagKey, context, droppedKeys);
+		if (droppedKeys.length > 0) throw new FlagshipError(`Evaluation context contains complex values that cannot be serialized for flag "${flagKey}". Unsupported keys: ${droppedKeys.join(", ")}. Use primitive values (string, number, boolean) or Date objects.`, FlagshipErrorCode.INVALID_CONTEXT);
+		return this.fetchWithRetry(url, this.options.retries);
+	}
+	/**
+	* Fetch with retry logic. Only retries on transient network/server errors —
+	* 404 and 400 responses are terminal and propagated immediately.
+	*/
+	async fetchWithRetry(url, retriesLeft) {
+		try {
+			return await this.fetchWithTimeout(url, this.options.timeout);
+		} catch (error) {
+			if (error instanceof FlagshipError && error.cause instanceof Response) {
+				const status = error.cause.status;
+				if (status === 404 || status === 400) throw error;
+			}
+			if (retriesLeft > 0) {
+				await new Promise((resolve) => setTimeout(resolve, this.options.retryDelay));
+				return this.fetchWithRetry(url, retriesLeft - 1);
+			}
+			throw error;
+		}
+	}
+	/**
+	* Fetch with timeout using AbortController
+	*/
+	async fetchWithTimeout(url, timeout) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), timeout);
+		try {
+			const response = await fetch(url, {
+				...this.options.fetchOptions,
+				signal: controller.signal
+			});
+			clearTimeout(timeoutId);
+			if (!response.ok) throw new FlagshipError(`HTTP ${response.status}: ${response.statusText}`, FlagshipErrorCode.NETWORK_ERROR, response);
+			const data = await response.json();
+			if (!data || typeof data !== "object" || !("flagKey" in data) || !("value" in data)) throw new FlagshipError("Invalid response format from Flagship API", FlagshipErrorCode.PARSE_ERROR);
+			return data;
+		} catch (error) {
+			clearTimeout(timeoutId);
+			if (error instanceof Error && error.name === "AbortError") throw new FlagshipError(`Request timeout after ${timeout}ms`, FlagshipErrorCode.TIMEOUT_ERROR, error);
+			if (error instanceof FlagshipError) throw error;
+			throw new FlagshipError(`Network error: ${error}`, FlagshipErrorCode.NETWORK_ERROR, error);
+		}
+	}
+};
+/**
+* Merge `authToken` and `fetchOptions` into a single `RequestInit`.
+*
+* Precedence for the `Authorization` header (highest → lowest):
+* 1. An explicit `Authorization` value inside `fetchOptions.headers`
+* 2. A value derived from `authToken`
+*
+* All other `fetchOptions` fields are spread as-is.
+*/
+function buildFetchOptions(options) {
+	const { authToken, fetchOptions = {} } = options;
+	if (!authToken) return fetchOptions;
+	const existingHeaders = new Headers(fetchOptions.headers);
+	if (!existingHeaders.has("Authorization")) existingHeaders.set("Authorization", `Bearer ${authToken}`);
+	return {
+		...fetchOptions,
+		headers: existingHeaders
+	};
+}
+function resolveEndpoint(options) {
+	const { appId, endpoint, baseUrl, accountId } = options;
+	if (appId && endpoint) throw new Error("Flagship: provide either \"appId\" or \"endpoint\", not both");
+	if (!appId && !endpoint) throw new Error("Flagship: either \"appId\" or \"endpoint\" is required");
+	if (endpoint) {
+		try {
+			new URL(endpoint);
+		} catch {
+			throw new Error(`Flagship: invalid endpoint URL: ${endpoint}`);
+		}
+		return endpoint;
+	}
+	if (!accountId) throw new Error("Flagship: \"accountId\" is required when using \"appId\"");
+	const resolved = `${(baseUrl || "https://api.cloudflare.com").replace(/\/+$/, "")}/client/v4/accounts/${encodeURIComponent(accountId)}/flagship/apps/${encodeURIComponent(appId)}/evaluate`;
+	try {
+		new URL(resolved);
+	} catch {
+		throw new Error(`Flagship: resolved endpoint is not a valid URL: ${resolved}`);
+	}
+	return resolved;
+}
+//#endregion
+export { FlagshipErrorCode as a, FlagshipError as i, ContextTransformer as n, FLAGSHIP_DEFAULT_BASE_URL as r, FlagshipClient as t };