@fonoster/common 0.27.0 → 0.30.0

package/dist/registry/prisma.js

@@ -0,0 +1,391 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaUsageSource = exports.PrismaRegistryStore = void 0;
+exports.openPrismaClient = openPrismaClient;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const WriteBehind_1 = require("../utils/WriteBehind");
+const stores_1 = require("./stores");
+const toState = (s) => s.toUpperCase();
+const fromState = (s) => s.toLowerCase();
+const opt = (v) => (v === null ? undefined : v);
+/** Drops undefined keys so loaded entries equal the ones the registry wrote. */
+function clean(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+class PrismaRegistryStore extends stores_1.MemoryRegistryStore {
+    constructor(prisma) {
+        super();
+        this.prisma = prisma;
+        this.writes = new WriteBehind_1.WriteBehind();
+    }
+    /** Opens the store with the current catalog and audit log loaded. */
+    static open(prisma) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const store = new PrismaRegistryStore(prisma);
+            yield store.refresh();
+            return store;
+        });
+    }
+    /** Reloads the catalog (and audit log) from the database, after pending writes. */
+    refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.writes.flush();
+            const [providers, models, voices, audit] = yield Promise.all([
+                this.prisma.registryProvider.findMany(),
+                this.prisma.registryModel.findMany(),
+                this.prisma.registryVoice.findMany({
+                    include: { models: { orderBy: { position: "asc" } } }
+                }),
+                this.prisma.registryAudit.findMany({ orderBy: { seq: "asc" } })
+            ]);
+            const entries = new Map();
+            for (const p of providers)
+                entries.set(p.id, clean({
+                    kind: "provider",
+                    id: p.id,
+                    adapter: p.adapter,
+                    capabilities: p.capabilities,
+                    credentialRef: p.credentialRef,
+                    state: fromState(p.state),
+                    replacement: opt(p.replacement),
+                    retireOn: opt(p.retireOn)
+                }));
+            for (const m of models)
+                entries.set(m.id, clean({
+                    kind: "model",
+                    id: m.id,
+                    type: m.type,
+                    features: m.features,
+                    languages: m.languages,
+                    settings: m.settings,
+                    state: fromState(m.state),
+                    replacement: opt(m.replacement),
+                    retireOn: opt(m.retireOn)
+                }));
+            for (const v of voices)
+                entries.set(v.id, clean({
+                    kind: "voice",
+                    id: v.id,
+                    models: v.models.map((r) => r.modelId),
+                    language: opt(v.language),
+                    gender: opt(v.gender),
+                    ownerWorkspace: opt(v.ownerWorkspace),
+                    state: fromState(v.state),
+                    replacement: opt(v.replacement),
+                    retireOn: opt(v.retireOn)
+                }));
+            this.entries = entries;
+            this.log = audit.map((a) => clean({
+                at: a.at.toISOString(),
+                actor: a.actor,
+                action: a.action,
+                target: a.target,
+                details: opt(a.details)
+            }));
+        });
+    }
+    put(entry) {
+        var _a, _b;
+        super.put(entry);
+        const e = JSON.parse(JSON.stringify(entry));
+        const common = {
+            state: toState(e.state),
+            replacement: (_a = e.replacement) !== null && _a !== void 0 ? _a : null,
+            retireOn: (_b = e.retireOn) !== null && _b !== void 0 ? _b : null
+        };
+        const provider = e.id.split("/")[0];
+        this.writes.push(() => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (e.kind === "provider") {
+                const data = Object.assign({ adapter: e.adapter, capabilities: e.capabilities, credentialRef: e.credentialRef }, common);
+                yield this.prisma.registryProvider.upsert({
+                    where: { id: e.id },
+                    create: Object.assign({ id: e.id }, data),
+                    update: data
+                });
+            }
+            else if (e.kind === "model") {
+                const data = Object.assign({ providerId: provider, type: e.type, features: e.features, languages: e.languages, settings: e.settings }, common);
+                yield this.prisma.registryModel.upsert({
+                    where: { id: e.id },
+                    create: Object.assign({ id: e.id }, data),
+                    update: data
+                });
+            }
+            else {
+                const data = Object.assign({ providerId: provider, language: (_a = e.language) !== null && _a !== void 0 ? _a : null, gender: (_b = e.gender) !== null && _b !== void 0 ? _b : null, ownerWorkspace: (_c = e.ownerWorkspace) !== null && _c !== void 0 ? _c : null }, common);
+                yield this.prisma.$transaction([
+                    this.prisma.registryVoice.upsert({
+                        where: { id: e.id },
+                        create: Object.assign({ id: e.id }, data),
+                        update: data
+                    }),
+                    this.prisma.registryVoiceModel.deleteMany({
+                        where: { voiceId: e.id }
+                    }),
+                    this.prisma.registryVoiceModel.createMany({
+                        data: e.models.map((modelId, position) => ({
+                            voiceId: e.id,
+                            modelId,
+                            position
+                        }))
+                    })
+                ]);
+            }
+        }));
+    }
+    audit(entry) {
+        super.audit(entry);
+        this.writes.push(() => {
+            var _a;
+            return this.prisma.registryAudit.create({
+                data: {
+                    at: new Date(entry.at),
+                    actor: entry.actor,
+                    action: entry.action,
+                    target: entry.target,
+                    details: (_a = entry.details) !== null && _a !== void 0 ? _a : undefined
+                }
+            });
+        });
+    }
+    /** Waits for every queued write; throws the first failure. */
+    flush() {
+        return this.writes.flush();
+    }
+}
+exports.PrismaRegistryStore = PrismaRegistryStore;
+/**
+ * Usages of catalog ids in apps (speech defaults: voice, TTS and STT models) and assistants (the
+ * Autopilot assistant in an app's Intelligence config: `languageModel.model`, and
+ * `conversationSettings.voice`). Legacy rows with raw vendor names are not usages until migrated
+ * to catalog ids (task 5.1).
+ */
+class PrismaUsageSource {
+    constructor(prisma, options) {
+        this.prisma = prisma;
+        this.options = options;
+        this.rows = [];
+        this.origins = new WeakMap();
+        this.writes = new WriteBehind_1.WriteBehind();
+        /** Rewrites skipped because the config changed after it was read. */
+        this.conflicts = [];
+    }
+    static open(prisma_1) {
+        return __awaiter(this, arguments, void 0, function* (prisma, options = {}) {
+            const source = new PrismaUsageSource(prisma, options);
+            yield source.refresh();
+            return source;
+        });
+    }
+    refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.writes.flush();
+            this.rows = yield this.prisma.application.findMany({
+                select: {
+                    ref: true,
+                    accessKeyId: true,
+                    name: true,
+                    speechVoice: true,
+                    speechSttModel: true,
+                    speechTtsModel: true,
+                    speechSettings: true,
+                    intelligence: { select: { config: true } }
+                },
+                orderBy: { ref: "asc" }
+            });
+        });
+    }
+    find(id) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const out = [];
+        const add = (usage, origin) => {
+            this.origins.set(usage, origin);
+            out.push(usage);
+        };
+        for (const row of this.rows) {
+            const app = { kind: "app", ref: row.ref, name: row.name };
+            if (row.speechVoice === id || row.speechTtsModel === id) {
+                add({
+                    workspace: row.accessKeyId,
+                    config: app,
+                    model: (_a = row.speechTtsModel) !== null && _a !== void 0 ? _a : undefined,
+                    voice: (_b = row.speechVoice) !== null && _b !== void 0 ? _b : undefined,
+                    settings: Object.keys((_c = row.speechSettings) !== null && _c !== void 0 ? _c : {}),
+                    requires: ["streaming"]
+                }, { kind: "app-tts", row });
+            }
+            if (row.speechSttModel === id) {
+                add({
+                    workspace: row.accessKeyId,
+                    config: app,
+                    model: id,
+                    settings: [],
+                    requires: ["streaming"]
+                }, { kind: "app-stt", row });
+            }
+            const assistant = (_d = row.intelligence) === null || _d === void 0 ? void 0 : _d.config;
+            const llm = (_e = assistant === null || assistant === void 0 ? void 0 : assistant.languageModel) === null || _e === void 0 ? void 0 : _e.model;
+            const config = {
+                kind: "assistant",
+                ref: row.ref,
+                name: row.name
+            };
+            if (llm === id) {
+                add({
+                    workspace: row.accessKeyId,
+                    config,
+                    model: llm,
+                    settings: [],
+                    requires: ((_g = (_f = assistant === null || assistant === void 0 ? void 0 : assistant.languageModel) === null || _f === void 0 ? void 0 : _f.tools) === null || _g === void 0 ? void 0 : _g.length)
+                        ? ["streaming", "tool-calling"]
+                        : ["streaming"]
+                }, { kind: "assistant-llm", row, model: llm });
+            }
+            const voice = (_h = assistant === null || assistant === void 0 ? void 0 : assistant.conversationSettings) === null || _h === void 0 ? void 0 : _h.voice;
+            if (voice === id) {
+                add({
+                    workspace: row.accessKeyId,
+                    config,
+                    model: (_j = row.speechTtsModel) !== null && _j !== void 0 ? _j : undefined,
+                    voice,
+                    settings: [],
+                    requires: ["streaming"]
+                }, { kind: "assistant-voice", row, voice });
+            }
+        }
+        return out;
+    }
+    /**
+     * Queues the rewrite. The write only applies if the field still holds the value read; otherwise
+     * it is skipped, audited by the caller's flush report (`conflicts`), and the config keeps its id.
+     */
+    rewrite(usage, change) {
+        var _a, _b;
+        const origin = this.origins.get(usage);
+        if (!origin)
+            return false;
+        const row = origin.row;
+        const conflict = (reason) => this.conflicts.push({ usage, reason });
+        if (origin.kind === "app-tts" || origin.kind === "app-stt") {
+            const where = { ref: row.ref };
+            const data = { updatedAt: new Date() };
+            if (origin.kind === "app-stt") {
+                where.speechSttModel = row.speechSttModel;
+                if (change.model)
+                    data.speechSttModel = change.model;
+            }
+            else {
+                where.speechVoice = row.speechVoice;
+                where.speechTtsModel = row.speechTtsModel;
+                if (change.model)
+                    data.speechTtsModel = change.model;
+                if (change.voice)
+                    data.speechVoice = change.voice;
+                if (change.dropSettings.length && row.speechSettings) {
+                    data.speechSettings = Object.fromEntries(Object.entries(row.speechSettings).filter(([k]) => !change.dropSettings.includes(k)));
+                }
+            }
+            this.writes.push(() => __awaiter(this, void 0, void 0, function* () {
+                const { count } = yield this.prisma.application.updateMany({
+                    where,
+                    data
+                });
+                if (count === 0)
+                    conflict("app changed since it was read");
+            }));
+            return true;
+        }
+        const config = JSON.parse(JSON.stringify((_b = (_a = row.intelligence) === null || _a === void 0 ? void 0 : _a.config) !== null && _b !== void 0 ? _b : {}));
+        let path;
+        let expected;
+        if (origin.kind === "assistant-llm") {
+            path = ["languageModel", "model"];
+            expected = origin.model;
+            if (change.model)
+                config.languageModel.model = change.model;
+        }
+        else {
+            path = ["conversationSettings", "voice"];
+            expected = origin.voice;
+            if (change.voice)
+                config.conversationSettings.voice = change.voice;
+        }
+        this.writes.push(() => __awaiter(this, void 0, void 0, function* () {
+            const { count } = yield this.prisma.intelligence.updateMany({
+                where: { applicationRef: row.ref, config: { path, equals: expected } },
+                data: { config }
+            });
+            if (count === 0)
+                conflict("assistant changed since it was read");
+            else
+                yield this.prisma.application.update({
+                    where: { ref: row.ref },
+                    data: { updatedAt: new Date() }
+                });
+        }));
+        return true;
+    }
+    notify(workspace, notice) {
+        this.writes.push(() => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            yield this.prisma.registryNotice.create({
+                data: {
+                    accessKeyId: workspace,
+                    type: String(notice.type),
+                    data: notice
+                }
+            });
+            (_b = (_a = this.options).onNotice) === null || _b === void 0 ? void 0 : _b.call(_a, workspace, notice);
+        }));
+    }
+    /** Waits for every queued write; throws the first failure. */
+    flush() {
+        return this.writes.flush();
+    }
+}
+exports.PrismaUsageSource = PrismaUsageSource;
+/**
+ * Opens a Prisma client generated from the apiserver's schema, with field encryption when a key
+ * is given. Loaded at run time so `@fonoster/common` does not depend on a generated client.
+ */
+function openPrismaClient(options) {
+    var _a, _b;
+    /* eslint-disable @typescript-eslint/no-var-requires */
+    const { PrismaClient, Prisma } = require((_b = (_a = options.clientModule) !== null && _a !== void 0 ? _a : process.env.FONOSTER_PRISMA_CLIENT) !== null && _b !== void 0 ? _b : "@prisma/client");
+    const client = new PrismaClient({ datasourceUrl: options.url });
+    if (!options.encryptionKey)
+        return client;
+    const { fieldEncryptionExtension } = require("prisma-field-encryption");
+    /* eslint-enable @typescript-eslint/no-var-requires */
+    return client.$extends(fieldEncryptionExtension({
+        encryptionKey: options.encryptionKey,
+        dmmf: Prisma === null || Prisma === void 0 ? void 0 : Prisma.dmmf
+    }));
+}

