dsclaw 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -1,2 +1,687 @@
+import pino from 'pino';
+import { z } from 'zod';
+import CircuitBreaker from 'opossum';
+import pLimit from 'p-limit';
+import { Job } from 'bullmq';
 
-export {  }
+/**
+ * Structured error classification for DropClaw.
+ * Every error flowing through the system must have a category
+ * so upstream layers (agents, channels) know how to react.
+ */
+declare const ErrorCategory: {
+    readonly RETRYABLE: "RETRYABLE";
+    readonly NEEDS_HUMAN: "NEEDS_HUMAN";
+    readonly NEEDS_DATA: "NEEDS_DATA";
+    readonly FATAL: "FATAL";
+    readonly DEGRADED: "DEGRADED";
+};
+type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+interface StructuredError {
+    category: ErrorCategory;
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+    cause?: Error;
+}
+declare class DropClawError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(opts: StructuredError);
+    toJSON(): StructuredError;
+}
+
+/**
+ * Structured logger powered by pino.
+ * Automatically injects traceId from AsyncLocalStorage.
+ */
+
+declare function createLogger(module: string): pino.Logger;
+
+/**
+ * Request-scoped tracing via AsyncLocalStorage.
+ * Every inbound message gets a traceId that propagates
+ * through agents, tools, API calls, and logs.
+ */
+interface TraceContext {
+    traceId: string;
+    userId?: string;
+    channelId?: string;
+    sessionId?: string;
+    agentId?: string;
+}
+declare function runWithTrace<T>(ctx: Partial<TraceContext>, fn: () => T): T;
+declare function getTraceContext(): TraceContext;
+declare function getTraceId(): string;
+
+/**
+ * Generate an idempotency key from operation parameters.
+ * Uses a 5-minute time bucket so the same operation within
+ * 5 minutes is considered duplicate.
+ */
+declare function idempotencyKey(userId: string, action: string, params: Record<string, unknown>): string;
+/**
+ * Sleep for a given number of milliseconds.
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Parse Retry-After header value to milliseconds.
+ * Supports both seconds (integer) and HTTP-date formats.
+ */
+declare function parseRetryAfter(value: string | null): number | null;
+
+/**
+ * Audit log for tracking all write operations.
+ * Every action an agent takes is recorded so the user
+ * can always answer "what did the bot do?"
+ */
+interface AuditEntry {
+    timestamp: string;
+    traceId: string;
+    userId: string;
+    agentId: string;
+    action: string;
+    target: string;
+    params?: Record<string, unknown>;
+    result: "success" | "failed" | "pending";
+    error?: string;
+}
+declare function writeAuditLog(entry: Omit<AuditEntry, "timestamp" | "traceId">): void;
+declare function auditFilePath(date: string): string;
+
+/**
+ * Configuration loader with JSON5 support and Zod validation.
+ * Sensitive fields are protected with chmod 0o600.
+ */
+
+declare const ConfigSchema: z.ZodObject<{
+    dsers: z.ZodObject<{
+        apiKey: z.ZodString;
+        baseUrl: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    llm: z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<{
+            openai: "openai";
+            anthropic: "anthropic";
+            google: "google";
+        }>>;
+        apiKey: z.ZodString;
+        model: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    channels: z.ZodObject<{
+        telegram: z.ZodOptional<z.ZodObject<{
+            botToken: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        feishu: z.ZodOptional<z.ZodObject<{
+            appId: z.ZodString;
+            appSecret: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        whatsapp: z.ZodOptional<z.ZodObject<{
+            phoneNumberId: z.ZodString;
+            accessToken: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    memory: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<{
+            file: "file";
+            "mem0-cloud": "mem0-cloud";
+            "mem0-local": "mem0-local";
+        }>>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        qdrantUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    resilience: z.ZodDefault<z.ZodObject<{
+        redis: z.ZodDefault<z.ZodString>;
+        circuitBreaker: z.ZodDefault<z.ZodObject<{
+            threshold: z.ZodDefault<z.ZodNumber>;
+            resetTimeout: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    scans: z.ZodDefault<z.ZodObject<{
+        logistics: z.ZodDefault<z.ZodObject<{
+            cron: z.ZodDefault<z.ZodString>;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        inventory: z.ZodDefault<z.ZodObject<{
+            cron: z.ZodDefault<z.ZodString>;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        profit: z.ZodDefault<z.ZodObject<{
+            cron: z.ZodDefault<z.ZodString>;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    agents: z.ZodDefault<z.ZodObject<{
+        navigator: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        clawOps: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type DropClawConfig = z.infer<typeof ConfigSchema>;
+declare function loadConfig(path?: string): DropClawConfig;
+declare function saveConfig(config: Record<string, unknown>): void;
+
+/**
+ * DropClaw Gateway — central orchestrator.
+ * Wires: Config → DSers Client → Agent → Channel → Memory → Queue.
+ * Handles the message lifecycle from channel input to agent response.
+ */
+
+declare class DropClawGateway {
+    private config;
+    private agent;
+    private channels;
+    private memory;
+    private dsers;
+    private running;
+    constructor(config: DropClawConfig);
+    start(): Promise<void>;
+    private handleMessage;
+    private processWithAgent;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+}
+
+/**
+ * DSers API configuration.
+ * Adapted from dsers-mcp-product, simplified for DropClaw's
+ * config-file-first approach (no env-var credential resolution).
+ */
+interface DSersClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    sessionFile: string;
+    sessionId?: string;
+    sessionState?: string;
+}
+declare function createDSersConfig(apiKey: string, baseUrl?: string): DSersClientConfig;
+
+/**
+ * Enhanced DSers HTTP client with:
+ *  - Circuit breaker (opossum)
+ *  - 429 Retry-After handling
+ *  - 5xx exponential backoff (max 2 retries)
+ *  - Structured error classification
+ *  - traceId injection
+ */
+
+declare class DSersClient {
+    private config;
+    private auth;
+    private limiter;
+    constructor(config: DSersClientConfig);
+    request(method: string, path: string, opts?: {
+        params?: Record<string, unknown>;
+        json?: Record<string, unknown>;
+    }, attempt?: number): Promise<Record<string, unknown>>;
+    get(path: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    post(path: string, json?: Record<string, unknown>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    put(path: string, json?: Record<string, unknown>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    del(path: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Core DSers domain types extracted from the OpenAPI spec.
+ * Covers the essential entities for the DropClaw workflow.
+ */
+interface DSersStore {
+    id: string;
+    name: string;
+    platform: string;
+    url?: string;
+    status?: string;
+}
+interface DSersProduct {
+    id: string;
+    title: string;
+    supplyProductId?: string;
+    supplyAppId?: number;
+    variants?: DSersVariant[];
+    images?: string[];
+    tags?: string[];
+    description?: string;
+}
+interface DSersVariant {
+    id: string;
+    title: string;
+    price: number;
+    compareAtPrice?: number;
+    cost?: number;
+    sku?: string;
+    inventory?: number;
+    image?: string;
+}
+interface DSersOrder {
+    id: string;
+    orderNumber?: string;
+    status: string;
+    storeId: string;
+    totalPrice?: number;
+    currency?: string;
+    createdAt?: string;
+    items?: DSersOrderItem[];
+}
+interface DSersOrderItem {
+    productId: string;
+    variantId: string;
+    title: string;
+    quantity: number;
+    price: number;
+}
+interface PushResult {
+    eventId: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    successCount?: number;
+    failedCount?: number;
+    errors?: string[];
+}
+
+/**
+ * Agent base interface and types.
+ * All agents (Navigator, Claw-Ops, or the combined prototype)
+ * implement this contract.
+ */
+interface AgentMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+interface AgentTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<AgentToolResult>;
+}
+interface AgentToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+interface AgentResponse {
+    text: string;
+    toolCalls?: Array<{
+        tool: string;
+        params: Record<string, unknown>;
+        result: AgentToolResult;
+    }>;
+}
+interface AgentContext {
+    userId: string;
+    sessionId: string;
+    channelId: string;
+    storeId?: string;
+    history: AgentMessage[];
+}
+interface AgentBase {
+    readonly id: string;
+    readonly name: string;
+    registerTool(tool: AgentTool): void;
+    removeTool(name: string): void;
+    getTools(): AgentTool[];
+    process(message: string, context: AgentContext): Promise<AgentResponse>;
+}
+
+/**
+ * Unified memory provider interface.
+ * Implementations: FileMemoryProvider (Plan B), Mem0CloudProvider (Plan C).
+ * The interface stays the same — swap implementations without changing agents.
+ */
+interface MemoryMeta {
+    userId: string;
+    sessionId?: string;
+    agentId?: string;
+    category: MemoryCategory;
+    tags?: string[];
+}
+type MemoryCategory = "preference" | "pattern" | "fact";
+interface Memory {
+    id: string;
+    content: string;
+    metadata: MemoryMeta;
+    score?: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface MemoryFilter {
+    userId?: string;
+    sessionId?: string;
+    category?: MemoryCategory;
+    tags?: string[];
+    limit?: number;
+}
+interface MemoryProvider {
+    readonly name: string;
+    readonly degraded: boolean;
+    add(content: string, metadata: MemoryMeta): Promise<string>;
+    search(query: string, filters: MemoryFilter): Promise<Memory[]>;
+    getAll(filters: MemoryFilter): Promise<Memory[]>;
+    update(id: string, content: string): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * DropClaw Core Agent — unified prototype agent using Vercel AI SDK.
+ * Combines Navigator (strategy) and Claw-Ops (execution) capabilities.
+ * Will be split into two specialized agents in Plan C.
+ */
+
+declare class DropClawCoreAgent implements AgentBase {
+    readonly id = "dropclaw-core";
+    readonly name = "DropClaw Core Agent";
+    private config;
+    private dsers;
+    private memory;
+    private customTools;
+    constructor(config: DropClawConfig, dsers: DSersClient, memory: MemoryProvider);
+    registerTool(t: AgentTool): void;
+    removeTool(name: string): void;
+    getTools(): AgentTool[];
+    process(message: string, context: AgentContext): Promise<AgentResponse>;
+    private buildAITools;
+}
+
+/**
+ * Unified channel adapter interface.
+ * Every messaging platform (Telegram, WhatsApp, Feishu)
+ * implements this contract so the gateway is platform-agnostic.
+ */
+interface NormalizedMessage {
+    traceId: string;
+    channelId: string;
+    channelName: string;
+    userId: string;
+    userName?: string;
+    text: string;
+    attachments?: Attachment[];
+    replyTo?: string;
+    timestamp: Date;
+    metadata: Record<string, unknown>;
+}
+interface Attachment {
+    type: "image" | "file" | "link";
+    url?: string;
+    data?: Buffer;
+    mimeType?: string;
+    fileName?: string;
+}
+interface ActionCard {
+    title: string;
+    summary: string;
+    actions: ActionButton[];
+    jobId?: string;
+    progress?: number;
+}
+interface ActionButton {
+    label: string;
+    callbackData: string;
+}
+interface OutboundMessage {
+    text?: string;
+    card?: ActionCard;
+    replyToMessageId?: string;
+}
+type MessageHandler = (message: NormalizedMessage) => Promise<void>;
+interface ChannelAdapter {
+    readonly name: string;
+    readonly connected: boolean;
+    connect(config: Record<string, unknown>): Promise<void>;
+    disconnect(): Promise<void>;
+    reconnect(): Promise<void>;
+    onMessage(handler: MessageHandler): void;
+    send(targetUserId: string, message: OutboundMessage): Promise<void>;
+    sendCard(targetUserId: string, card: ActionCard): Promise<void>;
+}
+
+/**
+ * Telegram channel adapter using grammY.
+ * Normalizes Telegram messages into the unified format,
+ * supports inline keyboards for confirmations, and auto-reconnects.
+ */
+
+declare class TelegramAdapter implements ChannelAdapter {
+    readonly name = "telegram";
+    private bot;
+    private handler;
+    private _connected;
+    private botToken;
+    get connected(): boolean;
+    connect(config: Record<string, unknown>): Promise<void>;
+    disconnect(): Promise<void>;
+    reconnect(): Promise<void>;
+    onMessage(handler: MessageHandler): void;
+    send(targetUserId: string, message: OutboundMessage): Promise<void>;
+    sendCard(targetUserId: string, card: ActionCard): Promise<void>;
+}
+
+/**
+ * Local JSON-based memory provider.
+ * Stores memories as JSONL files, one per user.
+ * Simple keyword-based search (no vector embeddings).
+ * Replaced by mem0 in Plan C for production use.
+ */
+
+declare class FileMemoryProvider implements MemoryProvider {
+    readonly name = "file";
+    readonly degraded = false;
+    constructor();
+    add(content: string, metadata: MemoryMeta): Promise<string>;
+    search(query: string, filters: MemoryFilter): Promise<Memory[]>;
+    getAll(filters: MemoryFilter): Promise<Memory[]>;
+    update(id: string, content: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    private userFile;
+}
+
+/**
+ * Circuit breaker factory wrapping opossum.
+ * Each external dependency (DSers, LLM, mem0) gets its own breaker
+ * so a single bad dependency cannot take down the entire system.
+ */
+
+interface BreakerOptions {
+    timeout?: number;
+    errorThresholdPercentage?: number;
+    resetTimeout?: number;
+    volumeThreshold?: number;
+    name: string;
+}
+declare function createCircuitBreaker<TArgs extends unknown[], TResult>(name: string, fn: (...args: TArgs) => Promise<TResult>, customOpts?: Partial<BreakerOptions>): CircuitBreaker<TArgs, TResult>;
+declare function getAllBreakerStatus(): Record<string, {
+    state: string;
+    stats: CircuitBreaker.Stats;
+}>;
+
+/**
+ * Generic retry with exponential backoff + jitter.
+ * Respects workspace rule: same error no more than 2 retries.
+ */
+
+interface RetryOptions {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    retryableCategories?: ErrorCategory[];
+}
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+
+/**
+ * Three-layer rate limiting:
+ *   L1 Inbound:  per-IP / per-channel flood protection
+ *   L2 Tenant:   per-userId session serialization + debounce
+ *   L3 Outbound: per-service concurrency cap (DSers, LLM, mem0)
+ */
+
+interface OutboundLimits {
+    dsers: number;
+    llm: number;
+    mem0: number;
+}
+declare function getOutboundLimiter(service: keyof OutboundLimits, customLimits?: Partial<OutboundLimits>): ReturnType<typeof pLimit>;
+/**
+ * Ensure messages from the same user are processed serially.
+ * Returns a release function to call when processing is done.
+ */
+declare function acquireUserLock(userId: string): Promise<() => void>;
+/**
+ * Debounce rapid-fire messages from the same user.
+ * Resolves after `delayMs` of silence.
+ */
+declare function debounceUser(userId: string, delayMs?: number): Promise<void>;
+/**
+ * Check if an inbound source has exceeded the rate limit.
+ * @returns true if the request should be allowed, false if throttled.
+ */
+declare function checkInboundLimit(sourceId: string, maxRequests?: number, windowMs?: number): boolean;
+
+/**
+ * Degradation strategies for when external services are unavailable.
+ * Each service has a defined fallback path.
+ */
+type ServiceName = "dsers" | "llm" | "mem0";
+interface DegradationState {
+    service: ServiceName;
+    degraded: boolean;
+    reason?: string;
+    since?: Date;
+    fallbackActive: boolean;
+}
+declare function markDegraded(service: ServiceName, reason: string): void;
+declare function markRecovered(service: ServiceName): void;
+declare function isDegraded(service: ServiceName): boolean;
+declare function getDegradationStatus(): DegradationState[];
+/**
+ * Produce a user-friendly degradation message for channel output.
+ */
+declare function degradationMessage(service: ServiceName): string;
+
+/**
+ * Job manager interface for BullMQ task queue.
+ * Two queues: high-priority (queries, alerts) and low-priority (batch ops).
+ */
+type JobPriority = "high" | "low";
+interface JobPayload {
+    type: string;
+    userId: string;
+    agentId: string;
+    params: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+interface JobStatus {
+    id: string;
+    state: "waiting" | "active" | "completed" | "failed" | "delayed";
+    progress: number;
+    result?: unknown;
+    error?: string;
+    createdAt: Date;
+    finishedAt?: Date;
+}
+interface JobManager {
+    enqueue(payload: JobPayload, priority?: JobPriority): Promise<string>;
+    getStatus(jobId: string): Promise<JobStatus | null>;
+    cancel(jobId: string): Promise<boolean>;
+    onComplete(handler: (jobId: string, result: unknown) => Promise<void>): void;
+    onFailed(handler: (jobId: string, error: string) => Promise<void>): void;
+}
+
+/**
+ * BullMQ queue manager — dual queues with priority separation.
+ * High: queries, alerts, short tasks (timeout 10s)
+ * Low: batch imports, sync, bulk operations (timeout 5min)
+ */
+
+declare class BullMQJobManager implements JobManager {
+    private highQueue;
+    private lowQueue;
+    private connection;
+    private highWorker?;
+    private lowWorker?;
+    private completeHandlers;
+    private failedHandlers;
+    constructor(redisUrl: string);
+    connect(): Promise<void>;
+    startWorkers(processor: (job: Job<JobPayload>) => Promise<unknown>): void;
+    enqueue(payload: JobPayload, priority?: JobPriority): Promise<string>;
+    getStatus(jobId: string): Promise<JobStatus | null>;
+    cancel(jobId: string): Promise<boolean>;
+    onComplete(handler: (jobId: string, result: unknown) => Promise<void>): void;
+    onFailed(handler: (jobId: string, error: string) => Promise<void>): void;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Rule engine interface for deterministic operations.
+ * Rules bypass the LLM — they execute predictable logic
+ * like price tracking, inventory thresholds, and format validation.
+ */
+interface Rule {
+    id: string;
+    name: string;
+    type: RuleType;
+    conditions: RuleCondition[];
+    actions: RuleAction[];
+    enabled: boolean;
+    priority: number;
+}
+type RuleType = "pricing" | "inventory" | "format" | "guard";
+interface RuleCondition {
+    field: string;
+    operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "in";
+    value: unknown;
+}
+interface RuleAction {
+    type: string;
+    params: Record<string, unknown>;
+}
+interface RuleEvaluationResult {
+    matched: Rule[];
+    actions: RuleAction[];
+    warnings: string[];
+    blocked: string[];
+}
+interface RuleEngine {
+    addRule(rule: Rule): void;
+    removeRule(id: string): void;
+    getRules(): Rule[];
+    evaluate(context: Record<string, unknown>, ruleTypes?: RuleType[]): RuleEvaluationResult;
+}
+
+/**
+ * OpenClaw plugin manifest and version compatibility.
+ * DropClaw registers as an OpenClaw plugin via Plugin SDK
+ * when running inside an OpenClaw gateway.
+ */
+interface PluginManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    configSchema: Record<string, unknown>;
+    kind?: "context-engine";
+    channels: string[];
+    providers: string[];
+    skills: string[];
+}
+declare const DROPCLAW_MANIFEST: PluginManifest;
+
+/**
+ * Version compatibility check against OpenClaw runtime.
+ * Maintains a compatibility matrix to ensure safe upgrades.
+ */
+interface CompatEntry {
+    openclawVersion: string;
+    dropclawVersion: string;
+    status: "tested" | "untested" | "incompatible";
+    notes?: string;
+}
+declare const COMPAT_MATRIX: CompatEntry[];
+declare function checkCompatibility(openclawVersion: string): CompatEntry | null;
+
+export { type ActionCard, type AgentBase, type AgentContext, type AgentResponse, type AgentTool, BullMQJobManager, COMPAT_MATRIX, type ChannelAdapter, ConfigSchema, DROPCLAW_MANIFEST, DSersClient, type DSersClientConfig, type DSersOrder, type DSersProduct, type DSersStore, type DSersVariant, type DropClawConfig, DropClawCoreAgent, DropClawError, DropClawGateway, ErrorCategory, FileMemoryProvider, type JobManager, type JobPayload, type JobStatus, type Memory, type MemoryFilter, type MemoryMeta, type MemoryProvider, type NormalizedMessage, type OutboundMessage, type PushResult, type RetryOptions, type Rule, type RuleEngine, type RuleEvaluationResult, type StructuredError, TelegramAdapter, acquireUserLock, auditFilePath, checkCompatibility, checkInboundLimit, createCircuitBreaker, createDSersConfig, createLogger, debounceUser, degradationMessage, getAllBreakerStatus, getDegradationStatus, getOutboundLimiter, getTraceContext, getTraceId, idempotencyKey, isDegraded, loadConfig, markDegraded, markRecovered, parseRetryAfter, runWithTrace, saveConfig, sleep, withRetry, writeAuditLog };