@barekey/sdk 0.1.0

package/src/internal/runtime.ts

@@ -0,0 +1,199 @@
+import {
+  FsNotAvailableError,
+  InvalidConfigurationProvidedError,
+  InvalidCredentialsProvidedError,
+  InvalidRefreshTokenError,
+  NoConfigurationProvidedError,
+  NoCredentialsProvidedError,
+  UnauthorizedError,
+} from "../errors.js";
+import type { BarekeyClientOptions, BarekeyJsonConfig, BarekeyStandardSchemaV1 } from "../types.js";
+import { type InternalAuthResolver, normalizeBaseUrl } from "./http.js";
+import {
+  isFilesystemAvailable,
+  loadBarekeyJsonConfig,
+  loadCliSessionAuthResolver,
+} from "./node-runtime.js";
+
+const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";
+
+type BarekeyResolvedScope = {
+  organization: string;
+  project: string;
+  environment: string;
+};
+
+export type BarekeyRuntimeContext = BarekeyResolvedScope & {
+  baseUrl: string;
+  auth: InternalAuthResolver;
+  requirements?: BarekeyStandardSchemaV1;
+};
+
+function readProcessEnv(key: string): string | undefined {
+  if (typeof process === "undefined" || typeof process.env !== "object" || process.env === null) {
+    return undefined;
+  }
+
+  const value = process.env[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readConfigString(value: unknown): string | undefined {
+  return typeof value === "string" ? value.trim() : undefined;
+}
+
+function normalizeScope(input: {
+  organization?: unknown;
+  project?: unknown;
+  environment?: unknown;
+  source: string;
+}): BarekeyResolvedScope {
+  const organization = readConfigString(input.organization) ?? "";
+  const project = readConfigString(input.project) ?? "";
+  const environment = readConfigString(input.environment) ?? "";
+  if (organization.length === 0 || project.length === 0 || environment.length === 0) {
+    throw new InvalidConfigurationProvidedError({
+      message: `${input.source} must provide organization, project, and environment.`,
+    });
+  }
+
+  return {
+    organization,
+    project,
+    environment,
+  };
+}
+
+function normalizeJsonConfig(
+  input: BarekeyJsonConfig | Record<string, unknown>,
+  source: string,
+): BarekeyResolvedScope {
+  return normalizeScope({
+    organization: input.organization ?? input.org,
+    project: input.project,
+    environment: input.environment ?? input.stage,
+    source,
+  });
+}
+
+async function resolveScope(options: BarekeyClientOptions): Promise<BarekeyResolvedScope> {
+  const explicitOrganization = "organization" in options ? options.organization : undefined;
+  const explicitProject = "project" in options ? options.project : undefined;
+  const explicitEnvironment = "environment" in options ? options.environment : undefined;
+  const explicitJson = "json" in options ? options.json : undefined;
+
+  const explicitCount =
+    Number(explicitOrganization !== undefined) +
+    Number(explicitProject !== undefined) +
+    Number(explicitEnvironment !== undefined);
+
+  if (explicitJson !== undefined && explicitCount > 0) {
+    throw new InvalidConfigurationProvidedError({
+      message: "Pass either json or organization/project/environment, not both.",
+    });
+  }
+
+  if (explicitCount > 0 && explicitCount < 3) {
+    throw new InvalidConfigurationProvidedError({
+      message: "organization, project, and environment must be provided together.",
+    });
+  }
+
+  if (explicitJson !== undefined) {
+    return normalizeJsonConfig(explicitJson, "The provided json configuration");
+  }
+
+  if (explicitCount === 3) {
+    return normalizeScope({
+      organization: explicitOrganization,
+      project: explicitProject,
+      environment: explicitEnvironment,
+      source: "The provided Barekey configuration",
+    });
+  }
+
+  const loadedConfig = await loadBarekeyJsonConfig();
+  if (loadedConfig === null) {
+    if (!(await isFilesystemAvailable())) {
+      throw new FsNotAvailableError();
+    }
+    throw new NoConfigurationProvidedError({
+      message: "No Barekey configuration was found and no barekey.json file could be loaded.",
+    });
+  }
+
+  return normalizeJsonConfig(
+    loadedConfig.json,
+    `The barekey.json file at ${loadedConfig.path}`,
+  );
+}
+
+async function resolveAuth(fetchFn: typeof globalThis.fetch): Promise<{
+  baseUrl: string;
+  auth: InternalAuthResolver;
+}> {
+  const envToken = readProcessEnv("BAREKEY_ACCESS_TOKEN");
+  if (envToken !== undefined) {
+    const normalizedToken = envToken.trim();
+    if (normalizedToken.length === 0) {
+      throw new InvalidCredentialsProvidedError({
+        message: "BAREKEY_ACCESS_TOKEN was provided but is empty.",
+      });
+    }
+
+    const envBaseUrl = readProcessEnv("BAREKEY_API_URL")?.trim();
+    return {
+      baseUrl: normalizeBaseUrl(
+        envBaseUrl && envBaseUrl.length > 0 ? envBaseUrl : DEFAULT_BAREKEY_API_URL,
+      ),
+      auth: {
+        async getAccessToken(): Promise<string> {
+          return normalizedToken;
+        },
+      },
+    };
+  }
+
+  const cliSession = await loadCliSessionAuthResolver(fetchFn);
+  if (cliSession === null) {
+    if (!(await isFilesystemAvailable())) {
+      throw new FsNotAvailableError();
+    }
+    throw new NoCredentialsProvidedError();
+  }
+
+  return {
+    baseUrl: normalizeBaseUrl(cliSession.baseUrl),
+    auth: {
+      async getAccessToken(): Promise<string> {
+        try {
+          return await cliSession.getAccessToken();
+        } catch (error: unknown) {
+          if (error instanceof InvalidRefreshTokenError || error instanceof UnauthorizedError) {
+            throw new InvalidCredentialsProvidedError({
+              message: "Stored Barekey CLI credentials are no longer valid.",
+              cause: error,
+            });
+          }
+          throw error;
+        }
+      },
+      async onUnauthorized(): Promise<void> {
+        await cliSession.onUnauthorized();
+      },
+    },
+  };
+}
+
+export async function resolveRuntimeContext(
+  options: BarekeyClientOptions,
+  fetchFn: typeof globalThis.fetch,
+): Promise<BarekeyRuntimeContext> {
+  const [scope, auth] = await Promise.all([resolveScope(options), resolveAuth(fetchFn)]);
+  return {
+    ...scope,
+    baseUrl: auth.baseUrl,
+    auth: auth.auth,
+    requirements: options.requirements,
+  };
+}

package/src/internal/ttl.ts

@@ -0,0 +1,41 @@
+import { InvalidDynamicOptionsError } from "../errors.js";
+import type { BarekeyTemporalInstantLike, BarekeyTtlInput } from "../types.js";
+
+export const DEFAULT_TYPEGEN_TTL_MS = 30_000;
+
+function buildTtlError(label: string) {
+  return new InvalidDynamicOptionsError({
+    message: `${label} must be a positive integer number of milliseconds, a future Date, or a future Temporal instant.`,
+  });
+}
+
+function isTemporalInstantLike(value: unknown): value is BarekeyTemporalInstantLike {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { epochMilliseconds?: unknown }).epochMilliseconds === "number"
+  );
+}
+
+function normalizePositiveMilliseconds(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0 || !Number.isInteger(value)) {
+    throw buildTtlError(label);
+  }
+  return value;
+}
+
+export function resolveTtlMilliseconds(value: BarekeyTtlInput, label: string): number {
+  if (typeof value === "number") {
+    return normalizePositiveMilliseconds(value, label);
+  }
+
+  if (value instanceof Date) {
+    return normalizePositiveMilliseconds(value.getTime() - Date.now(), label);
+  }
+
+  if (isTemporalInstantLike(value)) {
+    return normalizePositiveMilliseconds(value.epochMilliseconds - Date.now(), label);
+  }
+
+  throw buildTtlError(label);
+}

