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

package/dist/core/pluggable/describe-config-fields.d.ts

@@ -0,0 +1,35 @@
+import type { ConfigField } from '@marinoscar/platform-contract/settings';
+import { z } from 'zod';
+/**
+ * The descriptor of one field.
+ *
+ * @param name - the field's key in its object schema.
+ * @param schema - the field's zod schema.
+ * @returns the descriptor (never of kind `secret`): `name`, `kind` and the kind's bounds, then `label`
+ *   and, when the schema has a description, `help`.
+ *
+ * @stability experimental
+ */
+export declare function describeConfigField(name: string, schema: z.ZodType): ConfigField;
+/**
+ * The descriptors of every field of an object schema, in declaration order.
+ *
+ * Use it to render a form for a schema the form cannot import. For a pluggable
+ * implementation use {@link PluggableKind.describe}, which also adds the
+ * implementation's secrets.
+ *
+ * @param schema - the object schema (an implementation's `settingsSchema`).
+ * @returns one descriptor per field.
+ *
+ * @example
+ * ```ts
+ * describeConfigFields(z.object({ region: z.string().max(32).describe('Cloud region'), retries: z.number().int().min(0) }));
+ * // [{ name: 'region', kind: 'string', maxLength: 32, label: 'Region', help: 'Cloud region' },
+ * //  { name: 'retries', kind: 'number', min: 0, integer: true, label: 'Retries' }]
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function describeConfigFields(schema: z.ZodObject<z.ZodRawShape>): ConfigField[];
+//# sourceMappingURL=describe-config-fields.d.ts.map

package/dist/core/pluggable/describe-config-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-config-fields.d.ts","sourceRoot":"","sources":["../../../src/core/pluggable/describe-config-fields.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgDxB;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,WAAW,CAwBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,WAAW,EAAE,CAEtF"}

package/dist/core/pluggable/describe-config-fields.js

@@ -0,0 +1,133 @@
+"use strict";
+// =============================================================================
+// Describing a zod object as configuration fields (PP-14.5, issue #923)
+// =============================================================================
+//
+// A generated form cannot import a plugin's zod schema, so the API describes
+// each field of a settings schema as one of five kinds: boolean, enum (with its
+// options), number (with its bounds), string (with its maximum length) and
+// `other` (anything else: the form shows a note instead of a control).
+// Wrappers (`optional`, `nullable`, `readonly`, `nonoptional`, `default`,
+// `prefault`) are unwrapped first, so `z.enum(['us', 'eu']).default('us')` is an
+// `enum` field (PP-14.6, #924). Generalised from the organization settings page's `describeOrgFields`
+// (issue #733), which now delegates here and drops the two additions below, so
+// its wire output is unchanged.
+//
+// Two additions over the org-settings description:
+//   - `label`: from `.meta({ label: 'API base URL' })`, else the field name
+//     humanised (`apiBaseUrl` -> `Api base url`).
+//   - `help`:  from `.describe('...')` (the schema's description).
+// Both are looked up on the field and on every wrapper around it, outermost
+// first, so `z.string().describe('x').optional()` and
+// `z.string().optional().describe('x')` read the same.
+//
+// The `secret` kind is never produced here: a secret is not a settings field
+// (it lives in the encrypted credential store), so `PluggableKind.describe`
+// adds it from the implementation's declared secrets.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConfigField = describeConfigField;
+exports.describeConfigFields = describeConfigFields;
+const zod_1 = require("zod");
+const WRAPPERS = new Set(['optional', 'nullable', 'readonly', 'nonoptional', 'default', 'prefault']);
+const MAX_WRAPPER_DEPTH = 8;
+/** The schema, then each wrapper's inner schema, outermost first, ending at the first non-wrapper. */
+function unwrapChain(schema) {
+    const chain = [schema];
+    let current = schema;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth++) {
+        const def = current._zod.def;
+        if (!WRAPPERS.has(def.type) || def.innerType === undefined)
+            break;
+        current = def.innerType;
+        chain.push(current);
+    }
+    return chain;
+}
+/** `apiBaseUrl` becomes `Api base url`; `max_retries` becomes `Max retries`; `region-id` becomes `Region id`. */
+function humanise(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return words.length === 0 ? name : words.charAt(0).toUpperCase() + words.slice(1);
+}
+function labelOf(name, chain) {
+    for (const schema of chain) {
+        const label = schema.meta()?.label;
+        if (typeof label === 'string' && label.trim() !== '')
+            return label;
+    }
+    return humanise(name);
+}
+function helpOf(chain) {
+    for (const schema of chain) {
+        const help = schema.description;
+        if (typeof help === 'string' && help.trim() !== '')
+            return help;
+    }
+    return undefined;
+}
+/**
+ * The descriptor of one field.
+ *
+ * @param name - the field's key in its object schema.
+ * @param schema - the field's zod schema.
+ * @returns the descriptor (never of kind `secret`): `name`, `kind` and the kind's bounds, then `label`
+ *   and, when the schema has a description, `help`.
+ *
+ * @stability experimental
+ */
+function describeConfigField(name, schema) {
+    const chain = unwrapChain(schema);
+    const inner = chain[chain.length - 1];
+    const label = labelOf(name, chain);
+    const help = helpOf(chain);
+    const tail = help === undefined ? { label } : { label, help };
+    if (inner instanceof zod_1.z.ZodBoolean)
+        return { name, kind: 'boolean', ...tail };
+    if (inner instanceof zod_1.z.ZodEnum) {
+        return { name, kind: 'enum', options: inner.options.map(String), ...tail };
+    }
+    if (inner instanceof zod_1.z.ZodNumber) {
+        const bounds = {};
+        if (Number.isFinite(inner.minValue))
+            bounds.min = inner.minValue;
+        if (Number.isFinite(inner.maxValue))
+            bounds.max = inner.maxValue;
+        if (inner.isInt)
+            bounds.integer = true;
+        return { name, kind: 'number', ...bounds, ...tail };
+    }
+    if (inner instanceof zod_1.z.ZodString) {
+        return typeof inner.maxLength === 'number'
+            ? { name, kind: 'string', maxLength: inner.maxLength, ...tail }
+            : { name, kind: 'string', ...tail };
+    }
+    return { name, kind: 'other', ...tail };
+}
+/**
+ * The descriptors of every field of an object schema, in declaration order.
+ *
+ * Use it to render a form for a schema the form cannot import. For a pluggable
+ * implementation use {@link PluggableKind.describe}, which also adds the
+ * implementation's secrets.
+ *
+ * @param schema - the object schema (an implementation's `settingsSchema`).
+ * @returns one descriptor per field.
+ *
+ * @example
+ * ```ts
+ * describeConfigFields(z.object({ region: z.string().max(32).describe('Cloud region'), retries: z.number().int().min(0) }));
+ * // [{ name: 'region', kind: 'string', maxLength: 32, label: 'Region', help: 'Cloud region' },
+ * //  { name: 'retries', kind: 'number', min: 0, integer: true, label: 'Retries' }]
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+function describeConfigFields(schema) {
+    return Object.entries(schema.shape).map(([name, field]) => describeConfigField(name, field));
+}
+//# sourceMappingURL=describe-config-fields.js.map

package/dist/core/pluggable/describe-config-fields.js.map

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

package/dist/core/pluggable/index.d.ts

@@ -0,0 +1,5 @@
+export { definePluggableKind } from './pluggable-kind';
+export type { DefinePluggableKindOptions, PluggableBuildInput, PluggableImplementation, PluggableKind, PluggableSecretPresence, PluggableSecretSpec, } from './pluggable-kind';
+export { PluggableSettingsError, PluggableUnknownError } from './pluggable-errors';
+export { describeConfigField, describeConfigFields } from './describe-config-fields';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/pluggable/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/pluggable/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/pluggable/index.js

@@ -0,0 +1,14 @@
+"use strict";
+// The pluggable-kind primitive (PP-14.5, issue #923). Recipe: ../README.md,
+// "Pluggable kinds". Framework-free like the registry barrel.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConfigFields = exports.describeConfigField = exports.PluggableUnknownError = exports.PluggableSettingsError = exports.definePluggableKind = void 0;
+var pluggable_kind_1 = require("./pluggable-kind");
+Object.defineProperty(exports, "definePluggableKind", { enumerable: true, get: function () { return pluggable_kind_1.definePluggableKind; } });
+var pluggable_errors_1 = require("./pluggable-errors");
+Object.defineProperty(exports, "PluggableSettingsError", { enumerable: true, get: function () { return pluggable_errors_1.PluggableSettingsError; } });
+Object.defineProperty(exports, "PluggableUnknownError", { enumerable: true, get: function () { return pluggable_errors_1.PluggableUnknownError; } });
+var describe_config_fields_1 = require("./describe-config-fields");
+Object.defineProperty(exports, "describeConfigField", { enumerable: true, get: function () { return describe_config_fields_1.describeConfigField; } });
+Object.defineProperty(exports, "describeConfigFields", { enumerable: true, get: function () { return describe_config_fields_1.describeConfigFields; } });
+//# sourceMappingURL=index.js.map

package/dist/core/pluggable/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/pluggable/index.ts"],"names":[],"mappings":";AAAA,4EAA4E;AAC5E,8DAA8D;;;AAE9D,mDAAuD;AAA9C,qHAAA,mBAAmB,OAAA;AAS5B,uDAAmF;AAA1E,0HAAA,sBAAsB,OAAA;AAAE,yHAAA,qBAAqB,OAAA;AACtD,mEAAqF;AAA5E,6HAAA,mBAAmB,OAAA;AAAE,8HAAA,oBAAoB,OAAA"}

package/dist/core/pluggable/pluggable-errors.d.ts

@@ -0,0 +1,46 @@
+import type { z } from 'zod';
+/**
+ * No implementation is registered under the requested id. The message names the
+ * kind, the id and every registered id, and says how to register one.
+ *
+ * @stability experimental
+ */
+export declare class PluggableUnknownError extends Error {
+    /** Machine-readable reason. */
+    readonly code: "PLUGGABLE_UNKNOWN";
+    /** The kind that was asked. */
+    readonly kind: string;
+    /** The id that is not registered. */
+    readonly id: string;
+    /** The ids that are, in registration order. */
+    readonly registeredIds: readonly string[];
+    /**
+     * @param kind - the kind id.
+     * @param id - the unknown implementation id.
+     * @param registeredIds - the ids registered at the time.
+     */
+    constructor(kind: string, id: string, registeredIds: readonly string[]);
+}
+/**
+ * An implementation's settings do not parse with its own `settingsSchema`.
+ * Carries the zod issues.
+ *
+ * @stability experimental
+ */
+export declare class PluggableSettingsError extends Error {
+    /** Machine-readable reason. */
+    readonly code: "PLUGGABLE_SETTINGS_INVALID";
+    /** The kind. */
+    readonly kind: string;
+    /** The implementation id whose settings are invalid. */
+    readonly id: string;
+    /** The zod issues, with paths relative to the implementation's settings object. */
+    readonly issues: readonly z.core.$ZodIssue[];
+    /**
+     * @param kind - the kind id.
+     * @param id - the implementation id.
+     * @param issues - the zod issues.
+     */
+    constructor(kind: string, id: string, issues: readonly z.core.$ZodIssue[]);
+}
+//# sourceMappingURL=pluggable-errors.d.ts.map

