@barekey/sdk 0.4.3 → 0.5.0

package/src/client.ts

@@ -15,6 +15,10 @@ import { getJson, postJson } from "./internal/http.js";
 import { validateRequirements } from "./internal/requirements.js";
 import { resolveRuntimeContext, type BarekeyRuntimeContext } from "./internal/runtime.js";
 import { createBarekeyClientSingletonKey } from "./internal/singleton.js";
+import {
+  buildStandaloneTypegenManifest,
+  loadStandaloneDefinitions,
+} from "./internal/standalone.js";
 import { MemoryCache } from "./internal/cache.js";
 import { DEFAULT_TYPEGEN_TTL_MS, resolveTtlMilliseconds } from "./internal/ttl.js";
 import {
@@ -118,6 +122,26 @@ function resolveEvaluatedResponse(evaluated: EvaluateResponse): BarekeyEvaluated
   };
 }
 
+function createTypegenIdentity(context: BarekeyRuntimeContext): {
+  baseUrl: string | null;
+  orgSlug: string;
+  projectSlug: string;
+  stageSlug: string;
+  typegenMode: BarekeyRuntimeContext["typegenMode"];
+  runtimeMode: BarekeyRuntimeContext["mode"];
+  localEnvRoot: string | null;
+} {
+  return {
+    baseUrl: context.baseUrl,
+    orgSlug: context.organization,
+    projectSlug: context.project,
+    stageSlug: context.environment,
+    typegenMode: context.typegenMode,
+    runtimeMode: context.mode,
+    localEnvRoot: context.localEnvRoot,
+  };
+}
+
 export class BarekeyClient {
   private readonly options!: BarekeyClientOptions;
   private readonly fetchFn!: typeof globalThis.fetch;
@@ -128,6 +152,10 @@ export class BarekeyClient {
   private typegenWatcherStarted = false;
 
   constructor();
+  constructor(options: {
+    requirements?: BarekeyClientOptions["requirements"];
+    typegen?: BarekeyClientOptions["typegen"];
+  });
   constructor(options: {
     organization: string;
     project: string;
@@ -184,13 +212,17 @@ export class BarekeyClient {
       });
     }
 
-    const manifest = await this.fetchTypegenManifest(context);
-    return await writeInstalledSdkGeneratedTypes(manifest, {
-      baseUrl: context.baseUrl,
-      orgSlug: context.organization,
-      projectSlug: context.project,
-      stageSlug: context.environment,
-    });
+    const manifest =
+      context.mode === "standalone"
+        ? await buildStandaloneTypegenManifest({
+            rootDirectory: context.localEnvRoot,
+            organization: context.organization,
+            project: context.project,
+            environment: context.environment,
+          })
+        : await this.fetchTypegenManifest(context);
+
+    return await writeInstalledSdkGeneratedTypes(manifest, createTypegenIdentity(context));
   }
 
   private async getRuntimeContext(): Promise<BarekeyRuntimeContext> {
@@ -208,6 +240,15 @@ export class BarekeyClient {
 
   private async fetchTypegenManifest(context?: BarekeyRuntimeContext): Promise<TypegenManifest> {
     const resolvedContext = context ?? (await this.getRuntimeContext());
+    if (resolvedContext.mode !== "centralized") {
+      return await buildStandaloneTypegenManifest({
+        rootDirectory: resolvedContext.localEnvRoot,
+        organization: resolvedContext.organization,
+        project: resolvedContext.project,
+        environment: resolvedContext.environment,
+      });
+    }
+
     return await getJson<TypegenManifest>({
       fetchFn: this.fetchFn,
       baseUrl: resolvedContext.baseUrl,
@@ -245,10 +286,13 @@ export class BarekeyClient {
 
     const intervalMs = this.getTypegenIntervalMs();
     const watcherKey = [
-      context.baseUrl,
+      context.baseUrl ?? "",
       context.organization,
       context.project,
       context.environment,
+      context.mode,
+      context.localEnvRoot ?? "",
+      context.typegenMode,
       generatedTypesPath,
     ].join("|");
 
@@ -298,10 +342,7 @@ export class BarekeyClient {
     sharedTypegenWatchers.set(watcherKey, watcher);
     if (
       !(await hasFreshInstalledSdkTypegen(intervalMs, {
-        baseUrl: context.baseUrl,
-        orgSlug: context.organization,
-        projectSlug: context.project,
-        stageSlug: context.environment,
+        ...createTypegenIdentity(context),
       }))
     ) {
       void runWatcher(watcher);
@@ -320,7 +361,14 @@ export class BarekeyClient {
   }
 
   private buildDefinitionCacheKey(context: BarekeyRuntimeContext, name: string): string {
-    return [context.organization, context.project, context.environment, name].join("|");
+    return [
+      context.mode,
+      context.localEnvRoot ?? "",
+      context.organization,
+      context.project,
+      context.environment,
+      name,
+    ].join("|");
   }
 
   private buildEvaluationCacheKey(
@@ -329,12 +377,14 @@ export class BarekeyClient {
     options?: BarekeyGetOptions,
   ): string {
     return [
+      context.mode,
+      context.localEnvRoot ?? "",
       context.organization,
       context.project,
       context.environment,
       name,
-      options?.seed ?? "",
-      options?.key ?? "",
+      context.mode === "standalone" ? "" : options?.seed ?? "",
+      context.mode === "standalone" ? "" : options?.key ?? "",
     ].join("|");
   }
 
@@ -344,6 +394,19 @@ export class BarekeyClient {
     }
 
     const context = await this.getRuntimeContext();
+    if (context.mode === "standalone") {
+      const definitions = await loadStandaloneDefinitions(context.localEnvRoot);
+      for (const definition of definitions) {
+        this.definitionCache.set(this.buildDefinitionCacheKey(context, definition.name), definition);
+      }
+
+      if (names === undefined) {
+        return definitions;
+      }
+
+      return mapValuesToRequestedOrder(names, definitions);
+    }
+
     const response = await postJson<DefinitionsResponse>({
       fetchFn: this.fetchFn,
       baseUrl: context.baseUrl,
@@ -458,6 +521,14 @@ export class BarekeyClient {
     context: BarekeyRuntimeContext,
     options?: BarekeyGetOptions,
   ): Promise<Array<BarekeyEvaluatedValue>> {
+    if (context.mode === "standalone") {
+      const definitions = await loadStandaloneDefinitions(context.localEnvRoot);
+      const resolvedDefinitions = mapValuesToRequestedOrder(names, definitions);
+      return await Promise.all(
+        resolvedDefinitions.map(async (definition) => await evaluateDefinition(definition)),
+      );
+    }
+
     try {
       if (names.length === 1) {
         const evaluated = await postJson<EvaluateResponse>({

package/src/index.ts

@@ -53,6 +53,7 @@ export type {
   BarekeyJsonConfig,
   BarekeyKey,
   BarekeyLiteralString,
+  BarekeyMode,
   BarekeyKnownKey,
   BarekeyResolvedRecord,
   BarekeyResolvedRecords,
@@ -61,6 +62,7 @@ export type {
   BarekeyStandardSchemaV1,
   BarekeyTemporalInstant,
   BarekeyTemporalInstantLike,
+  BarekeyTypegenMode,
   BarekeyTtlInput,
   BarekeyTypegenResult,
   BarekeyValueForGeneratedMap,

package/src/internal/node-runtime.ts

@@ -9,7 +9,7 @@ import {
 } from "../errors.js";
 import { postJson } from "./http.js";
 
-type NodeRuntimeModules = {
+export type NodeRuntimeModules = {
   childProcess: typeof import("node:child_process");
   fs: typeof import("node:fs/promises");
   moduleApi: {
@@ -57,7 +57,7 @@ function isNodeRuntime(): boolean {
   );
 }
 
-async function loadNodeRuntime(): Promise<NodeRuntimeModules | null> {
+export async function loadNodeRuntime(): Promise<NodeRuntimeModules | null> {
   if (!isNodeRuntime()) {
     return null;
   }
@@ -352,6 +352,7 @@ export async function isFilesystemAvailable(): Promise<boolean> {
 
 export async function loadBarekeyJsonConfig(): Promise<{
   path: string;
+  directory: string;
   json: Record<string, unknown>;
 } | null> {
   const runtime = await loadNodeRuntime();
@@ -367,6 +368,7 @@ export async function loadBarekeyJsonConfig(): Promise<{
       try {
         return {
           path: candidate,
+          directory: current,
           json: JSON.parse(raw) as Record<string, unknown>,
         };
       } catch (error: unknown) {

package/src/internal/public-runtime.ts

@@ -4,7 +4,12 @@ import {
   NoConfigurationProvidedError,
 } from "../errors.js";
 import type { PublicBarekeyClientOptions } from "../public-types.js";
-import type { BarekeyJsonConfig, BarekeyStandardSchemaV1 } from "../types.js";
+import type {
+  BarekeyJsonConfig,
+  BarekeyMode,
+  BarekeyStandardSchemaV1,
+  BarekeyTypegenMode,
+} from "../types.js";
 import { normalizeBaseUrl } from "./http.js";
 import { isFilesystemAvailable, loadBarekeyJsonConfig } from "./node-runtime.js";
 
@@ -47,10 +52,62 @@ function normalizeScope(input: {
   };
 }
 
+function normalizeTypegenMode(value: unknown, source: string): BarekeyTypegenMode {
+  if (value === undefined) {
+    return "semantic";
+  }
+
+  if (value === "semantic" || value === "minimal") {
+    return value;
+  }
+
+  throw new InvalidConfigurationProvidedError({
+    message: `${source} must provide config.typegen as "semantic" or "minimal" when set.`,
+  });
+}
+
+function normalizeMode(value: unknown, source: string): BarekeyMode {
+  if (value === undefined) {
+    return "centralized";
+  }
+
+  if (value === "centralized" || value === "standalone") {
+    return value;
+  }
+
+  throw new InvalidConfigurationProvidedError({
+    message: `${source} must provide config.mode as "centralized" or "standalone" when set.`,
+  });
+}
+
+function createStandaloneUnsupportedError(source: string): Error {
+  return new InvalidConfigurationProvidedError({
+    message: [
+      `${source} sets config.mode to "standalone".`,
+      "PublicBarekeyClient does not support standalone local env mode because it relies on a server filesystem to read .env files.",
+      "Use BarekeyClient on the server instead, or switch barekey.json config.mode back to \"centralized\" for browser/public usage.",
+    ].join(" "),
+  });
+}
+
 function normalizeJsonConfig(
   input: BarekeyJsonConfig | Record<string, unknown>,
   source: string,
 ): BarekeyResolvedScope {
+  const config =
+    "config" in input && typeof input.config === "object" && input.config !== null
+      ? (input.config as Record<string, unknown>)
+      : undefined;
+
+  normalizeTypegenMode(
+    config?.typegen ?? ("typegen" in input ? input.typegen : undefined),
+    source,
+  );
+
+  if (normalizeMode(config?.mode, source) === "standalone") {
+    throw createStandaloneUnsupportedError(source);
+  }
+
   return normalizeScope({
     organization: input.organization ?? input.org,
     project: input.project,

package/src/internal/runtime.ts

@@ -7,7 +7,13 @@ import {
   NoCredentialsProvidedError,
   UnauthorizedError,
 } from "../errors.js";
-import type { BarekeyClientOptions, BarekeyJsonConfig, BarekeyStandardSchemaV1 } from "../types.js";
+import type {
+  BarekeyClientOptions,
+  BarekeyJsonConfig,
+  BarekeyMode,
+  BarekeyStandardSchemaV1,
+  BarekeyTypegenMode,
+} from "../types.js";
 import { type InternalAuthResolver, normalizeBaseUrl } from "./http.js";
 import {
   isFilesystemAvailable,
@@ -21,14 +27,31 @@ type BarekeyResolvedScope = {
   organization: string;
   project: string;
   environment: string;
+  typegenMode: BarekeyTypegenMode;
+  mode: BarekeyMode;
+  localEnvRoot: string | null;
 };
 
-export type BarekeyRuntimeContext = BarekeyResolvedScope & {
+type BarekeyCentralizedRuntimeContext = BarekeyResolvedScope & {
+  mode: "centralized";
+  localEnvRoot: null;
   baseUrl: string;
   auth: InternalAuthResolver;
   requirements?: BarekeyStandardSchemaV1;
 };
 
+type BarekeyStandaloneRuntimeContext = BarekeyResolvedScope & {
+  mode: "standalone";
+  localEnvRoot: string;
+  baseUrl: null;
+  auth: null;
+  requirements?: BarekeyStandardSchemaV1;
+};
+
+export type BarekeyRuntimeContext =
+  | BarekeyCentralizedRuntimeContext
+  | BarekeyStandaloneRuntimeContext;
+
 function readProcessEnv(key: string): string | undefined {
   if (typeof process === "undefined" || typeof process.env !== "object" || process.env === null) {
     return undefined;
@@ -42,36 +65,101 @@ function readConfigString(value: unknown): string | undefined {
   return typeof value === "string" ? value.trim() : undefined;
 }
 
+function safeCurrentWorkingDirectory(): string | null {
+  if (typeof process === "undefined" || typeof process.cwd !== "function") {
+    return null;
+  }
+
+  return process.cwd();
+}
+
+function normalizeTypegenMode(value: unknown, source: string): BarekeyTypegenMode {
+  if (value === undefined) {
+    return "semantic";
+  }
+
+  if (value === "semantic" || value === "minimal") {
+    return value;
+  }
+
+  throw new InvalidConfigurationProvidedError({
+    message: `${source} must provide config.typegen as "semantic" or "minimal" when set.`,
+  });
+}
+
+function normalizeMode(value: unknown, source: string): BarekeyMode {
+  if (value === undefined) {
+    return "centralized";
+  }
+
+  if (value === "centralized" || value === "standalone") {
+    return value;
+  }
+
+  throw new InvalidConfigurationProvidedError({
+    message: `${source} must provide config.mode as "centralized" or "standalone" when set.`,
+  });
+}
+
 function normalizeScope(input: {
   organization?: unknown;
   project?: unknown;
   environment?: unknown;
+  typegenMode?: BarekeyTypegenMode;
+  mode?: BarekeyMode;
+  localEnvRoot?: string | null;
   source: string;
 }): BarekeyResolvedScope {
+  const mode = input.mode ?? "centralized";
   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) {
+  if (
+    mode !== "standalone" &&
+    (organization.length === 0 || project.length === 0 || environment.length === 0)
+  ) {
     throw new InvalidConfigurationProvidedError({
       message: `${input.source} must provide organization, project, and environment.`,
     });
   }
 
+  const localEnvRoot = mode === "standalone" ? input.localEnvRoot ?? safeCurrentWorkingDirectory() : null;
+  if (mode === "standalone" && (!localEnvRoot || localEnvRoot.trim().length === 0)) {
+    throw new FsNotAvailableError({
+      message: "Barekey standalone mode requires filesystem access and a working directory.",
+    });
+  }
+
   return {
     organization,
     project,
     environment,
+    typegenMode: mode === "standalone" ? "minimal" : (input.typegenMode ?? "semantic"),
+    mode,
+    localEnvRoot: mode === "standalone" ? localEnvRoot : null,
   };
 }
 
 function normalizeJsonConfig(
   input: BarekeyJsonConfig | Record<string, unknown>,
   source: string,
+  localEnvRoot: string | null,
 ): BarekeyResolvedScope {
+  const config =
+    "config" in input && typeof input.config === "object" && input.config !== null
+      ? (input.config as Record<string, unknown>)
+      : undefined;
+
   return normalizeScope({
     organization: input.organization ?? input.org,
     project: input.project,
     environment: input.environment ?? input.stage,
+    typegenMode: normalizeTypegenMode(
+      config?.typegen ?? ("typegen" in input ? input.typegen : undefined),
+      source,
+    ),
+    mode: normalizeMode(config?.mode, source),
+    localEnvRoot,
     source,
   });
 }
@@ -100,7 +188,11 @@ async function resolveScope(options: BarekeyClientOptions): Promise<BarekeyResol
   }
 
   if (explicitJson !== undefined) {
-    return normalizeJsonConfig(explicitJson, "The provided json configuration");
+    return normalizeJsonConfig(
+      explicitJson,
+      "The provided json configuration",
+      safeCurrentWorkingDirectory(),
+    );
   }
 
   if (explicitCount === 3) {
@@ -108,6 +200,9 @@ async function resolveScope(options: BarekeyClientOptions): Promise<BarekeyResol
       organization: explicitOrganization,
       project: explicitProject,
       environment: explicitEnvironment,
+      typegenMode: "semantic",
+      mode: "centralized",
+      localEnvRoot: null,
       source: "The provided Barekey configuration",
     });
   }
@@ -125,6 +220,7 @@ async function resolveScope(options: BarekeyClientOptions): Promise<BarekeyResol
   return normalizeJsonConfig(
     loadedConfig.json,
     `The barekey.json file at ${loadedConfig.path}`,
+    loadedConfig.directory,
   );
 }
 
@@ -189,9 +285,29 @@ export async function resolveRuntimeContext(
   options: BarekeyClientOptions,
   fetchFn: typeof globalThis.fetch,
 ): Promise<BarekeyRuntimeContext> {
-  const [scope, auth] = await Promise.all([resolveScope(options), resolveAuth(fetchFn)]);
+  const scope = await resolveScope(options);
+  if (scope.mode === "standalone") {
+    if (!(await isFilesystemAvailable())) {
+      throw new FsNotAvailableError({
+        message: "Barekey standalone mode requires a local filesystem to read .env files.",
+      });
+    }
+
+    return {
+      ...scope,
+      mode: "standalone",
+      localEnvRoot: scope.localEnvRoot ?? safeCurrentWorkingDirectory() ?? "",
+      baseUrl: null,
+      auth: null,
+      requirements: options.requirements,
+    };
+  }
+
+  const auth = await resolveAuth(fetchFn);
   return {
     ...scope,
+    mode: "centralized",
+    localEnvRoot: null,
     baseUrl: auth.baseUrl,
     auth: auth.auth,
     requirements: options.requirements,

package/src/internal/singleton.ts

@@ -42,15 +42,36 @@ function safeCurrentWorkingDirectory(): string {
 
 function normalizeJsonScope(
   value: BarekeyJsonConfig | undefined,
-): { organization: string | null; project: string | null; environment: string | null } | null {
+): {
+  organization: string | null;
+  project: string | null;
+  environment: string | null;
+  typegenMode: string | null;
+  runtimeMode: string | null;
+  localEnvRoot: string | null;
+} | null {
   if (value === undefined) {
     return null;
   }
 
+  const config =
+    typeof value.config === "object" && value.config !== null
+      ? (value.config as { typegen?: unknown; mode?: unknown })
+      : undefined;
+  const runtimeMode = config?.mode === "standalone" ? "standalone" : "centralized";
+
   return {
     organization: readConfigString(value.organization ?? value.org),
     project: readConfigString(value.project),
     environment: readConfigString(value.environment ?? value.stage),
+    typegenMode:
+      runtimeMode === "standalone"
+        ? "minimal"
+        : config?.typegen === "minimal"
+          ? "minimal"
+          : "semantic",
+    runtimeMode,
+    localEnvRoot: runtimeMode === "standalone" ? safeCurrentWorkingDirectory() : null,
   };
 }
 
@@ -58,9 +79,18 @@ function normalizeScopeKey(
   options:
     | BarekeyClientOptions
     | PublicBarekeyClientOptions,
-): { organization: string | null; project: string | null; environment: string | null } | {
-  cwd: string;
-} {
+):
+  | {
+      organization: string | null;
+      project: string | null;
+      environment: string | null;
+      typegenMode: string | null;
+      runtimeMode: string | null;
+      localEnvRoot: string | null;
+    }
+  | {
+      cwd: string;
+    } {
   const jsonScope = normalizeJsonScope("json" in options ? options.json : undefined);
   if (jsonScope !== null) {
     return jsonScope;
@@ -74,6 +104,9 @@ function normalizeScopeKey(
       organization,
       project,
       environment,
+      typegenMode: "semantic",
+      runtimeMode: "centralized",
+      localEnvRoot: null,
     };
   }