dsclaw 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,707 @@
+import pino from 'pino';
+import { z } from 'zod';
+import CircuitBreaker from 'opossum';
+import pLimit from 'p-limit';
+import { Job } from 'bullmq';
+
+/**
+ * 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;
+
+/**
+ * Minimal configuration — defaults work out of the box.
+ * Web chat starts automatically; Telegram is optional.
+ */
+
+declare const ConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    telegramBotToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type DropClawConfig = z.infer<typeof ConfigSchema>;
+declare function loadConfig(path?: string): DropClawConfig;
+declare function saveConfig(config: DropClawConfig): void;
+
+/**
+ * User session state machine + encrypted credential storage.
+ * Each Telegram user has their own session with DSers + LLM credentials.
+ * Credentials are AES-256-GCM encrypted, bound to machine identity.
+ */
+type SessionState = "new" | "onboard_demo" | "onboard_dsers_email" | "onboard_dsers_password" | "onboard_llm" | "ready";
+interface UserSessionData {
+    state: SessionState;
+    dspiEmail?: string;
+    dspiPassword?: string;
+    llmProvider?: string;
+    llmApiKey?: string;
+    llmModel?: string;
+    language?: string;
+}
+declare function loadSession(userId: string): UserSessionData;
+declare function saveSession(userId: string, session: UserSessionData): void;
+declare function deleteSession(userId: string): void;
+declare function isOnboarding(state: SessionState): boolean;
+
+/**
+ * DropClaw Gateway — central orchestrator.
+ *
+ * Flow:
+ *   1. User opens web chat (or sends Telegram message)
+ *   2. Gateway loads user session (encrypted on disk)
+ *   3. If not "ready": handle onboarding conversation (no LLM needed)
+ *   4. If "ready": route to AI agent with streaming (web) or batch (Telegram)
+ *
+ * Web chat is the default channel (zero config).
+ * Telegram is optional (requires bot token in config).
+ */
+
+declare class DropClawGateway {
+    private config;
+    private channels;
+    private webChannel;
+    private memory;
+    private agents;
+    private dsersClients;
+    private running;
+    constructor(config: DropClawConfig);
+    start(): Promise<void>;
+    private handleMessage;
+    private handleOnboarding;
+    private onboardWelcome;
+    private onboardEmail;
+    private onboardPassword;
+    private onboardLLM;
+    private handleReady;
+    private handleReadyStreaming;
+    private handleReadyBatch;
+    private getOrCreateAgent;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+}
+
+/**
+ * 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>;
+    deleteMessage(chatId: string | number, messageId: number): Promise<void>;
+}
+
+/**
+ * Web Chat Server — HTTP + WebSocket.
+ * Serves chat.html and handles real-time messaging via WebSocket.
+ * Implements ChannelAdapter for gateway integration.
+ * Supports streaming for Claude-like token-by-token output.
+ */
+
+declare class WebChatServer implements ChannelAdapter {
+    readonly name = "web";
+    private server;
+    private wss;
+    private handler;
+    private connections;
+    private _connected;
+    private port;
+    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>;
+    deleteMessage(): Promise<void>;
+    sendStreamStart(userId: string): void;
+    sendStreamDelta(userId: string, delta: string): void;
+    sendStreamEnd(userId: string): void;
+    sendTyping(userId: string, active: boolean): void;
+    sendClearInput(userId: string): void;
+    sendSetInputType(userId: string, inputType: "text" | "password"): void;
+    private wsSendTo;
+    private wsSend;
+}
+
+/**
+ * DSers API configuration.
+ * Uses email + password auth (matching actual DSers login flow).
+ */
+interface DSersClientConfig {
+    baseUrl: string;
+    email: string;
+    password: string;
+    sessionFile: string;
+    sessionId?: string;
+    sessionState?: string;
+}
+declare function createDSersConfig(email: string, password: string, baseUrl?: string): DSersClientConfig;
+
+/**
+ * Enhanced DSers HTTP client with:
+ *  - 429 Retry-After handling
+ *  - 5xx exponential backoff (max 2 retries)
+ *  - Structured error classification
+ *  - traceId injection
+ *  - Session auto-refresh on 400 auth errors
+ */
+
+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.
+ * Created per-user with their own DSers client and LLM config.
+ * System prompt targets zero-technical-ability dropshipping users.
+ */
+
+interface LLMConfig {
+    provider: string;
+    apiKey: string;
+    model: string;
+}
+declare function getDefaultModel(provider: string): string;
+declare class DropClawCoreAgent implements AgentBase {
+    readonly id = "dropclaw-core";
+    readonly name = "DropClaw Core Agent";
+    private dsers;
+    private memory;
+    private llm;
+    private customTools;
+    constructor(dsers: DSersClient, memory: MemoryProvider, llm: LLMConfig);
+    registerTool(t: AgentTool): void;
+    removeTool(name: string): void;
+    getTools(): AgentTool[];
+    process(message: string, context: AgentContext): Promise<AgentResponse>;
+    /**
+     * Streaming version of process() — yields text chunks for real-time display.
+     * Returns textStream (async iterable) + response promise (resolves after completion).
+     */
+    processStream(message: string, context: AgentContext): {
+        textStream: AsyncIterable<string>;
+        response: Promise<AgentResponse>;
+    };
+    private buildAITools;
+}
+
+/**
+ * Telegram channel adapter using grammY.
+ * Normalizes messages, supports inline keyboards, auto-reconnects,
+ * and can delete sensitive messages (passwords, API keys).
+ */
+
+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>;
+    deleteMessage(chatId: string | number, messageId: number): 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 LLMConfig, type Memory, type MemoryFilter, type MemoryMeta, type MemoryProvider, type NormalizedMessage, type OutboundMessage, type PushResult, type RetryOptions, type Rule, type RuleEngine, type RuleEvaluationResult, type SessionState, type StructuredError, TelegramAdapter, type UserSessionData, WebChatServer, acquireUserLock, auditFilePath, checkCompatibility, checkInboundLimit, createCircuitBreaker, createDSersConfig, createLogger, debounceUser, degradationMessage, deleteSession, getAllBreakerStatus, getDefaultModel, getDegradationStatus, getOutboundLimiter, getTraceContext, getTraceId, idempotencyKey, isDegraded, isOnboarding, loadConfig, loadSession, markDegraded, markRecovered, parseRetryAfter, runWithTrace, saveConfig, saveSession, sleep, withRetry, writeAuditLog };