package/dist/core/pluggable/pluggable-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluggable-errors.d.ts","sourceRoot":"","sources":["../../../src/core/pluggable/pluggable-errors.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE;CAUvE;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;IACtD,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IAE7C;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE;CAU1E"}

package/dist/core/pluggable/pluggable-errors.js

@@ -0,0 +1,73 @@
+"use strict";
+// =============================================================================
+// Pluggable-kind errors (PP-14.5, issue #923)
+// =============================================================================
+//
+// Two errors, both framework-free (no Nest exception base) so a kind works in
+// seeds and scripts. The slice that consumes a kind maps them to its own
+// HTTP errors: `PluggableUnknownError` -> its `*_UNKNOWN_*` 400 code,
+// `PluggableSettingsError` -> a 400 carrying `issues`.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluggableSettingsError = exports.PluggableUnknownError = void 0;
+/**
+ * No implementation is registered under the requested id. The message names the
+ * kind, the id and every registered id, and says how to register one.
+ *
+ * @stability experimental
+ */
+class PluggableUnknownError extends Error {
+    /** Machine-readable reason. */
+    code = 'PLUGGABLE_UNKNOWN';
+    /** The kind that was asked. */
+    kind;
+    /** The id that is not registered. */
+    id;
+    /** The ids that are, in registration order. */
+    registeredIds;
+    /**
+     * @param kind - the kind id.
+     * @param id - the unknown implementation id.
+     * @param registeredIds - the ids registered at the time.
+     */
+    constructor(kind, id, registeredIds) {
+        super(`Unknown ${kind} implementation "${id}". Registered: ${registeredIds.join(', ') || '(none)'}. ` +
+            `Register one with the "${kind}" kind's register() at import time, before the application is created.`);
+        this.name = 'PluggableUnknownError';
+        this.kind = kind;
+        this.id = id;
+        this.registeredIds = [...registeredIds];
+    }
+}
+exports.PluggableUnknownError = PluggableUnknownError;
+/**
+ * An implementation's settings do not parse with its own `settingsSchema`.
+ * Carries the zod issues.
+ *
+ * @stability experimental
+ */
+class PluggableSettingsError extends Error {
+    /** Machine-readable reason. */
+    code = 'PLUGGABLE_SETTINGS_INVALID';
+    /** The kind. */
+    kind;
+    /** The implementation id whose settings are invalid. */
+    id;
+    /** The zod issues, with paths relative to the implementation's settings object. */
+    issues;
+    /**
+     * @param kind - the kind id.
+     * @param id - the implementation id.
+     * @param issues - the zod issues.
+     */
+    constructor(kind, id, issues) {
+        super(`Invalid ${kind} settings for "${id}": ` +
+            (issues.map((issue) => `${issue.path.length > 0 ? `${issue.path.join('.')}: ` : ''}${issue.message}`).join('; ') || 'invalid'));
+        this.name = 'PluggableSettingsError';
+        this.kind = kind;
+        this.id = id;
+        this.issues = [...issues];
+    }
+}
+exports.PluggableSettingsError = PluggableSettingsError;
+//# sourceMappingURL=pluggable-errors.js.map

