@pikku/core 0.12.143 → 0.12.144

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

@@ -1,3 +1,12 @@
+export declare const SECRET_GENERATE_MIN_SIZE = 16;
+/** A deployment creates the value: `size` random bytes, hex encoded. */
+export type SecretGenerate = {
+    size: number;
+};
+/**
+ * The declaration {@link defineSecret} takes. It describes a secret, never its
+ * value: the value lives in the `SecretService` under `secretId`.
+ */
 export type CoreSecret<T = unknown> = {
     /** The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE. */
     name: string;
@@ -16,8 +25,16 @@ export type CoreSecret<T = unknown> = {
     optional?: boolean;
     /** 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'`. */
+    /**
+     * Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`.
+     * With `generate` it is required, and `'never'` opts out of rotation.
+     */
     rotationPeriod?: string;
+    /**
+     * Makes the deployment create and replace the value. Nobody supplies it, and
+     * `setSecret` from a person is rejected. Requires `rotationPeriod`.
+     */
+    generate?: SecretGenerate;
     /**
      * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
      * `'*.notion.com'`. Omitted means unrestricted unless
@@ -25,6 +42,10 @@ export type CoreSecret<T = unknown> = {
      */
     allowedHosts?: string[];
 };
+/**
+ * The OAuth 2 provider endpoints and scopes for a secret or credential that is
+ * obtained by an authorization-code flow rather than pasted in.
+ */
 export type OAuth2CredentialConfig = {
     /** Where access/refresh tokens are stored */
     tokenSecretId: string;
@@ -41,6 +62,7 @@ export type OAuth2CredentialConfig = {
     /** Appended to the authorization URL's query string. */
     additionalParams?: Record<string, string>;
 };
+/** A secret declaration as recorded in generated meta, with the schema replaced by its name. */
 export type SecretDefinitionMeta = {
     name: string;
     displayName: string;
@@ -51,6 +73,7 @@ export type SecretDefinitionMeta = {
     docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;
+    generate?: SecretGenerate;
     /**
      * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
      * `'*.notion.com'`. Omitted means unrestricted unless
@@ -59,7 +82,9 @@ export type SecretDefinitionMeta = {
     allowedHosts?: string[];
     sourceFile?: string;
 };
+/** Secret declarations collected by the CLI, keyed by name. */
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;
+/** Secret declarations as the inspector found them, before de-duplication. */
 export type SecretDefinitions = SecretDefinitionMeta[];
 /**
  * Declares a secret this project needs, with the shape of its value. The CLI

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

@@ -1,3 +1,4 @@
+export const SECRET_GENERATE_MIN_SIZE = 16;
 /**
  * Declares a secret this project needs, with the shape of its value. The CLI
  * collects every declaration into `CredentialsMap`, which is what makes

package/dist/wirings/secret/validate-secret-definitions.d.ts

@@ -1,4 +1,12 @@
 import type { SecretDefinitions, SecretDefinitionsMeta } from './secret.types.js';
 import type { SchemaRefLike } from '../../types/core.types.js';
 export type { SchemaRefLike };
+/**
+ * Merges the secret declarations the inspector found into meta keyed by name.
+ * Declarations that share a `secretId` must agree on schema and OAuth 2 config.
+ *
+ * @throws Error when two declarations of one `secretId` disagree, or when a
+ * generated secret has no `rotationPeriod`.
+ * @internal Called by the CLI when generating meta.
+ */
 export declare function validateAndBuildSecretDefinitionsMeta(definitions: SecretDefinitions, schemaLookup: Map<string, SchemaRefLike>): SecretDefinitionsMeta;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -1,7 +1,20 @@
+/**
+ * Merges the secret declarations the inspector found into meta keyed by name.
+ * Declarations that share a `secretId` must agree on schema and OAuth 2 config.
+ *
+ * @throws Error when two declarations of one `secretId` disagree, or when a
+ * generated secret has no `rotationPeriod`.
+ * @internal Called by the CLI when generating meta.
+ */
 export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup) {
     const meta = {};
     const secretIdToDefinition = new Map();
     for (const def of definitions) {
+        if (def.generate && !def.rotationPeriod) {
+            throw new Error(`Secret '${def.secretId}' is generated but has no 'rotationPeriod'.\n` +
+                `  Declared in: ${def.sourceFile}\n` +
+                `Add a rotationPeriod such as '30day', or 'never' to generate it once.`);
+        }
         const existingDef = secretIdToDefinition.get(def.secretId);
         if (existingDef) {
             if (def.schema && existingDef.schema) {
@@ -35,6 +48,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     optional: def.optional,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
+                    generate: def.generate,
                     allowedHosts: def.allowedHosts,
                     docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
@@ -53,6 +67,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 optional: def.optional,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
+                generate: def.generate,
                 allowedHosts: def.allowedHosts,
                 docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,

package/dist/wirings/trigger/in-memory-trigger-service.d.ts

@@ -0,0 +1,11 @@
+import { PikkuTriggerService } from './pikku-trigger-service.js';
+/**
+ * Runs every wired trigger source in this process. `start` sets up each source
+ * that has at least one `wireTrigger` listening and logs, rather than throws, a
+ * source that fails to start; `stop` tears them all down.
+ *
+ * Single-process only: a second instance would start every source again.
+ */
+export declare class InMemoryTriggerService extends PikkuTriggerService {
+    start(): Promise<void>;
+}

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

@@ -1,6 +1,13 @@
-import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
-import { getSingletonServices } from '../pikku-state.js';
+import { PikkuTriggerService } from './pikku-trigger-service.js';
+import { getSingletonServices } from '../../pikku-state.js';
 // knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
+/**
+ * Runs every wired trigger source in this process. `start` sets up each source
+ * that has at least one `wireTrigger` listening and logs, rather than throws, a
+ * source that fails to start; `stop` tears them all down.
+ *
+ * Single-process only: a second instance would start every source again.
+ */
 export class InMemoryTriggerService extends PikkuTriggerService {
     async start() {
         const singletonServices = getSingletonServices();
@@ -16,7 +23,7 @@ export class InMemoryTriggerService extends PikkuTriggerService {
                 continue;
             }
             try {
-                const triggerInstance = await this.setupTriggerInstance(name, source.input, (data) => this.onTriggerFire(name, targets, data));
+                const triggerInstance = await this.setupTriggerInstance(name, source.input, (data, options) => this.onTriggerFire(name, targets, data, options));
                 this.activeTriggers.set(name, triggerInstance);
                 singletonServices.logger.info(`Started trigger: ${name}`);
             }

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

@@ -4,4 +4,4 @@ export type { OrphanedWebhookRegistration, WebhookRegistration, WebhookRegistrat
 export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, webhookSecretCredentialName, } from './webhook-source.types.js';
 export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, WebhookVerify, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';
-export type { TriggerMeta, TriggerSourceMeta, CorePikkuTriggerFunction, CorePikkuTriggerFunctionConfig, CoreTrigger, } from './trigger.types.js';
+export type { TriggerMeta, TriggerSourceMeta, CorePikkuTriggerFunction, CorePikkuTriggerFunctionConfig, CoreTrigger, PikkuTrigger, TriggerInvokeOptions, } from './trigger.types.js';

package/dist/wirings/trigger/pikku-trigger-service.d.ts

@@ -1,10 +1,15 @@
-import type { TriggerInstance } from './trigger.types.js';
+import type { TriggerInstance, TriggerInvokeOptions } from './trigger.types.js';
 import type { TriggerService } from '../../services/trigger-service.js';
 export type TriggerTarget = {
     targetType: 'rpc' | 'workflow';
     targetName: string;
     startNode?: string;
 };
+/**
+ * Base class for a {@link TriggerService}: pairs registered trigger sources with
+ * the triggers listening to them and owns teardown. Subclasses decide where and
+ * when sources start by implementing `start`.
+ */
 export declare abstract class PikkuTriggerService implements TriggerService {
     protected activeTriggers: Map<string, TriggerInstance>;
     abstract start(): Promise<void>;
@@ -13,6 +18,6 @@ export declare abstract class PikkuTriggerService implements TriggerService {
     protected getTriggerSources(): Map<string, {
         input?: unknown;
     }>;
-    protected setupTriggerInstance(name: string, input: unknown, onTrigger: (data: unknown) => Promise<void>): Promise<TriggerInstance>;
-    protected onTriggerFire(triggerName: string, targets: TriggerTarget[], data: unknown): Promise<void>;
+    protected setupTriggerInstance(name: string, input: unknown, onTrigger: (data: unknown, options?: TriggerInvokeOptions) => Promise<void>): Promise<TriggerInstance>;
+    protected onTriggerFire(triggerName: string, targets: TriggerTarget[], data: unknown, options?: TriggerInvokeOptions): Promise<void>;
 }

package/dist/wirings/trigger/pikku-trigger-service.js

@@ -1,6 +1,11 @@
 import { rpcService } from '../rpc/rpc-runner.js';
 import { setupTrigger } from './trigger-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
+/**
+ * Base class for a {@link TriggerService}: pairs registered trigger sources with
+ * the triggers listening to them and owns teardown. Subclasses decide where and
+ * when sources start by implementing `start`.
+ */
 export class PikkuTriggerService {
     activeTriggers = new Map();
     async stop() {
@@ -43,12 +48,18 @@ export class PikkuTriggerService {
             onTrigger,
         });
     }
-    async onTriggerFire(triggerName, targets, data) {
+    async onTriggerFire(triggerName, targets, data, options) {
         const singletonServices = getSingletonServices();
         const createWireServices = getCreateWireServices();
-        const wireServices = await createWireServices?.(singletonServices, {});
+        // The user rides on the wire, where the function runner resolves the
+        // target's session and credentials from it and a started workflow records
+        // it on the run.
+        const wire = options?.pikkuUserId
+            ? { pikkuUserId: options.pikkuUserId }
+            : {};
+        const wireServices = await createWireServices?.(singletonServices, wire);
         const services = { ...singletonServices, ...wireServices };
-        const rpc = rpcService.getContextRPCService(services, {}, false);
+        const rpc = rpcService.getContextRPCService(services, wire, false);
         for (const target of targets) {
             try {
                 if (target.targetType === 'workflow') {

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

@@ -1,10 +1,35 @@
-import type { CoreTrigger, CoreTriggerSource, TriggerInstance } from './trigger.types.js';
+import type { CoreTrigger, CoreTriggerSource, TriggerInstance, TriggerInvokeOptions } from './trigger.types.js';
+/**
+ * Registers a trigger: the function that runs each time a trigger source of the
+ * same `name` fires. The source is wired separately with
+ * {@link wireTriggerSource} (or {@link wireTriggerWebhookSource}).
+ *
+ * Skipped with a warning when `pikku all` generated no metadata for it, which
+ * usually means the wiring shares a file with the function it wires.
+ *
+ * @param trigger - The trigger's name and the function it runs.
+ *
+ * @example snippet: wireTrigger
+ */
 export declare const wireTrigger: (trigger: CoreTrigger) => void;
+/**
+ * Registers a trigger source: a long-lived function that subscribes to something
+ * outside the app and calls `wire.trigger.invoke(data)` whenever it fires, and
+ * returns its teardown. Its `name` must match a {@link wireTrigger}.
+ *
+ * The source and the triggers it fires run with no user session, so whatever
+ * the source pushes reaches them as untrusted input.
+ *
+ * @param source - The source's name, the function that sets it up, and its input.
+ * @throws Error when a source with the same name is already registered.
+ *
+ * @example snippet: wireTriggerSource
+ */
 export declare const wireTriggerSource: <TInput = unknown, TOutput = unknown>(source: CoreTriggerSource<TInput, TOutput>) => void;
 export type SetupTriggerParams<TInput = unknown, TOutput = unknown> = {
     name: string;
     input?: TInput;
-    onTrigger: (data: TOutput) => void | Promise<void>;
+    onTrigger: (data: TOutput, options?: TriggerInvokeOptions) => void | Promise<void>;
 };
 export declare function setupTrigger<TInput = unknown, TOutput = unknown>({ name, input, onTrigger, }: SetupTriggerParams<TInput, TOutput>): Promise<TriggerInstance>;
 export declare const getRegisteredTriggers: () => Map<string, CoreTrigger<any>>;

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

@@ -1,6 +1,18 @@
 import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
+/**
+ * Registers a trigger: the function that runs each time a trigger source of the
+ * same `name` fires. The source is wired separately with
+ * {@link wireTriggerSource} (or {@link wireTriggerWebhookSource}).
+ *
+ * Skipped with a warning when `pikku all` generated no metadata for it, which
+ * usually means the wiring shares a file with the function it wires.
+ *
+ * @param trigger - The trigger's name and the function it runs.
+ *
+ * @example snippet: wireTrigger
+ */
 export const wireTrigger = (trigger) => {
     const meta = pikkuState(null, 'trigger', 'meta');
     const triggerMeta = meta[trigger.name];
@@ -13,6 +25,19 @@ export const wireTrigger = (trigger) => {
     triggers.set(trigger.name, trigger);
 };
 // knowledge: decisions/internals/trigger-declaration-is-split-from-trigger-source.md
+/**
+ * Registers a trigger source: a long-lived function that subscribes to something
+ * outside the app and calls `wire.trigger.invoke(data)` whenever it fires, and
+ * returns its teardown. Its `name` must match a {@link wireTrigger}.
+ *
+ * The source and the triggers it fires run with no user session, so whatever
+ * the source pushes reaches them as untrusted input.
+ *
+ * @param source - The source's name, the function that sets it up, and its input.
+ * @throws Error when a source with the same name is already registered.
+ *
+ * @example snippet: wireTriggerSource
+ */
 export const wireTriggerSource = (source) => {
     const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta');
     const triggerSourceMeta = sourceMeta[source.name];
@@ -41,11 +66,19 @@ export async function setupTrigger({ name, input, onTrigger, }) {
     }
     const wire = {
         trigger: {
-            invoke: (data) => {
+            invoke: (data, options) => {
+                const pikkuUserId = options?.pikkuUserId;
+                if (pikkuUserId !== undefined &&
+                    (typeof pikkuUserId !== 'string' || pikkuUserId === '')) {
+                    // Running it as nobody would hide the source's bug, and as anyone
+                    // else is not possible: the event is dropped.
+                    singletonServices.logger.error(`Trigger '${name}' fired with an invalid pikkuUserId; dropping the event`);
+                    return;
+                }
                 singletonServices.logger.info(`Trigger fired: ${name}`);
                 // `invoke` is typed void for trigger sources, so a rejection from the
                 // trigger function is logged here rather than left unhandled.
-                Promise.resolve(onTrigger(data)).catch((e) => singletonServices.logger.error(`Trigger '${name}' handler failed: ${e?.message ?? e}`));
+                Promise.resolve(onTrigger(data, pikkuUserId ? { pikkuUserId } : undefined)).catch((e) => singletonServices.logger.error(`Trigger '${name}' handler failed: ${e?.message ?? e}`));
             },
         },
     };

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

@@ -1,22 +1,43 @@
 import type { CommonWireMeta, CoreSingletonServices } from '../../types/core.types.js';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CoreNodeConfig } from '../node/node.types.js';
+/**
+ * Facts about a trigger event that its source asserts, kept apart from the
+ * event data so that nothing in a payload the source received can set them.
+ */
+export interface TriggerInvokeOptions {
+    /**
+     * The user the event belongs to. The target runs as this user — its
+     * credentials and stored session resolve for them — exactly as a queue job
+     * or workflow run carrying a `pikkuUserId` does. Pass only a user the source
+     * has established itself, such as the one whose credential it polled with;
+     * never one read out of the event.
+     */
+    pikkuUserId?: string;
+}
 export interface PikkuTrigger<TOutput = unknown> {
-    invoke: (data: TOutput) => void;
+    invoke: (data: TOutput, options?: TriggerInvokeOptions) => void;
 }
+/** Generated metadata for every wired trigger, keyed by name. */
 export type TriggerMeta = Record<string, CommonWireMeta & {
     name: string;
 }>;
+/** Generated metadata for every wired trigger source, keyed by name. */
 export type TriggerSourceMeta = Record<string, {
     name: string;
     pikkuFuncId: string;
     packageName?: string;
 }>;
+/**
+ * A trigger source's body: subscribes using `input`, calls `wire.trigger.invoke`
+ * each time the event happens, and resolves to the function that unsubscribes.
+ */
 export type CorePikkuTriggerFunction<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices> = (services: Services, input: TInput, wire: {
-    trigger: {
-        invoke: (data: TOutput) => void;
-    };
+    trigger: PikkuTrigger<TOutput>;
 }) => Promise<() => void | Promise<void>>;
+/**
+ * A trigger source function with its schemas and descriptive metadata, as `pikkuTriggerFunc` returns it.
+ */
 export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
     title?: string;
     description?: string;
@@ -27,6 +48,7 @@ export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown,
     node?: CoreNodeConfig;
 };
 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>;
+/** What `wireTrigger` takes: the name a trigger source fires and the function run each time. */
 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;

package/dist/wirings/trigger/webhook-source-runner.d.ts

@@ -3,6 +3,25 @@ import type { CoreSingletonServices } from '../../types/core.types.js';
 import type { PikkuHTTP } from '../http/http.types.js';
 import type { DeclaredTriggerSource } from '../../services/trigger-source-store.js';
 import type { CoreTriggerWebhookSource, WebhookCheckResult, WebhookSetupResult, WebhookSourceJob, WebhookSourceState, WebhookTeardownResult } from './webhook-source.types.js';
+/**
+ * Registers a webhook trigger source: Pikku mounts its route (by default
+ * `POST /webhooks/<name>`), runs `receive` to turn each request into events,
+ * validates each event against `events`, and queues it on
+ * `pikku-incoming-webhooks` for the trigger named `<name>:<event>`. The sender
+ * is answered at once; a failing trigger is retried by the queue.
+ *
+ * With `verify`, a request with a body is refused with 401 unless it is signed
+ * with the secret in the source's credential; an unsigned body-less request
+ * (a HEAD probe, a validation handshake) may be answered but its events are
+ * refused. Without `verify`, `receive` is responsible for authenticating.
+ *
+ * Skipped with a warning when no metadata was generated for it.
+ *
+ * @param source - The source's name, events, verification and lifecycle steps.
+ * @throws Error when a webhook source with the same name is already registered.
+ *
+ * @example snippet: wireTriggerWebhookSource
+ */
 export declare const wireTriggerWebhookSource: <Events extends Record<string, StandardSchemaV1>>(source: CoreTriggerWebhookSource<Events>) => void;
 /** The declared events some trigger is wired to: what `setup` registers with the provider. */
 export declare const subscribedWebhookEvents: (source: string) => string[];
@@ -19,6 +38,7 @@ export declare const receiveWebhookSourceRequest: (sourceName: string, wire: {
 } | void>;
 /** The `pikku-incoming-webhooks` worker: runs the trigger an event was queued for. Throws so the queue retries. */
 export declare const dispatchWebhookSourceJob: (job: WebhookSourceJob) => Promise<void>;
+/** What one lifecycle pass (`check`, `setup` or `teardown`) did for one webhook source. */
 export type WebhookSourceOutcome = {
     source: string;
     url: string;
@@ -77,7 +97,11 @@ export type WebhookRegistration = {
     /** The signing secrets `setup` stored, so a wiped credential store can be refilled without registering again. */
     credentials?: Record<string, unknown>;
 };
+/** Every source's {@link WebhookRegistration}, keyed by source name. */
 export type WebhookRegistrations = Record<string, WebhookRegistration>;
+/**
+ * A registration kept for a source that is no longer declared, which nothing will tear down automatically.
+ */
 export type OrphanedWebhookRegistration = {
     source: string;
     url: string;

package/dist/wirings/trigger/webhook-source-runner.js

@@ -5,6 +5,25 @@ import { PikkuMissingMetaError, UnauthorizedError, } from '../../errors/errors.j
 import { timingSafeStringEqual, verifyHmacSignature, verifyPublicKeySignature, } from '../../utils/hmac.js';
 import { webhookSecretCredentialName } from './webhook-source.types.js';
 const LIFECYCLE = ['receive', 'check', 'setup', 'teardown'];
+/**
+ * Registers a webhook trigger source: Pikku mounts its route (by default
+ * `POST /webhooks/<name>`), runs `receive` to turn each request into events,
+ * validates each event against `events`, and queues it on
+ * `pikku-incoming-webhooks` for the trigger named `<name>:<event>`. The sender
+ * is answered at once; a failing trigger is retried by the queue.
+ *
+ * With `verify`, a request with a body is refused with 401 unless it is signed
+ * with the secret in the source's credential; an unsigned body-less request
+ * (a HEAD probe, a validation handshake) may be answered but its events are
+ * refused. Without `verify`, `receive` is responsible for authenticating.
+ *
+ * Skipped with a warning when no metadata was generated for it.
+ *
+ * @param source - The source's name, events, verification and lifecycle steps.
+ * @throws Error when a webhook source with the same name is already registered.
+ *
+ * @example snippet: wireTriggerWebhookSource
+ */
 export const wireTriggerWebhookSource = (source) => {
     const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source.name];
     if (!meta) {

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { HmacAlgorithm, SecretEncoding } from '../../utils/hmac.js';
-export declare const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = "pikku-incoming-webhooks";
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from '../../services/incoming-webhook-queue.js';
 /** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
 export declare const webhookSecretCredentialName: (source: string) => string;
 /** What every trigger source produces, whichever way it arrives. */
@@ -27,9 +27,11 @@ export type WebhookRequest = {
 export type WebhookReceiveResult = {
     events: TriggerEvent[];
 };
+/** The HTTP methods a webhook source can be mounted on. */
 export type WebhookSourceMethod = 'post' | 'put' | 'get' | 'head';
 /** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
 export type WebhookSourceState = Record<string, unknown>;
+/** What a webhook source's `check` and `setup` steps are given. */
 export type WebhookLifecycleInput = {
     /** Always this deployment's own route: nothing can point it elsewhere. */
     url: string;
@@ -39,6 +41,7 @@ export type WebhookLifecycleInput = {
     events: string[];
     previous?: WebhookSourceState;
 };
+/** Whether the provider-side registration matches what this deployment needs. */
 export type WebhookCheckResult = {
     status: 'ok';
 } | {
@@ -47,6 +50,7 @@ export type WebhookCheckResult = {
     status: 'drifted';
     reason: string;
 };
+/** What `setup` did at the provider. */
 export type WebhookSetupResult = {
     status: 'created' | 'updated' | 'unchanged';
     state?: WebhookSourceState;
@@ -56,10 +60,12 @@ export type WebhookSetupResult = {
     status: 'manual';
     instructions: string;
 };
+/** What a webhook source's `teardown` step is given. */
 export type WebhookTeardownInput = {
     label: string;
     previous?: WebhookSourceState;
 };
+/** Whether `teardown` removed a registration or found none. */
 export type WebhookTeardownResult = {
     status: 'deleted' | 'absent';
 };
@@ -98,6 +104,7 @@ export type WebhookVerify<Services = any> = {
 type SourceFunction<In, Out> = CorePikkuFunctionConfig<any, any> & {
     func: (services: any, data: In, wire: any) => Promise<Out>;
 };
+/** What `wireTriggerWebhookSource` takes. */
 export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
     /** Triggers subscribe to `<name>:<event>`. Unique across every kind of trigger source. */
     name: string;
@@ -129,6 +136,9 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
     setup?: SourceFunction<WebhookLifecycleInput, WebhookSetupResult>;
     teardown?: SourceFunction<WebhookTeardownInput, WebhookTeardownResult>;
 };
+/**
+ * Generated metadata for one webhook source: its route and the function ids of its lifecycle steps.
+ */
 export type WebhookSourceMeta = {
     name: string;
     method: WebhookSourceMethod | WebhookSourceMethod[];
@@ -139,6 +149,7 @@ export type WebhookSourceMeta = {
     setup?: string;
     teardown?: string;
 };
+/** Generated metadata for every webhook source, keyed by name. */
 export type WebhookSourcesMeta = Record<string, WebhookSourceMeta>;
 /** One queued event on its way to its trigger. */
 export type WebhookSourceJob = {
@@ -147,4 +158,3 @@ export type WebhookSourceJob = {
     /** Present when a store-backed service recorded the receipt. */
     receiptId?: string;
 };
-export {};

package/dist/wirings/trigger/webhook-source.types.js

@@ -1,3 +1,3 @@
-export const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = 'pikku-incoming-webhooks';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from '../../services/incoming-webhook-queue.js';
 /** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
 export const webhookSecretCredentialName = (source) => `${source.replace(/[-_]+([a-z0-9])/gi, (_, c) => c.toUpperCase())}WebhookSecret`;

package/dist/wirings/variable/validate-variable-definitions.d.ts

@@ -1,4 +1,11 @@
 import type { VariableDefinitions, VariableDefinitionsMeta } from './variable.types.js';
 import type { SchemaRefLike } from '../../types/core.types.js';
 export type { SchemaRefLike };
+/**
+ * Merges the variable declarations the inspector found into meta keyed by name.
+ * Declarations that share a `variableId` must use the same schema.
+ *
+ * @throws Error when two declarations of one `variableId` disagree on schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export declare function validateAndBuildVariableDefinitionsMeta(definitions: VariableDefinitions, schemaLookup: Map<string, SchemaRefLike>): VariableDefinitionsMeta;

package/dist/wirings/variable/validate-variable-definitions.js

@@ -1,3 +1,10 @@
+/**
+ * Merges the variable declarations the inspector found into meta keyed by name.
+ * Declarations that share a `variableId` must use the same schema.
+ *
+ * @throws Error when two declarations of one `variableId` disagree on schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLookup) {
     const meta = {};
     const variableIdToDefinition = new Map();

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

@@ -1,3 +1,7 @@
+/**
+ * The declaration {@link defineVariable} takes: a non-secret setting read from the
+ * environment. Anything sensitive belongs in {@link defineSecret} instead.
+ */
 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;
@@ -14,6 +18,7 @@ export type CoreVariable<T = unknown> = {
     /** Where to go to work out what to set this to. */
     docsUrl?: string;
 };
+/** A variable declaration as recorded in generated meta, with the schema replaced by its name. */
 export type VariableDefinitionMeta = {
     name: string;
     displayName: string;
@@ -24,7 +29,9 @@ export type VariableDefinitionMeta = {
     docsUrl?: string;
     sourceFile?: string;
 };
+/** Variable declarations collected by the CLI, keyed by name. */
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
+/** Variable declarations as the inspector found them, before de-duplication. */
 export type VariableDefinitions = VariableDefinitionMeta[];
 /**
  * Declares an environment variable this project needs, with the shape of its

package/dist/wirings/virtual-user/conversation/conversation.types.d.ts

@@ -1,4 +1,7 @@
 export type ConversationApprovalPolicy = 'in-virtual-user' | 'always' | 'never';
+/**
+ * What a scenario asks for when a virtual user holds a conversation with one of the app's agents.
+ */
 export interface ConverseOptions<TAgentName extends string = string> {
     agent: TAgentName;
     /** What the virtual user is trying to get the agent to accomplish. */
@@ -9,6 +12,7 @@ export interface ConverseOptions<TAgentName extends string = string> {
     model?: string;
     maxTurns?: number;
 }
+/** The virtual user's judgement of a conversation, with the transcript it judged. */
 export interface ConversationVerdict {
     passed: boolean;
     reasoning: string;
@@ -26,6 +30,7 @@ export interface TargetAgentReply {
     status?: 'completed' | 'suspended';
     pendingApprovals?: TargetPendingApproval[];
 }
+/** Transport to the agent under test: sends a message, and answers its tool-approval requests. */
 export interface TargetAgentDriver {
     run(message: string): Promise<TargetAgentReply>;
     approve(runId: string, decisions: {

package/dist/wirings/virtual-user/conversation/run-conversation.d.ts

@@ -3,6 +3,7 @@ import type { ResolvedVirtualUser } from '../../../services/virtual-users-servic
 import type { AgentRunnerParams, AgentStepResult } from '../../../services/agent-runner-service.js';
 /** The LLM call the virtual user uses for its own turns/decisions/evaluation. */
 export type VirtualUserLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>;
+/** What `runConversation` needs to play one virtual user against one agent. */
 export interface RunConversationParams {
     /** The person being played — name, job title, personality. */
     virtualUser: ResolvedVirtualUser;
@@ -27,6 +28,11 @@ export interface RunConversationParams {
     /** Display name of the target agent (transcript labelling). */
     agentName: string;
 }
+/** Read a structured `run` result, falling back to parsing JSON from text. */
+export declare function readObject<T>(result: {
+    object?: unknown;
+    text?: string;
+}): T | null;
 /**
  * Run a conversation: an LLM-driven virtual user holds a real multi-turn exchange
  * with a target agent (driven via the injected transport), answers the target's

package/dist/wirings/virtual-user/conversation/run-conversation.js

@@ -46,7 +46,7 @@ function msg(role, content) {
     };
 }
 /** Read a structured `run` result, falling back to parsing JSON from text. */
-function readObject(result) {
+export function readObject(result) {
     if (result.object && typeof result.object === 'object') {
         return result.object;
     }