@restormel/testing-keys-adapter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Allotment Technology Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapter.d.ts

@@ -0,0 +1,6 @@
+import type { KeysModelAdapterOptions, ModelResolutionResult } from "./types.js";
+/**
+ * Resolve a single logical model ref for test execution. Keys first; optional OpenAI env fallback.
+ */
+export declare function resolveModel(logicalRef: string, options?: KeysModelAdapterOptions): Promise<ModelResolutionResult>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAoB,qBAAqB,EAAiB,MAAM,YAAY,CAAC;AAuClH;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAmFhC"}

package/dist/adapter.js

@@ -0,0 +1,87 @@
+import { createHttpKeysTransport } from "./transport-http.js";
+import { readSecretFromEnv } from "./materialize.js";
+const REF_PREFIX = "ref:restormel-keys:";
+function isValidLogicalRef(ref) {
+    if (typeof ref !== "string" || ref.length === 0 || ref.length > 512)
+        return false;
+    if (ref.startsWith(REF_PREFIX) && ref.length > REF_PREFIX.length)
+        return true;
+    return false;
+}
+function fail(code, message, cause) {
+    return { ok: false, error: { code, message, cause } };
+}
+function buildResolved(logicalRef, provider, model, modelId, apiKey, source, providerBaseUrl) {
+    return {
+        meta: {
+            logicalRef,
+            provider,
+            model,
+            resolutionSource: source,
+            invocationCount: 0,
+        },
+        modelId,
+        providerBaseUrl,
+        credentials: { apiKey },
+    };
+}
+/**
+ * Resolve a single logical model ref for test execution. Keys first; optional OpenAI env fallback.
+ */
+export async function resolveModel(logicalRef, options = {}) {
+    const warnings = [];
+    if (!isValidLogicalRef(logicalRef)) {
+        return fail("invalid_ref", `Expected logical ref "${REF_PREFIX}…", got ${JSON.stringify(logicalRef)}`);
+    }
+    const transport = options.transport ??
+        (options.keysApiBaseUrl
+            ? createHttpKeysTransport({
+                baseUrl: options.keysApiBaseUrl,
+                getKeysApiToken: options.keysApiTokenEnvVar
+                    ? () => process.env[options.keysApiTokenEnvVar]
+                    : undefined,
+            })
+            : undefined);
+    if (transport) {
+        const tr = await transport.resolve(logicalRef);
+        if (tr.ok) {
+            const mat = readSecretFromEnv(tr.secretEnvVar);
+            if (!mat.ok) {
+                return fail("keys_missing_secret_binding", `Keys resolved model but ${mat.message}`);
+            }
+            return {
+                ok: true,
+                warnings,
+                model: buildResolved(logicalRef, tr.provider, tr.model, tr.model, mat.apiKey, "keys", tr.baseUrl),
+            };
+        }
+        warnings.push(`Keys resolution failed (${tr.code}): ${tr.message}. ${options.openAiEnvFallback?.enabled ? "Attempting documented env fallback." : "No fallback configured."}`);
+    }
+    else {
+        warnings.push("Keys transport not configured (no transport and no keysApiBaseUrl). BYOK should flow through Restormel / Keys when available.");
+    }
+    const fb = options.openAiEnvFallback;
+    if (!fb?.enabled) {
+        if (!transport) {
+            return fail("keys_not_configured", "Configure Keys (keysApiBaseUrl or transport) or enable openAiEnvFallback for the documented non-Keys escape hatch.");
+        }
+        return fail("fallback_disabled", "Keys resolution failed and OpenAI env fallback is disabled.");
+    }
+    if (fb.forLogicalRef !== undefined && fb.forLogicalRef !== logicalRef) {
+        return fail("fallback_disabled", `Env fallback is restricted to ref ${fb.forLogicalRef}; got ${logicalRef}`);
+    }
+    const apiKeyVar = fb.apiKeyEnvVar ?? "OPENAI_API_KEY";
+    const key = process.env[apiKeyVar];
+    if (key === undefined || key === "") {
+        return fail("fallback_missing_env", `Fallback enabled but ${apiKeyVar} is unset or empty.`);
+    }
+    const modelId = fb.defaultModel ?? "gpt-4o-mini";
+    const baseUrl = fb.baseUrl;
+    warnings.push(`RESTORMEL_TESTING_KEYS_FALLBACK: using ${apiKeyVar} for OpenAI-compatible calls. Prefer Restormel / Keys for BYOK and auditability.`);
+    return {
+        ok: true,
+        warnings,
+        model: buildResolved(logicalRef, "openai", modelId, modelId, key, "env_fallback", baseUrl),
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/env-from-process.d.ts

@@ -0,0 +1,12 @@
+import type { KeysModelAdapterOptions } from "./types.js";
+/**
+ * Build Keys adapter options from documented environment variables (CLI, GitHub Action, local).
+ *
+ * | Variable | Purpose |
+ * |----------|---------|
+ * | `RESTORMEL_KEYS_API_BASE_URL` | Keys HTTP API origin (e.g. `https://keys.example.com`). Enables POST `/v1/testing/resolve-model`. |
+ * | `RESTORMEL_KEYS_API_TOKEN_ENV` | Optional. Name of env var holding the **Keys API** bearer token (default `RESTORMEL_KEYS_API_TOKEN`). Values are never logged. |
+ * | `RESTORMEL_TESTING_OPENAI_FALLBACK` | Set to `1` to allow documented OpenAI-compatible env fallback when Keys is unset or resolution fails (`OPENAI_API_KEY`). |
+ */
+export declare function keysAdapterOptionsFromProcessEnv(): KeysModelAdapterOptions | undefined;
+//# sourceMappingURL=env-from-process.d.ts.map

package/dist/env-from-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-from-process.d.ts","sourceRoot":"","sources":["../src/env-from-process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,IAAI,uBAAuB,GAAG,SAAS,CAmBtF"}

package/dist/env-from-process.js

@@ -0,0 +1,27 @@
+/**
+ * Build Keys adapter options from documented environment variables (CLI, GitHub Action, local).
+ *
+ * | Variable | Purpose |
+ * |----------|---------|
+ * | `RESTORMEL_KEYS_API_BASE_URL` | Keys HTTP API origin (e.g. `https://keys.example.com`). Enables POST `/v1/testing/resolve-model`. |
+ * | `RESTORMEL_KEYS_API_TOKEN_ENV` | Optional. Name of env var holding the **Keys API** bearer token (default `RESTORMEL_KEYS_API_TOKEN`). Values are never logged. |
+ * | `RESTORMEL_TESTING_OPENAI_FALLBACK` | Set to `1` to allow documented OpenAI-compatible env fallback when Keys is unset or resolution fails (`OPENAI_API_KEY`). |
+ */
+export function keysAdapterOptionsFromProcessEnv() {
+    const baseUrl = process.env.RESTORMEL_KEYS_API_BASE_URL?.trim();
+    const tokenEnvName = process.env.RESTORMEL_KEYS_API_TOKEN_ENV?.trim() || "RESTORMEL_KEYS_API_TOKEN";
+    const fallbackOn = process.env.RESTORMEL_TESTING_OPENAI_FALLBACK?.trim() === "1";
+    const opts = {};
+    if (baseUrl) {
+        opts.keysApiBaseUrl = baseUrl;
+        opts.keysApiTokenEnvVar = tokenEnvName;
+    }
+    if (fallbackOn) {
+        opts.openAiEnvFallback = { enabled: true };
+    }
+    if (!opts.keysApiBaseUrl && !opts.openAiEnvFallback) {
+        return undefined;
+    }
+    return opts;
+}
+//# sourceMappingURL=env-from-process.js.map

package/dist/env-from-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-from-process.js","sourceRoot":"","sources":["../src/env-from-process.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,gCAAgC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,IAAI,EAAE,CAAC;IAChE,MAAM,YAAY,GAChB,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,IAAI,EAAE,IAAI,0BAA0B,CAAC;IACjF,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,iCAAiC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC;IAEjF,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,IAAI,CAAC,kBAAkB,GAAG,YAAY,CAAC;IACzC,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,CAAC,iBAAiB,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @restormel/testing-keys-adapter — thin Restormel / Keys resolution seam for Testing (MVP).
+ */
+export declare const testingKeysAdapterPackage: "@restormel/testing-keys-adapter";
+export { keysAdapterOptionsFromProcessEnv } from "./env-from-process.js";
+export { resolveModel } from "./adapter.js";
+export { readSecretFromEnv } from "./materialize.js";
+export { createHttpKeysTransport } from "./transport-http.js";
+export { createStubKeysTransport } from "./transport-stub.js";
+export type { StubResolutionEntry } from "./transport-stub.js";
+export type { KeysAdapterError, KeysAdapterErrorCode, KeysHttpResolveResponseBody, KeysModelAdapterOptions, KeysResolutionTransport, KeysTransportResolution, ModelResolutionResult, OpenAiEnvFallbackOptions, ResolvedModel, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAG,iCAA0C,CAAC;AAEpF,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @restormel/testing-keys-adapter — thin Restormel / Keys resolution seam for Testing (MVP).
+ */
+export const testingKeysAdapterPackage = "@restormel/testing-keys-adapter";
+export { keysAdapterOptionsFromProcessEnv } from "./env-from-process.js";
+export { resolveModel } from "./adapter.js";
+export { readSecretFromEnv } from "./materialize.js";
+export { createHttpKeysTransport } from "./transport-http.js";
+export { createStubKeysTransport } from "./transport-stub.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,iCAA0C,CAAC;AAEpF,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/materialize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Read BYOK material from the environment. Variable name only — never the secret value in errors beyond "missing".
+ */
+export declare function readSecretFromEnv(secretEnvVar: string): {
+    ok: true;
+    apiKey: string;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=materialize.d.ts.map

package/dist/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../src/materialize.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUrH"}

package/dist/materialize.js

@@ -0,0 +1,15 @@
+/**
+ * Read BYOK material from the environment. Variable name only — never the secret value in errors beyond "missing".
+ */
+export function readSecretFromEnv(secretEnvVar) {
+    const name = secretEnvVar.startsWith("env:") ? secretEnvVar.slice("env:".length) : secretEnvVar;
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+        return { ok: false, message: `Invalid secret env var name: ${secretEnvVar}` };
+    }
+    const apiKey = process.env[name];
+    if (apiKey === undefined || apiKey === "") {
+        return { ok: false, message: `Environment variable ${name} is unset or empty` };
+    }
+    return { ok: true, apiKey };
+}
+//# sourceMappingURL=materialize.js.map

package/dist/materialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.js","sourceRoot":"","sources":["../src/materialize.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAChG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,gCAAgC,YAAY,EAAE,EAAE,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,IAAI,oBAAoB,EAAE,CAAC;IAClF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/transport-http.d.ts

@@ -0,0 +1,10 @@
+import type { KeysResolutionTransport } from "./types.js";
+/**
+ * Calls Keys over HTTP. Path is versioned under this repo’s adapter until Keys publishes a canonical route.
+ */
+export declare function createHttpKeysTransport(options: {
+    baseUrl: string;
+    /** Return bearer token for Keys API (not the provider key). */
+    getKeysApiToken?: () => string | undefined;
+}): KeysResolutionTransport;
+//# sourceMappingURL=transport-http.d.ts.map

package/dist/transport-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-http.d.ts","sourceRoot":"","sources":["../src/transport-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,uBAAuB,EAA2B,MAAM,YAAY,CAAC;AAehH;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAC5C,GAAG,uBAAuB,CAsD1B"}

package/dist/transport-http.js

@@ -0,0 +1,72 @@
+function isResolveBody(x) {
+    if (x === null || typeof x !== "object")
+        return false;
+    const o = x;
+    return (typeof o.provider === "string" &&
+        typeof o.model === "string" &&
+        typeof o.secretEnvVar === "string" &&
+        o.provider.length > 0 &&
+        o.model.length > 0 &&
+        o.secretEnvVar.length > 0);
+}
+/**
+ * Calls Keys over HTTP. Path is versioned under this repo’s adapter until Keys publishes a canonical route.
+ */
+export function createHttpKeysTransport(options) {
+    const root = options.baseUrl.replace(/\/?$/, "");
+    return {
+        async resolve(logicalRef) {
+            const url = `${root}/v1/testing/resolve-model`;
+            const headers = {
+                "content-type": "application/json",
+                accept: "application/json",
+            };
+            const token = options.getKeysApiToken?.();
+            if (token) {
+                headers.authorization = `Bearer ${token}`;
+            }
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({ logicalRef }),
+                });
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    code: "network",
+                    message: `Keys HTTP request failed: ${e instanceof Error ? e.message : String(e)}`,
+                    cause: e,
+                };
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                return {
+                    ok: false,
+                    code: `http_${res.status}`,
+                    message: `Keys returned ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`,
+                };
+            }
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch (e) {
+                return { ok: false, code: "invalid_json", message: "Keys response was not JSON", cause: e };
+            }
+            if (!isResolveBody(body)) {
+                return { ok: false, code: "invalid_body", message: "Keys response missing provider, model, or secretEnvVar" };
+            }
+            return {
+                ok: true,
+                provider: body.provider,
+                model: body.model,
+                secretEnvVar: body.secretEnvVar,
+                baseUrl: typeof body.baseUrl === "string" ? body.baseUrl : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=transport-http.js.map

package/dist/transport-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-http.js","sourceRoot":"","sources":["../src/transport-http.ts"],"names":[],"mappings":"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"}

package/dist/transport-stub.d.ts

@@ -0,0 +1,11 @@
+import type { KeysResolutionTransport } from "./types.js";
+export interface StubResolutionEntry {
+    provider: string;
+    model: string;
+    /** Name of process.env var holding the provider API key. */
+    secretEnvVar: string;
+    baseUrl?: string;
+}
+/** In-memory map for tests and offline development; not a substitute for real Keys in production. */
+export declare function createStubKeysTransport(map: Record<string, StubResolutionEntry>): KeysResolutionTransport;
+//# sourceMappingURL=transport-stub.d.ts.map

package/dist/transport-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-stub.d.ts","sourceRoot":"","sources":["../src/transport-stub.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAA2B,MAAM,YAAY,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qGAAqG;AACrG,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,uBAAuB,CAoBzG"}

package/dist/transport-stub.js

@@ -0,0 +1,23 @@
+/** In-memory map for tests and offline development; not a substitute for real Keys in production. */
+export function createStubKeysTransport(map) {
+    return {
+        async resolve(logicalRef) {
+            const hit = map[logicalRef];
+            if (!hit) {
+                return {
+                    ok: false,
+                    code: "unknown_ref",
+                    message: `Stub Keys transport: no entry for logical ref "${logicalRef}"`,
+                };
+            }
+            return {
+                ok: true,
+                provider: hit.provider,
+                model: hit.model,
+                secretEnvVar: hit.secretEnvVar,
+                baseUrl: hit.baseUrl,
+            };
+        },
+    };
+}
+//# sourceMappingURL=transport-stub.js.map

package/dist/transport-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-stub.js","sourceRoot":"","sources":["../src/transport-stub.ts"],"names":[],"mappings":"AAUA,qGAAqG;AACrG,MAAM,UAAU,uBAAuB,CAAC,GAAwC;IAC9E,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,UAAkB;YAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;YAC5B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,kDAAkD,UAAU,GAAG;iBACzE,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,OAAO,EAAE,GAAG,CAAC,OAAO;aACrB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import type { KeysModelMeta } from "@restormel/testing-core";
+/**
+ * Documented HTTP contract (placeholder until Keys publishes a stable public API).
+ * Keys should respond with 200 and this JSON shape. Adapter does not implement Keys-side logic.
+ */
+export interface KeysHttpResolveResponseBody {
+    provider: string;
+    model: string;
+    /** Environment variable name holding the provider API key (BYOK), not the secret value. */
+    secretEnvVar: string;
+    /** Optional OpenAI-compatible API base URL. */
+    baseUrl?: string;
+}
+export interface ResolvedModel {
+    /** Safe to log and attach to RunRecord.keysModelMeta. */
+    meta: KeysModelMeta;
+    /** Provider API model id for requests. */
+    modelId: string;
+    /** OpenAI-compatible base URL if applicable. */
+    providerBaseUrl?: string;
+    /**
+     * In-memory credentials only. Never JSON.stringify, log, or write to artefacts.
+     */
+    credentials: {
+        apiKey: string;
+    };
+}
+export type KeysAdapterErrorCode = "invalid_ref" | "keys_not_configured" | "keys_unreachable" | "keys_rejected" | "keys_missing_secret_binding" | "fallback_disabled" | "fallback_missing_env";
+export interface KeysAdapterError {
+    code: KeysAdapterErrorCode;
+    message: string;
+    cause?: unknown;
+}
+export type ModelResolutionResult = {
+    ok: true;
+    model: ResolvedModel;
+    warnings: string[];
+} | {
+    ok: false;
+    error: KeysAdapterError;
+};
+/** Swappable transport: HTTP to Keys, in-memory stub, or future SDK. */
+export interface KeysResolutionTransport {
+    resolve(logicalRef: string): Promise<KeysTransportResolution>;
+}
+export type KeysTransportResolution = {
+    ok: true;
+    provider: string;
+    model: string;
+    secretEnvVar: string;
+    baseUrl?: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    cause?: unknown;
+};
+/**
+ * When Keys cannot resolve, optionally use a single OpenAI-compatible env key (documented escape hatch).
+ */
+export interface OpenAiEnvFallbackOptions {
+    enabled: boolean;
+    /** Env var for the API key (default OPENAI_API_KEY). */
+    apiKeyEnvVar?: string;
+    /** Model id when using fallback (default gpt-4o-mini). */
+    defaultModel?: string;
+    /** Optional base URL (default official API). */
+    baseUrl?: string;
+    /** Logical ref this fallback applies to; if omitted, applies to any ref when Keys fails. */
+    forLogicalRef?: string;
+}
+export interface KeysModelAdapterOptions {
+    /**
+     * Try transport first (Keys). If unset and no fallback, resolution fails unless you inject a transport via factory.
+     */
+    transport?: KeysResolutionTransport;
+    /** POST JSON to `${baseUrl}/v1/testing/resolve-model` when transport not passed explicitly. */
+    keysApiBaseUrl?: string;
+    /** Env var holding bearer token for the Keys HTTP API (optional). */
+    keysApiTokenEnvVar?: string;
+    openAiEnvFallback?: OpenAiEnvFallbackOptions;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,IAAI,EAAE,aAAa,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,qBAAqB,GACrB,kBAAkB,GAClB,eAAe,GACf,6BAA6B,GAC7B,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE3C,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC/D;AAED,MAAM,MAAM,uBAAuB,GAC/B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@restormel/testing-keys-adapter",
+  "version": "0.1.0",
+  "description": "Restormel / Keys resolution and BYOK execution seam (scaffold).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Allotment-Technology-Ltd/restormel-testing.git",
+    "directory": "packages/keys-adapter"
+  },
+  "bugs": {
+    "url": "https://github.com/Allotment-Technology-Ltd/restormel-testing/issues"
+  },
+  "homepage": "https://github.com/Allotment-Technology-Ltd/restormel-testing/tree/main/packages/keys-adapter#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@restormel/testing-core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json"
+  }
+}