@absolutejs/voice 0.0.22-beta.25 → 0.0.22-beta.251

package/dist/campaign.d.ts

@@ -0,0 +1,746 @@
+import { Elysia } from 'elysia';
+import type { VoiceRedisTaskLeaseCoordinator } from './queue';
+import type { VoiceTelephonyOutcomeDecision, VoiceTelephonyOutcomeProviderEvent, VoiceTelephonyWebhookDecision } from './telephonyOutcome';
+export type VoiceCampaignStatus = 'canceled' | 'completed' | 'draft' | 'paused' | 'running';
+export type VoiceCampaignRecipientStatus = 'canceled' | 'completed' | 'failed' | 'pending' | 'queued';
+export type VoiceCampaignAttemptStatus = 'canceled' | 'failed' | 'queued' | 'running' | 'succeeded';
+export type VoiceCampaignTimeWindow = {
+    daysOfWeek?: number[];
+    endHour: number;
+    startHour: number;
+    timeZoneOffsetMinutes?: number;
+};
+export type VoiceCampaignRateLimit = {
+    maxAttempts: number;
+    windowMs: number;
+};
+export type VoiceCampaignRetryPolicy = {
+    backoffMs?: number | number[];
+    maxBackoffMs?: number;
+};
+export type VoiceCampaignSchedule = {
+    attemptWindow?: VoiceCampaignTimeWindow;
+    quietHours?: VoiceCampaignTimeWindow;
+    rateLimit?: VoiceCampaignRateLimit;
+    retryPolicy?: VoiceCampaignRetryPolicy;
+};
+export type VoiceCampaignRecipient = {
+    attempts: number;
+    completedAt?: number;
+    createdAt: number;
+    error?: string;
+    id: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    phone: string;
+    status: VoiceCampaignRecipientStatus;
+    updatedAt: number;
+    variables?: Record<string, string | number | boolean | undefined>;
+};
+export type VoiceCampaignAttempt = {
+    campaignId: string;
+    completedAt?: number;
+    createdAt: number;
+    error?: string;
+    externalCallId?: string;
+    id: string;
+    metadata?: Record<string, unknown>;
+    recipientId: string;
+    startedAt?: number;
+    status: VoiceCampaignAttemptStatus;
+    updatedAt: number;
+};
+export type VoiceCampaign = {
+    createdAt: number;
+    description?: string;
+    id: string;
+    maxAttempts: number;
+    maxConcurrentAttempts: number;
+    metadata?: Record<string, unknown>;
+    name: string;
+    schedule?: VoiceCampaignSchedule;
+    status: VoiceCampaignStatus;
+    updatedAt: number;
+};
+export type VoiceCampaignRecord = {
+    attempts: VoiceCampaignAttempt[];
+    campaign: VoiceCampaign;
+    recipients: VoiceCampaignRecipient[];
+};
+export type VoiceCampaignStore = {
+    get: (id: string) => Promise<VoiceCampaignRecord | undefined> | VoiceCampaignRecord | undefined;
+    list: () => Promise<VoiceCampaignRecord[]> | VoiceCampaignRecord[];
+    remove: (id: string) => Promise<void> | void;
+    set: (id: string, record: VoiceCampaignRecord) => Promise<void> | void;
+};
+export type VoiceCampaignDialerInput = {
+    attempt: VoiceCampaignAttempt;
+    campaign: VoiceCampaign;
+    recipient: VoiceCampaignRecipient;
+};
+export type VoiceCampaignDialerResult = {
+    externalCallId?: string;
+    metadata?: Record<string, unknown>;
+    status?: 'queued' | 'running' | 'succeeded';
+};
+export type VoiceCampaignDialer = (input: VoiceCampaignDialerInput) => Promise<VoiceCampaignDialerResult> | VoiceCampaignDialerResult;
+export type VoiceCampaignCreateInput = {
+    description?: string;
+    id?: string;
+    maxAttempts?: number;
+    maxConcurrentAttempts?: number;
+    metadata?: Record<string, unknown>;
+    name: string;
+    schedule?: VoiceCampaignSchedule;
+};
+export type VoiceCampaignRecipientInput = {
+    id?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    phone: string;
+    variables?: VoiceCampaignRecipient['variables'];
+};
+export type VoiceCampaignRecipientImportRow = Record<string, unknown>;
+export type VoiceCampaignRecipientImportIssueCode = 'duplicate' | 'missing-consent' | 'missing-phone' | 'invalid-phone';
+export type VoiceCampaignRecipientImportIssue = {
+    code: VoiceCampaignRecipientImportIssueCode;
+    message: string;
+    row: number;
+    value?: unknown;
+};
+export type VoiceCampaignRecipientImportOptions = {
+    consentColumn?: string;
+    csv?: string;
+    dedupe?: boolean;
+    idColumn?: string;
+    metadataColumns?: string[];
+    nameColumn?: string;
+    phoneColumn?: string;
+    requireConsent?: boolean;
+    rows?: VoiceCampaignRecipientImportRow[];
+    variableColumns?: string[];
+};
+export type VoiceCampaignRecipientImportResult = {
+    accepted: VoiceCampaignRecipientInput[];
+    duplicates: number;
+    rejected: VoiceCampaignRecipientImportIssue[];
+    total: number;
+};
+export type VoiceCampaignAttemptResultInput = {
+    error?: string;
+    externalCallId?: string;
+    metadata?: Record<string, unknown>;
+    status: 'failed' | 'succeeded';
+};
+export type VoiceCampaignTickResult = {
+    attempted: number;
+    blocked: Array<{
+        reason: 'outside-attempt-window' | 'quiet-hours' | 'rate-limit' | 'retry-backoff';
+        recipientId?: string;
+        until?: number;
+    }>;
+    campaignId: string;
+    errors: Array<{
+        error: string;
+        recipientId: string;
+    }>;
+    started: VoiceCampaignAttempt[];
+};
+export type VoiceCampaignProofOptions = {
+    campaign?: VoiceCampaignCreateInput;
+    completeAttempts?: boolean;
+    recipients?: VoiceCampaignRecipientInput[];
+    runtime?: VoiceCampaignRuntime;
+    store?: VoiceCampaignStore;
+};
+export type VoiceCampaignProofReport = {
+    campaign: VoiceCampaignRecord;
+    created: VoiceCampaignRecord;
+    final: VoiceCampaignRecord;
+    proof: 'voice-campaign';
+    recipients: VoiceCampaignRecord;
+    summary: VoiceCampaignSummary;
+    tick: VoiceCampaignTickResult;
+};
+export type VoiceCampaignReadinessCheck = {
+    details?: Record<string, unknown>;
+    name: string;
+    status: 'fail' | 'pass';
+};
+export type VoiceCampaignReadinessProofOptions = {
+    store?: VoiceCampaignStore;
+};
+export type VoiceCampaignReadinessProofReport = {
+    campaigns: {
+        retry: VoiceCampaignRecord;
+        scheduled: VoiceCampaignRecord;
+    };
+    checks: VoiceCampaignReadinessCheck[];
+    generatedAt: number;
+    import: VoiceCampaignRecipientImportResult;
+    ok: boolean;
+    proof: 'voice-campaign-readiness';
+    ticks: {
+        allowed: VoiceCampaignTickResult;
+        quietHours: VoiceCampaignTickResult;
+        rateLimited: VoiceCampaignTickResult;
+        retryAllowed: VoiceCampaignTickResult;
+        retryBackoff: VoiceCampaignTickResult;
+        retryInitial: VoiceCampaignTickResult;
+        windowBlocked: VoiceCampaignTickResult;
+    };
+};
+export type VoiceCampaignSummary = {
+    attempts: {
+        failed: number;
+        queued: number;
+        running: number;
+        succeeded: number;
+        total: number;
+    };
+    campaigns: {
+        canceled: number;
+        completed: number;
+        draft: number;
+        paused: number;
+        running: number;
+        total: number;
+    };
+    recipients: {
+        canceled: number;
+        completed: number;
+        failed: number;
+        pending: number;
+        queued: number;
+        total: number;
+    };
+};
+export type VoiceCampaignRuntimeOptions = {
+    dialer?: VoiceCampaignDialer;
+    now?: () => number;
+    store: VoiceCampaignStore;
+};
+export type VoiceCampaignRuntime = {
+    addRecipients: (campaignId: string, recipients: VoiceCampaignRecipientInput[]) => Promise<VoiceCampaignRecord>;
+    cancel: (campaignId: string) => Promise<VoiceCampaignRecord>;
+    completeAttempt: (campaignId: string, attemptId: string, result: VoiceCampaignAttemptResultInput) => Promise<VoiceCampaignRecord>;
+    create: (input: VoiceCampaignCreateInput) => Promise<VoiceCampaignRecord>;
+    enqueue: (campaignId: string) => Promise<VoiceCampaignRecord>;
+    get: (campaignId: string) => Promise<VoiceCampaignRecord | undefined>;
+    importRecipients: (campaignId: string, input: VoiceCampaignRecipientImportOptions) => Promise<VoiceCampaignRecord & {
+        import: VoiceCampaignRecipientImportResult;
+    }>;
+    list: () => Promise<VoiceCampaignRecord[]>;
+    pause: (campaignId: string) => Promise<VoiceCampaignRecord>;
+    remove: (campaignId: string) => Promise<void>;
+    resume: (campaignId: string) => Promise<VoiceCampaignRecord>;
+    summarize: () => Promise<VoiceCampaignSummary>;
+    tick: (campaignId: string) => Promise<VoiceCampaignTickResult>;
+};
+export type VoiceCampaignRoutesOptions = VoiceCampaignRuntimeOptions & {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    observability?: VoiceCampaignObservabilityOptions;
+    operationsRecordHref?: false | string | ((input: {
+        attempt: VoiceCampaignAttempt;
+        campaign: VoiceCampaign;
+        recipient?: VoiceCampaignRecipient;
+        sessionId?: string;
+    }) => string | undefined);
+    name?: string;
+    path?: string;
+    title?: string;
+};
+export type VoiceCampaignWorkerOptions = {
+    campaignIds?: string[];
+    leaseMs?: number;
+    leases: VoiceRedisTaskLeaseCoordinator;
+    maxCampaigns?: number;
+    runtime?: VoiceCampaignRuntime;
+    statuses?: VoiceCampaignStatus[];
+    store?: VoiceCampaignStore;
+    workerId: string;
+};
+export type VoiceCampaignWorkerResult = {
+    attempted: number;
+    campaigns: number;
+    errors: Array<{
+        campaignId: string;
+        error: string;
+    }>;
+    skipped: number;
+    started: VoiceCampaignAttempt[];
+};
+export type VoiceCampaignWorker = {
+    drain: () => Promise<VoiceCampaignWorkerResult>;
+};
+export type VoiceCampaignWorkerLoopOptions = {
+    onError?: (error: unknown) => void | Promise<void>;
+    pollIntervalMs?: number;
+    worker: VoiceCampaignWorker;
+};
+export type VoiceCampaignWorkerLoop = {
+    isRunning: () => boolean;
+    start: () => void;
+    stop: () => void;
+    tick: () => Promise<VoiceCampaignWorkerResult>;
+};
+export type VoiceCampaignObservabilityOptions = {
+    leases?: VoiceRedisTaskLeaseCoordinator;
+    now?: number;
+    rateWindowMs?: number;
+    stuckAfterMs?: number;
+};
+export type VoiceCampaignObservabilityReport = {
+    attemptRate: {
+        failed: number;
+        started: number;
+        succeeded: number;
+        windowMs: number;
+    };
+    campaigns: Array<{
+        activeAttempts: number;
+        campaignId: string;
+        lease?: {
+            expiresAt: number;
+            workerId: string;
+        };
+        name: string;
+        queueDepth: number;
+        status: VoiceCampaignStatus;
+        stuckAttempts: number;
+        stuckRecipients: number;
+        updatedAt: number;
+    }>;
+    failureReasons: Array<{
+        count: number;
+        reason: string;
+    }>;
+    generatedAt: number;
+    leases: {
+        active: number;
+        known: boolean;
+    };
+    queue: {
+        activeAttempts: number;
+        queuedRecipients: number;
+        runningCampaigns: number;
+    };
+    stuck: {
+        attempts: Array<{
+            attemptId: string;
+            campaignId: string;
+            recipientId: string;
+            status: VoiceCampaignAttemptStatus;
+            updatedAt: number;
+        }>;
+        recipients: Array<{
+            campaignId: string;
+            recipientId: string;
+            status: VoiceCampaignRecipientStatus;
+            updatedAt: number;
+        }>;
+    };
+    summary: VoiceCampaignSummary;
+};
+export type VoiceCampaignTelephonyOutcomeInput<TResult = unknown> = {
+    campaignId?: string;
+    decision: VoiceTelephonyOutcomeDecision;
+    event?: VoiceTelephonyOutcomeProviderEvent;
+    externalCallId?: string;
+    routeResult?: TResult;
+    sessionId?: string;
+    attemptId?: string;
+};
+export type VoiceCampaignTelephonyOutcomeStatus = 'failed' | 'ignore' | 'succeeded';
+export type VoiceCampaignTelephonyOutcomeOptions<TResult = unknown> = {
+    resolveCampaignId?: (input: VoiceCampaignTelephonyOutcomeInput<TResult>) => Promise<string | undefined> | string | undefined;
+    resolveExternalCallId?: (input: VoiceCampaignTelephonyOutcomeInput<TResult>) => Promise<string | undefined> | string | undefined;
+    resolveAttemptId?: (input: VoiceCampaignTelephonyOutcomeInput<TResult>) => Promise<string | undefined> | string | undefined;
+    runtime?: VoiceCampaignRuntime;
+    statusForDecision?: (input: VoiceCampaignTelephonyOutcomeInput<TResult>) => Promise<VoiceCampaignTelephonyOutcomeStatus> | VoiceCampaignTelephonyOutcomeStatus;
+    store?: VoiceCampaignStore;
+};
+export type VoiceCampaignTelephonyOutcomeResult = {
+    applied: boolean;
+    campaignId?: string;
+    error?: string;
+    externalCallId?: string;
+    reason?: 'ignored' | 'missing-attempt' | 'missing-campaign' | 'missing-runtime' | 'terminal-attempt';
+    status?: 'failed' | 'succeeded';
+    attemptId?: string;
+};
+export declare const importVoiceCampaignRecipients: (options: VoiceCampaignRecipientImportOptions) => VoiceCampaignRecipientImportResult;
+export declare const createVoiceMemoryCampaignStore: () => VoiceCampaignStore;
+export declare const summarizeVoiceCampaigns: (records: VoiceCampaignRecord[]) => VoiceCampaignSummary;
+export declare const buildVoiceCampaignObservabilityReport: (records: VoiceCampaignRecord[], options?: VoiceCampaignObservabilityOptions) => Promise<VoiceCampaignObservabilityReport>;
+export declare const createVoiceCampaign: (options: VoiceCampaignRuntimeOptions) => VoiceCampaignRuntime;
+export declare const createVoiceCampaignWorker: (options: VoiceCampaignWorkerOptions) => VoiceCampaignWorker;
+export declare const createVoiceCampaignWorkerLoop: (options: VoiceCampaignWorkerLoopOptions) => VoiceCampaignWorkerLoop;
+export declare const applyVoiceCampaignTelephonyOutcome: <TResult = unknown>(input: VoiceCampaignTelephonyOutcomeInput<TResult>, options?: VoiceCampaignTelephonyOutcomeOptions<TResult>) => Promise<VoiceCampaignTelephonyOutcomeResult>;
+export declare const createVoiceCampaignTelephonyOutcomeHandler: <TResult = unknown>(options: VoiceCampaignTelephonyOutcomeOptions<TResult>) => (input: VoiceTelephonyWebhookDecision<TResult>) => Promise<VoiceCampaignTelephonyOutcomeResult>;
+export declare const runVoiceCampaignProof: (options?: VoiceCampaignProofOptions) => Promise<VoiceCampaignProofReport>;
+export declare const runVoiceCampaignReadinessProof: (options?: VoiceCampaignReadinessProofOptions) => Promise<VoiceCampaignReadinessProofReport>;
+export declare const renderVoiceCampaignsHTML: (records: VoiceCampaignRecord[], options?: Pick<VoiceCampaignRoutesOptions, "operationsRecordHref" | "title">) => string;
+export declare const renderVoiceCampaignObservabilityHTML: (report: VoiceCampaignObservabilityReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceCampaignRoutes: (options: VoiceCampaignRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: {
+                    campaigns: VoiceCampaignRecord[];
+                    summary: VoiceCampaignSummary;
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        observability: {
+            get: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: VoiceCampaignObservabilityReport;
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        "readiness-proof": {
+            get: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: VoiceCampaignReadinessProofReport;
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceCampaignRecord;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            get: {
+                body: unknown;
+                params: {
+                    campaignId: string;
+                } & {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    422: {
+                        type: "validation";
+                        on: string;
+                        summary?: string;
+                        message?: string;
+                        found?: unknown;
+                        property?: string;
+                        expected?: string;
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            delete: {
+                body: unknown;
+                params: {
+                    campaignId: string;
+                } & {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: {
+                        ok: boolean;
+                    };
+                    422: {
+                        type: "validation";
+                        on: string;
+                        summary?: string;
+                        message?: string;
+                        found?: unknown;
+                        property?: string;
+                        expected?: string;
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            recipients: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignRecord;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            recipients: {
+                import: {
+                    post: {
+                        body: unknown;
+                        params: {
+                            campaignId: string;
+                        } & {};
+                        query: unknown;
+                        headers: unknown;
+                        response: {
+                            200: VoiceCampaignRecord & {
+                                import: VoiceCampaignRecipientImportResult;
+                            };
+                            422: {
+                                type: "validation";
+                                on: string;
+                                summary?: string;
+                                message?: string;
+                                found?: unknown;
+                                property?: string;
+                                expected?: string;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            enqueue: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignRecord;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            pause: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignRecord;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            resume: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignRecord;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            cancel: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignRecord;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            tick: {
+                post: {
+                    body: unknown;
+                    params: {
+                        campaignId: string;
+                    } & {};
+                    query: unknown;
+                    headers: unknown;
+                    response: {
+                        200: VoiceCampaignTickResult;
+                        422: {
+                            type: "validation";
+                            on: string;
+                            summary?: string;
+                            message?: string;
+                            found?: unknown;
+                            property?: string;
+                            expected?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        ":campaignId": {
+            attempts: {
+                ":attemptId": {
+                    result: {
+                        post: {
+                            body: unknown;
+                            params: {
+                                campaignId: string;
+                                attemptId: string;
+                            } & {};
+                            query: unknown;
+                            headers: unknown;
+                            response: {
+                                200: VoiceCampaignRecord;
+                                422: {
+                                    type: "validation";
+                                    on: string;
+                                    summary?: string;
+                                    message?: string;
+                                    found?: unknown;
+                                    property?: string;
+                                    expected?: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;