@pikku/core 0.12.142 → 0.12.144

package/dist/services/secretless.d.ts

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

package/dist/services/secretless.js

@@ -1,3 +1,9 @@
+/**
+ * Thrown when code that may not read secrets (a function body, a permission)
+ * touches `services.secrets`. Secrets are read only in service factories and
+ * middleware; give the service that needs a secret the value when you construct
+ * it.
+ */
 export class SecretAccessDeniedError extends Error {
     constructor(context) {
         super(`'secrets' is not available inside ${context}. SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret when you construct it and ask that service here.`);

package/dist/services/session-store.d.ts

@@ -1,4 +1,9 @@
 import type { CoreUserSession } from '../types/core.types.js';
+/**
+ * Keeps sessions server-side, keyed by pikku user id. When provided as the
+ * `sessionStore` singleton service, a request without a session gets the stored
+ * one, and `setSession`/`clearSession` write through to it.
+ */
 export interface SessionStore<UserSession extends CoreUserSession = CoreUserSession> {
     get(pikkuUserId: string): Promise<UserSession | undefined>;
     set(pikkuUserId: string, session: UserSession): Promise<void>;

package/dist/services/stub-tracker.d.ts

@@ -1,3 +1,4 @@
+/** One recorded call on a stubbed service. */
 export type StubCall = {
     service: string;
     method: string;

package/dist/services/temporary-file-service.d.ts

@@ -1,4 +1,9 @@
 import type { Logger } from './logger.js';
+/**
+ * Scratch files for one unit of work, kept under a temporary directory.
+ * `cleanup` deletes every file this instance wrote. Keys are joined to the
+ * directory as given, so do not pass untrusted keys.
+ */
 export declare class TemporaryFileInstance {
     private logger;
     private tempDir;
@@ -12,6 +17,10 @@ export declare class TemporaryFileInstance {
     private createDir;
     cleanup(): Promise<void>;
 }
+/**
+ * Creates a {@link TemporaryFileInstance} per unit of work, all under one
+ * temporary directory.
+ */
 export declare class TemporaryFileService {
     private logger;
     private tempDir;

package/dist/services/temporary-file-service.js

@@ -2,6 +2,11 @@ import { createReadStream, createWriteStream } from 'fs';
 import { mkdir, rm, stat } from 'fs/promises';
 import { resolve } from 'path';
 import { pipeline } from 'stream/promises';
+/**
+ * Scratch files for one unit of work, kept under a temporary directory.
+ * `cleanup` deletes every file this instance wrote. Keys are joined to the
+ * directory as given, so do not pass untrusted keys.
+ */
 export class TemporaryFileInstance {
     logger;
     tempDir;
@@ -49,6 +54,10 @@ export class TemporaryFileInstance {
         await Promise.all(this.files.map((file) => rm(file)));
     }
 }
+/**
+ * Creates a {@link TemporaryFileInstance} per unit of work, all under one
+ * temporary directory.
+ */
 export class TemporaryFileService {
     logger;
     tempDir;

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

@@ -1,3 +1,7 @@
+/**
+ * Starts and stops the trigger subscriptions registered with `wireTrigger`, so
+ * their target functions run when the source fires.
+ */
 export interface TriggerService {
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/services/trigger-source-store.d.ts

@@ -1,5 +1,10 @@
 import type { WebhookSourceState } from '../wirings/trigger/webhook-source.types.js';
+/** The kinds of trigger source a provider can be registered for. */
 export type TriggerSourceKind = 'webhook';
+/**
+ * A trigger source as declared in code, before anything is registered with its
+ * provider.
+ */
 export type DeclaredTriggerSource = {
     name: string;
     kind: TriggerSourceKind;
@@ -25,6 +30,7 @@ export type TriggerSourceRow = Required<Pick<DeclaredTriggerSource, 'name' | 'ki
     detail: string | null;
     updatedAt: string | null;
 };
+/** The outcome of a setup or teardown step for a trigger source. */
 export type TriggerSourceResult = {
     status: string;
     state?: WebhookSourceState | null;
@@ -40,6 +46,13 @@ export interface TriggerSourceStore {
     setTriggerSourceEnabled(name: string, enabled: boolean): Promise<void>;
     deleteTriggerSource(name: string): Promise<void>;
 }
+/**
+ * A {@link TriggerSourceStore} held in process memory, for development and
+ * tests. Registrations are lost on restart.
+ *
+ * @throws Error from `recordTriggerSource` and `setTriggerSourceEnabled` when
+ * the source is unknown
+ */
 export declare class InMemoryTriggerSourceStore implements TriggerSourceStore {
     private rows;
     syncTriggerSources(sources: DeclaredTriggerSource[]): Promise<void>;

package/dist/services/trigger-source-store.js

@@ -1,3 +1,10 @@
+/**
+ * A {@link TriggerSourceStore} held in process memory, for development and
+ * tests. Registrations are lost on restart.
+ *
+ * @throws Error from `recordTriggerSource` and `setTriggerSourceEnabled` when
+ * the source is unknown
+ */
 export class InMemoryTriggerSourceStore {
     rows = new Map();
     async syncTriggerSources(sources) {

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

@@ -6,12 +6,18 @@ export interface CredentialStatusInfo {
     type: 'singleton' | 'wire';
     oauth2?: boolean;
 }
+/** Generated metadata for one declared credential. */
 export type CredentialMetaInfo = {
     name: string;
     displayName: string;
     type: 'singleton' | 'wire';
     oauth2?: boolean;
 };
+/**
+ * Wraps a `CredentialService` with the credential types generated from your
+ * `defineCredential` declarations, and reports which declared credentials are
+ * configured. Calls pass through unchanged.
+ */
 export declare class TypedCredentialService<TMap = Record<string, unknown>> implements CredentialService {
     private credentials;
     private credentialsMeta;

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

@@ -1,3 +1,8 @@
+/**
+ * Wraps a `CredentialService` with the credential types generated from your
+ * `defineCredential` declarations, and reports which declared credentials are
+ * configured. Calls pass through unchanged.
+ */
 export class TypedCredentialService {
     credentials;
     credentialsMeta;

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

@@ -19,6 +19,7 @@ export interface CredentialStatus {
         tokenSecretId: string;
     };
 }
+/** Generated metadata for one declared secret. */
 export type CredentialMeta = {
     name: string;
     displayName: string;
@@ -32,6 +33,17 @@ export type CredentialMeta = {
         tokenSecretId: string;
     };
 };
+/**
+ * Wraps a {@link SecretService} with the secret types generated from your
+ * `defineSecret` declarations. An `optional` secret that is not set resolves to
+ * `undefined` instead of throwing.
+ *
+ * Values are cached for the life of the process (writes and deletes through
+ * this wrapper clear the key), so a secret rotated in the store is not seen
+ * until restart.
+ *
+ * @example snippet: shopServices
+ */
 export declare class TypedSecretService<TMap = Record<string, unknown>> implements SecretService {
     private secrets;
     private credentialsMeta;

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

@@ -1,3 +1,14 @@
+/**
+ * Wraps a {@link SecretService} with the secret types generated from your
+ * `defineSecret` declarations. An `optional` secret that is not set resolves to
+ * `undefined` instead of throwing.
+ *
+ * Values are cached for the life of the process (writes and deletes through
+ * this wrapper clear the key), so a secret rotated in the store is not seen
+ * until restart.
+ *
+ * @example snippet: shopServices
+ */
 export class TypedSecretService {
     secrets;
     credentialsMeta;

package/dist/services/typed-variables-service.d.ts

@@ -8,6 +8,7 @@ export interface VariableStatus {
     /** Whether the declaration answers for itself when the host sets nothing. */
     hasDefault: boolean;
 }
+/** Generated metadata for one declared variable. */
 export type VariableMeta = {
     name: string;
     displayName: string;

package/dist/services/user-session-service.d.ts

@@ -1,5 +1,11 @@
 import type { CoreUserSession } from '../types/core.types.js';
 import type { SessionStore } from './session-store.js';
+/**
+ * Tracks the session during one invocation. Middleware sets the initial
+ * session; the function's view is frozen when it starts, and
+ * `setSession`/`clearSession` mark it changed so the transport (for example a
+ * cookie middleware) can write it back.
+ */
 export interface SessionService<UserSession extends CoreUserSession> {
     sessionChanged: boolean;
     initial: UserSession | undefined;
@@ -9,6 +15,10 @@ export interface SessionService<UserSession extends CoreUserSession> {
     clear(): Promise<void> | void;
     get(): UserSession | undefined;
 }
+/**
+ * The default {@link SessionService}. Writes through to a {@link SessionStore}
+ * when one is configured and the pikku user id is known.
+ */
 export declare class PikkuSessionService<UserSession extends CoreUserSession> implements SessionService<UserSession> {
     private sessionStore?;
     sessionChanged: boolean;
@@ -24,15 +34,35 @@ export declare class PikkuSessionService<UserSession extends CoreUserSession> im
     clear(): Promise<void>;
     get(): UserSession | undefined;
 }
+/**
+ * The session accessors a transport puts on the wire before middleware runs.
+ * `setSession` and `clearSession` mean the same here as in a function body:
+ * they mark the session changed (so `authCookie` re-issues the cookie) and
+ * write the session store. `setInitialSession` is the request-scoped one, for
+ * middleware that establishes who the caller is from a credential it was
+ * handed.
+ * Runtime adapters that run middleware outside the HTTP runner (such as the
+ * Next.js one) build it with this.
+ */
 export declare function createMiddlewareSessionWireProps<UserSession extends CoreUserSession>(session: SessionService<UserSession>): {
     session: UserSession | undefined;
-    setSession: (s: UserSession) => void;
+    setSession: (s: UserSession) => void | Promise<void>;
+    setInitialSession: (s: UserSession) => void;
+    clearSession: () => void | Promise<void>;
     getSession: () => UserSession | undefined;
     hasSessionChanged: () => boolean;
 };
 export declare function createFunctionSessionWireProps<UserSession extends CoreUserSession>(session: SessionService<UserSession>): {
     session: UserSession | undefined;
     setSession: (s: UserSession) => void | Promise<void>;
+    setInitialSession: (s: UserSession) => void;
+    clearSession: () => void | Promise<void>;
+    getSession: () => UserSession | undefined;
+    hasSessionChanged: () => boolean;
+};
+export declare function createSessionAccessors<UserSession extends CoreUserSession>(session: SessionService<UserSession>): {
+    setSession: (s: UserSession) => void | Promise<void>;
+    setInitialSession: (s: UserSession) => void;
     clearSession: () => void | Promise<void>;
     getSession: () => UserSession | undefined;
     hasSessionChanged: () => boolean;

package/dist/services/user-session-service.js

@@ -1,3 +1,7 @@
+/**
+ * The default {@link SessionService}. Writes through to a {@link SessionStore}
+ * when one is configured and the pikku user id is known.
+ */
 export class PikkuSessionService {
     sessionStore;
     sessionChanged = false;
@@ -25,6 +29,13 @@ export class PikkuSessionService {
     async set(session) {
         this.sessionChanged = true;
         this.session = session;
+        // A session set before anyone was resolved — the usual case for
+        // middleware or a login function signing someone in — is stored under its
+        // own user rather than not at all.
+        const userId = session?.userId;
+        if (this.pikkuUserId === undefined && typeof userId === 'string') {
+            this.pikkuUserId = userId;
+        }
         if (this.sessionStore && this.pikkuUserId) {
             await this.sessionStore.set(this.pikkuUserId, session);
         }
@@ -40,18 +51,33 @@ export class PikkuSessionService {
         return this.session;
     }
 }
+// knowledge: decisions/security/set-session-persists-and-set-initial-session-does-not.md
+/**
+ * The session accessors a transport puts on the wire before middleware runs.
+ * `setSession` and `clearSession` mean the same here as in a function body:
+ * they mark the session changed (so `authCookie` re-issues the cookie) and
+ * write the session store. `setInitialSession` is the request-scoped one, for
+ * middleware that establishes who the caller is from a credential it was
+ * handed.
+ * Runtime adapters that run middleware outside the HTTP runner (such as the
+ * Next.js one) build it with this.
+ */
 export function createMiddlewareSessionWireProps(session) {
     return {
         session: session.get(),
-        setSession: (s) => session.setInitial(s),
-        getSession: () => session.get(),
-        hasSessionChanged: () => session.sessionChanged,
+        ...createSessionAccessors(session),
     };
 }
 export function createFunctionSessionWireProps(session) {
     return {
         session: session.freezeInitial(),
+        ...createSessionAccessors(session),
+    };
+}
+export function createSessionAccessors(session) {
+    return {
         setSession: (s) => session.set(s),
+        setInitialSession: (s) => session.setInitial(s),
         clearSession: () => session.clear(),
         getSession: () => session.get(),
         hasSessionChanged: () => session.sessionChanged,

package/dist/services/v8-coverage-service.d.ts

@@ -1,19 +1,27 @@
+/** A V8 coverage range: byte offsets in the script and how often it ran. */
 export interface CoverageRange {
     startOffset: number;
     endOffset: number;
     count: number;
 }
+/** V8 coverage for one function in a script. */
 export interface FunctionCoverage {
     functionName: string;
     isBlockCoverage: boolean;
     ranges: CoverageRange[];
 }
+/** V8 coverage for one loaded script. */
 export interface ScriptCoverage {
     scriptId: string;
     url: string;
     functions: FunctionCoverage[];
 }
+/** Hit counts per line, keyed by file then line number. */
 export type LineHits = Map<string, Map<number, number>>;
+/**
+ * Coverage collected so far: raw V8 script coverage, or line hits from an
+ * instrumented build.
+ */
 export type CoverageSnapshot = {
     kind: 'v8-scripts';
     scripts: ScriptCoverage[];
@@ -22,7 +30,12 @@ export type CoverageSnapshot = {
     kind: 'line-hits';
     lineHits: LineHits;
 };
+/**
+ * Whether a function's lines all ran, some ran, none ran, or its source could
+ * not be mapped.
+ */
 export type CoverageStatus = 'covered' | 'partial' | 'uncovered' | 'unknown';
+/** Line coverage for one pikku function. */
 export interface FunctionCoverageEntry {
     name: string;
     sourceFile: string;
@@ -34,6 +47,7 @@ export interface FunctionCoverageEntry {
     ratio: number;
     status: CoverageStatus;
 }
+/** Line coverage per pikku function, with totals. */
 export interface FunctionCoverageReport {
     generatedAt: string;
     summary: {
@@ -46,6 +60,9 @@ export interface FunctionCoverageReport {
     };
     functions: FunctionCoverageEntry[];
 }
+/**
+ * Where a pikku function's body is in its source, for mapping coverage onto it.
+ */
 export interface CoverageFunctionMeta {
     name: string;
     sourceFile: string;
@@ -57,6 +74,11 @@ export interface CoverageFunctionMeta {
     bodyEnd?: number;
     funcWrapper?: string;
 }
+/**
+ * Collects code coverage from a running app, so a scenario run can report which
+ * functions it exercised. Provided as the `coverageService` singleton service
+ * during development and test runs.
+ */
 export interface CoverageService {
     start(): Promise<void>;
     takeCoverage(): Promise<CoverageSnapshot>;
@@ -66,6 +88,11 @@ export interface CoverageService {
     reset(): Promise<void>;
     stop(): Promise<void>;
 }
+/**
+ * A {@link CoverageService} that collects precise coverage from the V8
+ * inspector in the current Node process. Only `file://` scripts are reported.
+ * Not for production: precise coverage slows execution.
+ */
 export declare class V8CoverageService implements CoverageService {
     private session;
     private startPromise;

package/dist/services/v8-coverage-service.js

@@ -1,3 +1,8 @@
+/**
+ * A {@link CoverageService} that collects precise coverage from the V8
+ * inspector in the current Node process. Only `file://` scripts are reported.
+ * Not for production: precise coverage slows execution.
+ */
 export class V8CoverageService {
     session = null;
     startPromise = null;

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

@@ -1,3 +1,11 @@
+/**
+ * Reads and writes non-secret configuration, provided as the `variables`
+ * singleton service ({@link LocalVariablesService} reads `process.env`). Use
+ * {@link SecretService} for anything sensitive: variables are plain values and
+ * are not redacted from logs.
+ *
+ * @example snippet: shopServices
+ */
 export interface VariablesService {
     get<T = string>(name: string): Promise<T | undefined> | T | undefined;
     /** Same contract as `SecretService.getSecrets`: missing keys are omitted, hence `Partial<T>`. */

package/dist/services/virtual-user-sign-in.d.ts

@@ -26,6 +26,7 @@ export interface VirtualUserSignIn {
 export declare const authMount: (signInPath?: string) => string | undefined;
 /** Signs one statement naming `virtualUser`, for an audience the signer knows. */
 export type VirtualUserStatementMint = (virtualUser: ResolvedVirtualUser) => string | Promise<string>;
+/** Options for {@link statementSignIn}. */
 export interface StatementSignInOptions {
     apiUrl: string;
     /** Default `/auth/sign-in/virtual-user`. */

package/dist/services/virtual-user-statement.d.ts

@@ -16,6 +16,10 @@ export declare const VIRTUAL_USER_VERIFY_KEY_VARIABLE = "VIRTUAL_USER_VERIFY_KEY
 export declare const VIRTUAL_USER_SIGNING_KEY_VARIABLE = "VIRTUAL_USER_SIGNING_KEY";
 /** The key a run reaches the in-process sign-in under, on `auth.api`. */
 export declare const VIRTUAL_USER_IN_PROCESS_ENDPOINT = "signInVirtualUserInternal";
+/**
+ * Verifies the signed statement a virtual user presents to sign in to a
+ * deployed stage.
+ */
 export interface VirtualUserStatementVerifier {
     /**
      * Resolves to the virtual user the statement names. Throws
@@ -26,6 +30,10 @@ export interface VirtualUserStatementVerifier {
         virtualUserId: string;
     }>;
 }
+/**
+ * Thrown when a virtual user's sign-in statement is not valid: badly signed,
+ * expired, replayed, or for another audience.
+ */
 export declare class VirtualUserStatementError extends Error {
     constructor(message: string);
 }

package/dist/services/virtual-user-statement.js

@@ -16,6 +16,10 @@ export const VIRTUAL_USER_VERIFY_KEY_VARIABLE = 'VIRTUAL_USER_VERIFY_KEY';
 export const VIRTUAL_USER_SIGNING_KEY_VARIABLE = 'VIRTUAL_USER_SIGNING_KEY';
 /** The key a run reaches the in-process sign-in under, on `auth.api`. */
 export const VIRTUAL_USER_IN_PROCESS_ENDPOINT = 'signInVirtualUserInternal';
+/**
+ * Thrown when a virtual user's sign-in statement is not valid: badly signed,
+ * expired, replayed, or for another audience.
+ */
 export class VirtualUserStatementError extends Error {
     constructor(message) {
         super(message);

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

@@ -1,4 +1,5 @@
 import type { Safe } from '../classification/secret-value.js';
+/** One outgoing webhook to send. */
 export interface SendWebhookInput {
     url: string;
     /** Sent as the `X-Pikku-Event` header. */
@@ -14,6 +15,7 @@ export interface SendWebhookInput {
     /** Persisted only by store-backed implementations; the queue-only default ignores it. */
     organizationId?: string;
 }
+/** The queue job that will deliver the webhook. */
 export interface SendWebhookResult {
     jobId: string;
     /**
@@ -25,6 +27,10 @@ export interface SendWebhookResult {
      */
     deliveryId?: string;
 }
+/**
+ * The `webhook` section of your config: signing secret, signature header, retry
+ * policy and the hosts webhooks may be sent to.
+ */
 export interface WebhookServiceConfig {
     retries?: number;
     /** Omitted means exponential backoff. */
@@ -38,6 +44,7 @@ export interface WebhookServiceConfig {
      */
     allowedHosts?: string[];
 }
+/** A signed webhook as queued for delivery. */
 export interface WebhookJobData {
     url: string;
     event?: string;
@@ -49,6 +56,7 @@ export interface WebhookJobData {
      */
     deliveryId?: string;
 }
+/** The outcome of one delivery attempt. */
 export interface WebhookAttemptResult {
     /** Absent when the request never completed. */
     statusCode?: number;
@@ -57,6 +65,7 @@ export interface WebhookAttemptResult {
     error?: string;
     delivered: boolean;
 }
+/** A stored webhook delivery and its current status. */
 export interface WebhookDeliveryRecord {
     deliveryId: string;
     organizationId: string | null;
@@ -77,13 +86,29 @@ export interface WebhookAttemptRecord {
     error: string | null;
     createdAt: Date;
 }
+/** A stored webhook delivery with every attempt made. */
 export interface WebhookDeliveryWithAttempts {
     delivery: WebhookDeliveryRecord;
     attempts: WebhookAttemptRecord[];
 }
+/** The queue outgoing webhooks are delivered through. */
 export declare const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = "pikku-outgoing-webhooks";
 export declare const DEFAULT_WEBHOOK_SIGNATURE_HEADER = "X-Pikku-Signature";
+/**
+ * How many times a failed webhook delivery is retried when nothing else is
+ * configured.
+ */
 export declare const DEFAULT_WEBHOOK_RETRIES = 3;
+/**
+ * Sends signed outgoing webhooks, provided as the `webhookService` singleton
+ * service ({@link QueueWebhookService} delivers through a queue). Bodies are
+ * signed with HMAC-SHA256 as `sha256=<hex>` in the signature header (default
+ * `X-Pikku-Signature`); receivers check it with {@link WebhookService.verify},
+ * which compares in constant time.
+ *
+ * The input is `Safe<>`-guarded, so a `SecretValue` cannot be sent in a
+ * payload. Delivery history is optional: the default keeps none.
+ */
 export declare abstract class WebhookService {
     abstract send<T extends SendWebhookInput>(input: Safe<T>): Promise<SendWebhookResult>;
     /** Produces the header value, `sha256=<hex>`, not the bare digest. */

package/dist/services/webhook-service.js

@@ -1,8 +1,23 @@
 import { NotImplementedError } from '../errors/errors.js';
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js';
+/** The queue outgoing webhooks are delivered through. */
 export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks';
 export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature';
+/**
+ * How many times a failed webhook delivery is retried when nothing else is
+ * configured.
+ */
 export const DEFAULT_WEBHOOK_RETRIES = 3;
+/**
+ * Sends signed outgoing webhooks, provided as the `webhookService` singleton
+ * service ({@link QueueWebhookService} delivers through a queue). Bodies are
+ * signed with HMAC-SHA256 as `sha256=<hex>` in the signature header (default
+ * `X-Pikku-Signature`); receivers check it with {@link WebhookService.verify},
+ * which compares in constant time.
+ *
+ * The input is `Safe<>`-guarded, so a `SecretValue` cannot be sent in a
+ * payload. Delivery history is optional: the default keeps none.
+ */
 export class WebhookService {
     /** Produces the header value, `sha256=<hex>`, not the bare digest. */
     async sign(secret, body) {

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

@@ -2,6 +2,12 @@ import type { CoreUserSession } from '../types/core.types.js';
 import type { SerializedError } from '../errors/serialized-error.js';
 import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run-timeline.js';
+/**
+ * Stores and drives workflow runs, provided as the `workflowService` singleton
+ * service (implementations ship in `@pikku/kysely`, `@pikku/redis` and others,
+ * and an in-memory one in core). It records every step so a run can resume
+ * after a crash or a wait, and serialises work on one run through a lease.
+ */
 export interface WorkflowService {
     wireQueueWorkers?(): void;
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {

package/dist/test-utils.js

@@ -1,7 +1,7 @@
 import { getAllPackageStates } from './pikku-state.js';
 import { clearMiddlewareCache } from './middleware-runner.js';
 import { clearPermissionsCache } from './permissions.js';
-import { clearChannelMiddlewareCache } from './wirings/channel/channel-middleware-runner.js';
+import { clearChannelMiddlewareCache } from './channel-middleware-runner.js';
 /**
  * Clears all runtime caches between test scenarios without touching registered
  * routes, functions, or middleware groups (which are set at module load time

package/dist/testing/service-tests.d.ts

@@ -11,6 +11,10 @@ import type { AgentRunService } from '../wirings/agent/agent.types.js';
 import type { SessionStore } from '../services/session-store.js';
 import type { LeaseService } from '../services/lease-service.js';
 import type { WorkflowFencingHarness } from './service-tests/workflow-fencing-tests.js';
+/**
+ * Input to {@link defineServiceTests}: a backend `name` for the suite titles and a
+ * factory per service the backend implements. Only the services supplied are tested.
+ */
 export interface ServiceTestConfig {
     name: string;
     services: {

package/dist/time-utils.d.ts

@@ -1,10 +1,25 @@
 type TimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'year';
+/** An amount of time in a unit; `value` is negative for the past. A year is 365.25 days. */
 export interface RelativeTimeInput {
     value: number;
     unit: TimeUnit;
 }
+/** Converts a {@link RelativeTimeInput} to milliseconds, rounded to the whole second. */
 export declare const getRelativeTimeOffset: ({ value, unit, }: RelativeTimeInput) => number;
+/** The `Date` that is `relativeTime` away from now. */
 export declare const getRelativeTimeOffsetFromNow: (relativeTime: RelativeTimeInput) => Date;
+/**
+ * Normalises a duration to milliseconds: a number is taken as milliseconds already,
+ * a string is parsed by {@link parseDurationString}.
+ *
+ * @throws Error when the string is not a recognised duration.
+ */
 export declare const getDurationInMilliseconds: (duration: string | number) => number;
+/**
+ * Parses a duration such as `'500ms'`, `'5s'`, `'10min'`, `'1hour'`, `'2days'`,
+ * `'1week'` or `'1y'` into milliseconds. Whole numbers only, no spaces.
+ *
+ * @throws Error when the string does not match the format.
+ */
 export declare const parseDurationString: (duration: string) => number;
 export {};