@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/esm/ai/capabilities.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * A capability id on the wire. Open: any `AI_CAPABILITY_ID_PATTERN` string, never
+ * `z.enum(BUILTIN_AI_CAPABILITIES)`.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare const aiCapabilityIdSchema: z.ZodString;
+/**
+ * An operation id on the wire (the `operation` of a usage row). Open: any
+ * `AI_OPERATION_ID_PATTERN` string.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare const aiOperationIdSchema: z.ZodString;
+/**
+ * A feature id on the wire (the `feature` of a usage row or a run).
+ *
+ * @stability experimental
+ */
+export declare const aiFeatureIdSchema: z.ZodString;
+/**
+ * One capability, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export declare const aiCapabilityDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    builtin: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * One operation, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export declare const aiOperationDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    capability: z.ZodString;
+    builtin: z.ZodBoolean;
+    runnable: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The body of `GET /api/admin/ai/capabilities`.
+ *
+ * @stability experimental
+ */
+export declare const aiCapabilitiesResponseSchema: z.ZodObject<{
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodString;
+        builtin: z.ZodBoolean;
+    }, z.core.$strip>>;
+    operations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        capability: z.ZodString;
+        builtin: z.ZodBoolean;
+        runnable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * A cost the deployment's pricing port computed (`AI_PRICING`): an amount in
+ * a currency, never a rate card.
+ *
+ * @stability experimental
+ */
+export declare const aiUsageCostSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>;
+/** One capability on the wire. @stability experimental */
+export type AiCapabilityDescriptor = z.infer<typeof aiCapabilityDescriptorSchema>;
+/** One operation on the wire. @stability experimental */
+export type AiOperationDescriptor = z.infer<typeof aiOperationDescriptorSchema>;
+/** The capabilities response. @stability experimental */
+export type AiCapabilitiesResponse = z.infer<typeof aiCapabilitiesResponseSchema>;
+/** A computed cost. @stability experimental */
+export type AiUsageCost = z.infer<typeof aiUsageCostSchema>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/esm/ai/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/ai/capabilities.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,aAA6C,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAA4C,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAA0C,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;iBASvC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAWtC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;iBAKvC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;iBAK5B,CAAC;AAEH,0DAA0D;AAC1D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,yDAAyD;AACzD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,yDAAyD;AACzD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/esm/ai/capabilities.js

@@ -0,0 +1,90 @@
+// =============================================================================
+// The AI capability and operation vocabularies on the wire (PP-14.17, #935)
+// =============================================================================
+//
+// `GET /api/admin/ai/capabilities` lists every capability and operation the
+// deployment knows: the platform's own and the ones an app registered with
+// `registerAiCapability` / `registerAiOperation` (`@marinoscar/platform-api/ai`).
+// The admin pages draw their capability labels from it, so an app capability
+// needs no web change.
+// =============================================================================
+import { z } from 'zod';
+import { AI_CAPABILITY_ID_PATTERN, AI_FEATURE_ID_PATTERN, AI_OPERATION_ID_PATTERN } from './constants.js';
+/**
+ * A capability id on the wire. Open: any `AI_CAPABILITY_ID_PATTERN` string, never
+ * `z.enum(BUILTIN_AI_CAPABILITIES)`.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export const aiCapabilityIdSchema = z.string().regex(AI_CAPABILITY_ID_PATTERN);
+/**
+ * An operation id on the wire (the `operation` of a usage row). Open: any
+ * `AI_OPERATION_ID_PATTERN` string.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export const aiOperationIdSchema = z.string().regex(AI_OPERATION_ID_PATTERN);
+/**
+ * A feature id on the wire (the `feature` of a usage row or a run).
+ *
+ * @stability experimental
+ */
+export const aiFeatureIdSchema = z.string().regex(AI_FEATURE_ID_PATTERN);
+/**
+ * One capability, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export const aiCapabilityDescriptorSchema = z.object({
+    /** The capability id (`audio_transcription`). */
+    id: aiCapabilityIdSchema,
+    /** The short label the admin pages show (`Transcription`). */
+    label: z.string(),
+    /** One sentence on what a model with it can do. */
+    description: z.string(),
+    /** Whether the platform ships it (`false`: an app or package registered it). */
+    builtin: z.boolean(),
+});
+/**
+ * One operation, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export const aiOperationDescriptorSchema = z.object({
+    /** The operation id (`audio.transcribe`), the `operation` of its usage rows. */
+    id: aiOperationIdSchema,
+    /** The label usage reports show. */
+    label: z.string(),
+    /** The model capability an operation needs. */
+    capability: aiCapabilityIdSchema,
+    /** Whether the platform ships it. */
+    builtin: z.boolean(),
+    /** Whether `AiService.forUser(...).run(id, input)` can run it (an app operation with schemas). */
+    runnable: z.boolean(),
+});
+/**
+ * The body of `GET /api/admin/ai/capabilities`.
+ *
+ * @stability experimental
+ */
+export const aiCapabilitiesResponseSchema = z.object({
+    /** Every registered capability, built-ins first, then registration order. */
+    capabilities: z.array(aiCapabilityDescriptorSchema),
+    /** Every registered operation, built-ins first, then registration order. */
+    operations: z.array(aiOperationDescriptorSchema),
+});
+/**
+ * A cost the deployment's pricing port computed (`AI_PRICING`): an amount in
+ * a currency, never a rate card.
+ *
+ * @stability experimental
+ */
+export const aiUsageCostSchema = z.object({
+    /** The amount, in `currency`'s major unit. */
+    amount: z.number(),
+    /** An ISO 4217 code (`USD`) or any short label the pricing port uses. */
+    currency: z.string().min(1).max(8),
+});
+//# sourceMappingURL=capabilities.js.map

