@barekey/sdk 0.1.0

package/src/internal/evaluate.ts

@@ -0,0 +1,232 @@
+import {
+  CoerceFailedError,
+  parseBigIntOrThrow,
+  parseBooleanOrThrow,
+  parseDateOrThrow,
+  parseFloatOrThrow,
+  parseJsonOrThrow,
+} from "../errors.js";
+import { resolveTtlMilliseconds } from "./ttl.js";
+import type {
+  BarekeyCoerceTarget,
+  BarekeyDeclaredType,
+  BarekeyDecision,
+  BarekeyEvaluatedValue,
+  BarekeyGetOptions,
+  BarekeyRolloutMilestone,
+  BarekeyVariableDefinition,
+} from "../types.js";
+
+function parseRolloutInstant(value: string): number {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) {
+    throw new CoerceFailedError({
+      message: `Invalid Barekey rollout milestone instant "${value}".`,
+    });
+  }
+  return parsed;
+}
+
+function normalizeRolloutMilestones(
+  value: Array<BarekeyRolloutMilestone>,
+): Array<BarekeyRolloutMilestone> {
+  if (value.length === 0) {
+    throw new CoerceFailedError({
+      message: "Rollout milestones must contain at least one entry.",
+    });
+  }
+
+  let previousAtMs = -Infinity;
+  return value.map((milestone) => {
+    if (
+      !Number.isFinite(milestone.percentage) ||
+      milestone.percentage < 0 ||
+      milestone.percentage > 100
+    ) {
+      throw new CoerceFailedError({
+        message: "Rollout milestone percentages must be between 0 and 100.",
+      });
+    }
+
+    const atMs = parseRolloutInstant(milestone.at);
+    if (atMs <= previousAtMs) {
+      throw new CoerceFailedError({
+        message: "Rollout milestones must be strictly increasing by time.",
+      });
+    }
+    previousAtMs = atMs;
+
+    return {
+      at: new Date(atMs).toISOString(),
+      percentage: milestone.percentage,
+    };
+  });
+}
+
+export function validateDynamicOptions(options?: BarekeyGetOptions): void {
+  if (options?.dynamic === undefined || options.dynamic === true) {
+    return;
+  }
+  resolveTtlMilliseconds(options.dynamic.ttl, "dynamic.ttl");
+}
+
+async function deterministicBucket(input: string): Promise<number> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  const value =
+    ((bytes[0] ?? 0) << 24) | ((bytes[1] ?? 0) << 16) | ((bytes[2] ?? 0) << 8) | (bytes[3] ?? 0);
+  return (value >>> 0) / 4294967296;
+}
+
+function resolveLinearRolloutChance(input: {
+  milestones: Array<BarekeyRolloutMilestone>;
+  nowMs: number;
+}): number {
+  const milestones = normalizeRolloutMilestones(input.milestones);
+  const first = milestones[0];
+  if (first === undefined) {
+    return 0;
+  }
+
+  if (input.nowMs < parseRolloutInstant(first.at)) {
+    return 0;
+  }
+
+  for (let index = 0; index < milestones.length - 1; index += 1) {
+    const current = milestones[index];
+    const next = milestones[index + 1];
+    if (current === undefined || next === undefined) {
+      continue;
+    }
+
+    const currentAtMs = parseRolloutInstant(current.at);
+    const nextAtMs = parseRolloutInstant(next.at);
+    if (input.nowMs >= currentAtMs && input.nowMs < nextAtMs) {
+      const progress = (input.nowMs - currentAtMs) / (nextAtMs - currentAtMs);
+      const percentage = current.percentage + (next.percentage - current.percentage) * progress;
+      return percentage / 100;
+    }
+  }
+
+  const last = milestones[milestones.length - 1];
+  return last === undefined ? 0 : last.percentage / 100;
+}
+
+export async function evaluateDefinition(
+  definition: BarekeyVariableDefinition,
+  options?: Pick<BarekeyGetOptions, "seed" | "key">,
+): Promise<BarekeyEvaluatedValue> {
+  if (definition.kind === "secret") {
+    return {
+      name: definition.name,
+      kind: definition.kind,
+      declaredType: definition.declaredType,
+      value: definition.value,
+    };
+  }
+
+  const seed = options?.seed?.trim() ?? "";
+  const key = options?.key?.trim() ?? "";
+  const bucket =
+    seed.length > 0 || key.length > 0
+      ? await deterministicBucket(`${definition.kind}:${definition.name}:${seed}:${key}`)
+      : Math.random();
+
+  if (definition.kind === "ab_roll") {
+    const selectedArm = bucket < definition.chance ? "A" : "B";
+    return {
+      name: definition.name,
+      kind: definition.kind,
+      declaredType: definition.declaredType,
+      value: selectedArm === "A" ? definition.valueA : definition.valueB,
+      selectedArm,
+      decision: {
+        bucket,
+        chance: definition.chance,
+        seed: seed.length > 0 ? seed : undefined,
+        key: key.length > 0 ? key : undefined,
+        matchedRule: "ab_roll",
+      },
+    };
+  }
+
+  const chance = resolveLinearRolloutChance({
+    milestones: definition.rolloutMilestones,
+    nowMs: Date.now(),
+  });
+  const selectedArm = bucket < chance ? "B" : "A";
+  return {
+    name: definition.name,
+    kind: definition.kind,
+    declaredType: definition.declaredType,
+    value: selectedArm === "A" ? definition.valueA : definition.valueB,
+    selectedArm,
+    decision: {
+      bucket,
+      chance,
+      seed: seed.length > 0 ? seed : undefined,
+      key: key.length > 0 ? key : undefined,
+      matchedRule: "linear_rollout",
+    },
+  };
+}
+
+export function inferSelectedArmFromDecision(decision?: BarekeyDecision): "A" | "B" | undefined {
+  if (decision === undefined) {
+    return undefined;
+  }
+  if (decision.matchedRule === "ab_roll") {
+    return decision.bucket < decision.chance ? "A" : "B";
+  }
+  return decision.bucket < decision.chance ? "B" : "A";
+}
+
+export function parseDeclaredValue(value: string, declaredType: BarekeyDeclaredType): unknown {
+  if (declaredType === "string") {
+    return value;
+  }
+  if (declaredType === "boolean") {
+    return parseBooleanOrThrow(value);
+  }
+  if (declaredType === "int64") {
+    return parseBigIntOrThrow(value);
+  }
+  if (declaredType === "float") {
+    return parseFloatOrThrow(value);
+  }
+  if (declaredType === "date") {
+    return parseDateOrThrow(value);
+  }
+  return parseJsonOrThrow(value);
+}
+
+export function coerceEvaluatedValue(
+  resolved: BarekeyEvaluatedValue,
+  target: BarekeyCoerceTarget,
+): unknown {
+  if (target === "string") {
+    return resolved.value;
+  }
+
+  if (target === "boolean" && resolved.selectedArm !== undefined) {
+    return resolved.selectedArm === "B";
+  }
+
+  if (target === "boolean") {
+    return parseBooleanOrThrow(resolved.value);
+  }
+
+  if (target === "int64") {
+    return parseBigIntOrThrow(resolved.value);
+  }
+
+  if (target === "float") {
+    return parseFloatOrThrow(resolved.value);
+  }
+
+  if (target === "date") {
+    return parseDateOrThrow(resolved.value);
+  }
+
+  return parseJsonOrThrow(resolved.value);
+}

