@pikku/core 0.12.142 → 0.12.144

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

@@ -2,6 +2,22 @@ import { getErrorResponse, PikkuError } from '../../errors/error-handler.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
+/**
+ * Registers a sessionless function to run on a cron schedule.
+ *
+ * The task only runs once a scheduler service (or a platform cron trigger
+ * calling {@link runScheduledTask}) drives it; wiring alone schedules nothing.
+ * The function receives no input, and can call `scheduledTask.skip()` on its
+ * wire to end the run early.
+ *
+ * Registration needs the metadata `pikku` generates for the task. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param scheduledTask - The task's unique name, cron `schedule`, function, and optional middleware.
+ * @throws {Error} When a task with the same name is already wired.
+ *
+ * @example snippet: wireScheduler
+ */
 export const wireScheduler = (scheduledTask) => {
     const meta = pikkuState(null, 'scheduler', 'meta');
     const taskMeta = meta[scheduledTask.name];
@@ -22,6 +38,7 @@ export const wireScheduler = (scheduledTask) => {
     }
     tasks.set(scheduledTask.name, scheduledTask);
 };
+/** Thrown by {@link runScheduledTask} when no task, or no generated metadata, exists for the requested name. */
 export class ScheduledTaskNotFoundError extends PikkuError {
     constructor(title) {
         super(`Scheduled task not found: ${title}`);
@@ -33,6 +50,16 @@ class ScheduledTaskSkippedError extends PikkuError {
         this.name = 'ScheduledTaskSkippedError';
     }
 }
+/**
+ * Runs one wired scheduled task now. Scheduler services and platform cron handlers call this on each tick.
+ *
+ * When `session` is given it is placed on the wire, so the function and its
+ * middleware see that user; otherwise the task runs without one.
+ *
+ * @param params - See {@link RunScheduledTasksParams}. `traceId` defaults to `cron-<name>-<timestamp>`.
+ * @throws {ScheduledTaskNotFoundError} When the task or its metadata is missing.
+ * @throws The error the function threw, including the one `scheduledTask.skip()` raises, so the caller can tell a skip from a failure.
+ */
 export async function runScheduledTask({ name, session, traceId, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
@@ -85,6 +112,7 @@ export async function runScheduledTask({ name, session, traceId, }) {
         throw e;
     }
 }
+/** Every wired scheduled task, keyed by name. Scheduler services read this to know what to schedule. */
 export const getScheduledTasks = () => {
     return pikkuState(null, 'scheduler', 'tasks');
 };

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

@@ -1,11 +1,13 @@
 import type { CoreUserSession, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
+/** Generated metadata for every wired scheduled task, keyed by name. */
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, CommonWireMeta & {
     name: string;
     schedule: string;
     session?: UserSession;
 }>;
+/** The configuration {@link wireScheduler} takes. An app's generated `wireScheduler` narrows the function and middleware types to its own. */
 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;
@@ -18,6 +20,7 @@ export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<Core
     /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuMiddleware[];
 };
+/** The `scheduledTask` part of a scheduled function's wire: which task is running, when, and a `skip` to end the run without treating it as a failure. */
 export interface PikkuScheduledTask {
     name: string;
     schedule: string;
@@ -25,3 +28,15 @@ export interface PikkuScheduledTask {
     /** Never returns — throws to abort the run. */
     skip: (reason?: string) => void;
 }
+export interface ScheduledTaskRun {
+    startedAt: Date;
+    status: 'completed' | 'failed' | 'skipped';
+    durationMs: number;
+    error: string | null;
+}
+export interface ScheduledTaskRuns {
+    nextRun: Date | null;
+    lastRun: ScheduledTaskRun | null;
+    /** Newest first. */
+    history: ScheduledTaskRun[];
+}

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

@@ -16,6 +16,7 @@ export type CoreScopeNode = {
  * enforces that at runtime, only the build.
  */
 export type CoreScopes = Record<string, CoreScopeNode>;
+/** A node of a scope tree as recorded in generated meta. */
 export type ScopeNodeMeta = {
     displayName?: string;
     description?: string;
@@ -34,6 +35,7 @@ export type ScopeOrigin = {
     package: string;
     displayName?: string;
 };
+/** A root scope tree as recorded in generated meta, with where it came from. */
 export type ScopeDefinitionMeta = {
     name: string;
     displayName?: string;
@@ -42,8 +44,11 @@ export type ScopeDefinitionMeta = {
     sourceFile?: string;
     origin?: ScopeOrigin;
 };
+/** Scope trees as the inspector found them. */
 export type ScopeDefinitions = ScopeDefinitionMeta[];
+/** Scope trees collected by the CLI, keyed by root segment. */
 export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;
+/** One grantable scope from a flattened scope tree; every node, not just the leaves, appears. */
 export type FlatScope = {
     /** Colon-delimited id, e.g. `admin:invoices:create`. */
     id: string;

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

@@ -1,4 +1,4 @@
-export { defineSecret } from './secret.types.js';
-export type { CoreSecret, OAuth2CredentialConfig, SecretDefinitionMeta, SecretDefinitionsMeta, SecretDefinitions, } from './secret.types.js';
+export { defineSecret, SECRET_GENERATE_MIN_SIZE } from './secret.types.js';
+export type { CoreSecret, OAuth2CredentialConfig, SecretGenerate, SecretDefinitionMeta, SecretDefinitionsMeta, SecretDefinitions, } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
 export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

package/dist/wirings/secret/index.js

@@ -1,3 +1,3 @@
-export { defineSecret } from './secret.types.js';
+export { defineSecret, SECRET_GENERATE_MIN_SIZE } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
 export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

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) {