digital-workers 2.1.1 → 2.3.0

package/dist/runtime.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Runtime Integration for Human Request Processing
+ *
+ * Connects transport adapters (Slack, Email, etc.) to a request store and
+ * provides orchestration for approval workflows, questions, and notifications.
+ *
+ * The HumanRequestProcessor is the central coordinator that:
+ * - Sends requests via configured transports
+ * - Tracks request state in a store
+ * - Handles webhook callbacks from transports
+ * - Notifies when requests complete or timeout
+ *
+ * @packageDocumentation
+ */
+import type { Transport } from './transports.js';
+import type { WorkerRef } from './types.js';
+import type { SlackTransport } from './transports/slack.js';
+import type { EmailTransport } from './transports/email.js';
+/**
+ * Status of a human request
+ */
+export type RequestStatus = 'pending' | 'completed' | 'expired' | 'cancelled' | 'failed';
+/**
+ * Type of human request
+ */
+export type RequestType = 'approval' | 'question' | 'notification';
+/**
+ * Result of a completed request
+ */
+export interface RequestResult {
+    /** Whether the request was approved (for approval type) */
+    approved?: boolean;
+    /** Answer to a question (for question type) */
+    answer?: unknown;
+    /** Who responded to the request */
+    respondedBy?: WorkerRef;
+    /** When the response was received */
+    respondedAt?: Date;
+    /** Additional notes from the responder */
+    notes?: string;
+    /** The channel used for the response */
+    via?: Transport;
+}
+/**
+ * A human request tracked by the runtime
+ */
+export interface HumanRequest {
+    /** Unique request identifier */
+    id: string;
+    /** Type of request */
+    type: RequestType;
+    /** Target for the request (channel, email, etc.) */
+    target: string;
+    /** Request content/message */
+    content: string;
+    /** Current status */
+    status: RequestStatus;
+    /** Transport used to send the request */
+    transport: Transport;
+    /** External message ID from the transport */
+    externalId?: string;
+    /** Who initiated the request */
+    requestedBy?: WorkerRef;
+    /** Additional context for the request */
+    context?: Record<string, unknown>;
+    /** Channel to notify requestor of result */
+    notifyChannel?: string;
+    /** When the request was created */
+    createdAt: Date;
+    /** When the request was completed */
+    completedAt?: Date;
+    /** When the request expires */
+    expiresAt?: Date;
+    /** Result of the request (when completed) */
+    result?: RequestResult;
+}
+/**
+ * Data for creating a new request
+ */
+export interface CreateRequestData {
+    type: RequestType;
+    target: string;
+    content: string;
+    transport: Transport;
+    requestedBy?: WorkerRef;
+    context?: Record<string, unknown>;
+    notifyChannel?: string;
+    expiresAt?: Date;
+}
+/**
+ * Data for updating a request
+ */
+export interface UpdateRequestData {
+    status?: RequestStatus;
+    externalId?: string;
+    result?: RequestResult;
+    completedAt?: Date;
+}
+/**
+ * Store interface for persisting human requests
+ */
+export interface HumanRequestStore {
+    /** Create a new request */
+    create(data: CreateRequestData): Promise<HumanRequest>;
+    /** Get a request by ID */
+    get(id: string): Promise<HumanRequest | undefined>;
+    /** Update a request */
+    update(id: string, data: UpdateRequestData): Promise<HumanRequest | undefined>;
+    /** Find a request by external ID (transport message ID) */
+    findByExternalId(externalId: string): Promise<HumanRequest | undefined>;
+    /** List all pending requests */
+    listPending(): Promise<HumanRequest[]>;
+    /** List expired requests that need processing */
+    listExpired(): Promise<HumanRequest[]>;
+}
+/**
+ * In-memory implementation of HumanRequestStore
+ *
+ * Suitable for development and testing. For production, implement
+ * a store backed by Durable Objects, KV, or a database.
+ */
+export declare class InMemoryRequestStore implements HumanRequestStore {
+    private requests;
+    private externalIdIndex;
+    private counter;
+    private generateId;
+    create(data: CreateRequestData): Promise<HumanRequest>;
+    get(id: string): Promise<HumanRequest | undefined>;
+    update(id: string, data: UpdateRequestData): Promise<HumanRequest | undefined>;
+    findByExternalId(externalId: string): Promise<HumanRequest | undefined>;
+    listPending(): Promise<HumanRequest[]>;
+    listExpired(): Promise<HumanRequest[]>;
+}
+/**
+ * Supported transport adapters
+ */
+export interface TransportAdapters {
+    slack?: SlackTransport;
+    email?: EmailTransport;
+}
+/**
+ * Result of submitting a request
+ */
+export interface SubmitResult {
+    success: boolean;
+    requestId?: string;
+    externalId?: string;
+    error?: string;
+}
+/**
+ * Data for submitting a new request
+ */
+export interface SubmitRequestData {
+    type: RequestType;
+    target: string;
+    content: string;
+    transport: Transport;
+    context?: Record<string, unknown>;
+    requestedBy?: WorkerRef;
+    notifyChannel?: string;
+    timeout?: number;
+}
+/**
+ * Webhook payload for processing responses
+ */
+export interface WebhookPayload {
+    type: 'approval_response' | 'question_response' | 'email_reply';
+    requestId: string;
+    approved?: boolean;
+    answer?: unknown;
+    respondedBy?: WorkerRef;
+    notes?: string;
+    from?: string;
+    content?: string;
+}
+/**
+ * Result of processing a webhook
+ */
+export interface WebhookResult {
+    success: boolean;
+    requestId?: string;
+    error?: string;
+}
+/**
+ * Callback data when a request completes
+ */
+export interface CompleteCallbackData {
+    requestId: string;
+    request: HumanRequest;
+    result: RequestResult;
+}
+/**
+ * Callback data when a request times out
+ */
+export interface TimeoutCallbackData {
+    requestId: string;
+    request: HumanRequest;
+}
+/**
+ * Result of cancelling a request
+ */
+export interface CancelResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Configuration for HumanRequestProcessor
+ */
+export interface ProcessorConfig {
+    /** Request store for persistence */
+    store: HumanRequestStore;
+    /** Transport adapters */
+    transports: TransportAdapters;
+    /** Callback when a request completes */
+    onComplete?: (data: CompleteCallbackData) => void | Promise<void>;
+    /** Callback when a request times out */
+    onTimeout?: (data: TimeoutCallbackData) => void | Promise<void>;
+    /** Whether to notify requestor of results */
+    notifyRequestor?: boolean;
+    /** Interval for checking expired requests (ms) */
+    checkIntervalMs?: number;
+}
+/**
+ * Human Request Processor
+ *
+ * Coordinates between transport adapters and the request store to
+ * handle approval workflows, questions, and notifications.
+ *
+ * @example
+ * ```ts
+ * const processor = createHumanRequestProcessor({
+ *   store: new InMemoryRequestStore(),
+ *   transports: {
+ *     slack: createSlackTransport({ botToken, signingSecret }),
+ *     email: createEmailTransport({ apiKey }),
+ *   },
+ *   onComplete: (data) => {
+ *     console.log(`Request ${data.requestId} completed:`, data.result)
+ *   },
+ * })
+ *
+ * // Submit a request
+ * const result = await processor.submitRequest({
+ *   type: 'approval',
+ *   target: '#approvals',
+ *   content: 'Approve deployment?',
+ *   transport: 'slack',
+ * })
+ *
+ * // Handle webhook when user responds
+ * await processor.handleWebhook('slack', {
+ *   type: 'approval_response',
+ *   requestId: result.requestId,
+ *   approved: true,
+ * })
+ * ```
+ */
+export declare class HumanRequestProcessor {
+    private store;
+    private transports;
+    private onCompleteCallback;
+    private onTimeoutCallback;
+    private notifyRequestor;
+    private checkIntervalMs;
+    private timeoutChecker;
+    private destroyed;
+    constructor(config: ProcessorConfig);
+    /**
+     * Submit a new human request via the specified transport
+     */
+    submitRequest(data: SubmitRequestData): Promise<SubmitResult>;
+    /**
+     * Handle a webhook callback from a transport
+     */
+    handleWebhook(transport: Transport, payload: WebhookPayload): Promise<WebhookResult>;
+    /**
+     * Get a request by ID
+     */
+    getRequest(requestId: string): Promise<HumanRequest | undefined>;
+    /**
+     * Cancel a pending request
+     */
+    cancelRequest(requestId: string): Promise<CancelResult>;
+    /**
+     * Stop the processor and clean up resources
+     */
+    destroy(): void;
+    private getTransport;
+    private sendViaTransport;
+    private parseEmailApproval;
+    private notifyRequestorOfResult;
+    private startTimeoutChecker;
+}
+/**
+ * Create a HumanRequestProcessor instance
+ *
+ * @example
+ * ```ts
+ * const processor = createHumanRequestProcessor({
+ *   store: new InMemoryRequestStore(),
+ *   transports: {
+ *     slack: createSlackTransport({ botToken, signingSecret }),
+ *   },
+ *   onComplete: (data) => console.log('Completed:', data),
+ *   onTimeout: (data) => console.log('Timed out:', data),
+ * })
+ * ```
+ */
+export declare function createHumanRequestProcessor(config: ProcessorConfig): HumanRequestProcessor;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}