@pikku/core 0.12.143 → 0.12.144

package/dist/services/local-content.js

@@ -29,7 +29,15 @@ export const signedContentPath = (urlOrPath) => {
         return pathname;
     }
 };
+/**
+ * The leading URL segment that marks public content. A private bucket cannot
+ * use this name.
+ */
 export const PUBLIC_URL_SEGMENT = '_public';
+/**
+ * Every {@link ContentVisibility}, also the names of the two directories under
+ * the content root.
+ */
 export const CONTENT_VISIBILITIES = [
     'private',
     'public',
@@ -101,11 +109,20 @@ export const resolveContentRequestTarget = async (basePath, key, mode) => {
 };
 /** How long a presigned upload URL stays valid. Short, like an S3 PUT URL. */
 const UPLOAD_URL_TTL_MS = 15 * 60 * 1000;
+/**
+ * Thrown by {@link streamUploadToFile} when an upload passes its byte limit.
+ */
 export class UploadTooLargeError extends Error {
     constructor() {
         super('content_too_large');
     }
 }
+/**
+ * Parses a size such as `512kb` or `10mb` (binary units; no unit means bytes)
+ * into bytes.
+ *
+ * @throws Error when the string is not a size
+ */
 export const parseContentSizeLimit = (sizeLimit) => {
     const match = /^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/i.exec(sizeLimit.trim());
     if (!match) {
@@ -121,6 +138,14 @@ export const parseContentSizeLimit = (sizeLimit) => {
                 : 1;
     return Number(match[1]) * multiplier;
 };
+/**
+ * Streams an upload to `targetPath`, writing to a temporary file that is
+ * renamed into place only once the whole body arrived, so a failed or oversized
+ * upload never leaves a partial file behind.
+ *
+ * @returns the number of bytes written
+ * @throws UploadTooLargeError when the body passes `maxBytes`
+ */
 export const streamUploadToFile = async (source, targetPath, maxBytes) => {
     await mkdir(resolve(targetPath, '..'), { recursive: true });
     const partial = `${targetPath}.${process.pid}.${Date.now()}.${randomUUID()}.part`;
@@ -145,6 +170,16 @@ export const streamUploadToFile = async (source, targetPath, maxBytes) => {
         throw error;
     }
 };
+/**
+ * A {@link ContentService} that stores files on local disk, for development and
+ * single-server deployments. Private and public files live in separate
+ * directories; URLs for private files are signed with the given `JWTService`
+ * and checked by {@link createLocalContentRequestHandler}, and upload URLs
+ * expire after 15 minutes. Keys that would escape the content root are
+ * rejected.
+ *
+ * @throws Error from the constructor when no `JWTService` is given
+ */
 export class LocalContent {
     config;
     logger;

package/dist/services/local-credential-service.d.ts

@@ -1,4 +1,9 @@
 import type { CredentialService } from './credential-service.js';
+/**
+ * A `CredentialService` held in process memory, for development and tests.
+ * Values are stored unencrypted and lost on restart; do not use it in
+ * production.
+ */
 export declare class LocalCredentialService implements CredentialService {
     private store;
     private makeKey;

package/dist/services/local-credential-service.js

@@ -1,3 +1,8 @@
+/**
+ * A `CredentialService` held in process memory, for development and tests.
+ * Values are stored unencrypted and lost on restart; do not use it in
+ * production.
+ */
 export class LocalCredentialService {
     store = new Map();
     makeKey(name, userId) {

package/dist/services/local-email-service.d.ts

@@ -1,4 +1,11 @@
 import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js';
+/**
+ * An {@link EmailService} for development that sends nothing. It logs the
+ * recipients and subject to the console, with the body and attachments reduced
+ * to their lengths.
+ *
+ * @example snippet: shopServices
+ */
 export declare class LocalEmailService implements EmailService {
     send(input: SendEmailInput): Promise<SendEmailResult>;
 }

package/dist/services/local-email-service.js

@@ -1,3 +1,10 @@
+/**
+ * An {@link EmailService} for development that sends nothing. It logs the
+ * recipients and subject to the console, with the body and attachments reduced
+ * to their lengths.
+ *
+ * @example snippet: shopServices
+ */
 export class LocalEmailService {
     async send(input) {
         const payload = {

package/dist/services/local-secrets.d.ts

@@ -1,6 +1,14 @@
 import { type SecretValue } from '../classification/secret-value.js';
 import type { SecretService, SecretValues } from './secret-service.js';
 import type { VariablesService } from './variables-service.js';
+/**
+ * A {@link SecretService} for development that reads secrets from a
+ * `VariablesService` (by default `process.env`), with values set at runtime
+ * kept in memory. Values that parse as JSON are returned parsed. Use a
+ * vault-backed implementation in production.
+ *
+ * @example snippet: shopServices
+ */
 export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;

package/dist/services/local-secrets.js

@@ -1,5 +1,13 @@
 import { createSecretValue, isSecretValue, } from '../classification/secret-value.js';
 import { LocalVariablesService } from './local-variables.js';
+/**
+ * A {@link SecretService} for development that reads secrets from a
+ * `VariablesService` (by default `process.env`), with values set at runtime
+ * kept in memory. Values that parse as JSON are returned parsed. Use a
+ * vault-backed implementation in production.
+ *
+ * @example snippet: shopServices
+ */
 export class LocalSecretService {
     variables;
     localSecrets = new Map();

package/dist/services/local-variables.d.ts

@@ -1,4 +1,10 @@
 import type { VariablesService } from './variables-service.js';
+/**
+ * A {@link VariablesService} backed by a plain object, `process.env` by
+ * default. Values that parse as JSON are returned parsed.
+ *
+ * @example snippet: shopServices
+ */
 export declare class LocalVariablesService implements VariablesService {
     private variables;
     /**

package/dist/services/local-variables.js

@@ -1,3 +1,9 @@
+/**
+ * A {@link VariablesService} backed by a plain object, `process.env` by
+ * default. Values that parse as JSON are returned parsed.
+ *
+ * @example snippet: shopServices
+ */
 export class LocalVariablesService {
     variables;
     /**

package/dist/services/logger.d.ts

@@ -1,4 +1,8 @@
 import type { Safe } from '../classification/secret-value.js';
+/**
+ * Log levels in increasing severity. A logger set to one level drops the levels
+ * below it.
+ */
 export declare enum LogLevel {
     trace = 0,
     debug = 1,

package/dist/services/logger.js

@@ -1,3 +1,7 @@
+/**
+ * Log levels in increasing severity. A logger set to one level drops the levels
+ * below it.
+ */
 export var LogLevel;
 (function (LogLevel) {
     LogLevel[LogLevel["trace"] = 0] = "trace";

package/dist/services/meta-service.d.ts

@@ -24,13 +24,22 @@ import type { AgentsMeta } from '../wirings/agent/agent.types.js';
 import type { GatewaysMeta } from '../wirings/gateway/gateway.types.js';
 export type { FunctionMeta, FunctionsMeta, MiddlewareMetadata as MiddlewareMeta, PermissionMetadata as PermissionMeta, };
 export type { AgentsMeta };
+/** Generated metadata for one agent. */
 export type AgentMeta = AgentsMeta[string];
+/**
+ * Generated metadata for the MCP tools, resources and prompts the app exposes.
+ */
 export interface MCPMeta {
     resources: MCPResourceMeta;
     tools: MCPToolMeta;
     prompts: MCPPromptMeta;
 }
+/** Generated map from each RPC name to the function it invokes. */
 export type RPCMetaRecord = Record<string, string>;
+/**
+ * Generated description of one service: its package, interface and expanded
+ * properties.
+ */
 export interface ServiceMeta {
     name: string;
     summary: string;
@@ -41,7 +50,9 @@ export interface ServiceMeta {
     interface: string;
     expandedProperties: Record<string, string>;
 }
+/** Generated {@link ServiceMeta}, keyed by service name. */
 export type ServicesMetaRecord = Record<string, ServiceMeta>;
+/** Where a middleware is defined and which services it uses. */
 export interface MiddlewareDefinitionMeta {
     services: {
         optimized: boolean;
@@ -55,12 +66,16 @@ export interface MiddlewareDefinitionMeta {
     description?: string;
     package?: string;
 }
+/** One place a middleware definition is used. */
 export interface MiddlewareInstanceMeta {
     definitionId: string;
     sourceFile: string;
     position: number;
     isFactoryCall: boolean;
 }
+/**
+ * Middleware or permissions applied together to an HTTP route pattern or a tag.
+ */
 export interface GroupMeta {
     exportName: string | null;
     sourceFile: string;
@@ -73,12 +88,14 @@ export interface GroupMeta {
     instanceIds: string[];
     isFactory: boolean;
 }
+/** Generated metadata for every middleware definition, use and group. */
 export interface MiddlewareGroupsMeta {
     definitions: Record<string, MiddlewareDefinitionMeta>;
     instances: Record<string, MiddlewareInstanceMeta>;
     httpGroups: Record<string, GroupMeta>;
     tagGroups: Record<string, GroupMeta>;
 }
+/** Where a permission is defined and which services it uses. */
 export interface PermissionDefinitionMeta {
     services: {
         optimized: boolean;
@@ -91,15 +108,24 @@ export interface PermissionDefinitionMeta {
     name?: string;
     description?: string;
 }
+/** Generated metadata for every permission definition. */
 export interface PermissionsGroupsMeta {
     definitions: Record<string, PermissionDefinitionMeta>;
 }
+/**
+ * Content hashes of one email template in one locale, used to tell when a
+ * template changed.
+ */
 export interface EmailTemplateLocaleMeta {
     contentHash: string;
     htmlHash: string;
     subjectHash: string;
     textHash: string;
 }
+/**
+ * Generated metadata for one email template: the variables it reads, which
+ * parts it has, and its locales.
+ */
 export interface EmailTemplateMeta {
     variables: string[];
     hasHtml: boolean;
@@ -107,11 +133,17 @@ export interface EmailTemplateMeta {
     hasText: boolean;
     locales: Record<string, EmailTemplateLocaleMeta>;
 }
+/** Generated metadata for every email template. */
 export interface EmailsMeta {
     src: string;
     themeHash: string;
     templates: Record<string, EmailTemplateMeta>;
 }
+/**
+ * The raw sources of one email template in one locale, as read from disk for
+ * previewing. `missing` names the required parts (`theme`, `locale`, `html`,
+ * `subject`, `text`) that were not found.
+ */
 export interface EmailTemplateAssets {
     theme: Record<string, unknown>;
     strings: Record<string, unknown>;
@@ -194,6 +226,12 @@ export interface MetaService {
     getSchemas(schemaNames: string[]): Promise<Record<string, JSONSchema7 | null>>;
     clearCache(): void;
 }
+/**
+ * A {@link MetaService} that reads the generated metadata from a `.pikku`
+ * directory on local disk and caches each file after its first read. Missing
+ * files are returned as empty metadata rather than errors. Used by the console
+ * and dev tooling.
+ */
 export declare class LocalMetaService implements MetaService {
     readonly basePath: string;
     private httpMetaCache;

package/dist/services/meta-service.js

@@ -2,6 +2,12 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
+/**
+ * A {@link MetaService} that reads the generated metadata from a `.pikku`
+ * directory on local disk and caches each file after its first read. Missing
+ * files are returned as empty metadata rather than errors. Used by the console
+ * and dev tooling.
+ */
 export class LocalMetaService {
     basePath;
     httpMetaCache = null;

package/dist/services/queue-webhook-service.d.ts

@@ -1,6 +1,16 @@
 import type { JobOptions, QueueService } from '../wirings/queue/queue.types.js';
 import type { Logger } from './logger.js';
 import { type SendWebhookInput, type SendWebhookResult, type WebhookJobData, WebhookService } from './webhook-service.js';
+/**
+ * A {@link WebhookService} that delivers through the `pikku-outgoing-webhooks`
+ * queue, so a slow or failing receiver is retried by the queue rather than
+ * holding up the caller.
+ *
+ * The body is signed before it is enqueued, with `input.secret` or else the
+ * secret named by `config.webhook.secret`; if that secret resolves to nothing
+ * the webhook is sent unsigned and an error is logged. Retries default to
+ * `config.webhook.retries`, then {@link DEFAULT_WEBHOOK_RETRIES}.
+ */
 export declare class QueueWebhookService extends WebhookService {
     protected queueService: QueueService;
     constructor(queueService: QueueService);
@@ -15,6 +25,15 @@ export declare class QueueWebhookService extends WebhookService {
     }>;
     private resolveJobOptions;
 }
+/**
+ * The queue worker that delivers one outgoing webhook. It POSTs through
+ * `safeFetch`, so private and internal hosts are refused unless listed in
+ * `config.webhook.allowedHosts`, and times out after 30 seconds. Each attempt
+ * is recorded when the service keeps delivery history.
+ *
+ * @throws Error when the receiver does not answer with a 2xx status, so the
+ * queue retries the job
+ */
 export declare function pikkuWebhookWorkerFunc(services: {
     logger: Logger;
     webhookService?: WebhookService;

package/dist/services/queue-webhook-service.js

@@ -4,6 +4,16 @@ import { safeFetch } from '../utils/safe-fetch.js';
 import { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 const MAX_CAPTURED_RESPONSE_BODY = 2_000;
 // knowledge: decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md
+/**
+ * A {@link WebhookService} that delivers through the `pikku-outgoing-webhooks`
+ * queue, so a slow or failing receiver is retried by the queue rather than
+ * holding up the caller.
+ *
+ * The body is signed before it is enqueued, with `input.secret` or else the
+ * secret named by `config.webhook.secret`; if that secret resolves to nothing
+ * the webhook is sent unsigned and an error is logged. Retries default to
+ * `config.webhook.retries`, then {@link DEFAULT_WEBHOOK_RETRIES}.
+ */
 export class QueueWebhookService extends WebhookService {
     queueService;
     // knowledge: decisions/internals/webhook-service-collaborators-are-constructor-args-not-locator-lookups.md
@@ -63,6 +73,15 @@ export class QueueWebhookService extends WebhookService {
     }
 }
 // knowledge: decisions/internals/webhook-delivery-history-records-every-attempt-best-effort.md
+/**
+ * The queue worker that delivers one outgoing webhook. It POSTs through
+ * `safeFetch`, so private and internal hosts are refused unless listed in
+ * `config.webhook.allowedHosts`, and times out after 30 seconds. Each attempt
+ * is recorded when the service keeps delivery history.
+ *
+ * @throws Error when the receiver does not answer with a 2xx status, so the
+ * queue retries the job
+ */
 export async function pikkuWebhookWorkerFunc(services, { url, body, headers, deliveryId }) {
     let statusCode;
     let responseBody;

package/dist/services/remote-jobs.d.ts

@@ -1,27 +1,22 @@
-import type { Logger } from './logger.js';
 /** The variable holding the shared secret every remote job must present. */
 export declare const REMOTE_JOBS_SECRET_VARIABLE = "PIKKU_DISPATCH_SECRET";
+/** The header a remote job request carries the dispatch secret in. */
 export declare const REMOTE_JOBS_SECRET_HEADER = "x-pikku-dispatch";
+/** The HTTP path a deployment receives remote queue jobs on. */
 export declare const REMOTE_QUEUE_JOB_PATH = "/__pikku/queue-job";
+/** The HTTP path a deployment receives remote scheduled tasks on. */
 export declare const REMOTE_SCHEDULER_JOB_PATH = "/__pikku/scheduler-job";
+/** A queue job delivered over HTTP to {@link REMOTE_QUEUE_JOB_PATH}. */
 export interface RemoteQueueJobData {
     queueName: string;
     data?: unknown;
     jobId?: string;
     traceId?: string;
 }
+/**
+ * A scheduled task run delivered over HTTP to {@link
+ * REMOTE_SCHEDULER_JOB_PATH}.
+ */
 export interface RemoteScheduledJobData {
     taskName: string;
 }
-/**
- * A dispatched job is delivered, not owned: the sender retries, so a permanent
- * failure has to read differently from a transient one. An unknown worker or a
- * discarded job answers 4xx so the sender stops; anything else propagates and
- * is delivered again.
- */
-export declare function pikkuRemoteQueueJobFunc({ logger }: {
-    logger: Logger;
-}, { queueName, data, jobId, traceId }: RemoteQueueJobData): Promise<void>;
-export declare function pikkuRemoteScheduledJobFunc({ logger }: {
-    logger: Logger;
-}, { taskName }: RemoteScheduledJobData): Promise<void>;

package/dist/services/remote-jobs.js

@@ -1,59 +1,8 @@
-import { BadRequestError, PikkuMissingMetaError } from '../errors/errors.js';
-import { QueueJobDiscardedError, runQueueJob } from '../wirings/queue/queue-runner.js';
-import { ScheduledTaskNotFoundError, runScheduledTask, } from '../wirings/scheduler/scheduler-runner.js';
 /** The variable holding the shared secret every remote job must present. */
 export const REMOTE_JOBS_SECRET_VARIABLE = 'PIKKU_DISPATCH_SECRET';
+/** The header a remote job request carries the dispatch secret in. */
 export const REMOTE_JOBS_SECRET_HEADER = 'x-pikku-dispatch';
+/** The HTTP path a deployment receives remote queue jobs on. */
 export const REMOTE_QUEUE_JOB_PATH = '/__pikku/queue-job';
+/** The HTTP path a deployment receives remote scheduled tasks on. */
 export const REMOTE_SCHEDULER_JOB_PATH = '/__pikku/scheduler-job';
-/**
- * A dispatched job is delivered, not owned: the sender retries, so a permanent
- * failure has to read differently from a transient one. An unknown worker or a
- * discarded job answers 4xx so the sender stops; anything else propagates and
- * is delivered again.
- */
-export async function pikkuRemoteQueueJobFunc({ logger }, { queueName, data, jobId, traceId }) {
-    const job = {
-        queueName,
-        data,
-        id: jobId ?? traceId ?? `remote-${Date.now()}`,
-        status: async () => 'active',
-        metadata: () => ({
-            processedAt: new Date(),
-            attemptsMade: 0,
-            maxAttempts: undefined,
-            result: undefined,
-            progress: 0,
-            createdAt: new Date(),
-            completedAt: undefined,
-            failedAt: undefined,
-            error: undefined,
-        }),
-        waitForCompletion: async () => {
-            throw new Error('remote jobs do not support waitForCompletion');
-        },
-    };
-    try {
-        await runQueueJob({ job, traceId });
-    }
-    catch (error) {
-        if (error instanceof PikkuMissingMetaError ||
-            error instanceof QueueJobDiscardedError) {
-            throw new BadRequestError(error.message);
-        }
-        logger.error(`remote-jobs: queue '${queueName}' failed: ${error instanceof Error ? error.message : String(error)}`);
-        throw error;
-    }
-}
-export async function pikkuRemoteScheduledJobFunc({ logger }, { taskName }) {
-    try {
-        await runScheduledTask({ name: taskName, traceId: `cron-${taskName}` });
-    }
-    catch (error) {
-        if (error instanceof ScheduledTaskNotFoundError) {
-            throw new BadRequestError(error.message);
-        }
-        logger.error(`remote-jobs: task '${taskName}' failed: ${error instanceof Error ? error.message : String(error)}`);
-        throw error;
-    }
-}

package/dist/services/scenario-cookie-jar.d.ts

@@ -1,3 +1,7 @@
+/**
+ * A cookie store shared by the steps of one scenario run; see {@link
+ * createCookieJar}.
+ */
 export interface ScenarioCookieJar {
     fetch: typeof fetch;
     clear(): void;

package/dist/services/scheduler-service.d.ts

@@ -1,15 +1,28 @@
 import type { CoreUserSession } from '../types/core.types.js';
 import type { ScheduledTaskRuns } from '../wirings/scheduler/scheduler.types.js';
+/**
+ * A task scheduled with {@link SchedulerService.scheduleRPC}: which RPC it runs
+ * and when.
+ */
 export interface ScheduledTaskSummary {
     taskId: string;
     rpcName: string;
     scheduledFor: Date;
 }
+/** A scheduled task with the data and session it will run with. */
 export interface ScheduledTaskInfo extends ScheduledTaskSummary {
     data?: any;
     session?: CoreUserSession;
     status?: 'scheduled' | 'active' | 'completed' | 'failed';
 }
+/**
+ * Runs RPCs later, provided as the `schedulerService` singleton service
+ * (implementations ship in the queue and database packages). A task runs the
+ * named RPC with the given data, under the session it was scheduled with.
+ *
+ * This is for one-off delayed work; recurring cron tasks are declared with
+ * `wireScheduler`.
+ */
 export declare abstract class SchedulerService {
     abstract init(): Promise<void>;
     /** `delay` is milliseconds as a number, or a duration string such as `"5h"` / `"30m"`. */

package/dist/services/scheduler-service.js

@@ -1,3 +1,11 @@
+/**
+ * Runs RPCs later, provided as the `schedulerService` singleton service
+ * (implementations ship in the queue and database packages). A task runs the
+ * named RPC with the given data, under the session it was scheduled with.
+ *
+ * This is for one-off delayed work; recurring cron tasks are declared with
+ * `wireScheduler`.
+ */
 export class SchedulerService {
     /** Per wired cron task. Empty when this scheduler keeps no run history. */
     async getTaskRuns() {

package/dist/services/schema-service.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Validates function input against the JSON schemas generated from your types,
+ * provided as the `schema` singleton service (for example `@pikku/schema-ajv`
+ * or `@pikku/schema-cfworker`).
+ *
+ * `validateSchema` must throw when the data does not match; the implementations
+ * throw `UnprocessableContentError` (422). When no schema service is
+ * configured, input is not validated.
+ */
 export interface SchemaService {
     compileSchema: (name: string, value: any) => Promise<void> | void;
     validateSchema: (schema: string, data: any) => Promise<void> | void;

package/dist/services/scope-service.d.ts

@@ -1,5 +1,6 @@
 import type { FlatScope } from '../wirings/scope/scope.types.js';
 import type { SystemRole } from '../wirings/role/role.types.js';
+/** A named set of scopes that can be granted to a user. */
 export interface Role {
     name: string;
     description?: string;
@@ -17,6 +18,15 @@ export interface Role {
      */
     declared?: boolean;
 }
+/**
+ * Stores the scopes and roles declared in code and who holds them, and resolves
+ * a user's effective scopes. Sessions call {@link ScopeService.resolveScopes}
+ * so `scopes` checks on functions see role grants as well as direct ones.
+ *
+ * Syncing from code is additive: a scope or system role removed from code is
+ * marked `declared: false` rather than deleted, so a deploy never revokes
+ * grants on its own; `pikku scopes prune` and `pikku roles prune` remove them.
+ */
 export interface ScopeService {
     syncScopes(scopes: FlatScope[]): Promise<void>;
     /** The union of role-derived scopes and scopes granted directly. */

package/dist/services/scoped-secret-service.d.ts

@@ -1,5 +1,10 @@
 import type { SecretValue } from '../classification/secret-value.js';
 import type { SecretService, SecretValues } from './secret-service.js';
+/**
+ * A read-only view of a {@link SecretService} limited to an allow-list of keys,
+ * for handing to code that should see only the secrets it declared. Reading a
+ * key outside the list throws, and every write method throws.
+ */
 export declare class ScopedSecretService implements SecretService {
     private secrets;
     private allowedKeys;

package/dist/services/scoped-secret-service.js

@@ -1,3 +1,8 @@
+/**
+ * A read-only view of a {@link SecretService} limited to an allow-list of keys,
+ * for handing to code that should see only the secrets it declared. Reading a
+ * key outside the list throws, and every write method throws.
+ */
 export class ScopedSecretService {
     secrets;
     allowedKeys;

package/dist/services/secret-host-binding.d.ts

@@ -1,4 +1,9 @@
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
+/**
+ * Thrown when a secret would be sent to a host its `defineSecret` declaration
+ * does not list in `allowedHosts`, or, when the project requires
+ * `allowedHosts`, when it lists none.
+ */
 export declare class SecretHostNotAllowedError extends Error {
     readonly secretId: string;
     readonly host: string;

package/dist/services/secret-host-binding.js

@@ -1,3 +1,8 @@
+/**
+ * Thrown when a secret would be sent to a host its `defineSecret` declaration
+ * does not list in `allowedHosts`, or, when the project requires
+ * `allowedHosts`, when it lists none.
+ */
 export class SecretHostNotAllowedError extends Error {
     secretId;
     host;

package/dist/services/secret-service.d.ts

@@ -3,6 +3,19 @@ import type { SecretValue } from '../classification/secret-value.js';
 export type SecretValues<T> = {
     [K in keyof T]: SecretValue<T[K]>;
 };
+/**
+ * Reads and writes secrets, provided as the `secrets` singleton service (for
+ * example a cloud secret manager, or {@link LocalSecretService} in
+ * development).
+ *
+ * Values come back wrapped in a `SecretValue`, which logs and serializes as
+ * `[secret]` until `.reveal()` is called, and the logger, audit log and email
+ * service refuse a `SecretValue` at compile time. Function bodies and
+ * permissions cannot reach this service at all; read secrets in your service
+ * factories and pass the values to the services that need them.
+ *
+ * @example snippet: shopServices
+ */
 export interface SecretService {
     /**
      * Throws if the secret is not found, unless `defineSecret` declared it
@@ -10,7 +23,12 @@ export interface SecretService {
      * `.reveal()`.
      */
     getSecret<T = string>(key: string): Promise<SecretValue<T>>;
-    /** Answers for any key, including a disallowed one — it must not throw. */
+    /**
+     * Resolves `false` for a key that is absent or not allowed, rather than
+     * throwing. A backend failure (the store is unreachable, access is denied)
+     * must throw instead, so callers relying on the check fail closed rather
+     * than treating an outage as "no such secret".
+     */
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
     /**

package/dist/services/secretless.d.ts

@@ -1,4 +1,10 @@
 import type { SecretlessServices } from '../types/core.types.js';
+/**
+ * Thrown when code that may not read secrets (a function body, a permission)
+ * touches `services.secrets`. Secrets are read only in service factories and
+ * middleware; give the service that needs a secret the value when you construct
+ * it.
+ */
 export declare class SecretAccessDeniedError extends Error {
     constructor(context: string);
 }