@happyvertical/smrt-prompts 0.51.21 → 0.51.29

package/dist/prompt-settings.d.ts

@@ -0,0 +1,188 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { PromptOverrideCollection } from './collections/PromptOverrideCollection.js';
+import { PromptOverride } from './models/PromptOverride.js';
+import { PromptOverrideAuthorizer } from './prompt-override-service.js';
+import { PromptEditableConfig, PromptOverrideScopeType } from './types.js';
+/** The level that supplied a prompt's effective template. */
+export type PromptSettingsLevel = 'default' | 'config' | 'app' | 'tenant';
+/**
+ * One prompt, rendered for a management screen: the code-owned definition,
+ * the text actually in effect for the requested tenant, and the raw override
+ * state at each scope so the UI can show *why* it is in effect and what
+ * reverting a scope produces.
+ */
+export interface PromptSettingsRow {
+    /**
+     * The persisted identifier. Renaming it orphans every existing override —
+     * see the warning on {@link PromptSettingsService}.
+     */
+    key: string;
+    /** Human description from the definition; may be empty. */
+    description: string;
+    /** Which fields a stored override may change, from the definition. */
+    editable: PromptEditableConfig;
+    /** The code-registered template, before the config layer or any override. */
+    defaultTemplate: string;
+    /**
+     * What {@link resolvePrompt} resolves the template to for the requested
+     * context — the text the application actually uses (unrendered: no
+     * `{variable}` substitution).
+     */
+    effectiveTemplate: string;
+    /** The app-level override row's `template` field, or `null` when there is none. */
+    appTemplate: string | null;
+    /**
+     * The tenant-level override row's `template` field, or `null` when there is
+     * none (or when no `tenantId` was requested).
+     */
+    tenantTemplate: string | null;
+    /**
+     * What the **app** scope's "revert to default" produces: the code default
+     * merged with the config-file layer. Always knowable — nothing sits above
+     * the app scope — unlike {@link inheritedTemplate}.
+     */
+    appDefaultTemplate: string;
+    /**
+     * What the **tenant** scope's "revert to default" produces: the code
+     * default, the config-file layer, and the app-level override, merged with
+     * no tenant override of its own. `null` when no `tenantId` was requested.
+     *
+     * This is the value a "revert to default" control for the tenant scope must
+     * show or apply — never {@link defaultTemplate}, which ignores the config
+     * layer and any app-level override and would silently discard them.
+     */
+    inheritedTemplate: string | null;
+    /** Which level supplied {@link effectiveTemplate}. */
+    supplyingLevel: PromptSettingsLevel;
+}
+/** Selection for {@link PromptSettingsService.listPromptSettings}. */
+export interface ListPromptSettingsOptions {
+    /**
+     * Tenant whose overrides and effective template to report. Omit for an
+     * app-only view.
+     */
+    tenantId?: string | null;
+    /**
+     * Restrict to an explicit allowlist of keys. Keys with no definition are
+     * simply absent from the result — this filters, it does not validate.
+     */
+    keys?: string[];
+}
+/** One override write requested through {@link PromptSettingsService}. */
+export interface SetPromptOverrideRequest {
+    key: string;
+    scopeType: PromptOverrideScopeType;
+    scopeId: string;
+    /** `null` clears the override, returning the scope to whatever it inherits. */
+    template: string | null;
+}
+/**
+ * Thrown when a write names a `key` that has no registered {@link PromptDefinition}.
+ * Nothing is written.
+ *
+ * This is the generalized form of the per-app "is this one of my keys?" guard
+ * every consumer would otherwise hand-roll to keep a form post from creating an
+ * override for an arbitrary string.
+ */
+export declare class UnknownPromptKeyError extends Error {
+    readonly key: string;
+    readonly status = 400;
+    constructor(key: string);
+}
+/**
+ * Thrown when a write would set a field the definition's `editable` config
+ * does not allow overriding. Nothing is written.
+ */
+export declare class PromptFieldNotEditableError extends Error {
+    readonly key: string;
+    readonly field: string;
+    readonly status = 400;
+    constructor(key: string, field: string);
+}
+/** Options for {@link PromptSettingsService.create}. */
+export interface PromptSettingsServiceOptions {
+    /**
+     * The host's authorization decision for each override write, bound to the
+     * current caller. **Omitting it makes the service read-only**: every write
+     * then fails closed with `PromptOverrideAuthorizationError`. This package
+     * never decides who may write.
+     */
+    authorize?: PromptOverrideAuthorizer;
+}
+/**
+ * Read and write side of a prompt management screen, so consumers do not
+ * re-derive the row shape or the unknown-key guard.
+ *
+ * **Authorization stays with the consumer.** This service makes no
+ * authorization decision of its own: reads are unfiltered, and every write is
+ * delegated to {@link PromptOverrideService}, which asks the host-supplied
+ * {@link PromptOverrideAuthorizer} first and fails closed. Call it only from
+ * server code that has already established who the caller is. See
+ * `packages/prompts/README.md` for the consumer recipe.
+ *
+ * **Prompt keys are persisted identifiers.** Overrides are stored keyed by the
+ * exact `key` string and resolved by that string at runtime. Renaming a key
+ * orphans every existing override, silently reverting all tenants to the
+ * registry default. Treat a key as immutable once shipped; a rename needs a
+ * data migration, not an edit.
+ */
+export declare class PromptSettingsService {
+    private readonly overrides;
+    private readonly writes;
+    constructor(overrides: PromptOverrideCollection, authorize?: PromptOverrideAuthorizer);
+    /**
+     * Build a service over the given database options.
+     *
+     * The internal bulk override-enumeration read {@link listPromptSettings}
+     * runs is always issued without the caller's
+     * `defaultListLimit`/`maxListLimit` — see {@link withoutListBounds}. Only
+     * that read is affected; a `db` option is still honored.
+     *
+     * @param options - SMRT database options, as passed to any collection.
+     * @param serviceOptions - Host authorizer. Omit for a read-only (load-function) service.
+     */
+    static create(options?: SmrtClassOptions, serviceOptions?: PromptSettingsServiceOptions): Promise<PromptSettingsService>;
+    /**
+     * One {@link PromptSettingsRow} per matching registered prompt, ordered by
+     * key, so a rendered list is stable across loads.
+     *
+     * Makes no authorization decision — the caller has already decided that this
+     * principal may see this tenant's prompts.
+     */
+    listPromptSettings(options?: ListPromptSettingsOptions): Promise<PromptSettingsRow[]>;
+    /** The single row for one key, or `null` when no definition owns that key. */
+    getPromptSetting(key: string, tenantId?: string | null): Promise<PromptSettingsRow | null>;
+    /**
+     * Apply one override change to the `template` field.
+     *
+     * Refuses any `key` without a registered {@link PromptDefinition}, any scope
+     * the resolver would never read back, and a non-`null` template when the
+     * definition's `editable.template` is `false`, then delegates to
+     * {@link PromptOverrideService} so the host authorizer decides whether this
+     * caller may write this scope. `template: null` clears the override.
+     *
+     * @throws {UnknownPromptKeyError} when the key has no definition.
+     * @throws {InvalidPromptScopeError} when the scope is not one the resolver reads.
+     * @throws {PromptFieldNotEditableError} when the definition disallows template overrides.
+     * @throws `PromptOverrideAuthorizationError` when the authorizer declines.
+     */
+    setPromptOverride(request: SetPromptOverrideRequest): Promise<PromptOverride>;
+    /** {@link setPromptOverride} for the app-wide scope. */
+    setAppPromptOverride(key: string, template: string | null): Promise<PromptOverride>;
+    /** {@link setPromptOverride} for one tenant. */
+    setTenantPromptOverride(key: string, tenantId: string, template: string | null): Promise<PromptOverride>;
+    private assertKnownPromptKey;
+    private loadDefinitions;
+    private toRow;
+}
+/**
+ * Reject a scope the resolver would never read back.
+ *
+ * `PromptOverride` rows are looked up by the exact `(key, tenantId)` pair —
+ * `tenantId: null` for the app scope, a tenant id otherwise. A row written
+ * under a scope nothing queries is invisible state: it never takes effect,
+ * and the host authorizer cannot catch it, because `scopeType: 'app'` with
+ * someone else's tenant id looks like an ordinary app write to an authorizer
+ * that only gates the app scope.
+ */
+//# sourceMappingURL=prompt-settings.d.ts.map

package/dist/prompt-settings.d.ts.map

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