package/dist/esm/ai/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/ai/capabilities.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,kFAAkF;AAClF,6EAA6E;AAC7E,uBAAuB;AACvB,gFAAgF;AAEhF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE1G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,iDAAiD;IACjD,EAAE,EAAE,oBAAoB;IACxB,8DAA8D;IAC9D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,mDAAmD;IACnD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,gFAAgF;IAChF,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,gFAAgF;IAChF,EAAE,EAAE,mBAAmB;IACvB,oCAAoC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,+CAA+C;IAC/C,UAAU,EAAE,oBAAoB;IAChC,qCAAqC;IACrC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,kGAAkG;IAClG,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,6EAA6E;IAC7E,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,4BAA4B,CAAC;IACnD,4EAA4E;IAC5E,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC;CACjD,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,8CAA8C;IAC9C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC"}

package/dist/esm/ai/constants.d.ts

@@ -0,0 +1,239 @@
+/**
+ * The id pattern of an AI provider: a lower-case letter, then lower-case
+ * letters, digits and hyphens, 2 to 48 characters. Also the provider part of
+ * an `ai.limits.perModel` key (`AI_LIMIT_MODEL_KEY_PATTERN`). Permanent once a
+ * provider's settings or keys are stored under it.
+ *
+ * @stability experimental
+ */
+export declare const AI_PROVIDER_ID_PATTERN: RegExp;
+/**
+ * The id pattern of an AI model capability: a lower-case letter, then
+ * lower-case letters, digits and underscores, 2 to 48 characters
+ * (`audio_transcription`, `speaker_diarization`). Permanent once a catalog row
+ * or an override stores it. The vocabulary is open (PP-14.17, #935): the
+ * platform's own are `BUILTIN_AI_CAPABILITIES` in `@marinoscar/platform-api/ai`,
+ * an app adds its own with `registerAiCapability`.
+ *
+ * @stability experimental
+ */
+export declare const AI_CAPABILITY_ID_PATTERN: RegExp;
+/**
+ * The id pattern of an AI operation: dot-separated lower-case segments of
+ * letters, digits and underscores, 2 to 64 characters in all
+ * (`responses`, `audio.transcribe`, `audio.diarize`). It is the `operation`
+ * column of a usage row, so it is permanent once one is written. Open
+ * (PP-14.17, #935): an app adds its own with `registerAiOperation`.
+ *
+ * @stability experimental
+ */
+export declare const AI_OPERATION_ID_PATTERN: RegExp;
+/**
+ * The id pattern of a registered AI feature (`registerAiFeature`): lower snake
+ * case, starting with a letter, at most 64 characters. Also the `feature`
+ * column of a usage row and of a run.
+ *
+ * @stability experimental
+ */
+export declare const AI_FEATURE_ID_PATTERN: RegExp;
+/**
+ * The provider ids the platform ships an adapter and a settings slot for.
+ * Permanent strings. An app's own providers are not listed here: ask the API
+ * (`GET /api/admin/ai/config`, `GET /api/ai/config`) for the registered ones.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_AI_PROVIDER_IDS: readonly ["openai", "anthropic", "gemini", "azure-openai", "openai-compatible"];
+/**
+ * The provider ids the platform ships.
+ *
+ * @deprecated Use {@link BUILTIN_AI_PROVIDER_IDS}. The list is no longer the set
+ *   of providers a deployment can use (PP-14.6, #924); kept as an alias for one release.
+ * @stability experimental
+ */
+export declare const AI_PROVIDER_IDS: readonly ["openai", "anthropic", "gemini", "azure-openai", "openai-compatible"];
+/**
+ * One of {@link BUILTIN_AI_PROVIDER_IDS}.
+ *
+ * @stability experimental
+ */
+export type BuiltinAiProviderId = (typeof BUILTIN_AI_PROVIDER_IDS)[number];
+/**
+ * An AI provider id: a built-in one (autocompleted) or any string an app or
+ * package registered. See {@link AI_PROVIDER_ID_PATTERN}.
+ *
+ * @stability experimental
+ */
+export type AiProviderId = BuiltinAiProviderId | (string & {});
+/**
+ * How this deployment sources the API key a call actually authenticates
+ * with.
+ *
+ *  - `byok`                    — every call uses the CALLING USER's own key
+ *    (`UserAiKey`). No call succeeds for a user who has not saved one.
+ *  - `byok_with_org_fallback`  — a user's own key is preferred; a user with
+ *    none falls back to a deployment-wide org key. What that org key is, and
+ *    where it lives, is deliberately not modelled here: like the object
+ *    storage secret access key, an org-wide AI key is CREDENTIAL material and
+ *    belongs in the encrypted credential store, never in this JSONB blob that
+ *    `GET /api/system-settings` returns wholesale — see the block comment
+ *    on `systemAiSchema` below.
+ *
+ * @stability experimental
+ */
+export declare const AI_KEY_POLICIES: readonly ["byok", "byok_with_org_fallback"];
+/**
+ * The entries of the key-policy enum (`keyPolicyEnum()`).
+ *
+ * @stability experimental
+ */
+export type AiKeyPolicyEnum = {
+    [K in (typeof AI_KEY_POLICIES)[number]]: K;
+};
+/**
+ * Upper bound on `ai.usageRetentionDays` — ten years; anything longer is "forever" in practice.
+ *
+ * @stability experimental
+ */
+export declare const AI_USAGE_RETENTION_MAX_DAYS = 3650;
+/**
+ * One `ai.hostedTools.mcpAllowedHosts` entry: a hostname (`mcp.example.com`)
+ * or a subdomain wildcard (`*.example.com`). No scheme, port or path — the
+ * scheme is always `https`, and the entry is compared with the URL's host.
+ *
+ * @stability experimental
+ */
+export declare const AI_MCP_ALLOWED_HOST_PATTERN: RegExp;
+/**
+ * Most entries `ai.hostedTools.mcpAllowedHosts` may hold.
+ *
+ * @stability experimental
+ */
+export declare const AI_MCP_ALLOWED_HOSTS_MAX = 100;
+/**
+ * One `ai.limits.perModel` key: `<provider>:<modelId>` — a lower-case
+ * provider id, a colon, then the model id exactly as the catalog lists it
+ * (`openai:gpt-4.1-mini`). The model id may itself contain colons.
+ *
+ * @stability experimental
+ */
+export declare const AI_LIMIT_MODEL_KEY_PATTERN: RegExp;
+/**
+ * Longest accepted `ai.limits.perModel` key.
+ *
+ * @stability experimental
+ */
+export declare const AI_LIMIT_MODEL_KEY_MAX = 256;
+/**
+ * Most entries `ai.limits.perModel` may hold.
+ *
+ * @stability experimental
+ */
+export declare const AI_LIMITS_PER_MODEL_MAX = 500;
+/**
+ * Upper bound on any one `ai.limits` number — a billion is "unlimited" in practice.
+ *
+ * @stability experimental
+ */
+export declare const AI_LIMIT_VALUE_MAX = 1000000000;
+/**
+ * How the deployment sources a call's API key. See {@link AI_KEY_POLICIES}.
+ *
+ * @stability experimental
+ */
+export type AiKeyPolicy = (typeof AI_KEY_POLICIES)[number];
+/**
+ * Longest accepted `baseUrl` for the #448 slots.
+ *
+ * @stability experimental
+ */
+export declare const AI_ENDPOINT_URL_MAX = 2048;
+/**
+ * Why an endpoint URL is refused, or null when it is acceptable. Shared with the admin DTOs.
+ *
+ * @stability experimental
+ */
+export declare function aiEndpointUrlProblem(value: string, schemes: readonly string[]): string | null;
+/**
+ * Schemes a `providers['azure-openai'].baseUrl` may use.
+ *
+ * @stability experimental
+ */
+export declare const AI_AZURE_ENDPOINT_SCHEMES: readonly ["https"];
+/**
+ * Schemes a `providers['openai-compatible'].baseUrl` may use.
+ *
+ * @stability experimental
+ */
+export declare const AI_COMPATIBLE_ENDPOINT_SCHEMES: readonly ["http", "https"];
+/**
+ * Which wire API an OpenAI-family adapter speaks.
+ *
+ * @stability experimental
+ */
+export declare const AI_OPENAI_API_STYLES: readonly ["responses", "chat_completions"];
+/**
+ * The entries of the API-style enum (`apiStyleEnum()`).
+ *
+ * @stability experimental
+ */
+export type AiOpenAiApiStyleEnum = {
+    [K in (typeof AI_OPENAI_API_STYLES)[number]]: K;
+};
+/**
+ * One of `AI_OPENAI_API_STYLES`.
+ *
+ * @stability experimental
+ */
+export type AiOpenAiApiStyle = (typeof AI_OPENAI_API_STYLES)[number];
+/**
+ * An Azure `api-version` query value (`2025-04-01-preview`, `2024-10-21`,
+ * `preview`). A plain token: it is sent as a query parameter and nothing else.
+ *
+ * @stability experimental
+ */
+export declare const AI_AZURE_API_VERSION_PATTERN: RegExp;
+/**
+ * An Azure deployment name: letters, digits, `.`, `_` and `-`, at most 64.
+ *
+ * @stability experimental
+ */
+export declare const AI_AZURE_DEPLOYMENT_PATTERN: RegExp;
+/**
+ * Most entries `providers['azure-openai'].deployments` may hold.
+ *
+ * @stability experimental
+ */
+export declare const AI_AZURE_DEPLOYMENTS_MAX = 200;
+/**
+ * Longest accepted model id key in `deployments`.
+ *
+ * @stability experimental
+ */
+export declare const AI_AZURE_MODEL_ID_MAX = 256;
+/**
+ * The property names a settings namespace must never carry.
+ *
+ * @stability experimental
+ */
+export type AiSecretFieldNames = 'secretAccessKey' | 'secretKey' | 'sessionToken' | 'secret' | 'password' | 'apiKey' | 'apiKeys' | 'key' | 'token';
+/**
+ * Shortest key the org-key route accepts (the deployment-key route's bound).
+ *
+ * @stability experimental
+ */
+export declare const ORG_AI_KEY_MIN = 8;
+/**
+ * Longest key the org-key route accepts.
+ *
+ * @stability experimental
+ */
+export declare const ORG_AI_KEY_MAX = 512;
+/** Field names no org-key response may carry, ever. */
+/**
+ * The property names an organization key view must never carry.
+ *
+ * @stability experimental
+ */
+export type KeyMaterialFieldNames = 'apiKey' | 'key' | 'secret' | 'token' | 'ciphertext';
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/ai/constants.d.ts.map

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

