@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/ai/keys/org-keys.controller.js

@@ -0,0 +1,129 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiOrgKeysController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const index_1 = require("../../core/index");
+const index_2 = require("../../identity/index");
+const ai_constants_1 = require("../ai.constants");
+const org_ai_key_dto_1 = require("./dto/org-ai-key.dto");
+const org_key_service_1 = require("./org-key.service");
+// =============================================================================
+// /api/admin/ai/org-keys — an organization's own AI provider keys (issue #739)
+// =============================================================================
+//
+// ORG SCOPE: `org_ai_config:read` / `org_ai_config:write`, held through the
+// caller's membership role in their ACTIVE organization (`org_admin` by
+// default). The organization is always the principal's, never request input.
+//
+// DELIBERATELY NOT behind `AiEnabledGuard` (CLAUDE.md AI rule 4): like every
+// `/api/admin/ai/*` route, an administrator can always reach it.
+//
+// WRITE-ONLY: a key is verified with the provider, stored through the
+// credentials slice's `OrgCredentialsService`, and never returned: the
+// responses are masked views (`configured`, `hint`, `verifiedAt`).
+// =============================================================================
+const PROVIDER_PARAM = {
+    name: 'provider',
+    description: 'Provider id, e.g. `openai`.',
+    example: 'openai',
+};
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+let AiOrgKeysController = class AiOrgKeysController {
+    orgKeys;
+    constructor(orgKeys) {
+        this.orgKeys = orgKeys;
+    }
+    async list(orgId) {
+        return this.orgKeys.list(orgId);
+    }
+    async set(provider, dto, orgId, userId) {
+        return this.orgKeys.set(orgId, provider, dto.apiKey, userId);
+    }
+    async remove(provider, orgId, userId) {
+        await this.orgKeys.remove(orgId, provider, userId);
+    }
+};
+exports.AiOrgKeysController = AiOrgKeysController;
+__decorate([
+    (0, common_1.Get)(),
+    (0, index_2.Auth)({ permissions: [ai_constants_1.PERMISSIONS.ORG_AI_CONFIG_READ] }),
+    (0, swagger_1.ApiOperation)({
+        summary: "List your organization's AI provider keys",
+        description: 'One entry per registered provider: whether your organization stored a key, its last ' +
+            'characters (`hint`) and when it was verified and stored (`verifiedAt`). **Never the key.** ' +
+            'Reachable while AI is disabled.',
+    }),
+    (0, index_1.ApiDataResponse)(org_ai_key_dto_1.OrgAiKeyViewDto, { isArray: true, description: "The organization's keys, masked" }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'Missing `org_ai_config:read` in the active organization', type: index_1.ErrorDto }),
+    __param(0, (0, index_2.CurrentOrg)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AiOrgKeysController.prototype, "list", null);
+__decorate([
+    (0, common_1.Put)(':provider'),
+    (0, index_2.Auth)({ permissions: [ai_constants_1.PERMISSIONS.ORG_AI_CONFIG_WRITE] }),
+    (0, swagger_1.ApiOperation)({
+        summary: "Set or replace your organization's key for a provider",
+        description: 'The key is **verified against the provider first** (the adapter’s own test call) and ' +
+            'stored, encrypted, only when it passes. A rejected key answers **400** with ' +
+            '`details.reason: "AI_KEY_INVALID"` and nothing is stored. Audited with the ' +
+            "organization's id. **Write-only**: the response is the masked entry.",
+    }),
+    (0, swagger_1.ApiParam)(PROVIDER_PARAM),
+    (0, index_1.ApiDataResponse)(org_ai_key_dto_1.OrgAiKeyViewDto, { description: 'The stored key, masked' }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'Validation error, or `AI_KEY_INVALID`', type: index_1.ErrorDto }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'Missing `org_ai_config:write` in the active organization', type: index_1.ErrorDto }),
+    (0, swagger_1.ApiResponse)({ status: 404, description: 'Unknown provider', type: index_1.ErrorDto }),
+    (0, swagger_1.ApiResponse)({ status: 503, description: 'The provider could not be reached to verify the key', type: index_1.ErrorDto }),
+    __param(0, (0, common_1.Param)('provider')),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_2.CurrentOrg)()),
+    __param(3, (0, index_2.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, org_ai_key_dto_1.SetOrgAiKeyDto, String, String]),
+    __metadata("design:returntype", Promise)
+], AiOrgKeysController.prototype, "set", null);
+__decorate([
+    (0, common_1.Delete)(':provider'),
+    (0, index_2.Auth)({ permissions: [ai_constants_1.PERMISSIONS.ORG_AI_CONFIG_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    (0, swagger_1.ApiOperation)({
+        summary: "Remove your organization's key for a provider",
+        description: 'Idempotent: removing a key that is not there is a 204. Audited.',
+    }),
+    (0, swagger_1.ApiParam)(PROVIDER_PARAM),
+    (0, swagger_1.ApiResponse)({ status: 204, description: 'Removed (or there was nothing to remove)' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'Missing `org_ai_config:write` in the active organization', type: index_1.ErrorDto }),
+    (0, swagger_1.ApiResponse)({ status: 404, description: 'Unknown provider', type: index_1.ErrorDto }),
+    __param(0, (0, common_1.Param)('provider')),
+    __param(1, (0, index_2.CurrentOrg)()),
+    __param(2, (0, index_2.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String]),
+    __metadata("design:returntype", Promise)
+], AiOrgKeysController.prototype, "remove", null);
+exports.AiOrgKeysController = AiOrgKeysController = __decorate([
+    (0, swagger_1.ApiTags)('AI Administration'),
+    (0, common_1.Controller)('admin/ai/org-keys'),
+    __metadata("design:paramtypes", [org_key_service_1.AiOrgKeyService])
+], AiOrgKeysController);
+//# sourceMappingURL=org-keys.controller.js.map

package/dist/ai/keys/org-keys.controller.js.map

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

package/dist/ai/keys/usable-models.service.d.ts

@@ -0,0 +1,48 @@
+import type { AiPrisma } from '../data/ai-db';
+import { AiConfigService } from '../config/ai-config.service';
+import { type AiCapability } from '../core/capabilities';
+import { AiProviderRegistry } from '../core/provider-registry';
+import { AiKeyResolver, type AiKeySource } from './ai-key-resolver.service';
+import type { UsableAiModel } from './dto/usable-ai-model.dto';
+/**
+ * The models one user can actually call right now: enabled by an
+ * administrator, on an enabled provider, and reachable with the key that would
+ * pay (the user's own, or an administrator-managed one the policy lets serve
+ * them).
+ *
+ * @stability experimental
+ */
+export declare class UsableModelsService {
+    private readonly prisma;
+    private readonly aiConfig;
+    private readonly registry;
+    private readonly resolver;
+    constructor(prisma: AiPrisma, aiConfig: AiConfigService, registry: AiProviderRegistry, resolver: AiKeyResolver);
+    /**
+     * Every model `userId` can call right now, by provider then model id. With
+     * `scope.orgId` (#739) the organization's own switches and key apply too.
+     */
+    listForUser(userId: string, scope?: {
+        orgId?: string;
+    }): Promise<UsableAiModel[]>;
+    /**
+     * Refuse, with the precise reason, a call `userId` cannot make:
+     *
+     *   AI_DISABLED / AI_PROVIDER_DISABLED  the platform or provider is off
+     *   AI_MODEL_NOT_ENABLED                unknown, not admin-enabled, or deprecated
+     *   AI_CAPABILITY_UNSUPPORTED           the model (or provider) lacks a needed capability
+     *   AI_KEY_REQUIRED                     no key resolves (AiKeyResolver's rule)
+     *   AI_MODEL_NOT_REACHABLE              the user's key cannot reach this model
+     *
+     * Decrypts nothing — the runtime resolves the key itself, afterwards.
+     */
+    assertUsable(userId: string, provider: string, modelId: string, capability?: AiCapability | readonly AiCapability[], scope?: {
+        orgId?: string;
+    }): Promise<{
+        /** The model, as `listForUser` lists it. */
+        model: UsableAiModel;
+        /** Who would pay. */
+        keySource: AiKeySource;
+    }>;
+}
+//# sourceMappingURL=usable-models.service.d.ts.map

package/dist/ai/keys/usable-models.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usable-models.service.d.ts","sourceRoot":"","sources":["../../../src/ai/keys/usable-models.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAkB,MAAM,6BAA6B,CAAC;AAE9E,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAe,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAoC/D;;;;;;;GAOG;AACH,qBACa,mBAAmB;IAEH,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAHiB,MAAM,EAAE,QAAQ,EACzC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,aAAa;IAG1C;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAkE3F;;;;;;;;;;OAUG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,EACnD,KAAK,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7B,OAAO,CAAC;QACT,4CAA4C;QAC5C,KAAK,EAAE,aAAa,CAAC;QACrB,qBAAqB;QACrB,SAAS,EAAE,WAAW,CAAC;KACxB,CAAC;CAwDH"}

package/dist/ai/keys/usable-models.service.js

@@ -0,0 +1,186 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsableModelsService = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const ai_catalog_service_1 = require("../catalog/ai-catalog.service");
+const ai_config_service_1 = require("../config/ai-config.service");
+const ai_error_1 = require("../core/ai-error");
+const capabilities_1 = require("../core/capabilities");
+const provider_registry_1 = require("../core/provider-registry");
+const ai_key_resolver_service_1 = require("./ai-key-resolver.service");
+// =============================================================================
+// UsableModelsService — "which models can I use?" (issue #431, epic #419)
+// =============================================================================
+//
+// docs/specs/ai-platform.md §2.18. Not a new source of truth: it intersects two
+// facts that already exist —
+//
+//   - the ADMIN's decision: `ai_models` rows with `enabled` and no
+//     `deprecatedAt`;
+//   - the KEY's reach: the user's `reachableModelIds` (computed when the key
+//     was set, refreshed weekly and on every stored-key test), or — when the
+//     org key serves the provider (the fallback policy, or the caller holds
+//     `ai_config:write`, #593) — no restriction beyond the admin's.
+//
+// Which key serves a provider is `AiKeyResolver.sourceFor`'s answer, never
+// re-derived here, so the usable list and the runtime can never disagree
+// about whether the org key applies.
+//
+// `assertUsable` is the single-model form, called by the runtime's gate
+// pipeline (#432) before any provider call, and the one place the model-gate
+// error codes originate.
+// =============================================================================
+const MODEL_SELECT = {
+    provider: true,
+    modelId: true,
+    displayName: true,
+    capabilities: true,
+    enabled: true,
+    deprecatedAt: true,
+};
+/**
+ * The models one user can actually call right now: enabled by an
+ * administrator, on an enabled provider, and reachable with the key that would
+ * pay (the user's own, or an administrator-managed one the policy lets serve
+ * them).
+ *
+ * @stability experimental
+ */
+let UsableModelsService = class UsableModelsService {
+    prisma;
+    aiConfig;
+    registry;
+    resolver;
+    constructor(prisma, aiConfig, registry, resolver) {
+        this.prisma = prisma;
+        this.aiConfig = aiConfig;
+        this.registry = registry;
+        this.resolver = resolver;
+    }
+    /**
+     * Every model `userId` can call right now, by provider then model id. With
+     * `scope.orgId` (#739) the organization's own switches and key apply too.
+     */
+    async listForUser(userId, scope = {}) {
+        const policy = await this.aiConfig.resolveForOrg(scope.orgId);
+        if (!policy.enabled) {
+            return [];
+        }
+        const providers = this.registry.ids().filter((id) => (0, ai_config_service_1.providerPolicy)(policy, id)?.enabled);
+        if (providers.length === 0) {
+            return [];
+        }
+        const [keyRows, modelRows] = await Promise.all([
+            this.prisma.userAiKey.findMany({
+                where: { userId, provider: { in: providers } },
+                select: { provider: true, reachableModelIds: true },
+            }),
+            this.prisma.aiModel.findMany({
+                where: { provider: { in: providers }, enabled: true, deprecatedAt: null },
+                select: MODEL_SELECT,
+            }),
+        ]);
+        const reachableByProvider = new Map(keyRows.map((row) => [row.provider, new Set(row.reachableModelIds)]));
+        const usable = [];
+        // Rule 2's permission lookup, at most once per listing — and only if some
+        // provider without a user key actually reaches that rule.
+        let writer;
+        const holdsAiConfigWrite = () => (writer ??= this.resolver.holdsAiConfigWrite(userId));
+        // And the org tier's (#739), likewise memoised.
+        let orgWriter;
+        const orgId = scope.orgId;
+        const holdsOrgAiConfigWrite = orgId
+            ? () => (orgWriter ??= this.resolver.holdsOrgAiConfigWrite(userId, orgId))
+            : undefined;
+        for (const provider of providers) {
+            const reachable = reachableByProvider.get(provider);
+            const keySource = await this.resolver.sourceFor(userId, provider, reachable !== undefined, holdsAiConfigWrite, { ...(orgId ? { orgId } : {}), ...(holdsOrgAiConfigWrite ? { holdsOrgAiConfigWrite } : {}) });
+            if (!keySource) {
+                continue;
+            }
+            for (const row of modelRows) {
+                if (row.provider !== provider)
+                    continue;
+                if (keySource === 'user' && !reachable?.has(row.modelId))
+                    continue;
+                usable.push(toUsable(row, keySource));
+            }
+        }
+        return usable.sort((a, b) => a.provider.localeCompare(b.provider) || a.modelId.localeCompare(b.modelId));
+    }
+    /**
+     * Refuse, with the precise reason, a call `userId` cannot make:
+     *
+     *   AI_DISABLED / AI_PROVIDER_DISABLED  the platform or provider is off
+     *   AI_MODEL_NOT_ENABLED                unknown, not admin-enabled, or deprecated
+     *   AI_CAPABILITY_UNSUPPORTED           the model (or provider) lacks a needed capability
+     *   AI_KEY_REQUIRED                     no key resolves (AiKeyResolver's rule)
+     *   AI_MODEL_NOT_REACHABLE              the user's key cannot reach this model
+     *
+     * Decrypts nothing — the runtime resolves the key itself, afterwards.
+     */
+    async assertUsable(userId, provider, modelId, capability, scope = {}) {
+        await this.aiConfig.assertProviderEnabled(provider, scope.orgId);
+        const row = await this.prisma.aiModel.findUnique({
+            where: { provider_modelId: { provider, modelId } },
+            select: MODEL_SELECT,
+        });
+        if (!row || !row.enabled || row.deprecatedAt) {
+            throw new ai_error_1.AiError('AI_MODEL_NOT_ENABLED', `Model "${modelId}" is not available in this deployment.`, { details: { provider, model: modelId } });
+        }
+        const capabilities = parseCapabilities(row.capabilities);
+        const needed = capability === undefined ? [] : typeof capability === 'string' ? [capability] : capability;
+        for (const cap of needed) {
+            if (!capabilities.capabilities.includes(cap) || !this.registry.supports(provider, cap)) {
+                throw new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `Model "${modelId}" does not support ${cap}.`, { details: { provider, model: modelId, capability: cap } });
+            }
+        }
+        const keyRow = await this.prisma.userAiKey.findUnique({
+            where: { userId_provider: { userId, provider } },
+            select: { reachableModelIds: true },
+        });
+        const keySource = await this.resolver.sourceFor(userId, provider, keyRow !== null, undefined, scope.orgId ? { orgId: scope.orgId } : {});
+        if (!keySource) {
+            throw (0, ai_key_resolver_service_1.keyRequired)(provider);
+        }
+        if (keySource === 'user' && !keyRow?.reachableModelIds.includes(modelId)) {
+            throw new ai_error_1.AiError('AI_MODEL_NOT_REACHABLE', `Your API key for "${provider}" cannot reach model "${modelId}".`, { details: { provider, model: modelId } });
+        }
+        return { model: toUsable(row, keySource), keySource };
+    }
+};
+exports.UsableModelsService = UsableModelsService;
+exports.UsableModelsService = UsableModelsService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object, ai_config_service_1.AiConfigService,
+        provider_registry_1.AiProviderRegistry,
+        ai_key_resolver_service_1.AiKeyResolver])
+], UsableModelsService);
+function parseCapabilities(value) {
+    const parsed = capabilities_1.aiModelCapabilitiesSchema.safeParse(value);
+    return parsed.success ? parsed.data : ai_catalog_service_1.EMPTY_AI_MODEL_CAPABILITIES;
+}
+function toUsable(row, keySource) {
+    return {
+        provider: row.provider,
+        modelId: row.modelId,
+        displayName: row.displayName,
+        capabilities: parseCapabilities(row.capabilities),
+        keySource,
+    };
+}
+//# sourceMappingURL=usable-models.service.js.map

