@k-msg/messaging 0.1.1 → 0.1.2

package/dist/k-msg.d.ts

@@ -0,0 +1,8 @@
+import { KMsgError, type Provider, type Result, type SendOptions, type SendResult } from "@k-msg/core";
+import type { KMsgHooks } from "./hooks";
+export declare class KMsg {
+    private readonly provider;
+    private readonly hooks;
+    constructor(provider: Provider, hooks?: KMsgHooks);
+    send(options: SendOptions): Promise<Result<SendResult, KMsgError>>;
+}

package/dist/personalization/variable.replacer.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Variable replacement and personalization system
+ */
+import type { VariableMap } from "../types/message.types";
+export interface VariableReplacementOptions {
+    variablePattern: RegExp;
+    allowUndefined: boolean;
+    undefinedReplacement: string;
+    caseSensitive: boolean;
+    enableFormatting: boolean;
+    enableConditionals: boolean;
+    enableLoops: boolean;
+    maxRecursionDepth: number;
+}
+export interface VariableInfo {
+    name: string;
+    value: any;
+    formatted: string;
+    type: "string" | "number" | "date" | "boolean" | "array" | "object" | "undefined";
+    position: {
+        start: number;
+        end: number;
+    };
+}
+export interface ReplacementResult {
+    content: string;
+    variables: VariableInfo[];
+    missingVariables: string[];
+    errors: ReplacementError[];
+    metadata: {
+        originalLength: number;
+        finalLength: number;
+        variableCount: number;
+        replacementTime: number;
+    };
+}
+export interface ReplacementError {
+    type: "missing_variable" | "format_error" | "syntax_error" | "recursion_limit";
+    message: string;
+    variable?: string;
+    position?: {
+        start: number;
+        end: number;
+    };
+}
+export interface ConditionalBlock {
+    condition: string;
+    content: string;
+    elseContent?: string;
+}
+export interface LoopBlock {
+    variable: string;
+    array: string;
+    content: string;
+}
+export declare class VariableReplacer {
+    private options;
+    private defaultOptions;
+    constructor(options?: Partial<VariableReplacementOptions>);
+    /**
+     * Replace variables in content
+     */
+    replace(content: string, variables: VariableMap): ReplacementResult;
+    /**
+     * Extract variables from content without replacing
+     */
+    extractVariables(content: string): string[];
+    /**
+     * Validate that all required variables are provided
+     */
+    validate(content: string, variables: VariableMap): {
+        isValid: boolean;
+        missingVariables: string[];
+        errors: ReplacementError[];
+    };
+    /**
+     * Preview replacement result without actually replacing
+     */
+    preview(content: string, variables: VariableMap): {
+        originalContent: string;
+        previewContent: string;
+        variableHighlights: Array<{
+            variable: string;
+            value: string;
+            positions: Array<{
+                start: number;
+                end: number;
+            }>;
+        }>;
+    };
+    private replaceSimpleVariables;
+    private replaceRecursive;
+    private processConditionals;
+    private processLoops;
+    private parseVariableName;
+    private getVariableValue;
+    private formatValue;
+    private formatDate;
+    private getValueType;
+    private hasVariables;
+    private extractConditionals;
+    private extractLoops;
+    private extractVariablesFromExpression;
+    private evaluateCondition;
+    private buildConditionalPattern;
+    private buildLoopPattern;
+}
+/**
+ * Default instance with Korean-optimized settings
+ */
+export declare const defaultVariableReplacer: VariableReplacer;
+/**
+ * Utility functions
+ */
+export declare const VariableUtils: {
+    /**
+     * Extract all variables from content
+     */
+    extractVariables: (content: string) => string[];
+    /**
+     * Replace variables in content
+     */
+    replace: (content: string, variables: VariableMap) => string;
+    /**
+     * Validate content has all required variables
+     */
+    validate: (content: string, variables: VariableMap) => boolean;
+    /**
+     * Create personalized content for multiple recipients
+     */
+    personalize: (content: string, recipients: Array<{
+        phoneNumber: string;
+        variables: VariableMap;
+    }>) => Array<{
+        phoneNumber: string;
+        content: string;
+        errors?: string[];
+    }>;
+};

package/dist/queue/job-queue.interface.d.ts

