@barekey/sdk 0.1.2 → 0.2.0

package/src/public-client.ts

@@ -0,0 +1,231 @@
+import { VariableNotFoundError } from "./errors.js";
+import { BarekeyEnvHandle } from "./handle.js";
+import {
+  evaluateDefinition,
+  parseDeclaredValue,
+  validateDynamicOptions,
+} from "./internal/evaluate.js";
+import { postJson } from "./internal/http.js";
+import { MemoryCache } from "./internal/cache.js";
+import { validateRequirements } from "./internal/requirements.js";
+import {
+  resolvePublicRuntimeContext,
+  type BarekeyPublicRuntimeContext,
+} from "./internal/public-runtime.js";
+import { resolveTtlMilliseconds } from "./internal/ttl.js";
+import type {
+  BarekeyPublicGeneratedTypeMap,
+  BarekeyPublicKey,
+  BarekeyPublicKnownKey,
+  PublicBarekeyClientOptions,
+} from "./public-types.js";
+import type {
+  BarekeyEvaluatedValue,
+  BarekeyGetOptions,
+  BarekeyJsonConfig,
+  BarekeyVariableDefinition,
+} from "./types.js";
+
+type DefinitionsResponse = {
+  definitions: Array<BarekeyVariableDefinition>;
+};
+
+function createDefaultFetch(): typeof globalThis.fetch {
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+
+  return (async () => {
+    throw new Error("fetch is not available in this runtime.");
+  }) as typeof globalThis.fetch;
+}
+
+export class PublicBarekeyClient {
+  private readonly options: PublicBarekeyClientOptions;
+  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly definitionCache = new MemoryCache<BarekeyVariableDefinition>();
+  private readonly evaluationCache = new MemoryCache<BarekeyEvaluatedValue>();
+  private runtimeContextPromise: Promise<BarekeyPublicRuntimeContext> | null = null;
+  private requirementsPromise: Promise<void> | null = null;
+
+  constructor();
+  constructor(options: {
+    organization: string;
+    project: string;
+    environment: string;
+    requirements?: PublicBarekeyClientOptions["requirements"];
+    baseUrl?: string;
+  });
+  constructor(options: {
+    json: BarekeyJsonConfig;
+    requirements?: PublicBarekeyClientOptions["requirements"];
+    baseUrl?: string;
+  });
+  constructor(options: PublicBarekeyClientOptions = {}) {
+    this.options = options;
+    this.fetchFn = createDefaultFetch();
+  }
+
+  get<TKey extends BarekeyPublicKey>(
+    name: TKey,
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvHandle<
+    TKey extends BarekeyPublicKnownKey ? BarekeyPublicGeneratedTypeMap[TKey] : unknown
+  >;
+  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown> {
+    return new BarekeyEnvHandle(
+      async () => await this.resolveEvaluatedValue(name, options),
+    );
+  }
+
+  private async getRuntimeContext(): Promise<BarekeyPublicRuntimeContext> {
+    if (this.runtimeContextPromise === null) {
+      const runtimeContextPromise = resolvePublicRuntimeContext(this.options);
+      runtimeContextPromise.catch(() => {
+        if (this.runtimeContextPromise === runtimeContextPromise) {
+          this.runtimeContextPromise = null;
+        }
+      });
+      this.runtimeContextPromise = runtimeContextPromise;
+    }
+    return await this.runtimeContextPromise;
+  }
+
+  private buildDefinitionCacheKey(context: BarekeyPublicRuntimeContext, name: string): string {
+    return [context.organization, context.project, context.environment, name].join("|");
+  }
+
+  private buildEvaluationCacheKey(
+    context: BarekeyPublicRuntimeContext,
+    name: string,
+    options?: BarekeyGetOptions,
+  ): string {
+    return [
+      context.organization,
+      context.project,
+      context.environment,
+      name,
+      options?.seed ?? "",
+      options?.key ?? "",
+    ].join("|");
+  }
+
+  private async fetchDefinitions(names?: Array<string>): Promise<Array<BarekeyVariableDefinition>> {
+    const context = await this.getRuntimeContext();
+    const response = await postJson<DefinitionsResponse>({
+      fetchFn: this.fetchFn,
+      baseUrl: context.baseUrl,
+      path: "/v1/public/env/definitions",
+      payload: {
+        orgSlug: context.organization,
+        projectSlug: context.project,
+        stageSlug: context.environment,
+        ...(names === undefined ? {} : { names }),
+      },
+    });
+
+    for (const definition of response.definitions) {
+      this.definitionCache.set(this.buildDefinitionCacheKey(context, definition.name), definition);
+    }
+
+    return response.definitions;
+  }
+
+  private async ensureRequirementsValidated(): Promise<void> {
+    const context = await this.getRuntimeContext();
+    const requirements = context.requirements;
+    if (requirements === undefined) {
+      return;
+    }
+
+    if (this.requirementsPromise === null) {
+      const requirementsPromise = (async () => {
+        const definitions = await this.fetchDefinitions();
+        const values: Record<string, unknown> = {};
+        for (const definition of definitions) {
+          const evaluated = await evaluateDefinition(definition);
+          values[definition.name] = parseDeclaredValue(evaluated.value, evaluated.declaredType);
+        }
+        await validateRequirements(requirements, values);
+      })();
+      requirementsPromise.catch(() => {
+        if (this.requirementsPromise === requirementsPromise) {
+          this.requirementsPromise = null;
+        }
+      });
+      this.requirementsPromise = requirementsPromise;
+    }
+
+    await this.requirementsPromise;
+  }
+
+  private async getStaticDefinition(name: string): Promise<BarekeyVariableDefinition> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const cacheKey = this.buildDefinitionCacheKey(context, name);
+    const cached = this.definitionCache.get(cacheKey);
+    if (cached !== null) {
+      return cached;
+    }
+
+    const definitions = await this.fetchDefinitions([name]);
+    const resolved = definitions[0];
+    if (resolved === undefined) {
+      throw new VariableNotFoundError();
+    }
+    return resolved;
+  }
+
+  private async resolveStaticValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    const definition = await this.getStaticDefinition(name);
+    return await evaluateDefinition(definition, options);
+  }
+
+  private async resolveDynamicValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const cacheKey = this.buildEvaluationCacheKey(context, name, options);
+    const dynamic = options?.dynamic;
+    const dynamicTtlMs =
+      dynamic !== undefined && dynamic !== true
+        ? resolveTtlMilliseconds(dynamic.ttl, "dynamic.ttl")
+        : null;
+
+    if (dynamic !== true) {
+      const cached = this.evaluationCache.getRecord(cacheKey);
+      if (cached !== null && dynamicTtlMs !== null && Date.now() - cached.storedAtMs <= dynamicTtlMs) {
+        return cached.value;
+      }
+    }
+
+    const freshDefinitions = await this.fetchDefinitions([name]);
+    const freshDefinition = freshDefinitions[0];
+    if (freshDefinition === undefined) {
+      throw new VariableNotFoundError();
+    }
+    const resolved = await evaluateDefinition(freshDefinition, options);
+
+    if (dynamicTtlMs !== null) {
+      this.evaluationCache.set(cacheKey, resolved);
+    }
+
+    return resolved;
+  }
+
+  private async resolveEvaluatedValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    validateDynamicOptions(options);
+    if (options?.dynamic === undefined) {
+      return await this.resolveStaticValue(name, options);
+    }
+    return await this.resolveDynamicValue(name, options);
+  }
+}