package/dist/ai/keys/usable-models.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usable-models.service.js","sourceRoot":"","sources":["../../../src/ai/keys/usable-models.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAIpD,4CAAmD;AACnD,sEAA4E;AAC5E,mEAA8E;AAC9E,+CAA2C;AAC3C,uDAI8B;AAC9B,iEAA+D;AAC/D,uEAAyF;AAGzF,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,6BAA6B;AAC7B,EAAE;AACF,mEAAmE;AACnE,sBAAsB;AACtB,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,oEAAoE;AACpE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,qCAAqC;AACrC,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,yBAAyB;AACzB,gFAAgF;AAEhF,MAAM,YAAY,GAAG;IACnB,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,OAAO,EAAE,IAAI;IACb,YAAY,EAAE,IAAI;CACY,CAAC;AAIjC;;;;;;;GAOG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAEc;IACzB;IACA;IACA;IAJnB,YAC4C,MAAgB,EACzC,QAAyB,EACzB,QAA4B,EAC5B,QAAuB;QAHE,WAAM,GAAN,MAAM,CAAU;QACzC,aAAQ,GAAR,QAAQ,CAAiB;QACzB,aAAQ,GAAR,QAAQ,CAAoB;QAC5B,aAAQ,GAAR,QAAQ,CAAe;IACvC,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,QAA4B,EAAE;QAC9D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAE9D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAA,kCAAc,EAAC,MAAM,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;QAE1F,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;gBAC7B,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE;gBAC9C,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;aACpD,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC3B,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE;gBACzE,MAAM,EAAE,YAAY;aACrB,CAAC;SACH,CAAC,CAAC;QAEH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CACrE,CAAC;QACF,MAAM,MAAM,GAAoB,EAAE,CAAC;QACnC,0EAA0E;QAC1E,0DAA0D;QAC1D,IAAI,MAAoC,CAAC;QACzC,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;QACvF,gDAAgD;QAChD,IAAI,SAAuC,CAAC;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,qBAAqB,GAAG,KAAK;YACjC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC1E,CAAC,CAAC,SAAS,CAAC;QAEd,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAC7C,MAAM,EACN,QAAQ,EACR,SAAS,KAAK,SAAS,EACvB,kBAAkB,EAClB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAC7F,CAAC;YAEF,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YAED,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;gBAC5B,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;oBAAE,SAAS;gBACxC,IAAI,SAAS,KAAK,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,SAAS;gBAEnE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CACrF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,YAAY,CAChB,MAAc,EACd,QAAgB,EAChB,OAAe,EACf,UAAmD,EACnD,QAA4B,EAAE;QAO9B,MAAM,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAEjE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;YAC/C,KAAK,EAAE,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;YAClD,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;YAC7C,MAAM,IAAI,kBAAO,CACf,sBAAsB,EACtB,UAAU,OAAO,wCAAwC,EACzD,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAC1C,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACzD,MAAM,MAAM,GACV,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAE7F,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;gBACvF,MAAM,IAAI,kBAAO,CACf,2BAA2B,EAC3B,UAAU,OAAO,sBAAsB,GAAG,GAAG,EAC7C,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,CAC3D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;YACpD,KAAK,EAAE,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;YAChD,MAAM,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE;SACpC,CAAC,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAC7C,MAAM,EACN,QAAQ,EACR,MAAM,KAAK,IAAI,EACf,SAAS,EACT,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAC1C,CAAC;QAEF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAA,qCAAW,EAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,SAAS,KAAK,MAAM,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,kBAAO,CACf,wBAAwB,EACxB,qBAAqB,QAAQ,yBAAyB,OAAO,IAAI,EACjE,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAC1C,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IACxD,CAAC;CACF,CAAA;AA5JY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;6CACG,mCAAe;QACf,sCAAkB;QAClB,uCAAa;GAL/B,mBAAmB,CA4J/B;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,MAAM,MAAM,GAAG,wCAAyB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE1D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,gDAA2B,CAAC;AACpE,CAAC;AAED,SAAS,QAAQ,CAAC,GAAa,EAAE,SAAsB;IACrD,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,YAAY,EAAE,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC;QACjD,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/ai/keys/user-ai-keys.controller.d.ts

