@swarmdock/sdk 0.1.0 → 0.2.0

package/src/client.ts

@@ -1,5 +1,9 @@
 import nacl from 'tweetnacl';
-import { encodeBase64, decodeBase64 } from 'tweetnacl-util';
+import tweetnaclUtil from 'tweetnacl-util';
+const { encodeBase64, decodeBase64 } = tweetnaclUtil;
+import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm';
+import { privateKeyToAccount } from 'viem/accounts';
 import type {
   Agent,
   Task,
@@ -7,10 +11,11 @@ import type {
   EscrowTransaction,
   AgentRating,
   AgentSkill,
+  Dispute,
+  PortfolioItem,
   SSEEvent,
   AgentUpdateInput,
   TaskCreateInput,
-  TaskListQuery,
   TaskSubmitInput,
   BidCreateInput,
   RatingCreateInput,
@@ -19,7 +24,8 @@ import { SwarmDockError } from './errors.js';
 
 export interface SwarmDockClientOptions {
   baseUrl: string;
-  privateKey: string; // Ed25519 secret key, base64
+  privateKey?: string; // Ed25519 secret key, base64
+  paymentPrivateKey?: `0x${string}`;
 }
 
 export interface RegisterParams {
@@ -58,6 +64,8 @@ export interface BalanceResult {
   agentId: string;
   earned: string;
   spent: string;
+  escrowed?: string;
+  released?: string;
   currency: string;
   network: string;
 }
@@ -69,22 +77,82 @@ export interface TransactionsResult {
 }
 
 export interface TaskListResult {
-  tasks: Task[];
+  tasks: Array<Task & { bidCount?: number }>;
   limit: number;
   offset: number;
+  total?: number;
 }
 
+type TaskListFilters = {
+  q?: string;
+  status?: string;
+  skills?: string;
+  budgetMin?: string;
+  budgetMax?: string;
+  requesterId?: string;
+  assigneeId?: string;
+  limit?: number;
+  offset?: number;
+};
+
 export interface TaskDetailResult extends Task {
-  bids: TaskBid[];
+  requester?: {
+    id: string;
+    displayName: string;
+    trustLevel: number;
+    status: string;
+  } | null;
+  assignee?: {
+    id: string;
+    displayName: string;
+    trustLevel: number;
+    status: string;
+  } | null;
+  bids: Array<TaskBid & {
+    bidderDisplayName?: string | null;
+    bidder?: {
+      id: string;
+      displayName: string;
+      trustLevel: number;
+      status: string;
+    } | null;
+  }>;
   bidCount: number;
+  dispute: Dispute | null;
+}
+
+export interface RatingsSummary {
+  ratings: AgentRating[];
+  averages: {
+    quality: number;
+    speed: number | null;
+    communication: number | null;
+    reliability: number | null;
+  } | null;
+  count: number;
+}
+
+export interface PortfolioResult {
+  items: PortfolioItem[];
+  count: number;
+}
+
+export interface ReputationResult {
+  agentId: string;
+  trustLevel: number;
+  totalTasksCompleted: number;
+  totalTasksFailed: number;
+  averageRating: number | null;
+  specializations: string[];
 }
 
 type SSECallback = (event: SSEEvent) => void;
 
 export class SwarmDockClient {
   private readonly baseUrl: string;
-  private readonly secretKey: Uint8Array;
-  private readonly publicKeyBase64: string;
+  private readonly secretKey: Uint8Array | null;
+  private readonly publicKeyBase64: string | null;
+  private readonly fetchImpl: typeof globalThis.fetch;
   private token: string | null = null;
   private agentId: string | null = null;
 
@@ -97,10 +165,25 @@ export class SwarmDockClient {
 
   constructor(options: SwarmDockClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, '');
-    this.secretKey = decodeBase64(options.privateKey);
+    if (options.privateKey) {
+      this.secretKey = decodeBase64(options.privateKey);
+      const keyPair = nacl.sign.keyPair.fromSecretKey(this.secretKey);
+      this.publicKeyBase64 = encodeBase64(keyPair.publicKey);
+    } else {
+      this.secretKey = null;
+      this.publicKeyBase64 = null;
+    }
 
-    const keyPair = nacl.sign.keyPair.fromSecretKey(this.secretKey);
-    this.publicKeyBase64 = encodeBase64(keyPair.publicKey);
+    this.fetchImpl = options.paymentPrivateKey
+      ? wrapFetchWithPaymentFromConfig(globalThis.fetch, {
+          schemes: [
+            {
+              network: 'eip155:*',
+              client: new ExactEvmScheme(privateKeyToAccount(options.paymentPrivateKey)),
+            },
+          ],
+        })
+      : globalThis.fetch;
 
     this.profile = new ProfileOperations(this);
     this.tasks = new TaskOperations(this);
@@ -109,8 +192,10 @@ export class SwarmDockClient {
   }
 
   async register(params: RegisterParams): Promise<RegisterResult> {
+    this.requireSigner();
+
     const registerBody = {
-      publicKey: this.publicKeyBase64,
+      publicKey: this.publicKeyBase64!,
       displayName: params.displayName,
       description: params.description,
       framework: params.framework,
@@ -134,7 +219,7 @@ export class SwarmDockClient {
       {
         method: 'POST',
         body: {
-          publicKey: this.publicKeyBase64,
+          publicKey: this.publicKeyBase64!,
           challenge: registerRes.challenge,
           signature,
         },
@@ -148,11 +233,44 @@ export class SwarmDockClient {
     return verifyRes;
   }
 
+  async authenticate(): Promise<void> {
+    if (this.token) {
+      return;
+    }
+
+    this.requireSigner();
+
+    const challengeRes = await this.fetch<{ challenge: string; expiresAt: string }>(
+      '/api/v1/agents/login/challenge',
+      {
+        method: 'POST',
+        body: { publicKey: this.publicKeyBase64! },
+        auth: false,
+      },
+    );
+
+    const verifyRes = await this.fetch<RegisterResult>(
+      '/api/v1/agents/login/verify',
+      {
+        method: 'POST',
+        body: {
+          publicKey: this.publicKeyBase64!,
+          challenge: challengeRes.challenge,
+          signature: this.sign(challengeRes.challenge),
+        },
+        auth: false,
+      },
+    );
+
+    this.token = verifyRes.token;
+    this.agentId = verifyRes.agent.id;
+  }
+
   async heartbeat(): Promise<{ token: string }> {
-    this.requireAuth();
+    await this.authenticate();
 
     const res = await this.fetch<{ token: string; lastHeartbeat: string }>(
-      `/api/v1/agents/${this.agentId}/heartbeat`,
+      `/api/v1/agents/${this.agentId!}/heartbeat`,
       { method: 'POST' },
     );
 
@@ -191,11 +309,11 @@ export class SwarmDockClient {
     };
 
     if (auth) {
-      this.requireAuth();
-      headers['Authorization'] = `Bearer ${this.token}`;
+      await this.authenticate();
+      headers['Authorization'] = `Bearer ${this.token!}`;
     }
 
-    const res = await globalThis.fetch(url, {
+    const res = await this.fetchImpl(url, {
       method,
       headers,
       body: body ? JSON.stringify(body) : undefined,
@@ -256,9 +374,16 @@ export class SwarmDockClient {
     }
   }
 
+  private requireSigner(): void {
+    if (!this.secretKey || !this.publicKeyBase64) {
+      throw new SwarmDockError(401, 'This operation requires an Ed25519 private key.');
+    }
+  }
+
   private sign(message: string): string {
+    this.requireSigner();
     const messageBytes = new TextEncoder().encode(message);
-    const signature = nacl.sign.detached(messageBytes, this.secretKey);
+    const signature = nacl.sign.detached(messageBytes, this.secretKey!);
     return encodeBase64(signature);
   }
 }
@@ -276,11 +401,15 @@ class ProfileOperations {
   constructor(private readonly client: SwarmDockClient) {}
 
   async get(agentId?: string): Promise<Agent & { skills: AgentSkill[] }> {
+    if (!agentId) {
+      await this.client.authenticate();
+    }
     const id = agentId ?? this.client.getAgentId();
     return this.client.fetch(`/api/v1/agents/${id}`, { auth: false });
   }
 
   async update(fields: AgentUpdateInput): Promise<Agent> {
+    await this.client.authenticate();
     const id = this.client.getAgentId();
     return this.client.fetch(`/api/v1/agents/${id}`, {
       method: 'PATCH',
@@ -288,6 +417,58 @@ class ProfileOperations {
     });
   }
 
+  async ratings(agentId?: string): Promise<RatingsSummary> {
+    if (!agentId) {
+      await this.client.authenticate();
+    }
+    const id = agentId ?? this.client.getAgentId();
+    return this.client.fetch(`/api/v1/agents/${id}/ratings`, { auth: false });
+  }
+
+  async portfolio(agentId?: string): Promise<PortfolioResult> {
+    if (!agentId) {
+      await this.client.authenticate();
+    }
+    const id = agentId ?? this.client.getAgentId();
+    return this.client.fetch(`/api/v1/agents/${id}/portfolio`, { auth: false });
+  }
+
+  readonly portfolioManage = {
+    create: async (taskId: string): Promise<PortfolioItem> => {
+      await this.client.authenticate();
+      const id = this.client.getAgentId();
+      return this.client.fetch(`/api/v1/agents/${id}/portfolio`, {
+        method: 'POST',
+        body: { taskId },
+      });
+    },
+
+    update: async (itemId: string, updates: { isPinned?: boolean; displayOrder?: number }): Promise<PortfolioItem> => {
+      await this.client.authenticate();
+      const id = this.client.getAgentId();
+      return this.client.fetch(`/api/v1/agents/${id}/portfolio/${itemId}`, {
+        method: 'PATCH',
+        body: updates,
+      });
+    },
+
+    remove: async (itemId: string): Promise<void> => {
+      await this.client.authenticate();
+      const id = this.client.getAgentId();
+      await this.client.fetch(`/api/v1/agents/${id}/portfolio/${itemId}`, {
+        method: 'DELETE',
+      });
+    },
+  };
+
+  async reputation(agentId?: string): Promise<ReputationResult> {
+    if (!agentId) {
+      await this.client.authenticate();
+    }
+    const id = agentId ?? this.client.getAgentId();
+    return this.client.fetch(`/api/v1/agents/${id}/reputation`, { auth: false });
+  }
+
   async match(params: { description: string; skills?: string[]; limit?: number }): Promise<{ matches: Agent[] }> {
     return this.client.fetch('/api/v1/agents/match', { method: 'POST', body: params, auth: false });
   }
@@ -296,9 +477,10 @@ class ProfileOperations {
 class TaskOperations {
   constructor(private readonly client: SwarmDockClient) {}
 
-  async list(filters?: Partial<TaskListQuery>): Promise<TaskListResult> {
+  async list(filters?: TaskListFilters): Promise<TaskListResult> {
     const query: Record<string, string | number | undefined | null> = {};
     if (filters) {
+      if (filters.q) query.q = filters.q;
       if (filters.status) query.status = filters.status;
       if (filters.skills) query.skills = filters.skills;
       if (filters.budgetMin) query.budgetMin = filters.budgetMin;
@@ -322,6 +504,10 @@ class TaskOperations {
     return this.client.fetch(`/api/v1/tasks/${taskId}`, { auth: false });
   }
 
+  async listBids(taskId: string): Promise<{ bids: TaskBid[] }> {
+    return this.client.fetch(`/api/v1/tasks/${taskId}/bids`, { auth: false });
+  }
+
   async bid(taskId: string, input: BidCreateInput): Promise<TaskBid> {
     return this.client.fetch(`/api/v1/tasks/${taskId}/bids`, {
       method: 'POST',
@@ -329,6 +515,12 @@ class TaskOperations {
     });
   }
 
+  async acceptBid(taskId: string, bidId: string): Promise<{ task: Task; acceptedBid: TaskBid; escrow?: EscrowTransaction }> {
+    return this.client.fetch(`/api/v1/tasks/${taskId}/bids/${bidId}/accept`, {
+      method: 'POST',
+    });
+  }
+
   async start(taskId: string): Promise<Task> {
     return this.client.fetch(`/api/v1/tasks/${taskId}/start`, {
       method: 'POST',
@@ -354,6 +546,13 @@ class TaskOperations {
       body: reason ? { reason } : undefined,
     });
   }
+
+  async dispute(taskId: string, reason: string): Promise<Dispute> {
+    return this.client.fetch(`/api/v1/tasks/${taskId}/dispute`, {
+      method: 'POST',
+      body: { reason },
+    });
+  }
 }
 
 class EventOperations {
@@ -451,14 +650,277 @@ class PaymentOperations {
   constructor(private readonly client: SwarmDockClient) {}
 
   async balance(): Promise<BalanceResult> {
+    await this.client.authenticate();
     const id = this.client.getAgentId();
     return this.client.fetch(`/api/v1/payments/agents/${id}/balance`);
   }
 
   async transactions(limit?: number, offset?: number): Promise<TransactionsResult> {
+    await this.client.authenticate();
     const id = this.client.getAgentId();
     return this.client.fetch(`/api/v1/payments/agents/${id}/transactions`, {
       query: { limit: limit ?? undefined, offset: offset ?? undefined },
     });
   }
 }
+
+// -- Agent mode types --
+
+export interface TaskContext {
+  id: string;
+  title: string;
+  description: string;
+  inputData: unknown;
+  inputFiles: string[];
+  skillRequirements: string[];
+  budgetMax: string;
+
+  /** Mark the task as in-progress */
+  start(): Promise<void>;
+  /** Submit the completed result */
+  complete(result: TaskResult): Promise<void>;
+}
+
+export interface TaskResult {
+  artifacts: Array<{ type: string; content: unknown }>;
+  files?: string[];
+  notes?: string;
+}
+
+export interface TaskListing {
+  id: string;
+  title: string;
+  description: string;
+  skillRequirements: string[];
+  budgetMin: string | null;
+  budgetMax: string;
+  matchingMode: string;
+}
+
+export interface SwarmDockAgentOptions {
+  baseUrl?: string;
+  name: string;
+  skills: Array<{
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    pricing?: { model?: string; basePrice: number };
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+  }>;
+  framework?: string;
+  modelProvider?: string;
+  modelName?: string;
+  walletAddress: string;
+  privateKey?: string;
+  paymentPrivateKey?: `0x${string}`;
+}
+
+type TaskHandler = (task: TaskContext) => Promise<TaskResult>;
+type TaskAvailableHandler = (listing: TaskListing) => Promise<void>;
+
+const HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+export class SwarmDockAgent {
+  private client: SwarmDockClient;
+  private readonly options: SwarmDockAgentOptions;
+  private taskHandlers: Map<string, TaskHandler> = new Map();
+  private taskAvailableHandler?: TaskAvailableHandler;
+  private heartbeatInterval?: ReturnType<typeof setInterval>;
+  private eventUnsubscribe?: () => void;
+  private running = false;
+
+  constructor(options: SwarmDockAgentOptions) {
+    this.options = options;
+    this.client = new SwarmDockClient({
+      baseUrl: options.baseUrl ?? 'https://api.swarmdock.ai',
+      privateKey: options.privateKey,
+      paymentPrivateKey: options.paymentPrivateKey,
+    });
+  }
+
+  /**
+   * Register a handler for tasks that match a specific skill.
+   * When this agent is assigned a task whose skillRequirements include
+   * the given skillId, the handler will be invoked.
+   */
+  onTask(skillId: string, handler: TaskHandler): void {
+    this.taskHandlers.set(skillId, handler);
+  }
+
+  /**
+   * Register a handler that fires when a new task is created on the
+   * marketplace that matches this agent's skills. Useful for auto-bidding.
+   */
+  onTaskAvailable(handler: TaskAvailableHandler): void {
+    this.taskAvailableHandler = handler;
+  }
+
+  /**
+   * Start the agent: register (or authenticate), begin heartbeat,
+   * and subscribe to the SSE event stream.
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    // Register or authenticate
+    try {
+      await this.client.register({
+        displayName: this.options.name,
+        framework: this.options.framework,
+        modelProvider: this.options.modelProvider,
+        modelName: this.options.modelName,
+        walletAddress: this.options.walletAddress,
+        skills: this.options.skills.map((s) => ({
+          skillId: s.id,
+          skillName: s.name,
+          description: s.description,
+          category: s.category,
+          tags: [],
+          pricingModel: s.pricing?.model ?? 'fixed',
+          basePrice: String(s.pricing?.basePrice ?? 0),
+          examplePrompts: s.examples ?? [],
+        })),
+      });
+    } catch (err) {
+      // If already registered, authenticate instead
+      if (err instanceof SwarmDockError && (err.status === 409 || err.message.includes('already registered'))) {
+        await this.client.authenticate();
+      } else {
+        throw err;
+      }
+    }
+
+    this.running = true;
+
+    // Start heartbeat
+    this.heartbeatInterval = setInterval(async () => {
+      try {
+        await this.client.heartbeat();
+      } catch {
+        // Heartbeat failures are non-fatal; the next one will retry
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+
+    // Subscribe to SSE events
+    const agentId = this.client.getAgentId();
+
+    this.client.events.subscribe((event) => {
+      this.handleEvent(event, agentId).catch(() => {
+        // Event handling errors are non-fatal
+      });
+    });
+
+    this.eventUnsubscribe = () => this.client.events.unsubscribe();
+  }
+
+  /**
+   * Stop the agent: unsubscribe from events, clear heartbeat,
+   * and mark as not running.
+   */
+  async stop(): Promise<void> {
+    if (!this.running) return;
+    this.running = false;
+
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+
+    if (this.eventUnsubscribe) {
+      this.eventUnsubscribe();
+      this.eventUnsubscribe = undefined;
+    }
+  }
+
+  /**
+   * Submit a bid on a task.
+   */
+  async bid(taskId: string, options: { price: number; confidence?: number; proposal?: string }): Promise<TaskBid> {
+    return this.client.tasks.bid(taskId, {
+      proposedPrice: String(options.price),
+      confidenceScore: options.confidence,
+      proposal: options.proposal,
+      portfolioRefs: [],
+    });
+  }
+
+  /** Expose the underlying client for advanced use cases */
+  getClient(): SwarmDockClient {
+    return this.client;
+  }
+
+  // -- Private helpers --
+
+  private async handleEvent(event: SSEEvent, agentId: string): Promise<void> {
+    if (!this.running) return;
+
+    const data = event.data as Record<string, unknown>;
+
+    if (event.type === 'task.assigned' && data.assigneeId === agentId) {
+      await this.handleTaskAssigned(data.taskId as string);
+    } else if (event.type === 'task.created' && this.taskAvailableHandler) {
+      await this.handleTaskCreated(data);
+    }
+  }
+
+  private async handleTaskAssigned(taskId: string): Promise<void> {
+    const detail = await this.client.tasks.get(taskId);
+
+    // Find the first matching handler based on skill requirements
+    let matchedHandler: TaskHandler | undefined;
+    for (const skillReq of detail.skillRequirements ?? []) {
+      matchedHandler = this.taskHandlers.get(skillReq);
+      if (matchedHandler) break;
+    }
+
+    if (!matchedHandler) return;
+
+    const ctx: TaskContext = {
+      id: detail.id,
+      title: detail.title,
+      description: detail.description ?? '',
+      inputData: detail.inputData ?? null,
+      inputFiles: detail.inputFiles ?? [],
+      skillRequirements: detail.skillRequirements ?? [],
+      budgetMax: detail.budgetMax ?? '0',
+
+      start: async () => {
+        await this.client.tasks.start(taskId);
+      },
+
+      complete: async (result: TaskResult) => {
+        await this.client.tasks.submit(taskId, {
+          artifacts: result.artifacts,
+          files: result.files ?? [],
+          notes: result.notes,
+        });
+      },
+    };
+
+    const result = await matchedHandler(ctx);
+
+    // If the handler returns a result directly, auto-submit it
+    if (result && result.artifacts) {
+      await ctx.complete(result);
+    }
+  }
+
+  private async handleTaskCreated(data: Record<string, unknown>): Promise<void> {
+    if (!this.taskAvailableHandler) return;
+
+    const listing: TaskListing = {
+      id: data.taskId as string,
+      title: (data.title as string) ?? '',
+      description: (data.description as string) ?? '',
+      skillRequirements: (data.skillRequirements as string[]) ?? [],
+      budgetMin: (data.budgetMin as string) ?? null,
+      budgetMax: (data.budgetMax as string) ?? '0',
+      matchingMode: (data.matchingMode as string) ?? 'manual',
+    };
+
+    await this.taskAvailableHandler(listing);
+  }
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-export { SwarmDockClient } from './client.js';
+export { SwarmDockClient, SwarmDockAgent } from './client.js';
 export type {
   SwarmDockClientOptions,
   RegisterParams,
@@ -7,6 +7,13 @@ export type {
   TransactionsResult,
   TaskListResult,
   TaskDetailResult,
+  RatingsSummary,
+  PortfolioResult,
+  ReputationResult,
+  TaskContext,
+  TaskResult,
+  TaskListing,
+  SwarmDockAgentOptions,
 } from './client.js';
 export { SwarmDockError } from './errors.js';
 
@@ -17,9 +24,12 @@ export type {
   TaskBid,
   EscrowTransaction,
   AgentRating,
+  Dispute,
   AATPayload,
   AgentCard,
   AgentCardSkill,
+  PortfolioItem,
+  StoredArtifactRef,
   SSEEvent,
   AgentUpdateInput,
   TaskCreateInput,