package/src/public-types.ts

@@ -0,0 +1,63 @@
+export type {
+  AB,
+  BarekeyCoerceTarget,
+  BarekeyDeclaredType,
+  BarekeyDecision,
+  BarekeyErrorCode,
+  BarekeyEvaluatedValue,
+  BarekeyGetOptions,
+  BarekeyJsonConfig,
+  BarekeyResolvedKind,
+  BarekeyRolloutFunction,
+  BarekeyRolloutMatchedRule,
+  BarekeyRolloutMilestone,
+  BarekeyStandardSchemaPathSegment,
+  BarekeyStandardSchemaResult,
+  BarekeyStandardSchemaV1,
+  BarekeyTemporalInstant,
+  BarekeyTemporalInstantLike,
+  BarekeyTtlInput,
+  BarekeyTypegenResult,
+  BarekeyVariableDefinition,
+  EaseInOut,
+  Env,
+  Linear,
+  Secret,
+  Step,
+} from "./types.js";
+import type {
+  BarekeyJsonConfig,
+  BarekeyLiteralString,
+  BarekeyStandardSchemaV1,
+} from "./types.js";
+
+export interface BarekeyPublicGeneratedTypeMap {}
+
+export type BarekeyPublicKnownKey = Extract<keyof BarekeyPublicGeneratedTypeMap, string>;
+
+export type BarekeyPublicKey = BarekeyPublicKnownKey | BarekeyLiteralString;
+
+type BarekeyPublicBaseClientOptions = {
+  requirements?: BarekeyStandardSchemaV1;
+  baseUrl?: string;
+};
+
+export type PublicBarekeyClientOptions =
+  | (BarekeyPublicBaseClientOptions & {
+      organization: string;
+      project: string;
+      environment: string;
+      json?: never;
+    })
+  | (BarekeyPublicBaseClientOptions & {
+      json: BarekeyJsonConfig;
+      organization?: never;
+      project?: never;
+      environment?: never;
+    })
+  | (BarekeyPublicBaseClientOptions & {
+      organization?: never;
+      project?: never;
+      environment?: never;
+      json?: never;
+    });