@@ -0,0 +1,64 @@
+import { SetUserAiKeyDto, TestUserAiKeyDto } from './dto/user-ai-key.dto';
+import { UsableModelsService } from './usable-models.service';
+import { UserAiKeysService } from './user-ai-keys.service';
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+export declare class UserAiKeysController {
+    private readonly keys;
+    private readonly usableModels;
+    constructor(keys: UserAiKeysService, usableModels: UsableModelsService);
+    list(userId: string): Promise<{
+        provider: string;
+        configured: boolean;
+        hint: string | null;
+        verifiedAt: string | null;
+        lastErrorCode: string | null;
+        reachableModelCount: number;
+        reachableCheckedAt: string | null;
+    }[]>;
+    set(provider: string, dto: SetUserAiKeyDto, userId: string): Promise<{
+        provider: string;
+        configured: boolean;
+        hint: string | null;
+        verifiedAt: string | null;
+        lastErrorCode: string | null;
+        reachableModelCount: number;
+        reachableCheckedAt: string | null;
+    }>;
+    remove(provider: string, userId: string): Promise<void>;
+    test(provider: string, dto: TestUserAiKeyDto, userId: string): Promise<{
+        success: boolean;
+        provider: string;
+        usedStoredKey: boolean;
+        reachableModelCount: number | null;
+        checks: {
+            id: "credentials" | "list_models" | "responses_smoke";
+            label: string;
+            status: "failed" | "skipped" | "passed";
+            code: "ok" | "AI_DISABLED" | "AI_PROVIDER_DISABLED" | "AI_KEY_REQUIRED" | "AI_KEY_INVALID" | "AI_MODEL_NOT_ENABLED" | "AI_MODEL_NOT_REACHABLE" | "AI_CAPABILITY_UNSUPPORTED" | "AI_TOOL_DISABLED" | "AI_REALTIME_DISABLED" | "AI_RATE_LIMITED" | "AI_PROVIDER_UNAVAILABLE" | "AI_CONTENT_FILTERED" | "AI_INVALID_REQUEST" | "AI_STRUCTURED_OUTPUT_INVALID" | "AI_STORAGE_UNAVAILABLE" | "not_configured" | "not_attempted" | "no_eligible_model" | "not_supported";
+            detail: string;
+            error: string | null;
+        }[];
+        attemptedAt: string;
+    }>;
+    listModels(userId: string, orgId: string): Promise<{
+        provider: string;
+        modelId: string;
+        displayName: string | null;
+        capabilities: {
+            capabilities: string[];
+            inputModalities: ("file" | "text" | "image" | "audio")[];
+            outputModalities: ("text" | "image" | "audio" | "embedding")[];
+            reasoningEfforts?: ("minimal" | "low" | "medium" | "high")[] | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            voices?: string[] | undefined;
+        };
+        keySource: "org" | "user" | "none";
+    }[]>;
+}
+//# sourceMappingURL=user-ai-keys.controller.d.ts.map

package/dist/ai/keys/user-ai-keys.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-ai-keys.controller.d.ts","sourceRoot":"","sources":["../../../src/ai/keys/user-ai-keys.controller.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,eAAe,EACf,gBAAgB,EAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA8B3D;;;;;GAKG;AACH,qBAIa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,mBAAmB;IAe9C,IAAI,CAAoB,MAAM,EAAE,MAAM;;;;;;;;;IAwBtC,GAAG,CACY,QAAQ,EAAE,MAAM,EAC3B,GAAG,EAAE,eAAe,EACT,MAAM,EAAE,MAAM;;;;;;;;;IAe7B,MAAM,CAAoB,QAAQ,EAAE,MAAM,EAAqB,MAAM,EAAE,MAAM;IA0B7E,IAAI,CACW,QAAQ,EAAE,MAAM,EAC3B,GAAG,EAAE,gBAAgB,EACV,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;IAqB7B,UAAU,CAAoB,MAAM,EAAE,MAAM,EAAgB,KAAK,EAAE,MAAM;;;;;;;;;;;;;;;CAGhF"}