@pikku/core 0.12.91 → 0.12.93

package/dist/wirings/http/http.types.d.ts

@@ -26,14 +26,18 @@ export type RunHTTPWiringOptions = Partial<{
 export type HTTPMethod = 'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options';
 export type HTTPHeadersSchema = StandardSchemaV1<Record<string, string | string[] | undefined>>;
 export type HTTPRouteBaseConfig = {
+    /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
     contentType?: 'xml' | 'json';
+    /** Seconds before the request is abandoned. Work that can outlast a request should be dispatched instead, not given a longer timeout. */
     timeout?: number;
+    /** Filters this route in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** A schema the request headers are validated against, so a missing or malformed header fails before the function body runs. */
     headers?: HTTPHeadersSchema;
 };
 export type CoreHTTPFunction = HTTPRouteBaseConfig & {
     route: string;
-    eventChannel?: false;
+    /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
     returnsJSON?: false;
 };
 export interface PikkuHTTP<In = unknown> {
@@ -41,51 +45,61 @@ export interface PikkuHTTP<In = unknown> {
     response?: PikkuHTTPResponse;
 }
 export type PikkuQuery<T = Record<string, string | undefined>> = Record<string, string | T | null | Array<T | null>>;
-export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = (CoreHTTPFunction & {
+/**
+ * The keys every HTTP wiring takes, whatever it is wired to. The three that
+ * are not here — `method`, `auth` and `func` — are correlated rather than
+ * independent, and live in the unions below.
+ */
+type HTTPWiringShared<R extends string, PikkuMiddleware extends CorePikkuMiddleware<any, any>> = CoreHTTPFunction & {
+    /**
+     * The path this wiring answers on. `:name` marks a parameter, and every
+     * parameter in the path must be a key of the function's input schema —
+     * a mismatch is a compile error rather than a 404 at runtime.
+     */
     route: R;
-    method: HTTPMethod;
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
+    /** Wraps every request to this route: auth, tracing, rate limiting. Runs before the permissions on `func`. */
     middleware?: PikkuMiddleware[];
-    sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: HTTPMethod;
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
+};
+/**
+ * `auth` decides which kind of function this route can point at, so the two
+ * travel together: a route that requires a session gets a function that is
+ * handed one, and an open route gets a sessionless function that has none to
+ * read. Splitting them would let a function ask for a session the route never
+ * establishes.
+ */
+type HTTPWiringAuth<In, Out, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any>, PikkuPermission extends CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any>> = {
+    /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+    auth?: true;
+    /** The function to run. It is handed the session this route required. */
+    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
+} | {
+    /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
     auth?: false;
-    middleware?: PikkuMiddleware[];
+    /** On an open route there is no session, so this must be a sessionless function. */
+    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
+};
+/**
+ * `sse` and `query` are each valid on one method only, so the method carries
+ * them: streaming is a GET, and naming which input keys arrive in the query
+ * string is only a question on a POST, where the rest of the input is a body.
+ */
+type HTTPWiringMethod<In> = {
+    /** The HTTP method. A route and method together address one wiring. */
+    method: HTTPMethod;
     sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: 'get';
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
-    middleware?: PikkuMiddleware[];
-    sse?: boolean;
-}) | (CoreHTTPFunction & {
-    route: R;
+} | {
+    /** The HTTP method. A route and method together address one wiring. */
     method: 'get';
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    auth?: false;
-    middleware?: PikkuMiddleware[];
+    /** Streams the response as server-sent events instead of returning it once. GET only. */
     sse?: boolean;
-}) | (CoreHTTPFunction & {
-    route: R;
+} | {
+    /** The HTTP method. A route and method together address one wiring. */
     method: 'post';
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
-    middleware?: PikkuMiddleware[];
+    /** Input keys that arrive in the query string rather than the body. POST only, where the body is the default home for input. */
     query?: Array<keyof In>;
     sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: 'post';
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    auth?: false;
-    middleware?: PikkuMiddleware[];
-    query?: Array<keyof In>;
-    sse?: undefined;
-});
+};
+export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPWiringShared<R, PikkuMiddleware> & HTTPWiringAuth<In, Out, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware> & HTTPWiringMethod<In>;
 export type HTTPFunctionMetaInputTypes = {
     params?: string;
     query?: string;

package/dist/wirings/mcp/mcp.types.d.ts

@@ -40,36 +40,63 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
     middleware?: MiddlewareMetadata[];
 }>;
 export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */
     uri: string;
+    /** The name a human sees in a client's resource list. */
     title: string;
+    /** What the resource holds, written for the model deciding whether to read it. */
     description: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The media type of what the function returns, so the client knows whether it is text, JSON or an image. */
     mimeType?: string;
+    /** Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all. */
     size?: number;
+    /** Whether the function returns the content in chunks rather than at once. */
     streaming?: boolean;
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it. */
     name: string;
+    /** The name a human sees, where the calling `name` is not readable. */
     title?: string;
+    /** What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object. */
     description?: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Whether the function returns its result in chunks rather than at once. */
     streaming?: boolean;
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type CoreMCPPrompt<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, MCPPromptResponse>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the client asks for this prompt. */
     name: string;
+    /** What the prompt is for, written for the human picking it out of a list. */
     description: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type JsonRpcRequest = {

package/dist/wirings/queue/queue.types.d.ts

@@ -110,11 +110,17 @@ export type QueueWorkersMeta = Record<string, CommonWireMeta & {
     config?: PikkuWorkerConfig;
 }>;
 export type CoreQueueWorker<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
+    /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
     name: string;
+    /** The function to run per job. Its `input` schema is the job payload's schema — a job that does not match is rejected before the body runs. */
     func: PikkuFunctionConfig;
+    /** Concurrency, retry and backoff, passed through to the queue service backing this worker. Defaults come from the service, not from here. */
     config?: PikkuWorkerConfig;
+    /** Names of error classes that mean the job is bad rather than the run — thrown, they fail the job permanently instead of being retried. */
     errors?: string[];
+    /** Filters this worker in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuFunctionConfig['middleware'];
 };
 export interface PikkuQueue {

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -7,10 +7,15 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Reco
     session?: UserSession;
 }>;
 export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
     name: string;
+    /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
     schedule: string;
+    /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
     func: PikkuFunctionConfig;
+    /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuMiddleware[];
 };
 export interface PikkuScheduledTask {

package/dist/wirings/secret/secret.types.d.ts

@@ -4,21 +4,9 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
-    /**
-     * A secret is REQUIRED by default because `getSecret` throws when the value is
-     * missing — a deploy without it is a runtime failure waiting to happen, so the
-     * deploy gate refuses it. Mark a secret `optional` when absence is a supported
-     * state the app handles (a feature that simply stays off): the generated map
-     * emits it as an optional property and `getSecret` resolves `undefined`
-     * instead of throwing.
-     */
+    /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
     optional?: boolean;
-    /**
-     * Where a user goes to obtain this value — a provider's API-key page, a setup
-     * guide, an internal runbook. Consoles and deploy UIs surface it beside a
-     * missing value. The same field on every credential/variable definition means
-     * the same thing.
-     */
+    /** Where a user goes to obtain this value, surfaced beside a missing one. */
     docsUrl?: string;
     /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
     rotationPeriod?: string;
@@ -59,4 +47,11 @@ export type SecretDefinitionMeta = {
 };
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;
 export type SecretDefinitions = SecretDefinitionMeta[];
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export declare const defineSecret: <T>(_config: CoreSecret<T>) => void;

package/dist/wirings/secret/secret.types.js

@@ -1 +1,8 @@
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export const defineSecret = (_config) => { };

package/dist/wirings/trigger/trigger.types.d.ts

@@ -28,11 +28,14 @@ export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown,
 };
 export declare const pikkuTriggerFunc: <TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(triggerOrConfig: CorePikkuTriggerFunction<TInput, TOutput, Services> | CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>) => CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>;
 export interface CoreTrigger<PikkuFunctionConfig = any> {
+    /** What a `wireTriggerSource` points at to fire this trigger. It is the contract between the two, so both must spell it the same. */
     name: string;
+    /** The function to run each time the trigger fires. */
     func: PikkuFunctionConfig;
+    /** What firing this trigger means, for whoever is reading the wiring rather than writing it. */
     description?: string;
+    /** Filters this trigger in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
-    graph?: true;
 }
 export interface TriggerInstance {
     name: string;

package/dist/wirings/variable/variable.types.d.ts

@@ -1,23 +1,17 @@
 export type CoreVariable<T = unknown> = {
+    /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
     name: string;
+    /** The name shown to whoever configures the deployment. */
     displayName: string;
+    /** What the value does, for the person setting it rather than the one reading it. */
     description?: string;
+    /** The environment variable this reads, which is the name that has to exist on the host. */
     variableId: string;
+    /** The shape of the value. It arrives as a string, so this is also what parses it. */
     schema: T;
-    /**
-     * A variable is REQUIRED by default, and marking it `optional` is how a
-     * declaration says its absence is a supported state. Same flag, same
-     * polarity and same meaning as `CoreSecret.optional` — one word to learn
-     * rather than two with opposite senses.
-     *
-     * Defaulting to required rather than following `variables.get`'s
-     * `T | undefined` return is deliberate. That signature describes what a
-     * caller must HANDLE, not whether a deployment is correct without the value:
-     * an undefined feature flag is fine, an undefined API base URL is an outage
-     * that the type system cannot tell apart. Declaring the difference is the
-     * point of the flag, and the safe default for an undeclared one is to ask.
-     */
+    /** Required by default: this says the deployment is still correct without it. */
     optional?: boolean;
+    /** Where to go to work out what to set this to. */
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -32,4 +26,11 @@ export type VariableDefinitionMeta = {
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
 export type VariableDefinitions = VariableDefinitionMeta[];
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export declare const defineVariable: <T>(_config: CoreVariable<T>) => void;

package/dist/wirings/variable/variable.types.js

@@ -1 +1,8 @@
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export const defineVariable = (_config) => { };

package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts

@@ -1,10 +1,17 @@
 export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>, T> {
+    /** Keeps the graph in the codebase but out of the build. */
     disabled?: true;
+    /** Unique across the project. It is how the graph is started and how its runs are grouped. */
     name?: string;
+    /** What the graph does, for whoever is reading it rather than editing it. */
     description?: string;
+    /** Filters this graph in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here. */
     nodes: FuncMap;
+    /** Per-node settings — retries, timeouts, the edges between them. */
     config?: T;
+    /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
     notes?: string[];
 }
 export interface PikkuWorkflowGraphResult {

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -3,4 +3,10 @@ export interface ScenarioCookieJar {
     clear(): void;
     readonly empty: boolean;
 }
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -1,3 +1,9 @@
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export const createCookieJar = (apiUrl) => {
     const jar = new Map();
     const origin = new URL(apiUrl).origin;

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -2,4 +2,10 @@ export interface PollOptions {
     timeoutMs?: number;
     intervalMs?: number;
 }
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -1,3 +1,9 @@
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
     const deadline = Date.now() + timeoutMs;
     for (;;) {

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -1,2 +1,8 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,3 +1,9 @@
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

package/dist/wirings/workflow/workflow-errors.d.ts

@@ -9,6 +9,10 @@ export declare class WorkflowAsyncException extends Error {
     readonly stepName: string;
     constructor(runId: string, stepName: string);
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export declare class WorkflowCancelledException extends Error {
     readonly runId: string;
     readonly reason?: string | undefined;

package/dist/wirings/workflow/workflow-errors.js

@@ -13,6 +13,10 @@ export class WorkflowAsyncException extends Error {
         this.name = 'WorkflowAsyncException';
     }
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export class WorkflowCancelledException extends Error {
     runId;
     reason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.91",
+  "version": "0.12.93",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -124,12 +124,12 @@ const barrelSpecifiers = (file: string) => {
  * it otherwise never imports.
  */
 const namesOwnedByALeaf = new Map<string, string>([
-  ['defineCredential', '#pikku/credentials'],
+  ['defineCredential', '#pikku/auth'],
   ['defineSecret', '#pikku/secrets'],
   ['defineVariable', '#pikku/variables'],
   ['defineScope', '#pikku/scopes'],
   ['defineSystemRole', '#pikku/scopes'],
-  ['cors', '#pikku/http'],
+  ['cors', '#pikku/middleware'],
   ['InvalidOriginError', '#pikku/error'],
 ])
 

package/src/errors/error-handler.ts

@@ -13,19 +13,30 @@ export class PikkuError extends Error {
  * survives serialization across a workflow step boundary and rehydration as a
  * plain `Error`. Callers log the message alone for these, the full stack for
  * everything else.
+ *
+ * @example snippet: isExpectedError
  */
 export const isExpectedError = (error: unknown): boolean =>
   error instanceof PikkuError ||
   (error as { expected?: unknown } | null)?.expected === true
 
 export interface ErrorDetails {
+  /** The HTTP status this error answers with, instead of a 500. */
   status: number
+  /** What the caller is told. It leaves the process, so it must not name anything internal. */
   message: string
+  /** The JSON-RPC code an MCP client is given, where the HTTP status has no equivalent. */
   mcpCode?: number
 }
 
 export type PikkuErrorConstructor = new (...args: any[]) => Error
 
+/**
+ * Registers one of your own error classes with the HTTP status and message it
+ * should produce, so throwing it maps to a real response instead of a 500.
+ *
+ * @example snippet: addError
+ */
 export const addError = (
   error: any,
   { status, message, mcpCode }: ErrorDetails

package/src/errors/serialized-error.ts

@@ -1,6 +1,9 @@
 export interface SerializedError {
+  /** What went wrong, carried across a boundary that cannot carry an Error. */
   message: string
+  /** Present only where the failure was unexpected; a deliberate error is logged by its message alone. */
   stack?: string
+  /** The error class's registered name, which is what a caller matches on rather than the message. */
   code?: string
   // Set for a deliberate PikkuError; survives step-boundary rehydration so
   // the workflow runner logs the message alone rather than a stack trace.

package/src/function/function-runner.ts

@@ -29,7 +29,7 @@ import type { CorePikkuFunctionConfig } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
-import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js'
 import { verifyScopes } from '../scopes.js'
 import {
   PikkuCredentialWireService,
@@ -83,7 +83,7 @@ async function resolveSession(
 
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>,
+  funcConfig: CorePikkuFunctionConfig<any, any, any, any, any>,
   packageName: string | null = null
 ) => {
   pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
@@ -329,7 +329,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         resolveAddonAuth(packageName, addonInstance?.namespace)
       ) {
         if (!session) {
-          throw new ForbiddenError('Authentication required')
+          throw new MissingSessionError('Authentication required')
         }
       }
     } else {
@@ -339,7 +339,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       }
       if (!session) {
-        throw new ForbiddenError('Authentication required')
+        throw new MissingSessionError('Authentication required')
       }
     }