package/dist/core/pluggable/pluggable-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluggable-errors.js","sourceRoot":"","sources":["../../../src/core/pluggable/pluggable-errors.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8CAA8C;AAC9C,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,sEAAsE;AACtE,uDAAuD;AACvD,gFAAgF;;;AAIhF;;;;;GAKG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,+BAA+B;IACtB,IAAI,GAAG,mBAA4B,CAAC;IAC7C,+BAA+B;IACtB,IAAI,CAAS;IACtB,qCAAqC;IAC5B,EAAE,CAAS;IACpB,+CAA+C;IACtC,aAAa,CAAoB;IAE1C;;;;OAIG;IACH,YAAY,IAAY,EAAE,EAAU,EAAE,aAAgC;QACpE,KAAK,CACH,WAAW,IAAI,oBAAoB,EAAE,kBAAkB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,IAAI;YAC7F,0BAA0B,IAAI,wEAAwE,CACzG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,aAAa,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC;IAC1C,CAAC;CACF;AAzBD,sDAyBC;AAED;;;;;GAKG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,+BAA+B;IACtB,IAAI,GAAG,4BAAqC,CAAC;IACtD,gBAAgB;IACP,IAAI,CAAS;IACtB,wDAAwD;IAC/C,EAAE,CAAS;IACpB,mFAAmF;IAC1E,MAAM,CAA8B;IAE7C;;;;OAIG;IACH,YAAY,IAAY,EAAE,EAAU,EAAE,MAAmC;QACvE,KAAK,CACH,WAAW,IAAI,kBAAkB,EAAE,KAAK;YACtC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,CACjI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5B,CAAC;CACF;AAzBD,wDAyBC"}