package/src/internal/typegen.ts

@@ -0,0 +1,124 @@
+import {
+  readTextFile,
+  resolveInstalledSdkTypegenTarget,
+  writeTextFileAtomic,
+} from "./node-runtime.js";
+import type { BarekeyRolloutMilestone, BarekeyTypegenResult } from "../types.js";
+
+export type TypegenManifestVariable = {
+  name: string;
+  kind: "secret" | "ab_roll" | "rollout";
+  declaredType: "string" | "boolean" | "int64" | "float" | "date" | "json";
+  required: boolean;
+  updatedAtMs: number;
+  typeScriptType: string;
+  valueATypeScriptType: string | null;
+  valueBTypeScriptType: string | null;
+  rolloutFunction: "linear" | null;
+  rolloutMilestones: Array<BarekeyRolloutMilestone> | null;
+};
+
+export type TypegenManifest = {
+  orgId: string;
+  orgSlug: string;
+  projectSlug: string;
+  stageSlug: string;
+  generatedAtMs: number;
+  manifestVersion: string;
+  variables: Array<TypegenManifestVariable>;
+};
+
+const MANIFEST_VERSION_PATTERN = /\/\* barekey-manifest-version: ([^\n]+) \*\//;
+
+function renderLinearMilestones(milestones: Array<BarekeyRolloutMilestone>): string {
+  if (milestones.length === 0) {
+    return "readonly []";
+  }
+
+  return `readonly [${milestones
+    .map(
+      (milestone) =>
+        `readonly [${JSON.stringify(milestone.at)}, ${String(milestone.percentage)}]`,
+    )
+    .join(", ")}]`;
+}
+
+function renderVariableType(row: TypegenManifestVariable): string {
+  if (row.kind === "secret") {
+    return `Env<Secret, ${row.typeScriptType}>`;
+  }
+
+  if (row.kind === "ab_roll") {
+    return `Env<AB, ${row.typeScriptType}>`;
+  }
+
+  return `Env<AB, ${row.typeScriptType}, Linear<${renderLinearMilestones(
+    row.rolloutMilestones ?? [],
+  )}>>`;
+}
+
+function buildGeneratedTypesContents(manifest: TypegenManifest): string {
+  const mapLines = manifest.variables
+    .slice()
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((row) => `    ${JSON.stringify(row.name)}: ${renderVariableType(row)};`)
+    .join("\n");
+
+  return `/* eslint-disable */
+/* This file is generated by barekey typegen. */
+/* barekey-manifest-version: ${manifest.manifestVersion} */
+
+import type { AB, Env, Linear, Secret } from "./dist/types.js";
+
+declare module "./dist/types.js" {
+  interface BarekeyGeneratedTypeMap {
+${mapLines.length > 0 ? mapLines : ""}
+  }
+}
+
+export {};
+`;
+}
+
+function readManifestVersion(contents: string | null): string | null {
+  if (contents === null) {
+    return null;
+  }
+
+  const match = contents.match(MANIFEST_VERSION_PATTERN);
+  return match?.[1]?.trim() ?? null;
+}
+
+export async function resolveInstalledSdkGeneratedTypesPath(): Promise<string | null> {
+  const target = await resolveInstalledSdkTypegenTarget();
+  return target?.generatedTypesPath ?? null;
+}
+
+export async function writeInstalledSdkGeneratedTypes(
+  manifest: TypegenManifest,
+): Promise<BarekeyTypegenResult> {
+  const target = await resolveInstalledSdkTypegenTarget();
+  if (target === null) {
+    return {
+      written: false,
+      path: "",
+      manifestVersion: manifest.manifestVersion,
+    };
+  }
+
+  const existingContents = await readTextFile(target.generatedTypesPath);
+  if (readManifestVersion(existingContents) === manifest.manifestVersion) {
+    return {
+      written: false,
+      path: target.generatedTypesPath,
+      manifestVersion: manifest.manifestVersion,
+    };
+  }
+
+  await writeTextFileAtomic(target.generatedTypesPath, buildGeneratedTypesContents(manifest));
+  return {
+    written: true,
+    path: target.generatedTypesPath,
+    manifestVersion: manifest.manifestVersion,
+  };
+}