package/src/internal/http.ts

@@ -0,0 +1,134 @@
+import { NetworkError, UnauthorizedError, createBarekeyErrorFromCode } from "../errors.js";
+
+type ApiErrorPayload = {
+  error?: {
+    code?: string;
+    message?: string;
+    requestId?: string;
+  };
+} | null;
+
+export type InternalAuthResolver = {
+  getAccessToken(): Promise<string>;
+  onUnauthorized?(): Promise<void>;
+};
+
+async function parseJsonResponse(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/$/, "");
+}
+
+async function requestJson<TResponse>(input: {
+  fetchFn: typeof globalThis.fetch;
+  baseUrl: string;
+  path: string;
+  method: "GET" | "POST";
+  payload?: unknown;
+  auth?: InternalAuthResolver;
+}): Promise<TResponse> {
+  const makeRequest = async (accessToken?: string): Promise<Response> =>
+    input.fetchFn(`${normalizeBaseUrl(input.baseUrl)}${input.path}`, {
+      method: input.method,
+      headers: {
+        ...(input.method === "POST"
+          ? {
+              "content-type": "application/json",
+            }
+          : {}),
+        ...(accessToken
+          ? {
+              authorization: `Bearer ${accessToken}`,
+            }
+          : {}),
+      },
+      ...(input.method === "POST"
+        ? {
+            body: JSON.stringify(input.payload),
+          }
+        : {}),
+    });
+
+  const accessToken = input.auth ? await input.auth.getAccessToken() : undefined;
+  let response: Response;
+  try {
+    response = await makeRequest(accessToken);
+  } catch (error: unknown) {
+    throw new NetworkError({
+      message: error instanceof Error ? error.message : "A Barekey network request failed.",
+      cause: error,
+    });
+  }
+
+  if (response.status === 401 && input.auth?.onUnauthorized) {
+    await input.auth.onUnauthorized();
+    const retryAccessToken = await input.auth.getAccessToken();
+    try {
+      response = await makeRequest(retryAccessToken);
+    } catch (error: unknown) {
+      throw new NetworkError({
+        message: error instanceof Error ? error.message : "A Barekey network request failed.",
+        cause: error,
+      });
+    }
+  }
+
+  const parsed = (await parseJsonResponse(response)) as ApiErrorPayload | TResponse;
+  if (!response.ok) {
+    const parsedError = parsed as ApiErrorPayload;
+    const code =
+      parsedError?.error?.code ?? (response.status === 401 ? "UNAUTHORIZED" : "UNKNOWN_ERROR");
+    const message =
+      parsedError?.error?.message ??
+      (response.status === 401
+        ? "The provided Barekey credentials were rejected."
+        : `Barekey request failed with status ${response.status}.`);
+
+    if (response.status === 401 && code === "UNAUTHORIZED" && !parsedError?.error?.message) {
+      throw new UnauthorizedError({
+        requestId: parsedError?.error?.requestId ?? null,
+        status: response.status,
+      });
+    }
+
+    throw createBarekeyErrorFromCode({
+      code,
+      message,
+      requestId: parsedError?.error?.requestId ?? null,
+      status: response.status,
+    });
+  }
+
+  return parsed as TResponse;
+}
+
+export async function postJson<TResponse>(input: {
+  fetchFn: typeof globalThis.fetch;
+  baseUrl: string;
+  path: string;
+  payload: unknown;
+  auth?: InternalAuthResolver;
+}): Promise<TResponse> {
+  return await requestJson({
+    ...input,
+    method: "POST",
+  });
+}
+
+export async function getJson<TResponse>(input: {
+  fetchFn: typeof globalThis.fetch;
+  baseUrl: string;
+  path: string;
+  auth?: InternalAuthResolver;
+}): Promise<TResponse> {
+  return await requestJson({
+    ...input,
+    method: "GET",
+  });
+}