package/dist/core/pluggable/pluggable-kind.d.ts

@@ -0,0 +1,194 @@
+import { type PluggableDescriptor } from '@marinoscar/platform-contract/settings';
+import type { z } from 'zod';
+/**
+ * One secret an implementation needs (an API key, a signing token). Declared,
+ * never stored in settings: the consuming slice keeps the value in the
+ * encrypted credential store and tells `describe` only whether one exists.
+ *
+ * @stability experimental
+ */
+export interface PluggableSecretSpec {
+    /** The secret's name, e.g. `apiKey`. Passed to `build`'s `secret(name)`. */
+    name: string;
+    /** The label a form shows, e.g. `API key`. */
+    label: string;
+    /** Whether the implementation cannot work without it. */
+    required: boolean;
+    /** One sentence of help for the form. */
+    help?: string;
+}
+/**
+ * What `build` receives: the kind's own build context, the implementation's
+ * parsed settings and a resolver for its declared secrets.
+ *
+ * @stability experimental
+ */
+export type PluggableBuildInput<TBuildContext, TSettings extends Record<string, unknown>> = TBuildContext & {
+    /** This implementation's settings, parsed with its `settingsSchema`, defaults filled. */
+    settings: TSettings;
+    /** Resolves one of the implementation's declared secrets; `null` when none is stored. Held only for the call. */
+    secret(name: string): Promise<string | null>;
+};
+/**
+ * One implementation of a pluggable kind.
+ *
+ * @typeParam TInstance - what `build` returns (the provider, driver, transport...).
+ * @typeParam TBuildContext - what the consuming slice passes to `build` besides
+ *   `settings` and `secret` (a logger, a tenant scope...).
+ * @typeParam TSettings - the parsed settings; `settingsSchema` produces them.
+ *
+ * @stability experimental
+ */
+export interface PluggableImplementation<TInstance, TBuildContext, TSettings extends Record<string, unknown> = Record<string, unknown>> {
+    /** `^[a-z][a-z0-9-]{1,47}$`; permanent once stored. */
+    id: string;
+    /** The human label. */
+    label: string;
+    /** One sentence on what it is. */
+    description?: string;
+    /**
+     * The NON-secret settings. A field here whose name looks like a secret
+     * (`key`, `secret`, `token`, `password`) fails the conformance kit: declare it
+     * in {@link PluggableImplementation.secrets} instead. `.describe('help')`
+     * becomes the field's help text and `.meta({ label })` its label.
+     */
+    settingsSchema: z.ZodObject<z.ZodRawShape>;
+    /** The settings of a fresh install; must parse with `settingsSchema`. */
+    defaults: TSettings;
+    /** The secrets it needs, stored in the credential store, never in settings. */
+    secrets?: readonly PluggableSecretSpec[];
+    /**
+     * Builds the instance. Called by the consuming slice with its context, the
+     * parsed settings and a secret resolver.
+     */
+    build(input: PluggableBuildInput<TBuildContext, TSettings>): TInstance | Promise<TInstance>;
+    /** The hosts an instance with these settings calls, for the Doctor's egress contributors. */
+    egressHosts?: (settings: TSettings) => readonly string[];
+}
+/**
+ * Whether each of an implementation's declared secrets has a stored value.
+ *
+ * @stability experimental
+ */
+export interface PluggableSecretPresence {
+    /** Secret name to whether a value is stored. A missing name counts as `false`. */
+    secrets: Record<string, boolean>;
+}
+/**
+ * One pluggable kind: a registry of implementations plus the settings,
+ * secrets and descriptor logic they share. Create it with
+ * {@link definePluggableKind}.
+ *
+ * @typeParam TInstance - what an implementation builds.
+ * @typeParam TBuildContext - what the consuming slice passes to `build`.
+ *
+ * @stability experimental
+ */
+export interface PluggableKind<TInstance, TBuildContext = object> {
+    /** The kind id (`ai-provider`). Also names the registry: `pluggable.<kind>`. */
+    readonly kind: string;
+    /** The human label of the kind (`AI provider`). */
+    readonly label: string;
+    /**
+     * Adds an implementation. Call it at import time, before the application
+     * bootstraps (`apps/api/src/app-registrations/`).
+     *
+     * @throws RegistryError `INVALID_ID`, `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+     */
+    register(impl: PluggableImplementation<TInstance, TBuildContext, any>): void;
+    /**
+     * The implementation registered under `id`.
+     *
+     * @throws PluggableUnknownError when there is none; the message names the
+     *   kind, the id and the registered ids.
+     */
+    get(id: string): PluggableImplementation<TInstance, TBuildContext, any>;
+    /** Whether an implementation is registered under `id`. */
+    has(id: string): boolean;
+    /** Every registered id, in registration order. */
+    ids(): string[];
+    /** Every implementation, in registration order. */
+    list(): readonly PluggableImplementation<TInstance, TBuildContext, any>[];
+    /**
+     * Validates one implementation's stored settings and fills its defaults.
+     * `undefined` and `null` count as `{}`.
+     *
+     * @throws PluggableUnknownError for an unregistered id.
+     * @throws PluggableSettingsError with the zod issues when the settings do not parse.
+     */
+    parseSettings(id: string, raw: unknown): Record<string, unknown>;
+    /**
+     * Merges a patch into a stored record `{ [id]: settings }` on WRITE. For each
+     * patched id: an unregistered id is rejected, `null` removes the entry, and
+     * anything else is merged over the stored entry (shallow) and parsed with that
+     * implementation's schema, defaults filled. Entries the patch does not name,
+     * including ones stored for implementations that are no longer registered,
+     * are kept as they are.
+     *
+     * @throws PluggableUnknownError for an unregistered id in the patch.
+     * @throws PluggableSettingsError when a patched entry does not parse.
+     */
+    mergeSettingsRecord(stored: Record<string, unknown>, patch: Record<string, unknown>): Record<string, Record<string, unknown>>;
+    /**
+     * Reads a stored record `{ [id]: settings }` on READ. An id that is no longer
+     * registered is dropped with ONE `warn` call naming all of them; an entry
+     * that no longer parses falls back to the implementation's defaults with one
+     * `warn` call. Reading never throws on stored data, so removing a plugin
+     * never bricks the settings row.
+     */
+    readSettingsRecord(stored: Record<string, unknown>, warn: (msg: string) => void): Record<string, Record<string, unknown>>;
+    /**
+     * Describes one implementation for a generated form: its non-secret fields
+     * in declaration order, then one `secret` field per declared secret carrying
+     * only whether a value is stored.
+     *
+     * @throws PluggableUnknownError for an unregistered id.
+     */
+    describe(id: string, presence: PluggableSecretPresence): PluggableDescriptor;
+    /** Describes every implementation, in registration order. */
+    describeAll(presence: (id: string) => PluggableSecretPresence): PluggableDescriptor[];
+}
+/**
+ * Options of {@link definePluggableKind}.
+ *
+ * @stability experimental
+ */
+export interface DefinePluggableKindOptions {
+    /** The kind id: `^[a-z][a-z0-9-]{1,47}$` (`ai-provider`). Must be unique across kinds. */
+    kind: string;
+    /** The human label of the kind (`AI provider`). */
+    label: string;
+}
+/**
+ * Defines a pluggable kind: a registry of implementations that each bring
+ * their own settings schema, defaults, secrets and `build`. Call it once, at
+ * module scope, in the file that owns the kind.
+ *
+ * Built on {@link defineRegistry}: the registry is named `pluggable.<kind>`, a
+ * duplicate implementation id throws and the kind freezes once the application
+ * has bootstrapped.
+ *
+ * @param options - the kind id and label.
+ * @returns the kind.
+ * @throws RegistryError `INVALID_ID` for a malformed kind id; `DUPLICATE_REGISTRY` when the kind is already defined.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/platform-extensions/core/greeter.kind.ts
+ * export const greeterKind = definePluggableKind<Greeter>({ kind: 'greeter', label: 'Greeter' });
+ *
+ * // apps/api/src/app-registrations/core.ts
+ * greeterKind.register({
+ *   id: 'shouting',
+ *   label: 'Shouting greeter',
+ *   settingsSchema: z.object({ exclaim: z.boolean() }),
+ *   defaults: { exclaim: true },
+ *   build: ({ settings }) => ({ greet: async (name) => `HELLO ${name}${settings.exclaim ? '!' : ''}` }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function definePluggableKind<TInstance, TBuildContext = object>(options: DefinePluggableKindOptions): PluggableKind<TInstance, TBuildContext>;
+//# sourceMappingURL=pluggable-kind.d.ts.map

package/dist/core/pluggable/pluggable-kind.d.ts.map

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