@pear-protocol/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pear Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @pear-protocol/agent-sdk
+
+TypeScript client for the Pear **agent chat** API — the conversational assistant
+(pair-trade ideas, market data, and confirm-before-write trade execution).
+
+- **`@pear-protocol/agent-sdk`** — framework-agnostic core (`AgentChatClient`).
+- **`@pear-protocol/agent-sdk/react`** — optional React hooks (`useAgentChat`, `useAgentSessions`).
+
+Published to **public npm** (same registry as the org's other `@pear-protocol`
+packages — no `.npmrc` or token needed). The wire types are a single source of
+truth shared with the backend, so they can't silently drift.
+
+## Install
+
+```bash
+pnpm add @pear-protocol/agent-sdk zod
+# only if you use the React hooks:
+pnpm add react
+```
+
+`zod@^4.1.0` is a **required peer dependency** (the SDK ships zod schemas at
+runtime). `react@>=18` is required **only** for the `/react` hooks.
+
+## Quickstart (core)
+
+```ts
+import { AgentChatClient } from "@pear-protocol/agent-sdk";
+
+const client = new AgentChatClient({
+  // Inject your env — the SDK NEVER reads it.
+  baseUrl: import.meta.env.VITE_AGENT_PEAR_API_URL,      // Vite
+  // baseUrl: process.env.NEXT_PUBLIC_AGENT_PEAR_API_URL, // Next.js
+  getToken: () => auth.accessToken,   // returns the freshest JWT; called per request
+  tokenVersion: "v2",                 // "v2" wallet JWT (default) | "v3"
+});
+
+const { id } = await client.createSession();
+
+for await (const ev of client.streamChat({ sessionId: id, message: "Long ETH short BTC?" })) {
+  if (ev.type === "token") process.stdout.write(ev.delta);
+  if (ev.type === "done" && ev.result.pendingAction) {
+    // A money-moving trade was STAGED, not executed — render Confirm/Cancel.
+    await client.confirmTicket(ev.result.pendingAction.ticketId);
+    // ...or: await client.cancelTicket(ev.result.pendingAction.ticketId);
+  }
+}
+```
+
+`streamChat` yields `token` | `thinking` | `status` | `sources` events, then a
+synthetic `{ type: "done", result }`. **Token text is delta-only** — accumulate
+`ev.delta`. The SSE wire has no terminal `done` frame; the SDK assembles one. If
+the backend emits a mid-stream error, `streamChat` **throws** an `AgentChatError`.
+Aborting the stream (the hook's `stop()`, or your own `AbortSignal`) also stops
+generation **server-side** — the backend detects the disconnect and winds the
+worker job down at the next safe boundary (never mid-trade-write).
+
+There's also a sync `client.sendMessage({ sessionId, message })` returning a
+`ChatResult`, and sessions/history methods (`listSessions`,
+`listSessionSummaries`, `createSession`, `getSession`, `deleteSession`,
+`getMessages`).
+
+## React
+
+```tsx
+import { useAgentChat } from "@pear-protocol/agent-sdk/react";
+
+function Chat({ client }) {
+  const {
+    messages, sendMessage, isStreaming, status, stop,
+    pendingAction, confirmTicket, cancelTicket, mode, setMode,
+  } = useAgentChat({ client });
+
+  // render `messages`; if `pendingAction`, show Confirm/Cancel buttons wired to
+  // confirmTicket(pendingAction.ticketId) / cancelTicket(pendingAction.ticketId)
+}
+```
+
+`useAgentChat` uses plain React state (no forced data lib). `useAgentSessions(client)`
+is a minimal session-list hook; apps using TanStack Query can skip it and call the
+client directly.
+
+## Auth
+
+`getToken()` returns whatever bearer token the agent API accepts (today a v2
+HL-issued JWT). The SDK sends `Authorization: Bearer <token>` +
+`X-Auth-Token-Version`. **It does NOT own sign-in** — wire it to your wallet/auth
+flow. v3 callers are identity-only (no wallet → trade tickets disabled).
+
+## Errors
+
+`confirmTicket` / `cancelTicket` throw typed errors: `TicketExpiredError` (410),
+`ForbiddenError` (403, not your ticket), `ConflictError` (409, already handled),
+`AuthError` (401). All extend `AgentChatError` (carries `.status`).
+
+## Trade tickets (confirm-before-write)
+
+A turn that would move money returns a `pendingAction`
+(`{ ticketId, action, consequence, options: ["confirm","cancel"] }`) instead of
+executing. Render it, then call `confirmTicket(ticketId)` (executes) or
+`cancelTicket(ticketId)` (discards). `setTradeConfirmations(false)` opts a user out
+of the confirm step entirely.

package/dist/client-EVhAAxSx.d.cts

@@ -0,0 +1,348 @@
+import { z } from 'zod';
+
+interface AgentChatClientConfig {
+    baseUrl: string;
+    getToken: () => string | Promise<string>;
+    tokenVersion?: "v2" | "v3";
+    fetch?: typeof fetch;
+}
+
+declare const TokenEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"token">;
+    text: z.ZodString;
+}, z.core.$strip>;
+declare const ThinkingEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"thinking">;
+    text: z.ZodString;
+}, z.core.$strip>;
+declare const StatusEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+    text: z.ZodString;
+    phase: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>>;
+    node: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SourcesEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sources">;
+    researchAnnotations: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        url: string;
+    }, string>>, z.ZodObject<{
+        url: z.ZodString;
+        start_index: z.ZodOptional<z.ZodNumber>;
+        end_index: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>>;
+    twitterSources: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        author: z.ZodString;
+        tweetUrl: z.ZodString;
+        publishedAt: z.ZodString;
+    }, z.core.$strip>>>>;
+    tradeLinks: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        link: z.ZodString;
+        platform: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>>;
+    images: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodString>>>;
+    suggestedAction: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>>;
+    pendingAction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        ticketId: z.ZodString;
+        action: z.ZodString;
+        consequence: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare const ErrorEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const AgentWireEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"token">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"thinking">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+    text: z.ZodString;
+    phase: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>>;
+    node: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"sources">;
+    researchAnnotations: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        url: string;
+    }, string>>, z.ZodObject<{
+        url: z.ZodString;
+        start_index: z.ZodOptional<z.ZodNumber>;
+        end_index: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>>;
+    twitterSources: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        author: z.ZodString;
+        tweetUrl: z.ZodString;
+        publishedAt: z.ZodString;
+    }, z.core.$strip>>>>;
+    tradeLinks: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        link: z.ZodString;
+        platform: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>>;
+    images: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodString>>>;
+    suggestedAction: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>>;
+    pendingAction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        ticketId: z.ZodString;
+        action: z.ZodString;
+        consequence: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+type AgentWireEvent = z.infer<typeof AgentWireEventSchema>;
+declare const ChatResultSchema: z.ZodObject<{
+    finalText: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    researchAnnotations: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        url: string;
+    }, string>>, z.ZodObject<{
+        url: z.ZodString;
+        start_index: z.ZodOptional<z.ZodNumber>;
+        end_index: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>>;
+    twitterSources: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        author: z.ZodString;
+        tweetUrl: z.ZodString;
+        publishedAt: z.ZodString;
+    }, z.core.$strip>>>>;
+    tradeLinks: z.ZodOptional<z.ZodCatch<z.ZodArray<z.ZodObject<{
+        link: z.ZodString;
+        platform: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>>;
+    images: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    suggestedAction: z.ZodCatch<z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>>;
+    pendingAction: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        ticketId: z.ZodString;
+        action: z.ZodString;
+        consequence: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ChatResult = z.infer<typeof ChatResultSchema>;
+type AgentEvent = AgentWireEvent | {
+    type: "done";
+    result: ChatResult;
+};
+
+declare const SessionListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    appType: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+type SessionListItem = z.infer<typeof SessionListItemSchema>;
+declare const SessionSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    appType: z.ZodString;
+    createdAt: z.ZodString;
+    firstUserMessage: z.ZodOptional<z.ZodString>;
+    lastUserMessage: z.ZodOptional<z.ZodString>;
+    lastUserMessageAt: z.ZodOptional<z.ZodString>;
+    lastAssistantMessageAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SessionSummary = z.infer<typeof SessionSummarySchema>;
+declare const SessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    userId: z.ZodString;
+    appType: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+type Session = z.infer<typeof SessionSchema>;
+declare const AgentChatMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodString;
+    content: z.ZodString;
+    createdAt: z.ZodString;
+    researchAnnotations: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        url: string;
+    }, string>>, z.ZodObject<{
+        url: z.ZodString;
+        start_index: z.ZodOptional<z.ZodNumber>;
+        end_index: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>>;
+    twitterSources: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        author: z.ZodString;
+        tweetUrl: z.ZodString;
+        publishedAt: z.ZodString;
+    }, z.core.$strip>>>>;
+    tradeLinks: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        link: z.ZodString;
+        platform: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>>;
+    images: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    suggestedAction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$loose>;
+type AgentChatMessage = z.infer<typeof AgentChatMessageSchema>;
+
+declare const TradeLinkSchema: z.ZodObject<{
+    link: z.ZodString;
+    platform: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+type TradeLink = z.infer<typeof TradeLinkSchema>;
+declare const TwitterSourceSchema: z.ZodObject<{
+    author: z.ZodString;
+    tweetUrl: z.ZodString;
+    publishedAt: z.ZodString;
+}, z.core.$strip>;
+type TwitterSource = z.infer<typeof TwitterSourceSchema>;
+declare const CitationSourceSchema: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+    url: string;
+}, string>>, z.ZodObject<{
+    url: z.ZodString;
+    start_index: z.ZodOptional<z.ZodNumber>;
+    end_index: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+type CitationSource = z.infer<typeof CitationSourceSchema>;
+declare const SuggestedActionSchema: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type SuggestedAction = z.infer<typeof SuggestedActionSchema>;
+declare const ChatModeSchema: z.ZodEnum<{
+    standard: "standard";
+    advanced: "advanced";
+}>;
+type ChatMode = z.infer<typeof ChatModeSchema>;
+
+declare const TicketActionSchema: z.ZodEnum<{
+    open_position: "open_position";
+    close_position: "close_position";
+    close_all_positions: "close_all_positions";
+    adjust_position: "adjust_position";
+    adjust_advance_position: "adjust_advance_position";
+    reverse_position: "reverse_position";
+    rebalance_position: "rebalance_position";
+    set_risk_parameters: "set_risk_parameters";
+}>;
+type TicketAction = z.infer<typeof TicketActionSchema>;
+declare const TicketStatusSchema: z.ZodEnum<{
+    PENDING: "PENDING";
+    EXECUTING: "EXECUTING";
+    EXECUTED: "EXECUTED";
+    CANCELLED: "CANCELLED";
+    FAILED: "FAILED";
+}>;
+type TicketStatus = z.infer<typeof TicketStatusSchema>;
+declare const PendingActionSchema: z.ZodObject<{
+    ticketId: z.ZodString;
+    action: z.ZodString;
+    consequence: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type PendingAction = z.infer<typeof PendingActionSchema>;
+declare const ConfirmResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    status: z.ZodEnum<{
+        EXECUTED: "EXECUTED";
+        FAILED: "FAILED";
+    }>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    positionsSnapshot: z.ZodOptional<z.ZodUnknown>;
+    images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+type ConfirmResult = z.infer<typeof ConfirmResultSchema>;
+declare const CancelResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    status: z.ZodLiteral<"CANCELLED">;
+}, z.core.$strip>;
+type CancelResult = z.infer<typeof CancelResultSchema>;
+declare const SetConfirmationsResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+type SetConfirmationsResult = z.infer<typeof SetConfirmationsResultSchema>;
+declare const TradeSettingsSchema: z.ZodObject<{
+    executionEnabled: z.ZodBoolean;
+    confirmationsEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+type TradeSettings = z.infer<typeof TradeSettingsSchema>;
+declare const SetExecutionResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+type SetExecutionResult = z.infer<typeof SetExecutionResultSchema>;
+
+type StreamEvent = (Extract<AgentWireEvent, {
+    type: "token";
+}> & {
+    delta: string;
+}) | (Extract<AgentWireEvent, {
+    type: "thinking";
+}> & {
+    delta: string;
+}) | Exclude<AgentWireEvent, {
+    type: "token" | "thinking";
+}>;
+
+declare class AgentChatClient {
+    private readonly http;
+    constructor(config: AgentChatClientConfig);
+    listSessions(): Promise<SessionListItem[]>;
+    listSessionSummaries(): Promise<SessionSummary[]>;
+    createSession(): Promise<{
+        id: string;
+    }>;
+    getSession(sessionId: string): Promise<Session>;
+    deleteSession(sessionId: string): Promise<void>;
+    getMessages(sessionId: string, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<AgentChatMessage[]>;
+    streamChat(args: {
+        sessionId: string;
+        message: string;
+        mode?: ChatMode;
+        signal?: AbortSignal;
+        cta?: {
+            previousText: string;
+            question: string;
+            selectedOption: string;
+        };
+    }): AsyncGenerator<StreamEvent | {
+        type: "done";
+        result: ChatResult;
+    }>;
+    sendMessage(args: {
+        sessionId: string;
+        message: string;
+        mode?: ChatMode;
+    }): Promise<ChatResult>;
+    confirmTicket(ticketId: string): Promise<ConfirmResult>;
+    cancelTicket(ticketId: string): Promise<CancelResult>;
+    setTradeConfirmations(enabled: boolean): Promise<SetConfirmationsResult>;
+    getTradeSettings(): Promise<TradeSettings>;
+    setTradeExecution(enabled: boolean): Promise<SetExecutionResult>;
+}
+
+export { AgentChatClient as A, StatusEventSchema as B, type CancelResult as C, type StreamEvent as D, ErrorEventSchema as E, type SuggestedAction as F, SuggestedActionSchema as G, type TicketAction as H, TicketActionSchema as I, type TicketStatus as J, TicketStatusSchema as K, TokenEventSchema as L, type TradeLink as M, TradeLinkSchema as N, type TradeSettings as O, type PendingAction as P, TradeSettingsSchema as Q, type TwitterSource as R, type Session as S, ThinkingEventSchema as T, TwitterSourceSchema as U, type AgentChatClientConfig as a, type AgentChatMessage as b, AgentChatMessageSchema as c, type AgentEvent as d, type AgentWireEvent as e, AgentWireEventSchema as f, CancelResultSchema as g, type ChatMode as h, ChatModeSchema as i, type ChatResult as j, ChatResultSchema as k, type CitationSource as l, CitationSourceSchema as m, type ConfirmResult as n, ConfirmResultSchema as o, PendingActionSchema as p, type SessionListItem as q, SessionListItemSchema as r, SessionSchema as s, type SessionSummary as t, SessionSummarySchema as u, type SetConfirmationsResult as v, SetConfirmationsResultSchema as w, type SetExecutionResult as x, SetExecutionResultSchema as y, SourcesEventSchema as z };