package/dist/esm/ai/constants.js

@@ -0,0 +1,229 @@
+// =============================================================================
+// The AI slice's zod-free constants (issue #739, PP-8.6)
+// =============================================================================
+//
+// Plain values and string-literal unions only, never zod (the contract
+// convention, test/no-zod-in-constants.test.ts): a consumer that needs only a
+// constant or a type (the web app) never pulls zod into its bundle. The
+// schemas built from these are ./schemas.ts, ./org-keys.ts and ./features.ts.
+// =============================================================================
+// =============================================================================
+// AI platform namespace (issue #423, epic #419, umbrella #418)
+// =============================================================================
+//
+// Deployment-wide AI policy — declared on the same terms as `storage` above:
+// all six places in one pass (this file's two schemas, the wire DTOs' two
+// schemas, `DEFAULT_SYSTEM_SETTINGS`, and the hand-written merge in
+// `system-settings.service.ts`), ahead of every consumer. THIS ISSUE OWNS
+// SCHEMA ONLY — nothing in this build reads `ai.enabled` to gate a route, and
+// no controller exists yet that lets a caller actually run a model (#427,
+// #428, #431, #432).
+//
+// `BUILTIN_AI_PROVIDER_IDS` names the providers the platform SHIPS, not a closed
+// set (PP-14.6, #924): an app or package adds its own with `registerAiProvider`
+// (`@marinoscar/platform-api/ai`) and its id is any `AI_PROVIDER_ID_PATTERN`
+// string. Append only to the built-in list: the order is the admin UI's order.
+/**
+ * The id pattern of an AI provider: a lower-case letter, then lower-case
+ * letters, digits and hyphens, 2 to 48 characters. Also the provider part of
+ * an `ai.limits.perModel` key (`AI_LIMIT_MODEL_KEY_PATTERN`). Permanent once a
+ * provider's settings or keys are stored under it.
+ *
+ * @stability experimental
+ */
+export const AI_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{1,47}$/;
+/**
+ * The id pattern of an AI model capability: a lower-case letter, then
+ * lower-case letters, digits and underscores, 2 to 48 characters
+ * (`audio_transcription`, `speaker_diarization`). Permanent once a catalog row
+ * or an override stores it. The vocabulary is open (PP-14.17, #935): the
+ * platform's own are `BUILTIN_AI_CAPABILITIES` in `@marinoscar/platform-api/ai`,
+ * an app adds its own with `registerAiCapability`.
+ *
+ * @stability experimental
+ */
+export const AI_CAPABILITY_ID_PATTERN = /^[a-z][a-z0-9_]{1,47}$/;
+/**
+ * The id pattern of an AI operation: dot-separated lower-case segments of
+ * letters, digits and underscores, 2 to 64 characters in all
+ * (`responses`, `audio.transcribe`, `audio.diarize`). It is the `operation`
+ * column of a usage row, so it is permanent once one is written. Open
+ * (PP-14.17, #935): an app adds its own with `registerAiOperation`.
+ *
+ * @stability experimental
+ */
+export const AI_OPERATION_ID_PATTERN = /^(?=.{2,64}$)[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,3}$/;
+/**
+ * The id pattern of a registered AI feature (`registerAiFeature`): lower snake
+ * case, starting with a letter, at most 64 characters. Also the `feature`
+ * column of a usage row and of a run.
+ *
+ * @stability experimental
+ */
+export const AI_FEATURE_ID_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * The provider ids the platform ships an adapter and a settings slot for.
+ * Permanent strings. An app's own providers are not listed here: ask the API
+ * (`GET /api/admin/ai/config`, `GET /api/ai/config`) for the registered ones.
+ *
+ * @stability experimental
+ */
+export const BUILTIN_AI_PROVIDER_IDS = ['openai', 'anthropic', 'gemini', 'azure-openai', 'openai-compatible'];
+/**
+ * The provider ids the platform ships.
+ *
+ * @deprecated Use {@link BUILTIN_AI_PROVIDER_IDS}. The list is no longer the set
+ *   of providers a deployment can use (PP-14.6, #924); kept as an alias for one release.
+ * @stability experimental
+ */
+export const AI_PROVIDER_IDS = BUILTIN_AI_PROVIDER_IDS;
+/**
+ * How this deployment sources the API key a call actually authenticates
+ * with.
+ *
+ *  - `byok`                    — every call uses the CALLING USER's own key
+ *    (`UserAiKey`). No call succeeds for a user who has not saved one.
+ *  - `byok_with_org_fallback`  — a user's own key is preferred; a user with
+ *    none falls back to a deployment-wide org key. What that org key is, and
+ *    where it lives, is deliberately not modelled here: like the object
+ *    storage secret access key, an org-wide AI key is CREDENTIAL material and
+ *    belongs in the encrypted credential store, never in this JSONB blob that
+ *    `GET /api/system-settings` returns wholesale — see the block comment
+ *    on `systemAiSchema` below.
+ *
+ * @stability experimental
+ */
+export const AI_KEY_POLICIES = ['byok', 'byok_with_org_fallback'];
+/**
+ * Upper bound on `ai.usageRetentionDays` — ten years; anything longer is "forever" in practice.
+ *
+ * @stability experimental
+ */
+export const AI_USAGE_RETENTION_MAX_DAYS = 3650;
+/**
+ * One `ai.hostedTools.mcpAllowedHosts` entry: a hostname (`mcp.example.com`)
+ * or a subdomain wildcard (`*.example.com`). No scheme, port or path — the
+ * scheme is always `https`, and the entry is compared with the URL's host.
+ *
+ * @stability experimental
+ */
+export const AI_MCP_ALLOWED_HOST_PATTERN = /^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+/**
+ * Most entries `ai.hostedTools.mcpAllowedHosts` may hold.
+ *
+ * @stability experimental
+ */
+export const AI_MCP_ALLOWED_HOSTS_MAX = 100;
+/**
+ * One `ai.limits.perModel` key: `<provider>:<modelId>` — a lower-case
+ * provider id, a colon, then the model id exactly as the catalog lists it
+ * (`openai:gpt-4.1-mini`). The model id may itself contain colons.
+ *
+ * @stability experimental
+ */
+export const AI_LIMIT_MODEL_KEY_PATTERN = /^[a-z0-9-]+:.+$/;
+/**
+ * Longest accepted `ai.limits.perModel` key.
+ *
+ * @stability experimental
+ */
+export const AI_LIMIT_MODEL_KEY_MAX = 256;
+/**
+ * Most entries `ai.limits.perModel` may hold.
+ *
+ * @stability experimental
+ */
+export const AI_LIMITS_PER_MODEL_MAX = 500;
+/**
+ * Upper bound on any one `ai.limits` number — a billion is "unlimited" in practice.
+ *
+ * @stability experimental
+ */
+export const AI_LIMIT_VALUE_MAX = 1_000_000_000;
+/**
+ * Longest accepted `baseUrl` for the #448 slots.
+ *
+ * @stability experimental
+ */
+export const AI_ENDPOINT_URL_MAX = 2048;
+/**
+ * Why an endpoint URL is refused, or null when it is acceptable. Shared with the admin DTOs.
+ *
+ * @stability experimental
+ */
+export function aiEndpointUrlProblem(value, schemes) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'Must be an absolute URL';
+    }
+    if (!schemes.includes(url.protocol.replace(/:$/, ''))) {
+        return `The scheme must be ${schemes.join(' or ')}`;
+    }
+    if (url.username || url.password)
+        return 'Credentials may not be embedded in the URL';
+    if (url.hash || value.includes('#'))
+        return 'A fragment (#...) is not allowed';
+    if (!url.hostname)
+        return 'A host is required';
+    return null;
+}
+/**
+ * Schemes a `providers['azure-openai'].baseUrl` may use.
+ *
+ * @stability experimental
+ */
+export const AI_AZURE_ENDPOINT_SCHEMES = ['https'];
+/**
+ * Schemes a `providers['openai-compatible'].baseUrl` may use.
+ *
+ * @stability experimental
+ */
+export const AI_COMPATIBLE_ENDPOINT_SCHEMES = ['http', 'https'];
+/**
+ * Which wire API an OpenAI-family adapter speaks.
+ *
+ * @stability experimental
+ */
+export const AI_OPENAI_API_STYLES = ['responses', 'chat_completions'];
+/**
+ * An Azure `api-version` query value (`2025-04-01-preview`, `2024-10-21`,
+ * `preview`). A plain token: it is sent as a query parameter and nothing else.
+ *
+ * @stability experimental
+ */
+export const AI_AZURE_API_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * An Azure deployment name: letters, digits, `.`, `_` and `-`, at most 64.
+ *
+ * @stability experimental
+ */
+export const AI_AZURE_DEPLOYMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * Most entries `providers['azure-openai'].deployments` may hold.
+ *
+ * @stability experimental
+ */
+export const AI_AZURE_DEPLOYMENTS_MAX = 200;
+/**
+ * Longest accepted model id key in `deployments`.
+ *
+ * @stability experimental
+ */
+export const AI_AZURE_MODEL_ID_MAX = 256;
+// ---- organization keys (`/api/admin/ai/org-keys`) ---------------------------
+/**
+ * Shortest key the org-key route accepts (the deployment-key route's bound).
+ *
+ * @stability experimental
+ */
+export const ORG_AI_KEY_MIN = 8;
+/**
+ * Longest key the org-key route accepts.
+ *
+ * @stability experimental
+ */
+export const ORG_AI_KEY_MAX = 512;
+//# sourceMappingURL=constants.js.map

package/dist/esm/ai/constants.js.map

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