package/dist/registry/stores.d.ts

@@ -0,0 +1,21 @@
+import { AuditEntry, CatalogEntry, RegistryStore } from "./types";
+export declare class MemoryRegistryStore implements RegistryStore {
+    protected entries: Map<string, CatalogEntry>;
+    protected log: AuditEntry[];
+    all(): CatalogEntry[];
+    get(id: string): CatalogEntry;
+    put(entry: CatalogEntry): void;
+    audit(entry: AuditEntry): void;
+    history(id?: string): AuditEntry[];
+}
+/**
+ * A JSON file store, for the operator utility until the registry tables exist (see build-log.md).
+ * Every write rewrites the file atomically.
+ */
+export declare class FileRegistryStore extends MemoryRegistryStore {
+    private readonly file;
+    constructor(file: string);
+    put(entry: CatalogEntry): void;
+    audit(entry: AuditEntry): void;
+    private save;
+}

package/dist/{assistants/eventsHookSchema.js → registry/stores.js}

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventsHookAllowedEvents = exports.eventsHookSchema = void 0;
+exports.FileRegistryStore = exports.MemoryRegistryStore = void 0;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -52,20 +52,57 @@ exports.EventsHookAllowedEvents = exports.eventsHookSchema = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const zod_1 = require("zod");
-const Messages = __importStar(require("../messages"));
-var EventsHookAllowedEvents;
-(function (EventsHookAllowedEvents) {
-    EventsHookAllowedEvents["ALL"] = "all";
-    EventsHookAllowedEvents["CONVERSATION_STARTED"] = "conversation.started";
-    EventsHookAllowedEvents["CONVERSATION_ENDED"] = "conversation.ended";
-})(EventsHookAllowedEvents || (exports.EventsHookAllowedEvents = EventsHookAllowedEvents = {}));
-const eventsHookSchema = zod_1.z.object({
-    url: zod_1.z.string().url({ message: Messages.VALID_URL }),
-    headers: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
-    events: zod_1.z
-        .array(zod_1.z.nativeEnum(EventsHookAllowedEvents))
-        .min(1)
-        .default([EventsHookAllowedEvents.ALL])
-});
-exports.eventsHookSchema = eventsHookSchema;
+const fs = __importStar(require("fs"));
+class MemoryRegistryStore {
+    constructor() {
+        this.entries = new Map();
+        this.log = [];
+    }
+    all() {
+        return [...this.entries.values()].sort((a, b) => a.id.localeCompare(b.id));
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    put(entry) {
+        this.entries.set(entry.id, JSON.parse(JSON.stringify(entry)));
+    }
+    audit(entry) {
+        this.log.push(entry);
+    }
+    history(id) {
+        return id ? this.log.filter((e) => e.target === id) : [...this.log];
+    }
+}
+exports.MemoryRegistryStore = MemoryRegistryStore;
+/**
+ * A JSON file store, for the operator utility until the registry tables exist (see build-log.md).
+ * Every write rewrites the file atomically.
+ */
+class FileRegistryStore extends MemoryRegistryStore {
+    constructor(file) {
+        var _a;
+        super();
+        this.file = file;
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            for (const e of data.entries)
+                this.entries.set(e.id, e);
+            this.log = (_a = data.audit) !== null && _a !== void 0 ? _a : [];
+        }
+    }
+    put(entry) {
+        super.put(entry);
+        this.save();
+    }
+    audit(entry) {
+        super.audit(entry);
+        this.save();
+    }
+    save() {
+        const tmp = `${this.file}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ entries: this.all(), audit: this.log }, null, 2));
+        fs.renameSync(tmp, this.file);
+    }
+}
+exports.FileRegistryStore = FileRegistryStore;

package/dist/registry/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export type Lifecycle = "active" | "deprecated" | "retired";
+export type Capability = "stt" | "tts" | "llm";
+export type ItemKind = "provider" | "model" | "voice";
+export type ProviderEntry = {
+    kind: "provider";
+    id: string;
+    adapter: string;
+    capabilities: Capability[];
+    credentialRef: string;
+    state: Lifecycle;
+    replacement?: string;
+    retireOn?: string;
+};
+export type ModelEntry = {
+    kind: "model";
+    id: string;
+    type: Capability;
+    features: string[];
+    languages: string[];
+    /** Settings the model accepts (for example "style", "stability"). */
+    settings: string[];
+    state: Lifecycle;
+    replacement?: string;
+    retireOn?: string;
+};
+export type VoiceEntry = {
+    kind: "voice";
+    id: string;
+    models: string[];
+    language?: string;
+    gender?: string;
+    /** Set for a workspace's own (cloned) voice. */
+    ownerWorkspace?: string;
+    state: Lifecycle;
+    replacement?: string;
+    retireOn?: string;
+};
+export type CatalogEntry = ProviderEntry | ModelEntry | VoiceEntry;
+export type AuditEntry = {
+    at: string;
+    actor: string;
+    action: string;
+    target: string;
+    details?: Record<string, unknown>;
+};
+/** One place a catalog id is used: an app's speech config or an assistant's model config. */
+export type Usage = {
+    workspace: string;
+    config: {
+        kind: "app" | "assistant";
+        ref: string;
+        name: string;
+    };
+    model?: string;
+    voice?: string;
+    /** Settings the config sets on the model (dropped when the replacement does not accept them). */
+    settings: string[];
+    /** Hard features the config needs (derived from its content, e.g. tools need tool-calling). */
+    requires: string[];
+};
+/** Where usages come from (apps and assistants in the control-plane database). */
+export interface UsageSource {
+    find(id: string): Usage[];
+    /** Rewrites one config; returns false if it changed since it was read. */
+    rewrite(usage: Usage, change: {
+        model?: string;
+        voice?: string;
+        dropSettings: string[];
+    }): boolean;
+    /** Tells a workspace about a change (dashboard notice). */
+    notify(workspace: string, notice: Record<string, unknown>): void;
+}
+/** Where the catalog and the audit log are kept. */
+export interface RegistryStore {
+    all(): CatalogEntry[];
+    get(id: string): CatalogEntry | undefined;
+    put(entry: CatalogEntry): void;
+    audit(entry: AuditEntry): void;
+    history(id?: string): AuditEntry[];
+}

package/dist/{voice/Say.d.ts → registry/types.js}

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -16,13 +17,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Struct } from "pb-util";
-import { VerbRequest } from "./Verb";
-type SayRequest = VerbRequest & {
-    text: string;
-    options?: Struct;
-};
-type SayOptions = {
-    [key: string]: any;
-};
-export { SayOptions, SayRequest };
+// The provider registry (add-provider-registry): providers, models and voices by catalog id,
+// with a manual lifecycle. The catalog never holds a secret: providers name a credentialRef.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/workspaceKeys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { PrismaLike } from "./prisma";
+export type WorkspaceKeysOptions = {
+    /** How long a looked-up key (or its absence) is reused (default 30 s). */
+    cacheMs?: number;
+    now?: () => number;
+};
+export declare class PrismaWorkspaceKeys {
+    private readonly prisma;
+    private readonly options;
+    private cache;
+    constructor(prisma: PrismaLike, options?: WorkspaceKeysOptions);
+    private now;
+    /** The workspace's key for a provider, or undefined (then the platform key applies). */
+    get(workspaceRef: string, providerId: string): Promise<string | undefined>;
+    /**
+     * The workspace's key for a credentialRef: the providers that use that ref (from the catalog)
+     * are tried in order.
+     */
+    forCredentialRef(workspaceRef: string, credentialRef: string, providers: {
+        id: string;
+        credentialRef: string;
+    }[]): Promise<string | undefined>;
+}