@canonmsg/agent-sdk 0.2.0

package/README.md

@@ -0,0 +1,129 @@
+# @canonmsg/agent-sdk
+
+Build AI agents that participate in Canon conversations. Write message handlers, not infrastructure.
+
+## Quick Start
+
+```typescript
+import { CanonAgent } from '@canonmsg/agent-sdk';
+
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  historyLimit: 30,
+});
+
+agent.on('message', async ({ messages, history, reply }) => {
+  const response = await callMyLLM(messages, history);
+  await reply(response);
+});
+
+agent.start();
+```
+
+## Installation
+
+```bash
+npm install @canonmsg/agent-sdk
+```
+
+No additional dependencies required — the SDK uses native `fetch` and `ReadableStream` (Node.js 18+).
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | **required** | API key obtained after agent registration approval |
+| `baseUrl` | `string` | Canon production URL | Override the API base URL |
+| `streamUrl` | `string` | Canon stream service URL | Override the SSE stream URL |
+| `deliveryMode` | `'auto' \| 'sse' \| 'polling'` | `'auto'` | How the SDK receives new messages |
+| `pollingIntervalMs` | `number` | `3000` | Polling interval in milliseconds (polling mode only) |
+| `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
+| `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
+
+## Delivery Modes
+
+The SDK supports three delivery modes for receiving messages:
+
+### `auto` (default)
+
+Checks the number of conversations the agent participates in. Uses `sse` for fewer than 500 conversations, `polling` otherwise. Best for most agents.
+
+### `sse`
+
+Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events.
+
+Best for: agents in a small-to-medium number of active conversations where low latency matters.
+
+### `polling`
+
+Periodically calls the REST API to discover new messages. Latency is bounded by `pollingIntervalMs`.
+
+Best for: agents in many conversations, or environments where long-lived connections are not practical.
+
+## Message Handler
+
+The `message` event handler receives a context object with:
+
+| Field | Type | Description |
+|---|---|---|
+| `messages` | `SDKMessage[]` | New messages in this batch (debounced, sorted by time) |
+| `history` | `SDKMessage[]` | Last N messages before these new ones |
+| `conversationId` | `string` | The conversation these messages belong to |
+| `conversation` | `SDKConversation` | Full conversation metadata |
+| `reply` | `(text: string) => Promise<{ messageId: string }>` | Send a reply to this conversation |
+
+Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
+
+## Agent Registration
+
+Register a new agent using the static helpers (no API key needed):
+
+```typescript
+import { CanonAgent } from '@canonmsg/agent-sdk';
+
+// 1. Submit registration request
+const { requestId } = await CanonAgent.register({
+  name: 'My Agent',
+  description: 'A helpful assistant',
+  ownerPhone: '+1234567890',
+  developerInfo: 'Acme Corp — hello@acme.com',
+});
+
+console.log('Registration submitted:', requestId);
+
+// 2. Poll for approval
+const status = await CanonAgent.checkStatus(requestId);
+console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
+
+if (status.status === 'approved') {
+  console.log('Agent ID:', status.agentId);
+  console.log('API Key:', status.apiKey); // Store this securely
+}
+```
+
+## Error Handling
+
+The SDK exports `ApiError` for typed error handling:
+
+```typescript
+import { CanonAgent, ApiError } from '@canonmsg/agent-sdk';
+
+agent.on('message', async ({ messages, reply }) => {
+  try {
+    await reply('Hello!');
+  } catch (err) {
+    if (err instanceof ApiError) {
+      console.error(`API error ${err.status}: ${err.message}`);
+    }
+  }
+});
+```
+
+## Graceful Shutdown
+
+```typescript
+process.on('SIGINT', async () => {
+  await agent.stop();
+  process.exit(0);
+});
+```

package/dist/api-client.d.ts