package/src/public.ts

@@ -0,0 +1,71 @@
+export { PublicBarekeyClient } from "./public-client.js";
+export { BarekeyEnvHandle } from "./handle.js";
+export {
+  BarekeyError,
+  BillingUnavailableError,
+  CoerceFailedError,
+  DeviceCodeExpiredError,
+  DeviceCodeNotFoundError,
+  EvaluationFailedError,
+  FsNotAvailableError,
+  InvalidConfigurationProvidedError,
+  InvalidCredentialsProvidedError,
+  InvalidDynamicOptionsError,
+  InvalidJsonError,
+  InvalidOrgScopeError,
+  InvalidRefreshTokenError,
+  InvalidRequestError,
+  NetworkError,
+  NoConfigurationProvidedError,
+  NoCredentialsProvidedError,
+  OrgScopeInvalidError,
+  RequirementsValidationFailedError,
+  SdkModuleNotFoundError,
+  TemporalNotAvailableError,
+  TypegenReadFailedError,
+  TypegenUnsupportedSdkError,
+  TypegenWriteFailedError,
+  UnauthorizedError,
+  UnknownError,
+  UsageLimitExceededError,
+  UserCodeInvalidError,
+  VariableNotFoundError,
+  createBarekeyErrorFromCode,
+  docsUrlForErrorCode,
+  formatBarekeyErrorMessage,
+  isBarekeyErrorCode,
+  normalizeErrorCode,
+} from "./errors.js";
+
+export type {
+  AB,
+  BarekeyCoerceTarget,
+  BarekeyDeclaredType,
+  BarekeyDecision,
+  BarekeyErrorCode,
+  BarekeyEvaluatedValue,
+  BarekeyGetOptions,
+  BarekeyJsonConfig,
+  BarekeyLiteralString,
+  BarekeyResolvedKind,
+  BarekeyRolloutFunction,
+  BarekeyRolloutMatchedRule,
+  BarekeyRolloutMilestone,
+  BarekeyStandardSchemaV1,
+  BarekeyTemporalInstant,
+  BarekeyTemporalInstantLike,
+  BarekeyTtlInput,
+  BarekeyVariableDefinition,
+  EaseInOut,
+  Env,
+  Linear,
+  Secret,
+  Step,
+} from "./types.js";
+
+export type {
+  BarekeyPublicGeneratedTypeMap,
+  BarekeyPublicKey,
+  BarekeyPublicKnownKey,
+  PublicBarekeyClientOptions,
+} from "./public-types.js";

package/src/server.ts

