@barekey/sdk 0.1.2 → 0.1.3

package/{generated.d.ts → generated.server.d.ts}

@@ -1,6 +1,5 @@
 /* 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";
 
@@ -9,7 +8,14 @@ declare module "./dist/types.js" {
     "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; }; }; }>;
+    "JSON_DEEP": Env<
+      Secret,
+      {
+        bar: boolean;
+        foo: string;
+        nested: { count: number; flags: Array<boolean>; meta: { label: string } };
+      }
+    >;
   }
 }
 

package/index.d.ts

@@ -1,2 +1 @@
 export * from "./dist/index.js";
-import "./generated";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barekey/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Barekey TypeScript SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,18 +11,33 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./public": {
+      "types": "./public.d.ts",
+      "import": "./dist/public.js",
+      "default": "./dist/public.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "generated.d.ts",
+    "generated.public.d.ts",
+    "generated.server.d.ts",
     "index.d.ts",
+    "public.d.ts",
+    "server.d.ts",
     "src"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test test"
   },
+  "packageManager": "bun@1.2.22",
   "devDependencies": {
     "@types/node": "^24.10.1",
     "typescript": "^5.9.3"

package/public.d.ts

@@ -0,0 +1,2 @@
+export * from "./dist/public.js";
+import "./generated.public";

package/server.d.ts

@@ -0,0 +1,2 @@
+export * from "./dist/server.js";
+import "./generated.server";

package/src/index.ts

@@ -1,4 +1,5 @@
 export { BarekeyClient } from "./client.js";
+export { PublicBarekeyClient } from "./public-client.js";
 export { BarekeyEnvHandle } from "./handle.js";
 export {
   BarekeyError,
@@ -58,3 +59,9 @@ export type {
   Linear,
   Secret,
 } from "./types.js";
+
+export type {
+  BarekeyPublicGeneratedTypeMap,
+  BarekeyPublicKnownKey,
+  PublicBarekeyClientOptions,
+} from "./public-types.js";

package/src/internal/node-runtime.ts

@@ -476,7 +476,8 @@ function isMissingModuleError(error: unknown): boolean {
 
 type InstalledSdkTypegenTarget = {
   packageRoot: string;
-  generatedTypesPath: string;
+  serverGeneratedTypesPath: string;
+  publicGeneratedTypesPath: string;
   typegenMetadataPath: string;
 };
 
@@ -508,19 +509,22 @@ export async function resolveInstalledSdkTypegenTarget(): Promise<InstalledSdkTy
     const candidatePackageJson = runtime.path.join(current, "package.json");
     const rawPackageJson = await readJsonFile<Record<string, unknown>>(runtime, candidatePackageJson);
     if (rawPackageJson !== null && rawPackageJson.name === "@barekey/sdk") {
-      const generatedTypesPath = runtime.path.join(current, "generated.d.ts");
+      const serverGeneratedTypesPath = runtime.path.join(current, "generated.server.d.ts");
+      const publicGeneratedTypesPath = runtime.path.join(current, "generated.public.d.ts");
       try {
-        await runtime.fs.access(generatedTypesPath);
+        await runtime.fs.access(serverGeneratedTypesPath);
+        await runtime.fs.access(publicGeneratedTypesPath);
       } catch (error: unknown) {
         throw new TypegenUnsupportedSdkError({
-          message: `The installed @barekey/sdk module at ${current} does not include generated.d.ts.`,
+          message: `The installed @barekey/sdk module at ${current} does not include generated.server.d.ts and generated.public.d.ts.`,
           cause: error,
         });
       }
 
       return {
         packageRoot: current,
-        generatedTypesPath,
+        serverGeneratedTypesPath,
+        publicGeneratedTypesPath,
         typegenMetadataPath: runtime.path.join(current, "typegen.json"),
       };
     }

package/src/internal/public-runtime.ts

@@ -0,0 +1,123 @@
+import {
+  FsNotAvailableError,
+  InvalidConfigurationProvidedError,
+  NoConfigurationProvidedError,
+} from "../errors.js";
+import type { PublicBarekeyClientOptions } from "../public-types.js";
+import type { BarekeyJsonConfig, BarekeyStandardSchemaV1 } from "../types.js";
+import { normalizeBaseUrl } from "./http.js";
+import { isFilesystemAvailable, loadBarekeyJsonConfig } from "./node-runtime.js";
+
+const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";
+
+type BarekeyResolvedScope = {
+  organization: string;
+  project: string;
+  environment: string;
+};
+
+export type BarekeyPublicRuntimeContext = BarekeyResolvedScope & {
+  baseUrl: string;
+  requirements?: BarekeyStandardSchemaV1;
+};
+
+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: PublicBarekeyClientOptions): 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}`,
+  );
+}
+
+export async function resolvePublicRuntimeContext(
+  options: PublicBarekeyClientOptions,
+): Promise<BarekeyPublicRuntimeContext> {
+  const scope = await resolveScope(options);
+  return {
+    ...scope,
+    baseUrl: normalizeBaseUrl(options.baseUrl?.trim() || DEFAULT_BAREKEY_API_URL),
+    requirements: options.requirements,
+  };
+}

package/src/internal/typegen.ts

@@ -11,6 +11,7 @@ import type {
 
 export type TypegenManifestVariable = {
   name: string;
+  visibility: "private" | "public";
   kind: "secret" | "ab_roll" | "rollout";
   declaredType: "string" | "boolean" | "int64" | "float" | "date" | "json";
   required: boolean;
@@ -87,9 +88,18 @@ function renderVariableType(row: TypegenManifestVariable): string {
   return `Env<AB, ${row.typeScriptType}, ${renderRolloutMetadataType(row)}>`;
 }
 
-function buildGeneratedTypesContents(manifest: TypegenManifest): string {
+function buildGeneratedTypesContents(
+  manifest: TypegenManifest,
+  input: {
+    typeModulePath: "./dist/types.js" | "./dist/public-types.js";
+    declaredModulePath: "./dist/types.js" | "./dist/public-types.js";
+    interfaceName: "BarekeyGeneratedTypeMap" | "BarekeyPublicGeneratedTypeMap";
+    include: (row: TypegenManifestVariable) => boolean;
+  },
+): string {
   const mapLines = manifest.variables
     .slice()
+    .filter(input.include)
     .sort((left, right) => left.name.localeCompare(right.name))
     .map((row) => `    ${JSON.stringify(row.name)}: ${renderVariableType(row)};`)
     .join("\n");
@@ -98,10 +108,10 @@ function buildGeneratedTypesContents(manifest: TypegenManifest): string {
 /* This file is generated by barekey typegen. */
 /* barekey-manifest-version: ${manifest.manifestVersion} */
 
