@pikku/core 0.12.143 → 0.12.145

package/dist/wirings/http/pikku-fetch-http-response.d.ts

@@ -1,5 +1,6 @@
 import type { PikkuHTTPResponse } from './http.types.js';
 import type { SerializeOptions as CookieSerializeOptions } from 'cookie';
+/** A {@link PikkuHTTPResponse} that collects status, headers, cookies and body in memory, or as a stream for SSE, and converts them to a web `Response` with `toResponse()`. */
 export declare class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     #private;
     setMode(mode: 'stream'): void;

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -1,4 +1,5 @@
 import { stringifySetCookie } from 'cookie';
+/** A {@link PikkuHTTPResponse} that collects status, headers, cookies and body in memory, or as a stream for SSE, and converts them to a web `Response` with `toResponse()`. */
 export class PikkuFetchHTTPResponse {
     #statusCode = 200;
     #headers = new Headers();

package/dist/wirings/http/routers/http-router.d.ts

@@ -7,4 +7,10 @@ export type MatchResult = {
 export interface Router {
     match(method: HTTPMethod, path: string): MatchResult;
 }
+/**
+ * The router that matches a method and path against the wired HTTP routes and
+ * channels. It compiles the routes on first match, so a route wired after that
+ * is not seen until `reset()` is called; tests and hot reload call `reset()`
+ * after rewiring.
+ */
 export declare const httpRouter: PathToRegexRouter;

package/dist/wirings/http/routers/http-router.js

@@ -1,2 +1,8 @@
 import { PathToRegexRouter } from './path-to-regex.js';
+/**
+ * The router that matches a method and path against the wired HTTP routes and
+ * channels. It compiles the routes on first match, so a route wired after that
+ * is not seen until `reset()` is called; tests and hot reload call `reset()`
+ * after rewiring.
+ */
 export const httpRouter = new PathToRegexRouter();

package/dist/wirings/http/web-request.d.ts

@@ -1,4 +1,21 @@
 import type { PikkuHTTPRequest } from './http.types.js';
 import type { PikkuHTTPResponse } from './http.types.js';
+/**
+ * Converts a {@link PikkuHTTPRequest} into a web `Request`, for handing it to a library that speaks the fetch API.
+ *
+ * Without `baseUrl` the origin is built from `x-forwarded-proto` and
+ * `x-forwarded-host` (then `host`), which any client can set. Pass `baseUrl`
+ * unless the host sits behind a proxy that overwrites those headers.
+ *
+ * @param req - The request to convert. Its body is streamed, not buffered.
+ * @param baseUrl - The origin to resolve the path against.
+ */
 export declare function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request;
+/**
+ * Copies a web `Response`'s status, headers, cookies and body onto a {@link PikkuHTTPResponse}.
+ *
+ * This is what happens when a pikku function returns a `Response`. `Content-Length`
+ * and `Transfer-Encoding` are dropped, multiple `Set-Cookie` headers are kept, and an SSE
+ * body is streamed through when the target supports it.
+ */
 export declare function applyWebResponse(res: PikkuHTTPResponse, webResponse: Response): Promise<void>;

package/dist/wirings/http/web-request.js

@@ -1,4 +1,14 @@
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
+/**
+ * Converts a {@link PikkuHTTPRequest} into a web `Request`, for handing it to a library that speaks the fetch API.
+ *
+ * Without `baseUrl` the origin is built from `x-forwarded-proto` and
+ * `x-forwarded-host` (then `host`), which any client can set. Pass `baseUrl`
+ * unless the host sits behind a proxy that overwrites those headers.
+ *
+ * @param req - The request to convert. Its body is streamed, not buffered.
+ * @param baseUrl - The origin to resolve the path against.
+ */
 export function toWebRequest(req, baseUrl) {
     const proto = req.header('x-forwarded-proto') ?? 'http';
     const host = req.header('x-forwarded-host') ?? req.header('host') ?? 'localhost';
@@ -100,6 +110,13 @@ async function readBody(webResponse) {
     const bytes = new Uint8Array(await webResponse.arrayBuffer());
     return bytes.byteLength === 0 ? null : bytes;
 }
+/**
+ * Copies a web `Response`'s status, headers, cookies and body onto a {@link PikkuHTTPResponse}.
+ *
+ * This is what happens when a pikku function returns a `Response`. `Content-Length`
+ * and `Transfer-Encoding` are dropped, multiple `Set-Cookie` headers are kept, and an SSE
+ * body is streamed through when the target supports it.
+ */
 export async function applyWebResponse(res, webResponse) {
     res.status(webResponse.status);
     const setCookieValues = collectSetCookieHeaders(webResponse);

package/dist/wirings/mcp/mcp-endpoint-registry.d.ts

@@ -21,6 +21,13 @@ export interface MCPPromptEndpoint {
     inputSchema?: any;
     enabled: boolean;
 }
+/**
+ * Holds an MCP server's tools, resources and prompts as listed to clients, loaded from the
+ * generated MCP JSON, and tracks which of them are currently enabled.
+ *
+ * Used by MCP server adapters to answer `list` requests. Only `getTools()` filters by the
+ * enabled flag, and disabling an entry does not by itself refuse a call to it.
+ */
 export declare class MCPEndpointRegistry {
     private tools;
     private resources;

package/dist/wirings/mcp/mcp-endpoint-registry.js

@@ -1,3 +1,10 @@
+/**
+ * Holds an MCP server's tools, resources and prompts as listed to clients, loaded from the
+ * generated MCP JSON, and tracks which of them are currently enabled.
+ *
+ * Used by MCP server adapters to answer `list` requests. Only `getTools()` filters by the
+ * enabled flag, and disabling an entry does not by itself refuse a call to it.
+ */
 export class MCPEndpointRegistry {
     tools = new Map();
     resources = new Map();

package/dist/wirings/mcp/mcp-runner.d.ts

@@ -1,6 +1,10 @@
 import type { PikkuHTTP } from '../http/http.types.js';
 import type { CoreMCPResource, CoreMCPPrompt, JsonRpcRequest, JsonRpcResponse, JsonRpcErrorResponse, PikkuMCP } from './mcp.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
+/**
+ * A JSON-RPC error raised by `runMCPTool`, `runMCPResource` and `runMCPPrompt`; `error` is the
+ * response body to send back to the MCP client.
+ */
 export declare class MCPError extends Error {
     readonly error: JsonRpcErrorResponse;
     constructor(error: JsonRpcErrorResponse);
@@ -24,13 +28,71 @@ export type RunMCPEndpointParams<Tools extends string = any> = {
     /** Defaults to enabled outside production. */
     exposeErrors?: boolean;
 };
+/**
+ * Registers the function behind an MCP resource, addressed by `uri` (which may contain `{param}` placeholders).
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the URI, which usually
+ * means the wiring shares a file the inspector could not resolve.
+ *
+ * @param mcpResource - The resource's URI, description and function.
+ * @throws Error when a resource with the same URI is already wired.
+ * @example snippet: mcpResource
+ */
 export declare const wireMCPResource: <PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>> = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>>(mcpResource: CoreMCPResource<PikkuFunctionConfig>) => void;
+/**
+ * Registers the function behind an MCP prompt, addressed by `name`.
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the prompt.
+ *
+ * @param mcpPrompt - The prompt's name, description and function.
+ * @throws Error when a prompt with the same name is already wired.
+ * @example snippet: mcpPrompt
+ */
 export declare const wireMCPPrompt: <PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>> = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>>(mcpPrompt: CoreMCPPrompt<PikkuFunctionConfig>) => void;
+/**
+ * Runs a `resources/read` request through the function runner, matching `uri` exactly first and
+ * then against each templated resource URI, whose captured parameters are merged into the input.
+ *
+ * The resource's own middleware and permissions apply (keyed by the template, not the concrete
+ * URI). Auth middleware only sees a session when `params.http` carries the originating request.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the function input.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param uri - The concrete URI the client asked for.
+ * @returns The JSON-RPC response holding the function's result.
+ * @throws MCPError with the error's registered `mcpCode`, or `-32603` (internal error) otherwise.
+ * Stack details are attached only when `exposeErrors` is set and not in production.
+ */
 export declare function runMCPResource(request: JsonRpcRequest, params: RunMCPEndpointParams, uri: string): Promise<JsonRpcResponse>;
+/**
+ * Runs a `tools/call` request for the tool registered as `name` through the function runner.
+ *
+ * A result is wrapped as a single JSON text part unless the function declares `MCPToolResponse`
+ * as its output. Errors and auth behave as in `runMCPResource`.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the function input.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param name - The registered tool name (resolve a wire name with `mcpResolveWireName` first).
+ * @returns The JSON-RPC response holding the tool result.
+ * @throws MCPError as `runMCPResource` does; an unknown tool is a not-found error.
+ */
 export declare function runMCPTool(request: JsonRpcRequest, params: RunMCPEndpointParams, name: string): Promise<JsonRpcResponse>;
+/**
+ * Runs a `prompts/get` request for the prompt registered as `name` through the function runner.
+ * Errors and auth behave as in `runMCPResource`.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the prompt arguments.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param name - The prompt name.
+ * @returns The JSON-RPC response holding the prompt messages.
+ * @throws MCPError as `runMCPResource` does; an unknown prompt is a not-found error.
+ */
 export declare function runMCPPrompt(request: JsonRpcRequest, params: RunMCPEndpointParams, name: string): Promise<JsonRpcResponse>;
+/** The inspector-generated metadata for every MCP resource, keyed by URI (template). */
 export declare const getMCPResourcesMeta: () => import("./mcp.types.js").MCPResourceMeta;
+/** The inspector-generated metadata for every MCP tool, keyed by name. */
 export declare const getMCPToolsMeta: () => import("./mcp.types.js").MCPToolMeta;
+/** The inspector-generated metadata for every MCP prompt, keyed by name. */
 export declare const getMCPPromptsMeta: () => import("./mcp.types.js").MCPPromptMeta;
 /**
  * Whether a call to this MCP target would need a session to run.
@@ -54,6 +116,7 @@ export declare const mcpTargetRequiresSession: (type: 'tool' | 'resource' | 'pro
  * See `the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md`.
  */
 export declare const mcpEveryTargetRequiresSession: () => boolean;
+/** The three kinds of MCP target a server exposes. */
 export type McpTargetType = 'tool' | 'resource' | 'prompt';
 /** How a registered target's name is spelled on the wire. */
 export declare const mcpWireName: (type: McpTargetType, name: string) => string;

package/dist/wirings/mcp/mcp-runner.js

@@ -5,6 +5,10 @@ import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { resolveNamespace } from '../rpc/rpc-runner.js';
 import { BadRequestError, NotFoundError } from '../../errors/errors.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
+/**
+ * A JSON-RPC error raised by `runMCPTool`, `runMCPResource` and `runMCPPrompt`; `error` is the
+ * response body to send back to the MCP client.
+ */
 export class MCPError extends Error {
     error;
     constructor(error) {
@@ -14,6 +18,16 @@ export class MCPError extends Error {
         this.stack = new Error().stack;
     }
 }
+/**
+ * Registers the function behind an MCP resource, addressed by `uri` (which may contain `{param}` placeholders).
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the URI, which usually
+ * means the wiring shares a file the inspector could not resolve.
+ *
+ * @param mcpResource - The resource's URI, description and function.
+ * @throws Error when a resource with the same URI is already wired.
+ * @example snippet: mcpResource
+ */
 export const wireMCPResource = (mcpResource) => {
     const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta');
     const mcpResourceMeta = resourcesMeta[mcpResource.uri];
@@ -28,6 +42,15 @@ export const wireMCPResource = (mcpResource) => {
     }
     resources.set(mcpResource.uri, mcpResource);
 };
+/**
+ * Registers the function behind an MCP prompt, addressed by `name`.
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the prompt.
+ *
+ * @param mcpPrompt - The prompt's name, description and function.
+ * @throws Error when a prompt with the same name is already wired.
+ * @example snippet: mcpPrompt
+ */
 export const wireMCPPrompt = (mcpPrompt) => {
     const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta');
     const mcpPromptMeta = promptsMeta[mcpPrompt.name];
@@ -42,6 +65,20 @@ export const wireMCPPrompt = (mcpPrompt) => {
     }
     prompts.set(mcpPrompt.name, mcpPrompt);
 };
+/**
+ * Runs a `resources/read` request through the function runner, matching `uri` exactly first and
+ * then against each templated resource URI, whose captured parameters are merged into the input.
+ *
+ * The resource's own middleware and permissions apply (keyed by the template, not the concrete
+ * URI). Auth middleware only sees a session when `params.http` carries the originating request.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the function input.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param uri - The concrete URI the client asked for.
+ * @returns The JSON-RPC response holding the function's result.
+ * @throws MCPError with the error's registered `mcpCode`, or `-32603` (internal error) otherwise.
+ * Stack details are attached only when `exposeErrors` is set and not in production.
+ */
 export async function runMCPResource(request, params, uri) {
     let endpoint;
     let pikkuFuncId;
@@ -79,10 +116,32 @@ export async function runMCPResource(request, params, uri) {
         params: { ...request.params, ...extractedParams },
     }, 'resource', uri, endpoint, pikkuFuncId, { ...params, mcp: { ...params.mcp, uri } }, metaKey);
 }
+/**
+ * Runs a `tools/call` request for the tool registered as `name` through the function runner.
+ *
+ * A result is wrapped as a single JSON text part unless the function declares `MCPToolResponse`
+ * as its output. Errors and auth behave as in `runMCPResource`.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the function input.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param name - The registered tool name (resolve a wire name with `mcpResolveWireName` first).
+ * @returns The JSON-RPC response holding the tool result.
+ * @throws MCPError as `runMCPResource` does; an unknown tool is a not-found error.
+ */
 export async function runMCPTool(request, params, name) {
     const meta = pikkuState(null, 'mcp', 'toolsMeta')[name];
     return await runMCPPikkuFunc(request, 'tool', name, undefined, meta?.pikkuFuncId, params);
 }
+/**
+ * Runs a `prompts/get` request for the prompt registered as `name` through the function runner.
+ * Errors and auth behave as in `runMCPResource`.
+ *
+ * @param request - The JSON-RPC request; `params` becomes the prompt arguments.
+ * @param params - The MCP wire, HTTP request (if any) and error-exposure flag.
+ * @param name - The prompt name.
+ * @returns The JSON-RPC response holding the prompt messages.
+ * @throws MCPError as `runMCPResource` does; an unknown prompt is a not-found error.
+ */
 export async function runMCPPrompt(request, params, name) {
     const endpoint = pikkuState(null, 'mcp', 'prompts').get(name);
     const meta = pikkuState(null, 'mcp', 'promptsMeta')[name];
@@ -178,12 +237,15 @@ metaKey = name) {
         }
     }
 }
+/** The inspector-generated metadata for every MCP resource, keyed by URI (template). */
 export const getMCPResourcesMeta = () => {
     return pikkuState(null, 'mcp', 'resourcesMeta');
 };
+/** The inspector-generated metadata for every MCP tool, keyed by name. */
 export const getMCPToolsMeta = () => {
     return pikkuState(null, 'mcp', 'toolsMeta');
 };
+/** The inspector-generated metadata for every MCP prompt, keyed by name. */
 export const getMCPPromptsMeta = () => {
     return pikkuState(null, 'mcp', 'promptsMeta');
 };

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

@@ -9,6 +9,10 @@ export type AssertMCPResourceURIParams<In, URI extends string> = ExtractMCPURIPa
     'not in input type',
     keyof In
 ];
+/**
+ * The `mcp` wire handed to a function run over MCP: the resource URI being read, and controls to
+ * notify the client of resource updates or toggle which tools, resources and prompts it lists.
+ */
 export type PikkuMCP<Tools extends string = any> = {
     uri?: string;
     sendResourceUpdated: (uri: string) => void;
@@ -16,6 +20,7 @@ export type PikkuMCP<Tools extends string = any> = {
     enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>;
     enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>;
 };
+/** Inspector-generated metadata for MCP resources, keyed by URI. */
 export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
@@ -28,6 +33,7 @@ export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'mid
      */
     surface?: string;
 }>;
+/** Inspector-generated metadata for MCP tools, keyed by name. */
 export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
@@ -40,6 +46,7 @@ export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'
      */
     surface?: string;
 }>;
+/** Inspector-generated metadata for MCP prompts, keyed by name, including their argument list. */
 export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
@@ -57,6 +64,7 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
      */
     surface?: string;
 }>;
+/** The configuration `wireMCPResource` takes. */
 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;
@@ -101,6 +109,7 @@ export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuF
     /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
+/** The configuration `wireMCPPrompt` takes. */
 export type CoreMCPPrompt<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, MCPPromptResponse>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     /** How the client asks for this prompt. */
     name: string;
@@ -140,11 +149,13 @@ export type MCPPromptMessage = {
         data?: string;
     };
 };
+/** What an MCP prompt function returns: the messages that start the conversation. */
 export type MCPPromptResponse = MCPPromptMessage[];
 export type MCPResourceMessage = {
     uri: string;
     text: string;
 };
+/** What an MCP resource function returns: one or more text contents, each with its URI. */
 export type MCPResourceResponse = MCPResourceMessage[];
 export type MCPToolMessage = {
     type: 'text';
@@ -153,5 +164,6 @@ export type MCPToolMessage = {
     type: 'image';
     data: string;
 };
+/** What an MCP tool function may return to control its content parts directly; any other output is sent as JSON text. */
 export type MCPToolResponse = MCPToolMessage[];
 export {};

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

@@ -1,10 +1,13 @@
+/** The role a function plays as a node in a workflow graph: something that starts a flow, a step within one, or a terminal step. */
 export type NodeType = 'trigger' | 'action' | 'end';
+/** How a function is presented as a node in a workflow graph editor: its label, palette category and role, and whether it exposes an error output. */
 export type CoreNodeConfig = {
     displayName: string;
     category: string;
     type: NodeType;
     errorOutput?: boolean;
 };
+/** Generated metadata for one function exposed as a graph node. */
 export type NodeMeta = {
     name: string;
     displayName: string;
@@ -17,4 +20,5 @@ export type NodeMeta = {
     outputSchemaName: string | null;
     tags?: string[];
 };
+/** Generated metadata for every function exposed as a graph node, keyed by name. */
 export type NodesMeta = Record<string, NodeMeta>;

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

@@ -1,7 +1,9 @@
+/** An OAuth2 client registration. `clientSecret` is omitted for public clients using PKCE. */
 export type OAuth2AppCredential = {
     clientId: string;
     clientSecret?: string;
 };
+/** An OAuth2 token set as stored for a credential. `expiresAt` is a Unix timestamp; treat the token as secret. */
 export type OAuth2Token = {
     accessToken: string;
     refreshToken?: string;

package/dist/{services → wirings/queue}/in-memory-queue-service.d.ts

@@ -1,4 +1,12 @@
-import type { QueueService, JobOptions, QueueInspection } from '../wirings/queue/queue.types.js';
+import type { QueueService, JobOptions, QueueInspection } from './queue.types.js';
+/**
+ * A {@link QueueService} that runs jobs in-process, for development and tests.
+ *
+ * Jobs run after a short delay, payloads are JSON round-tripped as a real
+ * backend would, and failed jobs are retried up to `attempts` with the given
+ * backoff. Nothing is persisted, `getJob` always returns `null`, and jobs still
+ * pending when the process exits are lost.
+ */
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;
     private jobCounter;

package/dist/{services → wirings/queue}/in-memory-queue-service.js

@@ -1,6 +1,14 @@
-import { runQueueJob } from '../wirings/queue/queue-runner.js';
+import { runQueueJob } from './queue-runner.js';
 const FINISHED_JOBS_KEPT = 100;
 // knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
+/**
+ * A {@link QueueService} that runs jobs in-process, for development and tests.
+ *
+ * Jobs run after a short delay, payloads are JSON round-tripped as a real
+ * backend would, and failed jobs are retried up to `attempts` with the given
+ * backoff. Nothing is persisted, `getJob` always returns `null`, and jobs still
+ * pending when the process exits are lost.
+ */
 export class InMemoryQueueService {
     supportsResults = false;
     jobCounter = 0;

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

@@ -5,3 +5,4 @@ export { SignedQueueService } from './signed-queue-service.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';
 export { registerQueueWorkers } from './register-queue-helper.js';
 export type { QueueRegistrationCallback } from './register-queue-helper.js';
+export { pikkuRemoteQueueJobFunc } from './remote-queue-job.js';

package/dist/wirings/queue/index.js

@@ -1,3 +1,4 @@
 export { wireQueueWorker, runQueueJob, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { SignedQueueService } from './signed-queue-service.js';
 export { registerQueueWorkers } from './register-queue-helper.js';
+export { pikkuRemoteQueueJobFunc } from './remote-queue-job.js';

package/dist/wirings/queue/queue-identity.js

@@ -1,27 +1,15 @@
 import { decodeBase64UrlText, encodeBase64UrlText, signWithKeyMaterial, verifyWithKeyMaterial, } from '../../crypto-utils.js';
+import { stableStringify } from '../../utils/stable-stringify.js';
 export const QUEUE_IDENTITY_SECRET_NAME = 'PIKKU_QUEUE_IDENTITY_SECRET';
 /** Namespaces the queue signing key away from every other use of the same material. */
 export const QUEUE_IDENTITY_INFO = 'pikku:queue-identity';
 export const QUEUE_IDENTITY_CLAIM_VERSION = 'pq1';
-const stableStringify = (value) => {
-    if (value === null || typeof value !== 'object') {
-        return JSON.stringify(value) ?? 'null';
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(stableStringify).join(',')}]`;
-    }
-    const record = value;
-    const keys = Object.keys(record).sort();
-    return `{${keys
-        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
-        .join(',')}}`;
-};
 /**
  * Round-trips through JSON first so the producer hashes exactly what the
  * transport will deliver, then sorts keys so property order cannot change the
  * digest.
  */
-const canonicalizePayload = (data) => stableStringify(JSON.parse(JSON.stringify(data ?? null)));
+const canonicalizePayload = (data) => stableStringify(JSON.parse(JSON.stringify(data ?? null))) ?? 'null';
 const signingPayload = (encodedClaim, data) => `${QUEUE_IDENTITY_CLAIM_VERSION}.${encodedClaim}.${canonicalizePayload(data)}`;
 export const getQueueIdentitySecret = async (secrets) => {
     try {

package/dist/wirings/queue/queue-runner.d.ts

@@ -1,15 +1,52 @@
 import type { CoreQueueWorker, QueueJob } from './queue.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
+/** Thrown by `queue.fail()` inside a worker. Queue adapters treat it as a failed attempt, so the backend's retry policy applies. */
 export declare class QueueJobFailedError extends PikkuError {
     constructor(jobId: string, reason?: string);
 }
+/** Thrown by `queue.discard()` inside a worker. Queue adapters treat it as the end of the job: it is not retried and is not reported as a failure. */
 export declare class QueueJobDiscardedError extends PikkuError {
     constructor(jobId: string, reason?: string);
 }
+/**
+ * Registers the function that processes jobs on a queue.
+ *
+ * The worker's function is sessionless: a job has no request to authenticate.
+ * The only identity it sees is `queue.pikkuUserId` on its wire, which is set
+ * only when the producer's identity claim verifies against the
+ * `PIKKU_QUEUE_IDENTITY_SECRET` secret, and is dropped otherwise.
+ *
+ * Registration needs the metadata `pikku` generates for the queue. When none is
+ * found the wiring is skipped with a warning rather than throwing. A queue
+ * adapter (BullMQ, pg-boss, SQS, …) picks up registered workers through
+ * {@link registerQueueWorkers}.
+ *
+ * @param queueWorker - The queue name, the function to run per job, and optional worker config and middleware.
+ *
+ * @example snippet: wireQueue
+ */
 export declare const wireQueueWorker: <InputData = any, OutputData = any, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<InputData, OutputData>> = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<InputData, OutputData>>>(queueWorker: CoreQueueWorker<PikkuFunctionConfig>) => void;
+/** Every registered queue worker, keyed by queue name. */
 export declare function getQueueWorkers(): Map<string, CoreQueueWorker>;
+/** Unregisters the worker for `name`. Throws when no worker is registered under it. */
 export declare function removeQueueWorker(name: string): Promise<void>;
+/**
+ * Runs one job through the worker registered for its queue. Queue adapters call this for every job they receive.
+ *
+ * The job's `pikkuUserId` claim is verified before the function runs; an
+ * unsigned or invalid claim is logged and the job runs without one. The function
+ * runs with `auth: false`, the worker's middleware, and a `queue` wire carrying
+ * `updateProgress`, `fail` and `discard`.
+ *
+ * @param params.job - The job as the adapter received it.
+ * @param params.updateProgress - Reports progress to the backend; defaults to logging it.
+ * @param params.traceId - Defaults to `q-<jobId>`.
+ * @returns What the worker's function returned.
+ * @throws {PikkuMissingMetaError} When no metadata was generated for the queue.
+ * @throws {QueueJobFailedError | QueueJobDiscardedError} When the worker called `fail` or `discard`.
+ * @throws Whatever the worker threw, after logging it, so the adapter can apply its retry policy.
+ */
 export declare function runQueueJob({ job, updateProgress, traceId, }: {
     job: QueueJob;
     updateProgress?: (progress: number | string | object) => Promise<void>;

package/dist/wirings/queue/queue-runner.js

@@ -8,18 +8,37 @@ class QueueWorkerNotFoundError extends PikkuError {
         super(`Queue processor not found: ${name}`);
     }
 }
+/** Thrown by `queue.fail()` inside a worker. Queue adapters treat it as a failed attempt, so the backend's retry policy applies. */
 export class QueueJobFailedError extends PikkuError {
     constructor(jobId, reason) {
         super(`Queue job ${jobId} failed${reason ? `: ${reason}` : ''}`);
         this.name = 'QueueJobFailedError';
     }
 }
+/** Thrown by `queue.discard()` inside a worker. Queue adapters treat it as the end of the job: it is not retried and is not reported as a failure. */
 export class QueueJobDiscardedError extends PikkuError {
     constructor(jobId, reason) {
         super(`Queue job ${jobId} discarded${reason ? `: ${reason}` : ''}`);
         this.name = 'QueueJobDiscardedError';
     }
 }
+/**
+ * Registers the function that processes jobs on a queue.
+ *
+ * The worker's function is sessionless: a job has no request to authenticate.
+ * The only identity it sees is `queue.pikkuUserId` on its wire, which is set
+ * only when the producer's identity claim verifies against the
+ * `PIKKU_QUEUE_IDENTITY_SECRET` secret, and is dropped otherwise.
+ *
+ * Registration needs the metadata `pikku` generates for the queue. When none is
+ * found the wiring is skipped with a warning rather than throwing. A queue
+ * adapter (BullMQ, pg-boss, SQS, …) picks up registered workers through
+ * {@link registerQueueWorkers}.
+ *
+ * @param queueWorker - The queue name, the function to run per job, and optional worker config and middleware.
+ *
+ * @example snippet: wireQueue
+ */
 export const wireQueueWorker = (queueWorker) => {
     const meta = pikkuState(null, 'queue', 'meta');
     const processorMeta = meta[queueWorker.name];
@@ -37,9 +56,11 @@ export const wireQueueWorker = (queueWorker) => {
     const registrations = pikkuState(null, 'queue', 'registrations');
     registrations.set(queueWorker.name, queueWorker);
 };
+/** Every registered queue worker, keyed by queue name. */
 export function getQueueWorkers() {
     return pikkuState(null, 'queue', 'registrations');
 }
+/** Unregisters the worker for `name`. Throws when no worker is registered under it. */
 export async function removeQueueWorker(name) {
     const registrations = pikkuState(null, 'queue', 'registrations');
     const registration = registrations.get(name);
@@ -48,6 +69,22 @@ export async function removeQueueWorker(name) {
     }
     registrations.delete(name);
 }
+/**
+ * Runs one job through the worker registered for its queue. Queue adapters call this for every job they receive.
+ *
+ * The job's `pikkuUserId` claim is verified before the function runs; an
+ * unsigned or invalid claim is logged and the job runs without one. The function
+ * runs with `auth: false`, the worker's middleware, and a `queue` wire carrying
+ * `updateProgress`, `fail` and `discard`.
+ *
+ * @param params.job - The job as the adapter received it.
+ * @param params.updateProgress - Reports progress to the backend; defaults to logging it.
+ * @param params.traceId - Defaults to `q-<jobId>`.
+ * @returns What the worker's function returned.
+ * @throws {PikkuMissingMetaError} When no metadata was generated for the queue.
+ * @throws {QueueJobFailedError | QueueJobDiscardedError} When the worker called `fail` or `discard`.
+ * @throws Whatever the worker threw, after logging it, so the adapter can apply its retry policy.
+ */
 export async function runQueueJob({ job, updateProgress, traceId, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();