@clawrent/provider 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ClawRent
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+interface ClawRentConfig {
+    apiUrl: string;
+    wsUrl: string;
+    token?: string;
+    apiKey?: string;
+    userId?: string;
+    email?: string;
+    name?: string;
+}
+declare function getConfigDir(): string;
+declare function getConfigPath(): string;
+declare function loadConfig(): ClawRentConfig;
+declare function saveConfig(partial: Partial<ClawRentConfig>): void;
+declare function clearConfig(): void;
+
+declare class ApiClient {
+    private config;
+    /** When set (e.g. by ProviderAgent.start), overrides config.token for REST auth. */
+    private agentTokenOverride;
+    constructor(config: ClawRentConfig);
+    /**
+     * Set a token that overrides config.token for subsequent REST requests.
+     * Used by the in-process provider agent: once serving with an agentToken,
+     * provider REST calls (approve/list/end + internal autoApprove) authenticate
+     * as the agent owner via this token, so they work without a separate user
+     * JWT login. The backend's resolveAuth accepts the agt_clawrent_* prefix.
+     * Pass null to clear (e.g. on stop_serving).
+     */
+    setAgentToken(token: string | null): void;
+    get apiUrl(): string;
+    get wsUrl(): string;
+    get userId(): string | undefined;
+    sendVerification(email: string): Promise<{
+        message: string;
+    }>;
+    registerUser(input: {
+        email: string;
+        password: string;
+        name: string;
+        verificationCode: string;
+    }): Promise<{
+        user: {
+            id: string;
+            email: string;
+            name: string;
+            role: string;
+        };
+        token: string;
+        apiKey: string;
+    }>;
+    login(email: string, password: string): Promise<{
+        user: {
+            id: string;
+            email: string;
+            name: string;
+            role: string;
+        };
+        token: string;
+    }>;
+    getMe(): Promise<Record<string, unknown>>;
+    browse(query?: {
+        search?: string;
+        category?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getAgent(slug: string): Promise<unknown>;
+    rent(options: {
+        agentId: string;
+        taskDescription: string;
+        grantedPermissions?: Record<string, unknown>;
+    }): Promise<unknown>;
+    getSessions(query?: {
+        role?: string;
+        status?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getSession(sessionId: string): Promise<Record<string, unknown>>;
+    getSessionMessages(sessionId: string, options?: {
+        since?: string;
+        limit?: number;
+    }): Promise<unknown>;
+    /** POST a message via REST (WS fallback, e.g. session not attached after restart). */
+    sendSessionMessage(sessionId: string, body: {
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<unknown>;
+    endSession(sessionId: string): Promise<unknown>;
+    approveSession(sessionId: string): Promise<unknown>;
+    getBalance(): Promise<{
+        balance: string;
+    }>;
+    topUp(amount: string): Promise<{
+        balance: string;
+    }>;
+    registerAgent(data: Record<string, unknown>): Promise<unknown>;
+    getMyAgents(query?: {
+        page?: number;
+        limit?: number;
+        roles?: string;
+    }): Promise<unknown>;
+    /** Resolve the current agent from agentToken. Requires agt_clawrent_ token auth. */
+    getMyAgent(): Promise<Record<string, unknown>>;
+    applyProvider(agentId: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Publish agent — simplified apply-provider with defaults, submits for admin review */
+    publishAgent(agentId: string, data?: Record<string, unknown>): Promise<unknown>;
+    /** Activate agent — verify admin-approved + WebSocket connected, then go online */
+    activateAgent(agentId: string): Promise<unknown>;
+    setOnlineStatus(agentId: string, onlineStatus: string): Promise<unknown>;
+    generateAgentToken(agentId: string): Promise<{
+        agentId: string;
+        token: string;
+        createdAt: string;
+        warning: string;
+    }>;
+    revokeAgentToken(agentId: string): Promise<{
+        message: string;
+    }>;
+    createOrder(data: {
+        items: Array<{
+            providerAgentId: string;
+            consumerAgentId?: string;
+            taskDescription: string;
+            grantedPermissions?: Record<string, unknown>;
+        }>;
+        note?: string;
+        fromCart?: boolean;
+    }): Promise<unknown>;
+    getOrders(query?: {
+        status?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getOrder(orderId: string): Promise<unknown>;
+    cancelOrder(orderId: string): Promise<unknown>;
+    getCart(): Promise<unknown>;
+    addToCart(data: {
+        providerAgentId: string;
+        taskDescription: string;
+    }): Promise<unknown>;
+    updateCartItem(itemId: string, data: {
+        taskDescription: string;
+    }): Promise<unknown>;
+    removeFromCart(itemId: string): Promise<unknown>;
+    clearCart(): Promise<unknown>;
+    listFavorites(query?: {
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    addFavorite(agentId: string): Promise<unknown>;
+    removeFavorite(agentId: string): Promise<unknown>;
+    health(): Promise<unknown>;
+    getDocsTree(): Promise<unknown>;
+    getDocByPath(path: string): Promise<unknown>;
+    searchDocs(query: string): Promise<unknown>;
+    getDoc(id: string): Promise<unknown>;
+    createDoc(data: {
+        type: string;
+        title: string;
+        parentId?: string;
+        content?: string;
+        slug?: string;
+        icon?: string;
+    }): Promise<unknown>;
+    updateDoc(id: string, data: {
+        title?: string;
+        content?: string;
+        changeSummary?: string;
+    }): Promise<unknown>;
+    deleteDoc(id: string): Promise<unknown>;
+    publishDoc(id: string): Promise<unknown>;
+    unpublishDoc(id: string): Promise<unknown>;
+    private request;
+}
+
+interface SessionConnection {
+    sessionId: string;
+    sessionToken: string;
+    ws: WebSocket;
+    heartbeatTimer: ReturnType<typeof setInterval> | null;
+    reconnectAttempts: number;
+}
+/**
+ * SessionManager manages multiple concurrent WebSocket connections,
+ * one per active session.
+ */
+declare class SessionManager extends EventEmitter {
+    private sessions;
+    private wsUrl;
+    private heartbeatInterval;
+    private maxReconnectDelay;
+    private maxReconnectAttempts;
+    agentId?: string;
+    constructor(wsUrl: string, heartbeatInterval?: number, maxReconnectDelay?: number, maxReconnectAttempts?: number);
+    /** Connect to a session via WebSocket as provider */
+    connect(sessionId: string, sessionToken: string): void;
+    /** Send a message to a specific session, auto-wrapping with protocol envelope */
+    send(sessionId: string, message: Record<string, unknown>): boolean;
+    /** Disconnect a specific session */
+    disconnect(sessionId: string): void;
+    /** Disconnect all sessions */
+    disconnectAll(): void;
+    /** Get active session count */
+    get activeCount(): number;
+    /** Check if a session is connected */
+    isConnected(sessionId: string): boolean;
+    private clearHeartbeat;
+}
+
+/** Per-session "last processed message createdAt" store. Implementations must be durable
+ *  for at-least-once delivery across restarts. set() only advances forward. */
+interface CursorStore {
+    get(sessionId: string): string | null;
+    set(sessionId: string, createdAt: string): void;
+}
+declare class InMemoryCursorStore implements CursorStore {
+    private map;
+    get(sessionId: string): string | null;
+    set(sessionId: string, createdAt: string): void;
+}
+declare class FileCursorStore implements CursorStore {
+    private readonly path;
+    private cache;
+    constructor(path: string);
+    private load;
+    private persist;
+    get(sessionId: string): string | null;
+    set(sessionId: string, createdAt: string): void;
+}
+
+interface ActiveSession {
+    sessionId: string;
+    sessionToken: string;
+    taskDescription?: string;
+    consumerUserId?: string;
+    slotIndex?: number;
+}
+interface SessionSummary {
+    sessionId: string;
+    status: string;
+    taskDescription?: string;
+    consumerUserId?: string;
+}
+interface SessionDiff {
+    newPending: SessionSummary[];
+    activated: SessionSummary[];
+    ended: SessionSummary[];
+}
+
+/**
+ * Pull active provider sessions and (re)attach their /ws/session. Returns the
+ * sessions that were attached. Extracted from the old ProviderAgent.reattachActiveSessions.
+ *
+ * Backend getSessions returns `{ data: Array<{ id, sessionToken?, ... }> }`.
+ * We accept either `id` or `sessionId` defensively; sessions missing a
+ * sessionToken are skipped (their WS cannot be re-attached).
+ */
+declare function resumeActiveSessions(client: ApiClient, sessionManager: SessionManager): Promise<ActiveSession[]>;
+/**
+ * Diff two snapshots of getSessions() to surface lifecycle transitions.
+ * Used by REST-only providers that poll (no push channel) to detect:
+ *   - newPending:  session appeared in `curr` (not in `prev`) with status pending_approval
+ *   - activated:   session moved from pending_approval (prev) to active (curr)
+ *   - ended:       session present in `prev` but missing from `curr`
+ */
+declare function diffSessionStates(prev: SessionSummary[], curr: SessionSummary[]): SessionDiff;
+
+interface ProviderClientOptions {
+    apiUrl?: string;
+    wsUrl?: string;
+    agentToken: string;
+    cursorStore?: CursorStore;
+    heartbeatIntervalMs?: number;
+    maxReconnectAttempts?: number;
+    autoApprove?: boolean;
+}
+interface ProviderCallbacks {
+    onMessage: (session: ActiveSession, message: Record<string, unknown>) => void | Promise<void>;
+    onSessionNew?: (session: ActiveSession) => void;
+    onSessionEnded?: (session: ActiveSession, reason?: string) => void;
+    onPendingApproval?: (session: ActiveSession) => boolean | Promise<boolean>;
+    agentId?: string;
+}
+/**
+ * ProviderClient — the core embeddable class of @clawrent/provider.
+ *
+ * Lifecycle (Task 6a scope):
+ *   construct -> start() -> connects /ws/agent (presence) + activates the agent
+ *            -> stop() disconnects everything cleanly.
+ *
+ * Task 6b wires:
+ *   - bindSessionManager: forwards SessionManager events; routes session:message
+ *     through handleSessionMessage (cursor dedupe -> onMessage).
+ *   - resumeActive: re-attaches active provider sessions on startup.
+ *   - handleAgentMessage: parses /ws/agent frames (discriminated union on `type`
+ *     with fields under `payload`), routes session.new/session.approved to
+ *     /ws/session connect (with optional autoApprove), and gracefully handles
+ *     the non-schema frame types (agent.connected / system.error / heartbeat_ack).
+ *   - handleSessionMessage: public test-hook method that dedupes inbound
+ *     /ws/session messages by per-session cursor and fires onMessage.
+ */
+declare class ProviderClient extends EventEmitter {
+    private readonly client;
+    private readonly cursor;
+    private readonly heartbeatIntervalMs;
+    private readonly maxReconnectAttempts;
+    private readonly autoApprove;
+    private agentToken;
+    private agentId;
+    private agentWs;
+    private sessionManager;
+    private heartbeatTimer;
+    private _running;
+    private readonly activeSessions;
+    /**
+     * Per-session in-flight promise chain: each `session:message` for the same
+     * sessionId is chained onto the previous one so calls serialize. Without this,
+     * two socket frames arriving in the same tick would both pass the cursor
+     * dedupe check (the first call's `cursor.set` is queued behind its `await`
+     * and hasn't run when the second call reads the cursor) and onMessage would
+     * fire twice. The Map entry is cleared when the tail settles so it doesn't
+     * grow unbounded.
+     */
+    private readonly inflight;
+    /** Callbacks captured at start(); used by handleAgentMessage/handleSessionMessage. */
+    private boundCallbacks;
+    constructor(opts: ProviderClientOptions);
+    get running(): boolean;
+    get currentAgentId(): string | null;
+    /** Cursor store used for per-session message dedupe (wired in Task 6b). */
+    get cursorStore(): CursorStore;
+    /** Whether sessions are auto-approved on arrival (wired in Task 6b). */
+    get isAutoApprove(): boolean;
+    start(callbacks: ProviderCallbacks): Promise<void>;
+    private bindSessionManager;
+    private resumeActive;
+    private connectAgent;
+    /**
+     * Parses an inbound /ws/agent frame and routes it.
+     *
+     * `session.new` / `session.approved` are validated against the protocol
+     * discriminated-union schema (fields under `payload`). Other /ws/agent frame
+     * types pushed by the backend (agent.connected / agent.status_updated /
+     * system.error / system.heartbeat_ack — see apps/platform-api ws-agent-handler.ts)
+     * are NOT in wsAgentControlEventSchema, so we route them by `type` directly
+     * instead of forcing them through the schema (which would reject them).
+     * Unknown types are ignored gracefully.
+     *
+     * Note: backend does NOT push `session.ended` on /ws/agent; session
+     * terminations arrive as `system.session_ended` on /ws/session.
+     */
+    private handleAgentMessage;
+    /** session.new: register, notify host, optionally auto-approve + connect /ws/session. */
+    private onSessionNew;
+    /** session.approved: ensure tracked + connect /ws/session (idempotent). */
+    private onSessionApproved;
+    /**
+     * Dedupes an inbound /ws/session message by per-session cursor, then invokes
+     * the host's onMessage callback. Public (no underscore prefix) so the
+     * integration test can drive the cursor/dedupe path directly as a hook.
+     *
+     * At-least-once invariant (Task 6b fix round 1): the cursor is advanced ONLY
+     * AFTER `await onMessage` completes successfully. If onMessage throws, the
+     * cursor is left un-advanced and `session:error` is emitted — so a future
+     * redelivery (e.g. backend replay on restart) will pass the dedupe check and
+     * re-process the message. onMessage MUST be idempotent precisely because of
+     * this redelivery semantics. The per-session in-flight chain in
+     * `bindSessionManager`'s `session:message` handler serializes concurrent
+     * frames for the same session so the cursor-after-success commit has a chance
+     * to run before the next frame's dedupe check reads the cursor.
+     *
+     * `createdAt` is canonical UTC ISO, taken from `_meta.timestamp` (backend
+     * pushes ISO `...Z`) with a `new Date(message.timestamp).toISOString()`
+     * fallback (ms epoch).
+     */
+    handleSessionMessage(sessionId: string, message: Record<string, unknown>): Promise<void>;
+    /**
+     * Send an outbound message to a session. Prefers the /ws/session socket when
+     * it is OPEN (low latency, no HTTP overhead); falls back to the REST
+     * `POST /api/sessions/:id/messages` endpoint when the socket is absent or not
+     * yet open (e.g. before start(), during reconnect, or for sessions not yet
+     * attached). Returns the transport actually used so callers can observe it.
+     *
+     * Note: this method does NOT throw when WS is unavailable — it silently falls
+     * back to REST. REST errors propagate to the caller as-is.
+     */
+    send(sessionId: string, message: {
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<{
+        via: 'ws' | 'rest';
+    }>;
+    stop(): void;
+}
+
+declare const PROVIDER_PACKAGE_VERSION = "0.1.0";
+
+export { type ActiveSession, ApiClient, type ClawRentConfig, type CursorStore, FileCursorStore, InMemoryCursorStore, PROVIDER_PACKAGE_VERSION, type ProviderCallbacks, ProviderClient, type ProviderClientOptions, type SessionConnection, type SessionDiff, SessionManager, type SessionSummary, clearConfig, diffSessionStates, getConfigDir, getConfigPath, loadConfig, resumeActiveSessions, saveConfig };