@@ -0,0 +1,62 @@
+export { BarekeyClient } from "./client.js";
+export { BarekeyEnvHandle } from "./handle.js";
+export {
+  BarekeyError,
+  BillingUnavailableError,
+  CoerceFailedError,
+  DeviceCodeExpiredError,
+  DeviceCodeNotFoundError,
+  EvaluationFailedError,
+  FsNotAvailableError,
+  InvalidConfigurationProvidedError,
+  InvalidCredentialsProvidedError,
+  InvalidDynamicOptionsError,
+  InvalidJsonError,
+  InvalidOrgScopeError,
+  InvalidRefreshTokenError,
+  InvalidRequestError,
+  NetworkError,
+  NoConfigurationProvidedError,
+  NoCredentialsProvidedError,
+  OrgScopeInvalidError,
+  RequirementsValidationFailedError,
+  SdkModuleNotFoundError,
+  TemporalNotAvailableError,
+  TypegenReadFailedError,
+  TypegenUnsupportedSdkError,
+  TypegenWriteFailedError,
+  UnauthorizedError,
+  UnknownError,
+  UsageLimitExceededError,
+  UserCodeInvalidError,
+  VariableNotFoundError,
+  createBarekeyErrorFromCode,
+  docsUrlForErrorCode,
+  formatBarekeyErrorMessage,
+  isBarekeyErrorCode,
+  normalizeErrorCode,
+} from "./errors.js";
+
+export type {
+  AB,
+  BarekeyClientOptions,
+  BarekeyCoerceTarget,
+  BarekeyDeclaredType,
+  BarekeyErrorCode,
+  BarekeyGeneratedTypeMap,
+  BarekeyGetOptions,
+  BarekeyJsonConfig,
+  BarekeyKey,
+  BarekeyLiteralString,
+  BarekeyKnownKey,
+  BarekeyResolvedKind,
+  BarekeyRolloutMilestone,
+  BarekeyStandardSchemaV1,
+  BarekeyTemporalInstant,
+  BarekeyTemporalInstantLike,
+  BarekeyTtlInput,
+  BarekeyTypegenResult,
+  Env,
+  Linear,
+  Secret,
+} from "./types.js";

package/src/types.ts

@@ -45,10 +45,11 @@ export type EaseInOut<
   readonly milestones: TMilestones;
 };
 
-export type Env<TMode, TValue, TFunction = never> = TValue & {
+export type Env<TMode, TValue, TFunction = never, V = never> = TValue & {
   readonly __barekey?: {
     readonly mode: TMode;
     readonly function: TFunction;
+    readonly visibility: V;
   };
 };
 
@@ -58,6 +59,10 @@ export interface BarekeyGeneratedTypeMap {}
 
 export type BarekeyKnownKey = Extract<keyof BarekeyGeneratedTypeMap, string>;
 
+export type BarekeyLiteralString = string & {};
+
+export type BarekeyKey = BarekeyKnownKey | BarekeyLiteralString;
+
 export type BarekeyRolloutMilestone = {
   at: string;
   percentage: number;
@@ -160,6 +165,8 @@ type BarekeyBaseClientOptions = {
 export type BarekeyTypegenResult = {
   written: boolean;
   path: string;
+  serverPath: string;
+  publicPath: string;
   manifestVersion: string;
 };
 

package/generated.d.ts

@@ -1,16 +0,0 @@
-/* eslint-disable */
-/* This file is generated by barekey typegen. */
-/* barekey-manifest-version: REnQvc_83Zn-Xs-tvl2fA375JUy3Jp1IOIoYFB8y-74 */
-
-import type { AB, Env, Linear, Secret } from "./dist/types.js";
-
-declare module "./dist/types.js" {
-  interface BarekeyGeneratedTypeMap {
-    "CODEX_TEST_SECRET": Env<Secret, string>;
-    "DATABASE_URL": Env<Secret, string>;
-    "foo": Env<Secret, string>;
-    "JSON_DEEP": Env<Secret, { bar: boolean; foo: string; nested: { count: number; flags: Array<boolean>; meta: { label: string; }; }; }>;
-  }
-}
-
-export {};