-import type { AB, EaseInOut, Env, Linear, Secret, Step } from "./dist/types.js";
+import type { AB, EaseInOut, Env, Linear, Secret, Step } from "${input.typeModulePath}";
 
-declare module "./dist/types.js" {
-  interface BarekeyGeneratedTypeMap {
+declare module "${input.declaredModulePath}" {
+  interface ${input.interfaceName} {
 ${mapLines.length > 0 ? mapLines : ""}
   }
 }
@@ -191,7 +201,27 @@ function buildTypegenMetadataContents(
 
 export async function resolveInstalledSdkGeneratedTypesPath(): Promise<string | null> {
   const target = await resolveInstalledSdkTypegenTarget();
-  return target?.generatedTypesPath ?? null;
+  return target?.serverGeneratedTypesPath ?? null;
+}
+
+export function renderGeneratedTypesForManifest(manifest: TypegenManifest): {
+  serverContents: string;
+  publicContents: string;
+} {
+  return {
+    serverContents: buildGeneratedTypesContents(manifest, {
+      typeModulePath: "./dist/types.js",
+      declaredModulePath: "./dist/types.js",
+      interfaceName: "BarekeyGeneratedTypeMap",
+      include: () => true,
+    }),
+    publicContents: buildGeneratedTypesContents(manifest, {
+      typeModulePath: "./dist/public-types.js",
+      declaredModulePath: "./dist/public-types.js",
+      interfaceName: "BarekeyPublicGeneratedTypeMap",
+      include: (row) => row.visibility === "public",
+    }),
+  };
 }
 
 export async function hasFreshInstalledSdkTypegen(
@@ -229,31 +259,54 @@ export async function writeInstalledSdkGeneratedTypes(
     return {
       written: false,
       path: "",
+      serverPath: "",
+      publicPath: "",
       manifestVersion: manifest.manifestVersion,
     };
   }
 
-  const existingContents = await readTextFile(target.generatedTypesPath);
-  if (readManifestVersion(existingContents) === manifest.manifestVersion) {
+  const [existingServerContents, existingPublicContents] = await Promise.all([
+    readTextFile(target.serverGeneratedTypesPath),
+    readTextFile(target.publicGeneratedTypesPath),
+  ]);
+  if (
+    readManifestVersion(existingServerContents) === manifest.manifestVersion &&
+    readManifestVersion(existingPublicContents) === manifest.manifestVersion
+  ) {
     await writeTextFileAtomic(
       target.typegenMetadataPath,
       buildTypegenMetadataContents(new Date(), identity),
     );
     return {
       written: false,
-      path: target.generatedTypesPath,
+      path: target.serverGeneratedTypesPath,
+      serverPath: target.serverGeneratedTypesPath,
+      publicPath: target.publicGeneratedTypesPath,
       manifestVersion: manifest.manifestVersion,
     };
   }
 
-  await writeTextFileAtomic(target.generatedTypesPath, buildGeneratedTypesContents(manifest));
+  const rendered = renderGeneratedTypesForManifest(manifest);
+
+  await Promise.all([
+    writeTextFileAtomic(
+      target.serverGeneratedTypesPath,
+      rendered.serverContents,
+    ),
+    writeTextFileAtomic(
+      target.publicGeneratedTypesPath,
+      rendered.publicContents,
+    ),
+  ]);
   await writeTextFileAtomic(
     target.typegenMetadataPath,
     buildTypegenMetadataContents(new Date(), identity),
   );
   return {
     written: true,
-    path: target.generatedTypesPath,
+    path: target.serverGeneratedTypesPath,
+    serverPath: target.serverGeneratedTypesPath,
+    publicPath: target.publicGeneratedTypesPath,
     manifestVersion: manifest.manifestVersion,
   };
 }

package/src/public-client.ts

@@ -0,0 +1,229 @@
+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,
+  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 BarekeyPublicKnownKey>(
+    name: TKey,
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvHandle<BarekeyPublicGeneratedTypeMap[TKey]>;
+  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<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,57 @@
+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, BarekeyStandardSchemaV1 } from "./types.js";
+
+export interface BarekeyPublicGeneratedTypeMap {}
+
+export type BarekeyPublicKnownKey = Extract<keyof BarekeyPublicGeneratedTypeMap, string>;
+
+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;
+    });