@barekey/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Barekey Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,21 @@
+# @barekey/sdk
+
+Barekey TypeScript SDK.
+
+## Install
+
+```bash
+npm install @barekey/sdk
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Typecheck
+
+```bash
+npm run typecheck
+```

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { BarekeyEnvHandle } from "./handle.js";
+import type { BarekeyClientOptions, BarekeyGeneratedTypeMap, BarekeyGetOptions, BarekeyJsonConfig, BarekeyKnownKey, BarekeyTypegenResult } from "./types.js";
+export declare class BarekeyClient {
+    private readonly options;
+    private readonly fetchFn;
+    private readonly definitionCache;
+    private readonly evaluationCache;
+    private runtimeContextPromise;
+    private requirementsPromise;
+    private typegenWatcherStarted;
+    constructor();
+    constructor(options: {
+        organization: string;
+        project: string;
+        environment: string;
+        requirements?: BarekeyClientOptions["requirements"];
+        typegen?: BarekeyClientOptions["typegen"];
+    });
+    constructor(options: {
+        json: BarekeyJsonConfig;
+        requirements?: BarekeyClientOptions["requirements"];
+        typegen?: BarekeyClientOptions["typegen"];
+    });
+    get<TKey extends BarekeyKnownKey>(name: TKey, options?: BarekeyGetOptions): BarekeyEnvHandle<BarekeyGeneratedTypeMap[TKey]>;
+    get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown>;
+    typegen(): Promise<BarekeyTypegenResult>;
+    private getRuntimeContext;
+    private fetchTypegenManifest;
+    private getTypegenIntervalMs;
+    private startTypegenWatcher;
+    private ensureTypegenWatcher;
+    private buildDefinitionCacheKey;
+    private buildEvaluationCacheKey;
+    private fetchDefinitions;
+    private ensureRequirementsValidated;
+    private getStaticDefinition;
+    private resolveStaticValue;
+    private resolveDynamicValue;
+    private resolveEvaluatedValue;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAiB/C,OAAO,KAAK,EACV,oBAAoB,EAEpB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAiDpB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAChF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4C;IAC5E,OAAO,CAAC,qBAAqB,CAA+C;IAC5E,OAAO,CAAC,mBAAmB,CAA8B;IACzD,OAAO,CAAC,qBAAqB,CAAS;;gBAG1B,OAAO,EAAE;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;QACpD,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;KAC3C;gBACW,OAAO,EAAE;QACnB,IAAI,EAAE,iBAAiB,CAAC;QACxB,YAAY,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;QACpD,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;KAC3C;IAMD,GAAG,CAAC,IAAI,SAAS,eAAe,EAC9B,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAClD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAAC,OAAO,CAAC;IAOnE,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;YAahC,iBAAiB;YAajB,oBAAoB;IAclC,OAAO,CAAC,oBAAoB;YAWd,mBAAmB;IAoEjC,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,uBAAuB;YAejB,gBAAgB;YAsBhB,2BAA2B;YA4B3B,mBAAmB;YAiBnB,kBAAkB;YAQlB,mBAAmB;YAkEnB,qBAAqB;CAYpC"}

package/dist/client.js

@@ -0,0 +1,302 @@
+import { BillingUnavailableError, FsNotAvailableError, NetworkError, VariableNotFoundError, } from "./errors.js";
+import { BarekeyEnvHandle } from "./handle.js";
+import { evaluateDefinition, inferSelectedArmFromDecision, parseDeclaredValue, validateDynamicOptions, } from "./internal/evaluate.js";
+import { getJson, postJson } from "./internal/http.js";
+import { validateRequirements } from "./internal/requirements.js";
+import { resolveRuntimeContext } from "./internal/runtime.js";
+import { MemoryCache } from "./internal/cache.js";
+import { DEFAULT_TYPEGEN_TTL_MS, resolveTtlMilliseconds } from "./internal/ttl.js";
+import { resolveInstalledSdkGeneratedTypesPath, writeInstalledSdkGeneratedTypes, } from "./internal/typegen.js";
+const sharedTypegenWatchers = new Map();
+function createDefaultFetch() {
+    if (typeof globalThis.fetch === "function") {
+        return globalThis.fetch.bind(globalThis);
+    }
+    return (async () => {
+        throw new NetworkError({
+            message: "fetch is not available in this runtime.",
+        });
+    });
+}
+function createTypegenInterval(callback, intervalMs) {
+    const timer = setInterval(callback, intervalMs);
+    if ("unref" in timer && typeof timer.unref === "function") {
+        timer.unref();
+    }
+    return timer;
+}
+function warnAutomaticTypegenFailure(error) {
+    const message = error instanceof Error ? error.message : "Barekey automatic typegen refresh failed.";
+    console.warn(`[barekey] Automatic typegen refresh failed.\n${message}`);
+}
+export class BarekeyClient {
+    options;
+    fetchFn;
+    definitionCache = new MemoryCache();
+    evaluationCache = new MemoryCache();
+    runtimeContextPromise = null;
+    requirementsPromise = null;
+    typegenWatcherStarted = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.fetchFn = createDefaultFetch();
+    }
+    get(name, options) {
+        return new BarekeyEnvHandle(async () => await this.resolveEvaluatedValue(name, options));
+    }
+    async typegen() {
+        const context = await this.getRuntimeContext();
+        const generatedTypesPath = await resolveInstalledSdkGeneratedTypesPath();
+        if (generatedTypesPath === null) {
+            throw new FsNotAvailableError({
+                message: "Barekey could not update generated SDK types because filesystem access is unavailable.",
+            });
+        }
+        const manifest = await this.fetchTypegenManifest(context);
+        return await writeInstalledSdkGeneratedTypes(manifest);
+    }
+    async getRuntimeContext() {
+        if (this.runtimeContextPromise === null) {
+            const runtimeContextPromise = resolveRuntimeContext(this.options, this.fetchFn);
+            runtimeContextPromise.catch(() => {
+                if (this.runtimeContextPromise === runtimeContextPromise) {
+                    this.runtimeContextPromise = null;
+                }
+            });
+            this.runtimeContextPromise = runtimeContextPromise;
+        }
+        return await this.runtimeContextPromise;
+    }
+    async fetchTypegenManifest(context) {
+        const resolvedContext = context ?? (await this.getRuntimeContext());
+        return await getJson({
+            fetchFn: this.fetchFn,
+            baseUrl: resolvedContext.baseUrl,
+            path: `/v1/typegen/manifest?projectSlug=${encodeURIComponent(resolvedContext.project)}&stageSlug=${encodeURIComponent(resolvedContext.environment)}&orgSlug=${encodeURIComponent(resolvedContext.organization)}`,
+            auth: resolvedContext.auth,
+        });
+    }
+    getTypegenIntervalMs() {
+        const typegenOptions = this.options.typegen;
+        if (typegenOptions === false) {
+            return 0;
+        }
+        if (typegenOptions?.ttl === undefined) {
+            return DEFAULT_TYPEGEN_TTL_MS;
+        }
+        return resolveTtlMilliseconds(typegenOptions.ttl, "typegen.ttl");
+    }
+    async startTypegenWatcher(context) {
+        if (this.options.typegen === false || context.environment !== "development") {
+            return;
+        }
+        const generatedTypesPath = await resolveInstalledSdkGeneratedTypesPath();
+        if (generatedTypesPath === null) {
+            throw new FsNotAvailableError({
+                message: "Automatic Barekey typegen refresh requires filesystem access.",
+            });
+        }
+        const intervalMs = this.getTypegenIntervalMs();
+        const watcherKey = [
+            context.baseUrl,
+            context.organization,
+            context.project,
+            context.environment,
+            generatedTypesPath,
+        ].join("|");
+        const runWatcher = async (watcher) => {
+            if (watcher.inFlight !== null) {
+                await watcher.inFlight;
+                return;
+            }
+            watcher.inFlight = (async () => {
+                try {
+                    await this.typegen();
+                    watcher.warned = false;
+                }
+                catch (error) {
+                    if (!watcher.warned) {
+                        warnAutomaticTypegenFailure(error);
+                        watcher.warned = true;
+                    }
+                }
+                finally {
+                    watcher.inFlight = null;
+                }
+            })();
+            await watcher.inFlight;
+        };
+        const existingWatcher = sharedTypegenWatchers.get(watcherKey);
+        if (existingWatcher !== undefined) {
+            if (intervalMs < existingWatcher.intervalMs) {
+                clearInterval(existingWatcher.timer);
+                existingWatcher.intervalMs = intervalMs;
+                existingWatcher.timer = createTypegenInterval(() => {
+                    void runWatcher(existingWatcher);
+                }, intervalMs);
+            }
+            return;
+        }
+        const watcher = {
+            intervalMs,
+            inFlight: null,
+            warned: false,
+            timer: createTypegenInterval(() => {
+                void runWatcher(watcher);
+            }, intervalMs),
+        };
+        sharedTypegenWatchers.set(watcherKey, watcher);
+        void runWatcher(watcher);
+    }
+    ensureTypegenWatcher(context) {
+        if (this.typegenWatcherStarted || this.options.typegen === false || context.environment !== "development") {
+            return;
+        }
+        this.typegenWatcherStarted = true;
+        void this.startTypegenWatcher(context).catch((error) => {
+            warnAutomaticTypegenFailure(error);
+        });
+    }
+    buildDefinitionCacheKey(context, name) {
+        return [context.organization, context.project, context.environment, name].join("|");
+    }
+    buildEvaluationCacheKey(context, name, options) {
+        return [
+            context.organization,
+            context.project,
+            context.environment,
+            name,
+            options?.seed ?? "",
+            options?.key ?? "",
+        ].join("|");
+    }
+    async fetchDefinitions(names) {
+        const context = await this.getRuntimeContext();
+        const response = await postJson({
+            fetchFn: this.fetchFn,
+            baseUrl: context.baseUrl,
+            path: "/v1/env/definitions",
+            payload: {
+                orgSlug: context.organization,
+                projectSlug: context.project,
+                stageSlug: context.environment,
+                ...(names === undefined ? {} : { names }),
+            },
+            auth: context.auth,
+        });
+        for (const definition of response.definitions) {
+            this.definitionCache.set(this.buildDefinitionCacheKey(context, definition.name), definition);
+        }
+        return response.definitions;
+    }
+    async ensureRequirementsValidated() {
+        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 = {};
+                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;
+    }
+    async getStaticDefinition(name) {
+        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;
+    }
+    async resolveStaticValue(name, options) {
+        const definition = await this.getStaticDefinition(name);
+        return await evaluateDefinition(definition, options);
+    }
+    async resolveDynamicValue(name, options) {
+        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;
+            }
+        }
+        let resolved;
+        try {
+            const evaluated = await postJson({
+                fetchFn: this.fetchFn,
+                baseUrl: context.baseUrl,
+                path: "/v1/env/evaluate",
+                payload: {
+                    orgSlug: context.organization,
+                    projectSlug: context.project,
+                    stageSlug: context.environment,
+                    name,
+                    seed: options?.seed,
+                    key: options?.key,
+                },
+                auth: context.auth,
+            });
+            resolved = {
+                name: evaluated.name,
+                kind: evaluated.kind,
+                declaredType: evaluated.declaredType,
+                value: evaluated.value,
+                decision: evaluated.decision,
+                selectedArm: inferSelectedArmFromDecision(evaluated.decision),
+            };
+        }
+        catch (error) {
+            if (!(error instanceof BillingUnavailableError)) {
+                throw error;
+            }
+            const freshDefinitions = await this.fetchDefinitions([name]);
+            const freshDefinition = freshDefinitions[0];
+            if (freshDefinition === undefined) {
+                throw new VariableNotFoundError();
+            }
+            resolved = await evaluateDefinition(freshDefinition, options);
+        }
+        if (dynamicTtlMs !== null) {
+            // dynamic.ttl is evaluated per read, so keep the cached fetch time and let
+            // later calls decide whether the entry is still fresh for their requested ttl.
+            this.evaluationCache.set(cacheKey, resolved);
+        }
+        return resolved;
+    }
+    async resolveEvaluatedValue(name, options) {
+        const context = await this.getRuntimeContext();
+        this.ensureTypegenWatcher(context);
+        validateDynamicOptions(options);
+        if (options?.dynamic === undefined) {
+            return await this.resolveStaticValue(name, options);
+        }
+        return await this.resolveDynamicValue(name, options);
+    }
+}