@microfox/ai-worker 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+import * as aws_lambda from 'aws-lambda';
+import { DispatchOptions, DispatchResult } from './client.mjs';
+export { SerializedContext, dispatch, dispatchLocal } from './client.mjs';
+import { WorkerHandler } from './handler.mjs';
+export { JobStore, JobStoreUpdate, SQSMessageBody, WebhookPayload, WorkerHandlerParams, createLambdaHandler } from './handler.mjs';
+import { ZodType, z } from 'zod';
+export { WorkersConfig, clearWorkersConfigCache, getWorkersConfig, resolveQueueUrl } from './config.mjs';
+
+/**
+ * Schedule event configuration for a worker.
+ * Supports both simple rate/cron strings and full configuration objects.
+ *
+ * @example Simple rate/cron
+ * ```typescript
+ * schedule: 'rate(2 hours)'
+ * // or
+ * schedule: 'cron(0 12 * * ? *)'
+ * ```
+ *
+ * @example Full configuration
+ * ```typescript
+ * schedule: {
+ *   rate: 'rate(10 minutes)',
+ *   enabled: true,
+ *   input: { key1: 'value1' }
+ * }
+ * ```
+ *
+ * @example Multiple schedules
+ * ```typescript
+ * schedule: [
+ *   'rate(2 hours)',
+ *   { rate: 'cron(0 12 * * ? *)', enabled: false }
+ * ]
+ * ```
+ */
+interface ScheduleEventConfig {
+    /**
+     * Schedule rate using either rate() or cron() syntax.
+     * Can be a string or array of strings for multiple schedules.
+     *
+     * @example 'rate(2 hours)' or 'cron(0 12 * * ? *)'
+     * @example ['cron(0 0/4 ? * MON-FRI *)', 'cron(0 2 ? * SAT-SUN *)']
+     */
+    rate: string | string[];
+    /**
+     * Whether the schedule is enabled (default: true).
+     */
+    enabled?: boolean;
+    /**
+     * Input payload to pass to the function.
+     */
+    input?: Record<string, any>;
+    /**
+     * JSONPath expression to select part of the event data as input.
+     */
+    inputPath?: string;
+    /**
+     * Input transformer configuration for custom input mapping.
+     */
+    inputTransformer?: {
+        inputPathsMap?: Record<string, string>;
+        inputTemplate?: string;
+    };
+    /**
+     * Name of the schedule event.
+     */
+    name?: string;
+    /**
+     * Description of the schedule event.
+     */
+    description?: string;
+    /**
+     * Method to use: 'eventBus' (default) or 'scheduler'.
+     * Use 'scheduler' for higher limits (1M events vs 300).
+     */
+    method?: 'eventBus' | 'scheduler';
+    /**
+     * Timezone for the schedule (only used with method: 'scheduler').
+     * @example 'America/New_York'
+     */
+    timezone?: string;
+}
+type ScheduleConfig = string | ScheduleEventConfig | (string | ScheduleEventConfig)[];
+/**
+ * Configuration for a worker's Lambda function deployment.
+ *
+ * **Best Practice**: Export this as a separate const from your worker file:
+ * ```typescript
+ * export const workerConfig: WorkerConfig = {
+ *   timeout: 900,
+ *   memorySize: 2048,
+ *   layers: ['arn:aws:lambda:${aws:region}:${aws:accountId}:layer:ffmpeg:1'],
+ *   schedule: 'rate(2 hours)',
+ * };
+ * ```
+ *
+ * The CLI will automatically extract it from the export. You do not need to pass it to `createWorker()`.
+ */
+interface WorkerConfig {
+    /**
+     * Lambda function timeout in seconds (max 900).
+     */
+    timeout?: number;
+    /**
+     * Lambda function memory size in MB (128-10240).
+     */
+    memorySize?: number;
+    /**
+     * Optional Lambda layers ARNs to attach to this worker function.
+     *
+     * This is primarily used by @microfox/ai-worker-cli when generating serverless.yml.
+     * Supports CloudFormation pseudo-parameters like ${aws:region} and ${aws:accountId}.
+     *
+     * Example:
+     *   layers: ['arn:aws:lambda:${aws:region}:${aws:accountId}:layer:ffmpeg:1']
+     */
+    layers?: string[];
+    /**
+     * Schedule events configuration for this worker.
+     * Allows multiple schedule events to be attached to the same function.
+     *
+     * @example Simple rate
+     * ```typescript
+     * schedule: 'rate(2 hours)'
+     * ```
+     *
+     * @example Multiple schedules
+     * ```typescript
+     * schedule: [
+     *   'rate(2 hours)',
+     *   { rate: 'cron(0 12 * * ? *)', enabled: true, input: { key: 'value' } }
+     * ]
+     * ```
+     *
+     * @example Using scheduler method with timezone
+     * ```typescript
+     * schedule: {
+     *   method: 'scheduler',
+     *   rate: 'cron(0 0/4 ? * MON-FRI *)',
+     *   timezone: 'America/New_York',
+     *   input: { key1: 'value1' }
+     * }
+     * ```
+     */
+    schedule?: ScheduleConfig;
+    /**
+     * SQS queue settings for this worker (used by @microfox/ai-worker-cli when generating serverless.yml).
+     *
+     * Notes:
+     * - To effectively disable retries, set `maxReceiveCount: 1` (requires DLQ; the CLI will create one).
+     * - SQS does not support `maxReceiveCount: 0`.
+     * - `messageRetentionPeriod` is in seconds (max 1209600 = 14 days).
+     */
+    sqs?: {
+        /**
+         * How many receives before sending to DLQ.
+         * Use 1 to avoid retries.
+         */
+        maxReceiveCount?: number;
+        /**
+         * How long messages are retained in the main queue (seconds).
+         */
+        messageRetentionPeriod?: number;
+        /**
+         * Visibility timeout for the main queue (seconds).
+         * If not set, CLI defaults to (worker timeout + 60s).
+         */
+        visibilityTimeout?: number;
+        /**
+         * DLQ message retention period (seconds).
+         * Defaults to `messageRetentionPeriod` (or 14 days).
+         */
+        deadLetterMessageRetentionPeriod?: number;
+    };
+}
+interface WorkerAgentConfig<INPUT_SCHEMA extends ZodType<any>, OUTPUT> {
+    id: string;
+    inputSchema: INPUT_SCHEMA;
+    outputSchema: ZodType<OUTPUT>;
+    handler: WorkerHandler<z.infer<INPUT_SCHEMA>, OUTPUT>;
+    /**
+     * @deprecated Prefer exporting `workerConfig` as a separate const from your worker file.
+     * The CLI will automatically extract it from the export. This parameter is kept for backward compatibility.
+     */
+    workerConfig?: WorkerConfig;
+}
+interface WorkerAgent<INPUT_SCHEMA extends ZodType<any>, OUTPUT> {
+    id: string;
+    dispatch: (input: z.input<INPUT_SCHEMA>, options: DispatchOptions) => Promise<DispatchResult>;
+    handler: WorkerHandler<z.infer<INPUT_SCHEMA>, OUTPUT>;
+    inputSchema: INPUT_SCHEMA;
+    outputSchema: ZodType<OUTPUT>;
+    workerConfig?: WorkerConfig;
+}
+/**
+ * Creates a worker agent that can be dispatched to SQS/Lambda.
+ *
+ * In development mode (NODE_ENV === 'development' and WORKERS_LOCAL_MODE !== 'false'),
+ * dispatch() will run the handler immediately in the same process.
+ *
+ * In production, dispatch() sends a message to SQS which triggers a Lambda function.
+ *
+ * @template INPUT_SCHEMA - The Zod schema type (e.g., `typeof InputSchema`).
+ *                          Used to derive both:
+ *                          - Pre-parse input type via `z.input<INPUT_SCHEMA>` for `dispatch()` (preserves optional fields)
+ *                          - Parsed input type via `z.infer<INPUT_SCHEMA>` for handler (defaults applied)
+ * @template OUTPUT - The output type returned by the handler. Use `z.infer<typeof OutputSchema>`.
+ *
+ * @param config - Worker agent configuration
+ * @returns A worker agent object with a dispatch method
+ *
+ * @example
+ * ```typescript
+ * const InputSchema = z.object({
+ *   url: z.string().url(),
+ *   timeout: z.number().optional().default(5000), // optional with default
+ * });
+ *
+ * export const worker = createWorker<typeof InputSchema, Output>({
+ *   // dispatch() accepts { url: string, timeout?: number } (pre-parse, optional preserved)
+ *   // handler receives { url: string, timeout: number } (parsed, default applied)
+ * });
+ * ```
+ */
+declare function createWorker<INPUT_SCHEMA extends ZodType<any>, OUTPUT>(config: WorkerAgentConfig<INPUT_SCHEMA, OUTPUT>): WorkerAgent<INPUT_SCHEMA, OUTPUT>;
+/**
+ * Creates a Lambda handler entrypoint for a worker agent.
+ * This is used by the deployment script to generate Lambda entrypoints.
+ *
+ * @param agent - The worker agent
+ * @returns A Lambda handler function
+ */
+declare function createLambdaEntrypoint<INPUT_SCHEMA extends ZodType<any>, OUTPUT>(agent: WorkerAgent<INPUT_SCHEMA, OUTPUT>): (event: aws_lambda.SQSEvent, context: aws_lambda.Context) => Promise<void>;
+
+export { DispatchOptions, DispatchResult, type ScheduleConfig, type ScheduleEventConfig, type WorkerAgent, type WorkerAgentConfig, type WorkerConfig, WorkerHandler, createLambdaEntrypoint, createWorker };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import * as aws_lambda from 'aws-lambda';
+import { DispatchOptions, DispatchResult } from './client.js';
+export { SerializedContext, dispatch, dispatchLocal } from './client.js';
+import { WorkerHandler } from './handler.js';
+export { JobStore, JobStoreUpdate, SQSMessageBody, WebhookPayload, WorkerHandlerParams, createLambdaHandler } from './handler.js';
+import { ZodType, z } from 'zod';
+export { WorkersConfig, clearWorkersConfigCache, getWorkersConfig, resolveQueueUrl } from './config.js';
+
+/**
+ * Schedule event configuration for a worker.
+ * Supports both simple rate/cron strings and full configuration objects.
+ *
+ * @example Simple rate/cron
+ * ```typescript
+ * schedule: 'rate(2 hours)'
+ * // or
+ * schedule: 'cron(0 12 * * ? *)'
+ * ```
+ *
+ * @example Full configuration
+ * ```typescript
+ * schedule: {
+ *   rate: 'rate(10 minutes)',
+ *   enabled: true,
+ *   input: { key1: 'value1' }
+ * }
+ * ```
+ *
+ * @example Multiple schedules
+ * ```typescript
+ * schedule: [
+ *   'rate(2 hours)',
+ *   { rate: 'cron(0 12 * * ? *)', enabled: false }
+ * ]
+ * ```
+ */
+interface ScheduleEventConfig {
+    /**
+     * Schedule rate using either rate() or cron() syntax.
+     * Can be a string or array of strings for multiple schedules.
+     *
+     * @example 'rate(2 hours)' or 'cron(0 12 * * ? *)'
+     * @example ['cron(0 0/4 ? * MON-FRI *)', 'cron(0 2 ? * SAT-SUN *)']
+     */
+    rate: string | string[];
+    /**
+     * Whether the schedule is enabled (default: true).
+     */
+    enabled?: boolean;
+    /**
+     * Input payload to pass to the function.
+     */
+    input?: Record<string, any>;
+    /**
+     * JSONPath expression to select part of the event data as input.
+     */
+    inputPath?: string;
+    /**
+     * Input transformer configuration for custom input mapping.
+     */
+    inputTransformer?: {
+        inputPathsMap?: Record<string, string>;
+        inputTemplate?: string;
+    };
+    /**
+     * Name of the schedule event.
+     */
+    name?: string;
+    /**
+     * Description of the schedule event.
+     */
+    description?: string;
+    /**
+     * Method to use: 'eventBus' (default) or 'scheduler'.
+     * Use 'scheduler' for higher limits (1M events vs 300).
+     */
+    method?: 'eventBus' | 'scheduler';
+    /**
+     * Timezone for the schedule (only used with method: 'scheduler').
+     * @example 'America/New_York'
+     */
+    timezone?: string;
+}
+type ScheduleConfig = string | ScheduleEventConfig | (string | ScheduleEventConfig)[];
+/**
+ * Configuration for a worker's Lambda function deployment.
+ *
+ * **Best Practice**: Export this as a separate const from your worker file:
+ * ```typescript
+ * export const workerConfig: WorkerConfig = {
+ *   timeout: 900,
+ *   memorySize: 2048,
+ *   layers: ['arn:aws:lambda:${aws:region}:${aws:accountId}:layer:ffmpeg:1'],
+ *   schedule: 'rate(2 hours)',
+ * };
+ * ```
+ *
+ * The CLI will automatically extract it from the export. You do not need to pass it to `createWorker()`.
+ */
+interface WorkerConfig {
+    /**
+     * Lambda function timeout in seconds (max 900).
+     */
+    timeout?: number;
+    /**
+     * Lambda function memory size in MB (128-10240).
+     */
+    memorySize?: number;
+    /**
+     * Optional Lambda layers ARNs to attach to this worker function.
+     *
+     * This is primarily used by @microfox/ai-worker-cli when generating serverless.yml.
+     * Supports CloudFormation pseudo-parameters like ${aws:region} and ${aws:accountId}.
+     *
+     * Example:
+     *   layers: ['arn:aws:lambda:${aws:region}:${aws:accountId}:layer:ffmpeg:1']
+     */
+    layers?: string[];
+    /**
+     * Schedule events configuration for this worker.
+     * Allows multiple schedule events to be attached to the same function.
+     *
+     * @example Simple rate
+     * ```typescript
+     * schedule: 'rate(2 hours)'
+     * ```
+     *
+     * @example Multiple schedules
+     * ```typescript
+     * schedule: [
+     *   'rate(2 hours)',
+     *   { rate: 'cron(0 12 * * ? *)', enabled: true, input: { key: 'value' } }
+     * ]
+     * ```
+     *
+     * @example Using scheduler method with timezone
+     * ```typescript
+     * schedule: {
+     *   method: 'scheduler',
+     *   rate: 'cron(0 0/4 ? * MON-FRI *)',
+     *   timezone: 'America/New_York',
+     *   input: { key1: 'value1' }
+     * }
+     * ```
+     */
+    schedule?: ScheduleConfig;
+    /**
+     * SQS queue settings for this worker (used by @microfox/ai-worker-cli when generating serverless.yml).
+     *
+     * Notes:
+     * - To effectively disable retries, set `maxReceiveCount: 1` (requires DLQ; the CLI will create one).
+     * - SQS does not support `maxReceiveCount: 0`.
+     * - `messageRetentionPeriod` is in seconds (max 1209600 = 14 days).
+     */
+    sqs?: {
+        /**
+         * How many receives before sending to DLQ.
+         * Use 1 to avoid retries.
+         */
+        maxReceiveCount?: number;
+        /**
+         * How long messages are retained in the main queue (seconds).
+         */
+        messageRetentionPeriod?: number;
+        /**
+         * Visibility timeout for the main queue (seconds).
+         * If not set, CLI defaults to (worker timeout + 60s).
+         */
+        visibilityTimeout?: number;
+        /**
+         * DLQ message retention period (seconds).
+         * Defaults to `messageRetentionPeriod` (or 14 days).
+         */
+        deadLetterMessageRetentionPeriod?: number;
+    };
+}
+interface WorkerAgentConfig<INPUT_SCHEMA extends ZodType<any>, OUTPUT> {
+    id: string;
+    inputSchema: INPUT_SCHEMA;
+    outputSchema: ZodType<OUTPUT>;
+    handler: WorkerHandler<z.infer<INPUT_SCHEMA>, OUTPUT>;
+    /**
+     * @deprecated Prefer exporting `workerConfig` as a separate const from your worker file.
+     * The CLI will automatically extract it from the export. This parameter is kept for backward compatibility.
+     */
+    workerConfig?: WorkerConfig;
+}
+interface WorkerAgent<INPUT_SCHEMA extends ZodType<any>, OUTPUT> {
+    id: string;
+    dispatch: (input: z.input<INPUT_SCHEMA>, options: DispatchOptions) => Promise<DispatchResult>;
+    handler: WorkerHandler<z.infer<INPUT_SCHEMA>, OUTPUT>;
+    inputSchema: INPUT_SCHEMA;
+    outputSchema: ZodType<OUTPUT>;
+    workerConfig?: WorkerConfig;
+}
+/**
+ * Creates a worker agent that can be dispatched to SQS/Lambda.
+ *
+ * In development mode (NODE_ENV === 'development' and WORKERS_LOCAL_MODE !== 'false'),
+ * dispatch() will run the handler immediately in the same process.
+ *
+ * In production, dispatch() sends a message to SQS which triggers a Lambda function.
+ *
+ * @template INPUT_SCHEMA - The Zod schema type (e.g., `typeof InputSchema`).
+ *                          Used to derive both:
+ *                          - Pre-parse input type via `z.input<INPUT_SCHEMA>` for `dispatch()` (preserves optional fields)
+ *                          - Parsed input type via `z.infer<INPUT_SCHEMA>` for handler (defaults applied)
+ * @template OUTPUT - The output type returned by the handler. Use `z.infer<typeof OutputSchema>`.
+ *
+ * @param config - Worker agent configuration
+ * @returns A worker agent object with a dispatch method
+ *
+ * @example
+ * ```typescript
+ * const InputSchema = z.object({
+ *   url: z.string().url(),
+ *   timeout: z.number().optional().default(5000), // optional with default
+ * });
+ *
+ * export const worker = createWorker<typeof InputSchema, Output>({
+ *   // dispatch() accepts { url: string, timeout?: number } (pre-parse, optional preserved)
+ *   // handler receives { url: string, timeout: number } (parsed, default applied)
+ * });
+ * ```
+ */
+declare function createWorker<INPUT_SCHEMA extends ZodType<any>, OUTPUT>(config: WorkerAgentConfig<INPUT_SCHEMA, OUTPUT>): WorkerAgent<INPUT_SCHEMA, OUTPUT>;
+/**
+ * Creates a Lambda handler entrypoint for a worker agent.
+ * This is used by the deployment script to generate Lambda entrypoints.
+ *
+ * @param agent - The worker agent
+ * @returns A Lambda handler function
+ */
+declare function createLambdaEntrypoint<INPUT_SCHEMA extends ZodType<any>, OUTPUT>(agent: WorkerAgent<INPUT_SCHEMA, OUTPUT>): (event: aws_lambda.SQSEvent, context: aws_lambda.Context) => Promise<void>;
+
+export { DispatchOptions, DispatchResult, type ScheduleConfig, type ScheduleEventConfig, type WorkerAgent, type WorkerAgentConfig, type WorkerConfig, WorkerHandler, createLambdaEntrypoint, createWorker };