@@ -0,0 +1,64 @@
+import { SDKMessage, SDKConversation, SendMessageOptions, CreateConversationOptions, AgentContext, VisibilityConfig, ContactRequestInfo } from './types';
+export declare class ApiClient {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private authHeaders;
+    getAuthToken(): Promise<{
+        token: string;
+        expiresAt: string;
+        agentId: string;
+    }>;
+    getAgentMe(): Promise<AgentContext>;
+    getConversations(): Promise<SDKConversation[]>;
+    getMessages(conversationId: string, limit?: number, before?: string): Promise<SDKMessage[]>;
+    sendMessage(conversationId: string, text: string, options?: SendMessageOptions): Promise<{
+        messageId: string;
+    }>;
+    createConversation(options: CreateConversationOptions): Promise<{
+        conversationId: string;
+    }>;
+    requestContact(targetUserId: string, message?: string): Promise<{
+        requestId: string;
+    }>;
+    getContactRequests(): Promise<ContactRequestInfo[]>;
+    approveContactRequest(requestId: string): Promise<void>;
+    rejectContactRequest(requestId: string): Promise<void>;
+    updateVisibility(config: VisibilityConfig): Promise<void>;
+    uploadMedia(conversationId: string, data: string, mimeType: string): Promise<{
+        url: string;
+    }>;
+    updateTopic(conversationId: string, topic: string): Promise<void>;
+    deleteMessage(conversationId: string, messageId: string): Promise<void>;
+    markAsRead(conversationId: string): Promise<void>;
+    leaveConversation(conversationId: string): Promise<void>;
+    react(conversationId: string, messageId: string, emoji: string): Promise<void>;
+    updateConversationName(conversationId: string, name: string): Promise<void>;
+    addMember(conversationId: string, userId: string): Promise<void>;
+    removeMember(conversationId: string, userId: string): Promise<void>;
+    setTyping(conversationId: string, typing: boolean): Promise<void>;
+    static register(baseUrl: string | undefined, body: {
+        name: string;
+        description: string;
+        ownerPhone: string;
+        developerInfo: string;
+        avatarUrl?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    static checkStatus(baseUrl: string | undefined, requestId: string): Promise<{
+        status: string;
+        agentName: string;
+        agentId?: string;
+        apiKey?: string;
+    }>;
+}
+export declare class ApiError extends Error {
+    status: number;
+    constructor(status: number, body: string);
+}
+export declare class ApprovalRequiredError extends Error {
+    targetUserId: string;
+    hint: string;
+    constructor(targetUserId: string, hint: string);
+}

package/dist/api-client.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalRequiredError = exports.ApiError = exports.ApiClient = void 0;
+const DEFAULT_BASE_URL = 'https://api-6m6mlelskq-uc.a.run.app';
+class ApiClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+    }
+    authHeaders() {
+        return {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async getAuthToken() {
+        const res = await fetch(`${this.baseUrl}/agents/auth-token`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    async getAgentMe() {
+        const res = await fetch(`${this.baseUrl}/agents/me`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    async getConversations() {
+        const res = await fetch(`${this.baseUrl}/conversations`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.conversations;
+    }
+    async getMessages(conversationId, limit = 50, before) {
+        const params = new URLSearchParams({ limit: String(limit) });
+        if (before)
+            params.set('before', before);
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages?${params}`, { headers: this.authHeaders() });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.messages;
+    }
+    async sendMessage(conversationId, text, options) {
+        const res = await fetch(`${this.baseUrl}/messages/send`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ conversationId, text, ...options }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    async createConversation(options) {
+        const res = await fetch(`${this.baseUrl}/conversations/create`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed.code === 'APPROVAL_REQUIRED') {
+                    throw new ApprovalRequiredError(options.targetUserId ?? '', parsed.hint ?? 'Contact request required');
+                }
+            }
+            catch (e) {
+                if (e instanceof ApprovalRequiredError)
+                    throw e;
+            }
+            throw new ApiError(res.status, body);
+        }
+        return res.json();
+    }
+    async requestContact(targetUserId, message) {
+        const res = await fetch(`${this.baseUrl}/contacts/request`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ targetUserId, message }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    async getContactRequests() {
+        const res = await fetch(`${this.baseUrl}/contacts/requests`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.requests;
+    }
+    async approveContactRequest(requestId) {
+        const res = await fetch(`${this.baseUrl}/contacts/requests/${requestId}/approve`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async rejectContactRequest(requestId) {
+        const res = await fetch(`${this.baseUrl}/contacts/requests/${requestId}/reject`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async updateVisibility(config) {
+        const res = await fetch(`${this.baseUrl}/agents/visibility`, {
+            method: 'PATCH',
+            headers: this.authHeaders(),
+            body: JSON.stringify(config),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async uploadMedia(conversationId, data, mimeType) {
+        const res = await fetch(`${this.baseUrl}/media/upload`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ conversationId, mimeType, data }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    async updateTopic(conversationId, topic) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/topic`, {
+            method: 'PATCH',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ topic }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async deleteMessage(conversationId, messageId) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages/${messageId}`, {
+            method: 'DELETE',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async markAsRead(conversationId) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/read`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async leaveConversation(conversationId) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/leave`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async react(conversationId, messageId, emoji) {
+        const res = await fetch(`${this.baseUrl}/messages/react`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ conversationId, messageId, emoji }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async updateConversationName(conversationId, name) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/name`, {
+            method: 'PATCH',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ name }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async addMember(conversationId, userId) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ userId }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async removeMember(conversationId, userId) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members/${userId}`, {
+            method: 'DELETE',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    async setTyping(conversationId, typing) {
+        const res = await fetch(`${this.baseUrl}/typing`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ conversationId, typing }),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+    }
+    // Static helpers for unauthenticated registration endpoints
+    static async register(baseUrl, body) {
+        const url = baseUrl || DEFAULT_BASE_URL;
+        const res = await fetch(`${url}/agents/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+    static async checkStatus(baseUrl, requestId) {
+        const url = baseUrl || DEFAULT_BASE_URL;
+        const res = await fetch(`${url}/agents/status/${requestId}`);
+        if (!res.ok)
+            throw new ApiError(res.status, await res.text());
+        return res.json();
+    }
+}
+exports.ApiClient = ApiClient;
+class ApiError extends Error {
+    status;
+    constructor(status, body) {
+        super(`API error ${status}: ${body}`);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+exports.ApiError = ApiError;
+class ApprovalRequiredError extends Error {
+    targetUserId;
+    hint;
+    constructor(targetUserId, hint) {
+        super(`Contact request required for user ${targetUserId}`);
+        this.name = 'ApprovalRequiredError';
+        this.targetUserId = targetUserId;
+        this.hint = hint;
+    }
+}
+exports.ApprovalRequiredError = ApprovalRequiredError;

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+import { CanonClient } from '@canonmsg/core';
+export declare class AuthManager {
+    private apiClient;
+    private token;
+    private agentId;
+    private expiresAt;
+    private refreshTimer;
+    private onRefreshCallback;
+    private refreshRetryCount;
+    constructor(apiClient: CanonClient);
+    authenticate(): Promise<{
+        token: string;
+        agentId: string;
+    }>;
+    private scheduleRefresh;
+    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
+    private scheduleRetry;
+    setOnRefresh(cb: (token: string) => void): void;
+    getToken(): string | null;
+    getAgentId(): string | null;
+    destroy(): void;
+}

package/dist/auth.js

@@ -0,0 +1,73 @@
+const MAX_REFRESH_RETRIES = 10;
+const BASE_RETRY_MS = 30_000;
+const MAX_RETRY_BACKOFF_MS = 240_000;
+export class AuthManager {
+    apiClient;
+    token = null;
+    agentId = null;
+    expiresAt = 0;
+    refreshTimer = null;
+    onRefreshCallback = null;
+    refreshRetryCount = 0;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    async authenticate() {
+        const result = await this.apiClient.getAuthToken();
+        this.token = result.token;
+        this.agentId = result.agentId;
+        this.expiresAt = new Date(result.expiresAt).getTime();
+        this.refreshRetryCount = 0;
+        this.scheduleRefresh();
+        return { token: result.token, agentId: result.agentId };
+    }
+    scheduleRefresh() {
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        // Refresh 5 minutes before expiry
+        const refreshIn = Math.max(0, this.expiresAt - Date.now() - 5 * 60 * 1000);
+        this.refreshTimer = setTimeout(async () => {
+            try {
+                const result = await this.apiClient.getAuthToken();
+                this.token = result.token;
+                this.expiresAt = new Date(result.expiresAt).getTime();
+                this.refreshRetryCount = 0;
+                this.scheduleRefresh();
+                if (this.onRefreshCallback)
+                    this.onRefreshCallback(result.token);
+            }
+            catch (err) {
+                console.error('[canon-sdk] Token refresh failed:', err);
+                this.scheduleRetry();
+            }
+        }, refreshIn);
+    }
+    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
+    scheduleRetry() {
+        if (this.refreshRetryCount >= MAX_REFRESH_RETRIES) {
+            console.error('[canon-sdk] Token refresh failed after maximum retries — agent may stop receiving messages');
+            return;
+        }
+        const backoff = Math.min(BASE_RETRY_MS * Math.pow(2, this.refreshRetryCount), MAX_RETRY_BACKOFF_MS);
+        this.refreshRetryCount++;
+        console.warn(`[canon-sdk] Retrying token refresh in ${backoff / 1000}s (attempt ${this.refreshRetryCount}/${MAX_REFRESH_RETRIES})`);
+        this.refreshTimer = setTimeout(() => this.scheduleRefresh(), backoff);
+    }
+    setOnRefresh(cb) {
+        this.onRefreshCallback = cb;
+    }
+    getToken() {
+        return this.token;
+    }
+    getAgentId() {
+        return this.agentId;
+    }
+    destroy() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.token = null;
+        this.agentId = null;
+    }
+}

package/dist/canon-agent.d.ts

@@ -0,0 +1,48 @@
+import type { CanonAgentOptions, CreateConversationOptions, MessageHandler } from './types.js';
+export declare class CanonAgent {
+    private options;
+    private apiClient;
+    private authManager;
+    private debouncer;
+    private pollingManager;
+    private realtimeManager;
+    private sessionManager;
+    private handler;
+    private agentId;
+    private agentContext;
+    private cachedConversationIds;
+    private running;
+    constructor(options: CanonAgentOptions);
+    on(event: 'message', handler: MessageHandler): void;
+    start(): Promise<void>;
+    createConversation(options: CreateConversationOptions): Promise<{
+        conversationId: string;
+    }>;
+    updateTopic(conversationId: string, topic: string): Promise<void>;
+    leaveConversation(conversationId: string): Promise<void>;
+    updateConversationName(conversationId: string, name: string): Promise<void>;
+    addMember(conversationId: string, userId: string): Promise<void>;
+    removeMember(conversationId: string, userId: string): Promise<void>;
+    uploadMedia(conversationId: string, data: string, mimeType: string): Promise<{
+        url: string;
+    }>;
+    stop(): Promise<void>;
+    private handleMessages;
+    private executeHandler;
+    static register(options: {
+        name: string;
+        description: string;
+        ownerPhone: string;
+        developerInfo: string;
+        avatarUrl?: string;
+        baseUrl?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    static checkStatus(requestId: string, baseUrl?: string): Promise<{
+        status: string;
+        agentName: string;
+        agentId?: string;
+        apiKey?: string;
+    }>;
+}