march-ai-sdk 0.3.0

package/src/attachment-client.ts

@@ -0,0 +1,78 @@
+/**
+ * March Agent SDK - Attachment Client
+ * Port of Python march_agent/attachment_client.py
+ */
+
+import { APIException } from './exceptions.js'
+import { AttachmentInfoSchema, type AttachmentInfo } from './types.js'
+
+/**
+ * Re-export AttachmentInfo for convenience
+ */
+export { type AttachmentInfo } from './types.js'
+
+/**
+ * Create AttachmentInfo from API data
+ */
+export function createAttachmentInfo(data: Record<string, unknown>): AttachmentInfo {
+    return AttachmentInfoSchema.parse({
+        url: data.url,
+        filename: data.filename || data.file_name,
+        contentType: data.content_type || data.contentType,
+        size: data.size,
+        fileType: data.file_type || data.fileType,
+    })
+}
+
+/**
+ * HTTP client for downloading attachments.
+ */
+export class AttachmentClient {
+    private readonly baseUrl: string
+
+    constructor(baseUrl: string) {
+        this.baseUrl = baseUrl.replace(/\/$/, '')
+    }
+
+    /**
+     * Build full URL for an attachment.
+     */
+    private buildUrl(attachmentUrl: string): string {
+        // If already absolute URL, use as-is
+        if (attachmentUrl.startsWith('http://') || attachmentUrl.startsWith('https://')) {
+            return attachmentUrl
+        }
+        // Otherwise, prepend base URL
+        return `${this.baseUrl}${attachmentUrl.startsWith('/') ? '' : '/'}${attachmentUrl}`
+    }
+
+    /**
+     * Download attachment as bytes (Buffer).
+     */
+    async download(url: string): Promise<Buffer> {
+        const fullUrl = this.buildUrl(url)
+
+        try {
+            const response = await fetch(fullUrl)
+
+            if (!response.ok) {
+                throw new APIException(`Failed to download attachment: ${response.status}`, response.status)
+            }
+
+            const arrayBuffer = await response.arrayBuffer()
+            return Buffer.from(arrayBuffer)
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to download attachment: ${error}`)
+        }
+    }
+
+    /**
+     * Download attachment as base64 string.
+     * Useful for LLM vision APIs.
+     */
+    async downloadAsBase64(url: string): Promise<string> {
+        const buffer = await this.download(url)
+        return buffer.toString('base64')
+    }
+}

package/src/checkpoint-client.ts

@@ -0,0 +1,175 @@
+/**
+ * March Agent SDK - Checkpoint Client
+ * Port of Python march_agent/checkpoint_client.py
+ */
+
+import { APIException } from './exceptions.js'
+
+export interface CheckpointConfig {
+    configurable: {
+        thread_id: string
+        checkpoint_ns?: string
+        checkpoint_id?: string
+    }
+}
+
+export interface CheckpointData {
+    v: number
+    id: string
+    ts: string
+    channel_values: Record<string, unknown>
+    channel_versions: Record<string, string>
+    versions_seen: Record<string, Record<string, string>>
+    pending_sends?: unknown[]
+}
+
+export interface CheckpointMetadata {
+    source: string
+    step: number
+    writes?: unknown
+    parents?: Record<string, string>
+}
+
+export interface CheckpointTuple {
+    config: CheckpointConfig
+    checkpoint: CheckpointData
+    metadata: CheckpointMetadata
+    parent_config?: CheckpointConfig
+    pending_writes?: unknown[]
+}
+
+export interface CheckpointListOptions {
+    threadId?: string
+    checkpointNs?: string
+    before?: string
+    limit?: number
+}
+
+/**
+ * Async HTTP client for checkpoint-store API.
+ * Used by LangGraph integration for persisting graph state.
+ */
+export class CheckpointClient {
+    private readonly baseUrl: string
+
+    constructor(baseUrl: string) {
+        this.baseUrl = baseUrl.replace(/\/$/, '')
+    }
+
+    /**
+     * Store a checkpoint.
+     */
+    async put(
+        config: CheckpointConfig,
+        checkpoint: CheckpointData,
+        metadata: CheckpointMetadata,
+        newVersions: Record<string, unknown> = {}
+    ): Promise<{ config: CheckpointConfig }> {
+        const url = `${this.baseUrl}/checkpoints/`
+        const payload = {
+            config,
+            checkpoint,
+            metadata,
+            new_versions: newVersions,
+        }
+
+        try {
+            const response = await fetch(url, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            })
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to store checkpoint: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as { config: CheckpointConfig }
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to store checkpoint: ${error}`)
+        }
+    }
+
+    /**
+     * Get a checkpoint tuple.
+     */
+    async getTuple(
+        threadId: string,
+        checkpointNs: string = '',
+        checkpointId?: string
+    ): Promise<CheckpointTuple | null> {
+        const url = new URL(`${this.baseUrl}/checkpoints/${threadId}`)
+        url.searchParams.set('checkpoint_ns', checkpointNs)
+        if (checkpointId) {
+            url.searchParams.set('checkpoint_id', checkpointId)
+        }
+
+        try {
+            const response = await fetch(url.toString())
+
+            if (response.status === 404) {
+                return null
+            }
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to get checkpoint: ${response.status} - ${errorText}`, response.status)
+            }
+
+            const result = await response.json() as CheckpointTuple | null
+            return result || null
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to get checkpoint: ${error}`)
+        }
+    }
+
+    /**
+     * List checkpoints.
+     */
+    async list(options: CheckpointListOptions = {}): Promise<CheckpointTuple[]> {
+        const url = new URL(`${this.baseUrl}/checkpoints/`)
+
+        if (options.threadId) url.searchParams.set('thread_id', options.threadId)
+        if (options.checkpointNs !== undefined) url.searchParams.set('checkpoint_ns', options.checkpointNs)
+        if (options.before) url.searchParams.set('before', options.before)
+        if (options.limit) url.searchParams.set('limit', String(options.limit))
+
+        try {
+            const response = await fetch(url.toString())
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to list checkpoints: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as CheckpointTuple[]
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to list checkpoints: ${error}`)
+        }
+    }
+
+    /**
+     * Delete all checkpoints for a thread.
+     */
+    async deleteThread(threadId: string): Promise<{ thread_id: string; deleted: number }> {
+        const url = `${this.baseUrl}/checkpoints/${threadId}`
+
+        try {
+            const response = await fetch(url, { method: 'DELETE' })
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to delete checkpoints: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as { thread_id: string; deleted: number }
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to delete checkpoints: ${error}`)
+        }
+    }
+}