@@ -0,0 +1,39 @@
+export declare enum JobStatus {
+    PENDING = "pending",
+    PROCESSING = "processing",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    DELAYED = "delayed"
+}
+export interface Job<T> {
+    id: string;
+    type: string;
+    data: T;
+    status: JobStatus;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    delay: number;
+    createdAt: Date;
+    processAt: Date;
+    completedAt?: Date;
+    failedAt?: Date;
+    error?: string;
+    metadata: Record<string, any>;
+}
+export interface JobQueue<T> {
+    enqueue(type: string, data: T, options?: {
+        priority?: number;
+        delay?: number;
+        maxAttempts?: number;
+        metadata?: Record<string, any>;
+    }): Promise<Job<T>>;
+    dequeue(): Promise<Job<T> | undefined>;
+    complete(jobId: string, result?: any): Promise<void>;
+    fail(jobId: string, error: string | Error, shouldRetry?: boolean): Promise<void>;
+    peek(): Promise<Job<T> | undefined>;
+    size(): Promise<number>;
+    getJob(jobId: string): Promise<Job<T> | undefined>;
+    remove(jobId: string): Promise<boolean>;
+    clear(): Promise<void>;
+}

package/dist/queue/job.processor.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Job processor for message queue system
+ */
+import { type Provider } from "@k-msg/core";
+import { EventEmitter } from "events";
+import { type MessageRequest } from "../types/message.types";
+import type { Job, JobQueue } from "./job-queue.interface";
+export interface JobProcessorOptions {
+    concurrency: number;
+    retryDelays: number[];
+    maxRetries: number;
+    pollInterval: number;
+    enableMetrics: boolean;
+    rateLimiter?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    circuitBreaker?: {
+        failureThreshold: number;
+        timeout: number;
+        resetTimeout: number;
+    };
+}
+export type JobHandler<T = any> = (job: Job<T>) => Promise<any>;
+export interface JobProcessorMetrics {
+    processed: number;
+    succeeded: number;
+    failed: number;
+    retried: number;
+    activeJobs: number;
+    queueSize: number;
+    averageProcessingTime: number;
+    lastProcessedAt?: Date;
+}
+export declare class JobProcessor extends EventEmitter {
+    private options;
+    private handlers;
+    private queue;
+    private processing;
+    private isRunning;
+    private pollTimer?;
+    private metrics;
+    private rateLimiter?;
+    private circuitBreaker?;
+    constructor(options: JobProcessorOptions, jobQueue?: JobQueue<any>);
+    /**
+     * Register a job handler
+     */
+    handle<T>(jobType: string, handler: JobHandler<T>): void;
+    /**
+     * Add a job to the queue
+     */
+    add<T>(jobType: string, data: T, options?: {
+        priority?: number;
+        delay?: number;
+        maxAttempts?: number;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Start processing jobs
+     */
+    start(): void;
+    /**
+     * Stop processing jobs
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): JobProcessorMetrics;
+    /**
+     * Get queue status
+     */
+    getQueueStatus(): Promise<{
+        pending: number;
+        processing: number;
+        failed: number;
+        totalProcessed: number;
+    }>;
+    /**
+     * Remove completed jobs from queue
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Get specific job by ID
+     */
+    getJob(jobId: string): Promise<Job<any> | undefined>;
+    /**
+     * Remove job from queue
+     */
+    removeJob(jobId: string): Promise<boolean>;
+    private scheduleNextPoll;
+    private processJobs;
+    private processJob;
+    private failJob;
+    private getRetryDelay;
+    private updateMetrics;
+    private updateAverageProcessingTime;
+}
+/**
+ * Specific processor for message jobs
+ */
+export declare class MessageJobProcessor extends JobProcessor {
+    private provider;
+    constructor(provider: Provider, options?: Partial<JobProcessorOptions>, jobQueue?: JobQueue<any>);
+    private setupMessageHandlers;
+    private processSingleMessage;
+    private processBulkMessages;
+    private processDeliveryUpdate;
+    private processScheduledMessage;
+    /**
+     * Add a message to the processing queue
+     */
+    queueMessage(messageRequest: MessageRequest, options?: {
+        priority?: number;
+        delay?: number;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Add bulk messages to the processing queue
+     */
+    queueBulkMessages(messageRequests: MessageRequest[], options?: {
+        priority?: number;
+        delay?: number;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Schedule a message for future delivery
+     */
+    scheduleMessage(messageRequest: MessageRequest, scheduledAt: Date, options?: {
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+}

package/dist/queue/retry.handler.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Retry handler for failed message deliveries
+ */
+import { EventEmitter } from "events";
+import { type DeliveryReport, MessageStatus } from "../types/message.types";
+export interface RetryPolicy {
+    maxAttempts: number;
+    backoffMultiplier: number;
+    initialDelay: number;
+    maxDelay: number;
+    jitter: boolean;
+    retryableStatuses: MessageStatus[];
+    retryableErrorCodes: string[];
+}
+export interface RetryAttempt {
+    messageId: string;
+    phoneNumber: string;
+    attemptNumber: number;
+    scheduledAt: Date;
+    provider: string;
+    templateId: string;
+    variables: Record<string, any>;
+    metadata: Record<string, any>;
+}
+export interface RetryQueueItem {
+    id: string;
+    messageId: string;
+    phoneNumber: string;
+    originalDeliveryReport: DeliveryReport;
+    attempts: RetryAttempt[];
+    nextRetryAt: Date;
+    status: "pending" | "processing" | "exhausted" | "cancelled";
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface RetryHandlerOptions {
+    policy: RetryPolicy;
+    checkInterval: number;
+    maxQueueSize: number;
+    enablePersistence: boolean;
+    onRetryExhausted?: (item: RetryQueueItem) => Promise<void>;
+    onRetrySuccess?: (item: RetryQueueItem, result: any) => Promise<void>;
+    onRetryFailed?: (item: RetryQueueItem, error: Error) => Promise<void>;
+}
+export interface RetryHandlerMetrics {
+    totalRetries: number;
+    successfulRetries: number;
+    failedRetries: number;
+    exhaustedRetries: number;
+    queueSize: number;
+    averageRetryDelay: number;
+    lastRetryAt?: Date;
+}
+export declare class MessageRetryHandler extends EventEmitter {
+    private options;
+    private retryQueue;
+    private processing;
+    private checkTimer?;
+    private isRunning;
+    private metrics;
+    private defaultPolicy;
+    constructor(options: RetryHandlerOptions);
+    /**
+     * Start the retry handler
+     */
+    start(): void;
+    /**
+     * Stop the retry handler
+     */
+    stop(): Promise<void>;
+    /**
+     * Add a failed delivery for retry
+     */
+    addForRetry(deliveryReport: DeliveryReport): Promise<boolean>;
+    /**
+     * Cancel retry for a specific message
+     */
+    cancelRetry(messageId: string): boolean;
+    /**
+     * Get retry status for a message
+     */
+    getRetryStatus(messageId: string): RetryQueueItem | undefined;
+    /**
+     * Get all retry queue items
+     */
+    getRetryQueue(): RetryQueueItem[];
+    /**
+     * Get metrics
+     */
+    getMetrics(): RetryHandlerMetrics;
+    /**
+     * Clean up completed/exhausted retry items
+     */
+    cleanup(): number;
+    private scheduleNextCheck;
+    private processRetryQueue;
+    private processRetryItem;
+    private executeRetry;
+    private shouldRetry;
+    private createRetryItem;
+    private updateRetryItem;
+    private calculateRetryDelay;
+    private cleanupQueue;
+    private updateMetrics;
+}

package/dist/queue/sqlite-job-queue.d.ts

@@ -0,0 +1,28 @@
+import { type Job, type JobQueue } from "./job-queue.interface";
+interface SQLiteJobQueueOptions {
+    dbPath?: string;
+}
+export declare class SQLiteJobQueue<T> implements JobQueue<T> {
+    private db;
+    constructor(options?: SQLiteJobQueueOptions);
+    private initializeSchema;
+    private jobToRow;
+    private rowToJob;
+    private generateId;
+    enqueue(type: string, data: T, options?: {
+        priority?: number;
+        delay?: number;
+        maxAttempts?: number;
+        metadata?: Record<string, any>;
+    }): Promise<Job<T>>;
+    dequeue(): Promise<Job<T> | undefined>;
+    complete(jobId: string, _result?: any): Promise<void>;
+    fail(jobId: string, error: string | Error, shouldRetry?: boolean): Promise<void>;
+    peek(): Promise<Job<T> | undefined>;
+    size(): Promise<number>;
+    getJob(jobId: string): Promise<Job<T> | undefined>;
+    remove(jobId: string): Promise<boolean>;
+    clear(): Promise<void>;
+    close(): void;
+}
+export {};

package/dist/sender/bulk.sender.d.ts

@@ -0,0 +1,18 @@
+import type { KMsg } from "../k-msg";
+import { type BulkBatchResult, type BulkMessageRequest, type BulkMessageResult } from "../types/message.types";
+export declare class BulkMessageSender {
+    private kmsg;
+    private activeBulkJobs;
+    constructor(kmsg: KMsg);
+    sendBulk(request: BulkMessageRequest): Promise<BulkMessageResult>;
+    private processBatchesAsync;
+    private processBatch;
+    private processRecipient;
+    private createBatches;
+    private delay;
+    private generateRequestId;
+    getBulkStatus(requestId: string): Promise<BulkMessageResult | null>;
+    cancelBulkJob(requestId: string): Promise<boolean>;
+    retryFailedBatch(requestId: string, batchId: string): Promise<BulkBatchResult | null>;
+    cleanup(): void;
+}