package/src/types.ts

@@ -0,0 +1,189 @@
+export type BarekeyResolvedKind = "secret" | "ab_roll" | "rollout";
+
+export type BarekeyDeclaredType = "string" | "boolean" | "int64" | "float" | "date" | "json";
+
+export type BarekeyTemporalInstant = {
+  readonly epochMilliseconds: number;
+  toJSON(): string;
+  toString(): string;
+};
+
+export type BarekeyTemporalInstantLike = {
+  readonly epochMilliseconds: number;
+};
+
+export type BarekeyTtlInput = number | Date | BarekeyTemporalInstantLike;
+
+export type Secret = "secret";
+
+export type AB = "ab";
+
+export type Linear<
+  TMilestones extends ReadonlyArray<readonly [string, number]> = ReadonlyArray<
+    readonly [string, number]
+  >,
+> = {
+  readonly kind: "linear";
+  readonly milestones: TMilestones;
+};
+
+export type Env<TMode, TValue, TFunction = never> = TValue & {
+  readonly __barekey?: {
+    readonly mode: TMode;
+    readonly function: TFunction;
+  };
+};
+
+export type BarekeyCoerceTarget = "string" | "boolean" | "int64" | "float" | "date" | "json";
+
+export interface BarekeyGeneratedTypeMap {}
+
+export type BarekeyKnownKey = Extract<keyof BarekeyGeneratedTypeMap, string>;
+
+export type BarekeyRolloutMilestone = {
+  at: string;
+  percentage: number;
+};
+
+export type BarekeyDecision = {
+  bucket: number;
+  chance: number;
+  seed?: string;
+  key?: string;
+  matchedRule: "ab_roll" | "linear_rollout";
+};
+
+export type BarekeyEvaluatedValue = {
+  name: string;
+  kind: BarekeyResolvedKind;
+  declaredType: BarekeyDeclaredType;
+  value: string;
+  decision?: BarekeyDecision;
+  selectedArm?: "A" | "B";
+};
+
+export type BarekeyVariableDefinition =
+  | {
+      name: string;
+      kind: "secret";
+      declaredType: BarekeyDeclaredType;
+      value: string;
+    }
+  | {
+      name: string;
+      kind: "ab_roll";
+      declaredType: BarekeyDeclaredType;
+      valueA: string;
+      valueB: string;
+      chance: number;
+    }
+  | {
+      name: string;
+      kind: "rollout";
+      declaredType: BarekeyDeclaredType;
+      valueA: string;
+      valueB: string;
+      rolloutFunction: "linear";
+      rolloutMilestones: Array<BarekeyRolloutMilestone>;
+    };
+
+export type BarekeyGetOptions = {
+  dynamic?: true | { ttl: BarekeyTtlInput };
+  seed?: string;
+  key?: string;
+};
+
+export type BarekeyJsonConfig = {
+  organization?: string;
+  project?: string;
+  environment?: string;
+  org?: string;
+  stage?: string;
+};
+
+export type BarekeyStandardSchemaResult =
+  | {
+      value: unknown;
+      issues?: undefined;
+    }
+  | {
+      issues: ReadonlyArray<{
+        message?: string;
+        path?: ReadonlyArray<BarekeyStandardSchemaPathSegment>;
+      }>;
+      value?: undefined;
+    };
+
+export type BarekeyStandardSchemaPathSegment =
+  | PropertyKey
+  | {
+      key: PropertyKey;
+    };
+
+export type BarekeyStandardSchemaV1 = {
+  readonly ["~standard"]?: {
+    readonly version?: number;
+    validate(value: unknown): BarekeyStandardSchemaResult | Promise<BarekeyStandardSchemaResult>;
+  };
+};
+
+type BarekeyBaseClientOptions = {
+  requirements?: BarekeyStandardSchemaV1;
+  typegen?: false | { ttl?: BarekeyTtlInput };
+};
+
+export type BarekeyTypegenResult = {
+  written: boolean;
+  path: string;
+  manifestVersion: string;
+};
+
+export type BarekeyClientOptions =
+  | (BarekeyBaseClientOptions & {
+      organization: string;
+      project: string;
+      environment: string;
+      json?: never;
+    })
+  | (BarekeyBaseClientOptions & {
+      json: BarekeyJsonConfig;
+      organization?: never;
+      project?: never;
+      environment?: never;
+    })
+  | (BarekeyBaseClientOptions & {
+      organization?: never;
+      project?: never;
+      environment?: never;
+      json?: never;
+    });
+
+export type BarekeyErrorCode =
+  | "FS_NOT_AVAILABLE"
+  | "NO_CONFIGURATION_PROVIDED"
+  | "INVALID_CONFIGURATION_PROVIDED"
+  | "NO_CREDENTIALS_PROVIDED"
+  | "INVALID_CREDENTIALS_PROVIDED"
+  | "INVALID_DYNAMIC_OPTIONS"
+  | "REQUIREMENTS_VALIDATION_FAILED"
+  | "NETWORK_ERROR"
+  | "COERCE_FAILED"
+  | "TEMPORAL_NOT_AVAILABLE"
+  | "SDK_MODULE_NOT_FOUND"
+  | "TYPEGEN_UNSUPPORTED_SDK"
+  | "TYPEGEN_READ_FAILED"
+  | "TYPEGEN_WRITE_FAILED"
+  | "UNAUTHORIZED"
+  | "INVALID_ORG_SCOPE"
+  | "ORG_SCOPE_INVALID"
+  | "INVALID_JSON"
+  | "INVALID_REQUEST"
+  | "VARIABLE_NOT_FOUND"
+  | "EVALUATION_FAILED"
+  | "USAGE_LIMIT_EXCEEDED"
+  | "BILLING_UNAVAILABLE"
+  | "DEVICE_CODE_NOT_FOUND"
+  | "DEVICE_CODE_EXPIRED"
+  | "USER_CODE_INVALID"
+  | "INVALID_REFRESH_TOKEN"
+  | "UNKNOWN_ERROR";