package/src/conversation-client.ts

@@ -0,0 +1,109 @@
+/**
+ * March Agent SDK - Conversation Client
+ * Port of Python march_agent/conversation_client.py
+ */
+
+import { APIException } from './exceptions.js'
+import type { ConversationData, GetMessagesOptions, ConversationMessageData } from './types.js'
+
+/**
+ * HTTP client for interacting with conversation-store API.
+ */
+export class ConversationClient {
+    private readonly baseUrl: string
+
+    constructor(baseUrl: string) {
+        this.baseUrl = baseUrl.replace(/\/$/, '')
+    }
+
+    /**
+     * Get conversation metadata.
+     */
+    async getConversation(conversationId: string): Promise<ConversationData> {
+        const url = `${this.baseUrl}/conversations/${conversationId}`
+
+        try {
+            const response = await fetch(url)
+
+            if (response.status === 404) {
+                throw new APIException(`Conversation ${conversationId} not found`, 404)
+            }
+
+            if (!response.ok) {
+                throw new APIException(`Failed to fetch conversation: ${response.status}`, response.status)
+            }
+
+            return await response.json() as ConversationData
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to fetch conversation: ${error}`)
+        }
+    }
+
+    /**
+     * Get messages from a conversation.
+     */
+    async getMessages(
+        conversationId: string,
+        options: GetMessagesOptions = {}
+    ): Promise<ConversationMessageData[]> {
+        const url = new URL(`${this.baseUrl}/conversations/${conversationId}/messages`)
+
+        const params: Record<string, string> = {
+            limit: String(Math.min(options.limit ?? 100, 1000)),
+            offset: String(options.offset ?? 0),
+        }
+
+        if (options.role) params.role = options.role
+        if (options.from) params.from = options.from
+        if (options.to) params.to = options.to
+
+        Object.entries(params).forEach(([key, value]) => {
+            url.searchParams.set(key, value)
+        })
+
+        try {
+            const response = await fetch(url.toString())
+
+            if (response.status === 404) {
+                throw new APIException(`Conversation ${conversationId} not found`, 404)
+            }
+
+            if (!response.ok) {
+                throw new APIException(`Failed to fetch messages: ${response.status}`, response.status)
+            }
+
+            return await response.json() as ConversationMessageData[]
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to fetch messages: ${error}`)
+        }
+    }
+
+    /**
+     * Update conversation fields (PATCH).
+     */
+    async updateConversation(
+        conversationId: string,
+        data: Partial<ConversationData>
+    ): Promise<ConversationData> {
+        const url = `${this.baseUrl}/conversations/${conversationId}`
+
+        try {
+            const response = await fetch(url, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(data),
+            })
+
+            if (!response.ok) {
+                throw new APIException(`Failed to update conversation: ${response.status}`, response.status)
+            }
+
+            return await response.json() as ConversationData
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to update conversation: ${error}`)
+        }
+    }
+}

package/src/conversation-message.ts

@@ -0,0 +1,61 @@
+/**
+ * March Agent SDK - Conversation Message
+ * Port of Python march_agent/conversation_message.py
+ */
+
+import type { ConversationMessageData } from './types.js'
+
+/**
+ * Represents a message from conversation history.
+ */
+export class ConversationMessage {
+    readonly id: string
+    readonly conversationId: string
+    readonly role: 'user' | 'assistant' | 'system'
+    readonly content: string
+    readonly from?: string
+    readonly to?: string
+    readonly createdAt: Date
+    readonly metadata?: Record<string, unknown>
+
+    constructor(data: ConversationMessageData) {
+        this.id = data.id
+        this.conversationId = data.conversationId
+        this.role = data.role
+        this.content = data.content
+        this.from = data.from
+        this.to = data.to
+        this.createdAt = new Date(data.createdAt)
+        this.metadata = data.metadata
+    }
+
+    /**
+     * Create from API response
+     */
+    static fromApiResponse(data: Record<string, unknown>): ConversationMessage {
+        return new ConversationMessage({
+            id: data.id as string,
+            conversationId: data.conversation_id as string,
+            role: data.role as 'user' | 'assistant' | 'system',
+            content: data.content as string,
+            from: data.from as string | undefined,
+            to: data.to as string | undefined,
+            createdAt: data.created_at as string,
+            metadata: data.metadata as Record<string, unknown> | undefined,
+        })
+    }
+
+    /**
+     * Check if this is a user message
+     */
+    isUser(): boolean {
+        return this.role === 'user'
+    }
+
+    /**
+     * Check if this is an assistant message
+     */
+    isAssistant(): boolean {
+        return this.role === 'assistant'
+    }
+}

package/src/conversation.ts

@@ -0,0 +1,123 @@
+/**
+ * March Agent SDK - Conversation Helper
+ * Port of Python march_agent/conversation.py
+ */
+
+import { ConversationClient } from './conversation-client.js'
+import { ConversationMessage } from './conversation-message.js'
+// Types are inlined to avoid unused import warnings
+
+export interface GetHistoryOptions {
+    limit?: number
+    offset?: number
+}
+
+export interface GetAgentHistoryOptions extends GetHistoryOptions {
+    agentName?: string
+}
+
+/**
+ * Helper class for accessing conversation history.
+ * Provides convenient methods for fetching messages.
+ */
+export class Conversation {
+    readonly conversationId: string
+    private readonly client: ConversationClient
+    private readonly agentName?: string
+
+    constructor(
+        conversationId: string,
+        client: ConversationClient,
+        agentName?: string
+    ) {
+        this.conversationId = conversationId
+        this.client = client
+        this.agentName = agentName
+    }
+
+    /**
+     * Get all messages in the conversation.
+     */
+    async getHistory(options: GetHistoryOptions = {}): Promise<ConversationMessage[]> {
+        const messages = await this.client.getMessages(this.conversationId, {
+            limit: options.limit ?? 100,
+            offset: options.offset ?? 0,
+        })
+
+        return messages.map((m) => ConversationMessage.fromApiResponse(m as unknown as Record<string, unknown>))
+    }
+
+    /**
+     * Get messages to/from the current agent.
+     * Useful for getting conversation history for a specific agent.
+     */
+    async getAgentHistory(options: GetAgentHistoryOptions = {}): Promise<ConversationMessage[]> {
+        const targetAgent = options.agentName ?? this.agentName
+        if (!targetAgent) {
+            // If no agent name, return all messages
+            return this.getHistory(options)
+        }
+
+        // Get messages where the agent is either sender or receiver
+        const [toAgent, fromAgent] = await Promise.all([
+            this.client.getMessages(this.conversationId, {
+                to: targetAgent,
+                limit: options.limit ?? 50,
+                offset: options.offset ?? 0,
+            }),
+            this.client.getMessages(this.conversationId, {
+                from: targetAgent,
+                limit: options.limit ?? 50,
+                offset: options.offset ?? 0,
+            }),
+        ])
+
+        // Combine and sort by creation time
+        const allMessages = [...toAgent, ...fromAgent]
+        const uniqueMessages = Array.from(
+            new Map(allMessages.map((m) => [m.id, m])).values()
+        )
+
+        // Sort by createdAt
+        uniqueMessages.sort((a, b) => {
+            const dateA = new Date(a.createdAt).getTime()
+            const dateB = new Date(b.createdAt).getTime()
+            return dateA - dateB
+        })
+
+        return uniqueMessages.map((m) =>
+            ConversationMessage.fromApiResponse(m as unknown as Record<string, unknown>)
+        )
+    }
+
+    /**
+     * Get the last N messages.
+     */
+    async getLastMessages(count: number): Promise<ConversationMessage[]> {
+        return this.getHistory({ limit: count })
+    }
+
+    /**
+     * Get user messages only.
+     */
+    async getUserMessages(options: GetHistoryOptions = {}): Promise<ConversationMessage[]> {
+        const messages = await this.client.getMessages(this.conversationId, {
+            ...options,
+            role: 'user',
+        })
+
+        return messages.map((m) => ConversationMessage.fromApiResponse(m as unknown as Record<string, unknown>))
+    }
+
+    /**
+     * Get assistant messages only.
+     */
+    async getAssistantMessages(options: GetHistoryOptions = {}): Promise<ConversationMessage[]> {
+        const messages = await this.client.getMessages(this.conversationId, {
+            ...options,
+            role: 'assistant',
+        })
+
+        return messages.map((m) => ConversationMessage.fromApiResponse(m as unknown as Record<string, unknown>))
+    }
+}

package/src/exceptions.ts

@@ -0,0 +1,78 @@
+/**
+ * March Agent SDK - Custom Errors
+ * Port of Python march_agent/exceptions.py
+ */
+
+/**
+ * Base error class for March Agent SDK
+ */
+export class MarchAgentError extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = 'MarchAgentError'
+        Error.captureStackTrace?.(this, this.constructor)
+    }
+}
+
+/**
+ * Error during agent registration with AI Inventory
+ */
+export class RegistrationError extends MarchAgentError {
+    constructor(message: string) {
+        super(message)
+        this.name = 'RegistrationError'
+    }
+}
+
+/**
+ * Error during Kafka operations (produce/consume)
+ */
+export class KafkaError extends MarchAgentError {
+    constructor(message: string) {
+        super(message)
+        this.name = 'KafkaError'
+    }
+}
+
+/**
+ * Error in SDK configuration
+ */
+export class ConfigurationError extends MarchAgentError {
+    constructor(message: string) {
+        super(message)
+        this.name = 'ConfigurationError'
+    }
+}
+
+/**
+ * Error from API calls to backend services
+ */
+export class APIException extends MarchAgentError {
+    statusCode?: number
+
+    constructor(message: string, statusCode?: number) {
+        super(message)
+        this.name = 'APIException'
+        this.statusCode = statusCode
+    }
+}
+
+/**
+ * Error during heartbeat operations
+ */
+export class HeartbeatError extends MarchAgentError {
+    constructor(message: string) {
+        super(message)
+        this.name = 'HeartbeatError'
+    }
+}
+
+/**
+ * Error during gRPC connection/communication
+ */
+export class GatewayError extends MarchAgentError {
+    constructor(message: string) {
+        super(message)
+        this.name = 'GatewayError'
+    }
+}

package/src/extensions/index.ts

@@ -0,0 +1,6 @@
+/**
+ * March Agent SDK - Extensions
+ */
+
+export { HTTPCheckpointSaver } from './langgraph.js'
+export { VercelAIMessageStore } from './vercel-ai.js'