@pingagent/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,501 @@
+import { ApiResponse, InboxBoxType, TaskState } from '@pingagent/schemas';
+import { Identity } from '@pingagent/protocol';
+import Database from 'better-sqlite3';
+import { AgentCard } from '@pingagent/a2a';
+
+declare class LocalStore {
+    private db;
+    constructor(dbPath?: string);
+    getDb(): Database.Database;
+    close(): void;
+}
+
+interface Contact {
+    did: string;
+    alias?: string;
+    display_name?: string;
+    notes?: string;
+    conversation_id?: string;
+    trusted: boolean;
+    added_at: number;
+    last_message_at?: number;
+    tags?: string[];
+}
+declare class ContactManager {
+    private store;
+    constructor(store: LocalStore);
+    add(contact: Omit<Contact, 'added_at'> & {
+        added_at?: number;
+    }): Contact;
+    remove(did: string): boolean;
+    get(did: string): Contact | null;
+    update(did: string, updates: Partial<Omit<Contact, 'did'>>): Contact | null;
+    list(opts?: {
+        tag?: string;
+        trusted?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Contact[];
+    search(query: string): Contact[];
+    export(format?: 'json' | 'csv'): string;
+    import(data: string, format?: 'json' | 'csv'): {
+        imported: number;
+        skipped: number;
+    };
+}
+
+interface StoredMessage {
+    conversation_id: string;
+    message_id: string;
+    seq?: number;
+    sender_did: string;
+    schema: string;
+    payload: any;
+    ts_ms: number;
+    direction: 'sent' | 'received';
+}
+interface ConversationSummary {
+    conversation_id: string;
+    message_count: number;
+    last_message_at: number;
+}
+declare class HistoryManager {
+    private store;
+    constructor(store: LocalStore);
+    save(messages: StoredMessage[]): number;
+    list(conversationId: string, opts?: {
+        limit?: number;
+        beforeSeq?: number;
+        afterSeq?: number;
+    }): StoredMessage[];
+    /** Returns the N most recent messages (chronological order, oldest to newest of those N). */
+    listRecent(conversationId: string, limit: number): StoredMessage[];
+    search(query: string, opts?: {
+        conversationId?: string;
+        limit?: number;
+    }): StoredMessage[];
+    delete(conversationId: string): number;
+    listConversations(): ConversationSummary[];
+    getLastSyncedSeq(conversationId: string): number;
+    setLastSyncedSeq(conversationId: string, seq: number): void;
+    export(opts?: {
+        conversationId?: string;
+        format?: 'json' | 'csv';
+    }): string;
+    syncFromServer(client: PingAgentClient, conversationId: string, opts?: {
+        full?: boolean;
+    }): Promise<{
+        synced: number;
+    }>;
+}
+
+interface ClientOptions {
+    serverUrl: string;
+    identity: Identity;
+    accessToken: string;
+    mode?: 'long-running' | 'one-shot';
+    onTokenRefreshed?: (token: string, expiresAt: number) => void;
+    store?: LocalStore;
+}
+interface SendResponse {
+    message_id: string;
+    seq: number;
+    receipt: {
+        status: string;
+        reason?: string;
+        server_ts_ms: number;
+    };
+}
+interface FetchResponse {
+    messages: any[];
+    next_since_seq: number;
+    has_more: boolean;
+}
+interface TaskResult {
+    status: 'ok' | 'error';
+    task_id: string;
+    result?: {
+        summary?: string;
+        artifacts?: any[];
+        structured_data?: any;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+    elapsed_ms: number;
+}
+interface SubscriptionUsage {
+    relay_today: number;
+    relay_limit: number;
+    artifact_bytes: number;
+    artifact_limit_bytes: number;
+    alias_count: number;
+    alias_limit: number;
+}
+interface SubscriptionResponse {
+    tier: string;
+    limits: {
+        relay_per_day: number;
+        max_group_size: number;
+        artifact_storage_mb: number;
+        audit_export_allowed: boolean;
+        alias_limit: number;
+    };
+    usage: SubscriptionUsage;
+    has_stripe_customer: boolean;
+}
+interface ConversationEntry {
+    conversation_id: string;
+    type: string;
+    target_did: string;
+    trusted: boolean;
+    created_at: number;
+}
+interface ConversationListResponse {
+    conversations: ConversationEntry[];
+}
+interface AgentProfile {
+    did: string;
+    alias?: string;
+    display_name?: string;
+    bio?: string;
+    capabilities?: string[];
+    tags?: string[];
+    verification_status?: string;
+    discoverable?: boolean;
+}
+interface DirectoryBrowseResponse {
+    agents: AgentProfile[];
+    total?: number;
+}
+interface FeedPost {
+    post_id: string;
+    text: string;
+    artifact_ref?: string | null;
+    ts_ms: number;
+}
+interface FeedPublicResponse {
+    posts: Array<FeedPost & {
+        did: string;
+    }>;
+    next_since?: number;
+}
+interface FeedByDidResponse {
+    did: string;
+    posts: FeedPost[];
+}
+declare class PingAgentClient {
+    private opts;
+    private transport;
+    private identity;
+    private contactManager?;
+    private historyManager?;
+    constructor(opts: ClientOptions);
+    getContactManager(): ContactManager | undefined;
+    getHistoryManager(): HistoryManager | undefined;
+    /** Update the in-memory access token (e.g. after proactive refresh from disk). */
+    setAccessToken(token: string): void;
+    register(developerToken?: string): Promise<ApiResponse>;
+    openConversation(targetDid: string): Promise<ApiResponse<{
+        conversation_id: string;
+        type: string;
+        trusted: boolean;
+        relay_ws_url: string;
+    }>>;
+    sendMessage(conversationId: string, schema: string, payload: Record<string, unknown>): Promise<ApiResponse<SendResponse>>;
+    sendTask(conversationId: string, task: {
+        task_id: string;
+        title: string;
+        description?: string;
+        input?: any;
+        timeout_ms?: number;
+    }): Promise<ApiResponse<SendResponse>>;
+    sendContactRequest(conversationId: string, message?: string): Promise<ApiResponse<SendResponse>>;
+    fetchInbox(conversationId: string, opts?: {
+        sinceSeq?: number;
+        limit?: number;
+        box?: InboxBoxType;
+    }): Promise<ApiResponse<FetchResponse>>;
+    ack(conversationId: string, forMessageId: string, status: string, opts?: {
+        forTaskId?: string;
+        reason?: string;
+        detail?: Record<string, unknown>;
+    }): Promise<ApiResponse>;
+    approveContact(conversationId: string): Promise<ApiResponse<{
+        trusted: boolean;
+        dm_conversation_id?: string;
+    }>>;
+    revokeConversation(conversationId: string): Promise<ApiResponse>;
+    cancelTask(conversationId: string, taskId: string): Promise<ApiResponse<{
+        task_state: TaskState;
+    }>>;
+    blockSender(conversationId: string, senderDid: string): Promise<ApiResponse>;
+    acquireLease(conversationId: string): Promise<ApiResponse>;
+    renewLease(conversationId: string): Promise<ApiResponse>;
+    releaseLease(conversationId: string): Promise<ApiResponse>;
+    uploadArtifact(content: Buffer): Promise<{
+        artifact_ref: string;
+        sha256: string;
+        size: number;
+    }>;
+    downloadArtifact(artifactRef: string, expectedSha256: string, expectedSize: number): Promise<Buffer>;
+    getSubscription(): Promise<ApiResponse<SubscriptionResponse>>;
+    resolveAlias(alias: string): Promise<ApiResponse<{
+        did: string;
+        alias: string;
+    }>>;
+    registerAlias(alias: string): Promise<ApiResponse>;
+    listConversations(opts?: {
+        type?: string;
+    }): Promise<ApiResponse<ConversationListResponse>>;
+    getProfile(): Promise<ApiResponse<AgentProfile>>;
+    updateProfile(profile: {
+        display_name?: string;
+        bio?: string;
+        capabilities?: string[];
+        tags?: string[];
+        discoverable?: boolean;
+    }): Promise<ApiResponse<AgentProfile>>;
+    enableDiscovery(): Promise<ApiResponse<{
+        discoverable: boolean;
+    }>>;
+    disableDiscovery(): Promise<ApiResponse<{
+        discoverable: boolean;
+    }>>;
+    browseDirectory(opts?: {
+        tag?: string;
+        query?: string;
+        limit?: number;
+        offset?: number;
+        sort?: 'default' | 'updated';
+    }): Promise<ApiResponse<DirectoryBrowseResponse>>;
+    publishPost(opts: {
+        text: string;
+        artifact_ref?: string;
+    }): Promise<ApiResponse<{
+        post_id: string;
+        ts_ms: number;
+    }>>;
+    listFeedPublic(opts?: {
+        limit?: number;
+        since?: number;
+    }): Promise<ApiResponse<FeedPublicResponse>>;
+    listFeedByDid(did: string, opts?: {
+        limit?: number;
+    }): Promise<ApiResponse<FeedByDidResponse>>;
+    createChannel(opts: {
+        name: string;
+        alias?: string;
+        description?: string;
+        discoverable?: boolean;
+    }): Promise<ApiResponse<{
+        conversation_id: string;
+        alias: string;
+        name: string;
+        discoverable: boolean;
+        relay_ws_url: string;
+    }>>;
+    updateChannel(opts: {
+        alias: string;
+        name?: string;
+        description?: string;
+        discoverable?: boolean;
+    }): Promise<ApiResponse<{
+        alias: string;
+        name: string;
+        description?: string | null;
+        discoverable: boolean;
+    }>>;
+    deleteChannel(alias: string): Promise<ApiResponse<{
+        deleted: boolean;
+        alias: string;
+    }>>;
+    discoverChannels(opts?: {
+        limit?: number;
+        query?: string;
+    }): Promise<ApiResponse<{
+        channels: Array<{
+            alias: string;
+            name: string;
+            description?: string | null;
+            owner_did: string;
+        }>;
+    }>>;
+    joinChannel(alias: string): Promise<ApiResponse<{
+        conversation_id: string;
+        alias: string;
+        owner_did: string;
+        relay_ws_url: string;
+    }>>;
+    getDid(): string;
+    createBillingLinkCode(): Promise<ApiResponse<{
+        code: string;
+        expires_in_seconds: number;
+    }>>;
+    redeemBillingLink(code: string): Promise<ApiResponse<{
+        primary_did: string;
+    }>>;
+    unlinkBillingDevice(did: string): Promise<ApiResponse>;
+    getLinkedDevices(): Promise<ApiResponse<{
+        primary_did: string;
+        linked_dids: string[];
+        is_primary: boolean;
+    }>>;
+    sendTaskAndWait(targetDid: string, task: {
+        title: string;
+        description?: string;
+        input?: any;
+    }, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<TaskResult>;
+}
+
+declare function generateIdentity(): Identity;
+declare function identityExists(identityPath?: string): boolean;
+declare function loadIdentity(identityPath?: string): Identity & {
+    serverUrl?: string;
+    accessToken?: string;
+    tokenExpiresAt?: number;
+    mode?: string;
+};
+declare function saveIdentity(identity: Identity, opts?: {
+    serverUrl?: string;
+    accessToken?: string;
+    tokenExpiresAt?: number;
+    mode?: string;
+    alias?: string;
+}, identityPath?: string): void;
+declare function updateStoredToken(accessToken: string, expiresAt: number, identityPath?: string): void;
+
+/**
+ * Proactive token refresh: call before creating the client when token is near or past expiry.
+ * Server allows refresh only within a short grace period (default 5 min) after expiry.
+ */
+/**
+ * If the stored token is expired or expires within the refresh grace window,
+ * call the server's /v1/auth/refresh and persist the new token.
+ * Call this after loadIdentity() and before creating PingAgentClient.
+ * @returns true if a refresh was performed and the identity file was updated, false otherwise
+ */
+declare function ensureTokenValid(identityPath?: string, serverUrl?: string): Promise<boolean>;
+
+declare function getRootDir(): string;
+declare function getProfile(): string | undefined;
+declare function getIdentityPath(explicitPath?: string): string;
+declare function getStorePath(explicitPath?: string): string;
+
+interface TransportOptions {
+    serverUrl: string;
+    accessToken: string;
+    maxRetries?: number;
+    onTokenRefreshed?: (newToken: string, expiresAt: number) => void;
+}
+declare class HttpTransport {
+    private serverUrl;
+    private accessToken;
+    private maxRetries;
+    private onTokenRefreshed?;
+    constructor(opts: TransportOptions);
+    setToken(token: string): void;
+    /** Fetch a URL with Bearer auth (e.g. artifact upload/download). */
+    fetchWithAuth(url: string, options?: {
+        method?: string;
+        body?: ArrayBuffer | Buffer;
+        contentType?: string;
+    }): Promise<ArrayBuffer>;
+    request<T = any>(method: string, path: string, body?: any, skipAuth?: boolean): Promise<ApiResponse<T>>;
+    private refreshToken;
+}
+
+/**
+ * A2A adapter for PingAgentClient.
+ * Allows PingAgent to call external agents that speak the A2A protocol,
+ * translating PingAgent's task model to A2A's message/send + tasks/get.
+ */
+
+interface A2AAdapterOptions {
+    agentUrl: string;
+    authToken?: string;
+    timeoutMs?: number;
+}
+/**
+ * Wraps an A2AClient and exposes PingAgent-style operations that delegate
+ * to an external A2A agent.
+ */
+declare class A2AAdapter {
+    private client;
+    private cachedCard;
+    constructor(opts: A2AAdapterOptions);
+    getAgentCard(): Promise<AgentCard>;
+    /**
+     * Send a task to the external A2A agent and optionally wait for completion.
+     */
+    sendTask(opts: {
+        title: string;
+        description?: string;
+        input?: unknown;
+        wait?: boolean;
+        timeoutMs?: number;
+    }): Promise<A2ATaskResult>;
+    getTaskStatus(taskId: string): Promise<A2ATaskResult>;
+    cancelTask(taskId: string): Promise<A2ATaskResult>;
+    sendText(text: string, opts?: {
+        blocking?: boolean;
+    }): Promise<A2ATaskResult>;
+    private convertTask;
+    private extractText;
+}
+interface A2ATaskResult {
+    taskId: string;
+    contextId?: string;
+    state: string;
+    summary?: string;
+    output?: unknown;
+    timestamp?: string;
+}
+
+/**
+ * WebSocket subscription for real-time inbox messages.
+ * Connects to Gateway /v1/ws per conversation and receives ws_message pushes.
+ */
+
+interface WsControlPayload {
+    action: string;
+    target?: string;
+}
+interface WsSubscriptionOptions {
+    serverUrl: string;
+    getAccessToken: () => string | Promise<string>;
+    myDid: string;
+    listConversations: () => Promise<ConversationEntry[]>;
+    onMessage: (envelope: any, conversationId: string) => void;
+    onControl?: (control: WsControlPayload, conversationId: string) => void;
+    onError?: (err: Error) => void;
+}
+declare class WsSubscription {
+    private opts;
+    private connections;
+    private reconnectTimers;
+    private reconnectAttempts;
+    private listInterval;
+    private stopped;
+    /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
+    private stoppedConversations;
+    constructor(opts: WsSubscriptionOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * Stop a single conversation's WebSocket and do not reconnect.
+     * Used when the conversation is revoked or the client no longer wants to subscribe.
+     */
+    stopConversation(conversationId: string): void;
+    private wsUrl;
+    private connectAsync;
+    private scheduleReconnect;
+    private connectAll;
+    private syncConnections;
+}
+
+export { A2AAdapter, type A2AAdapterOptions, type A2ATaskResult, type AgentProfile, type ClientOptions, type Contact, ContactManager, type ConversationEntry, type ConversationListResponse, type DirectoryBrowseResponse, type FeedByDidResponse, type FeedPost, type FeedPublicResponse, type FetchResponse, HistoryManager, HttpTransport, LocalStore, PingAgentClient, type SendResponse, type StoredMessage, type SubscriptionResponse, type SubscriptionUsage, type TaskResult, type TransportOptions, WsSubscription, type WsSubscriptionOptions, ensureTokenValid, generateIdentity, getIdentityPath, getProfile, getRootDir, getStorePath, identityExists, loadIdentity, saveIdentity, updateStoredToken };

package/dist/index.js

@@ -0,0 +1,38 @@
+import {
+  A2AAdapter,
+  ContactManager,
+  HistoryManager,
+  HttpTransport,
+  LocalStore,
+  PingAgentClient,
+  WsSubscription,
+  ensureTokenValid,
+  generateIdentity,
+  getIdentityPath,
+  getProfile,
+  getRootDir,
+  getStorePath,
+  identityExists,
+  loadIdentity,
+  saveIdentity,
+  updateStoredToken
+} from "./chunk-4SRPVWK4.js";
+export {
+  A2AAdapter,
+  ContactManager,
+  HistoryManager,
+  HttpTransport,
+  LocalStore,
+  PingAgentClient,
+  WsSubscription,
+  ensureTokenValid,
+  generateIdentity,
+  getIdentityPath,
+  getProfile,
+  getRootDir,
+  getStorePath,
+  identityExists,
+  loadIdentity,
+  saveIdentity,
+  updateStoredToken
+};

package/dist/web-server.d.ts

@@ -0,0 +1,26 @@
+import * as http from 'node:http';
+
+/**
+ * PingAgent Web - Local debugging and audit UI.
+ * Serves a simple web app for viewing contacts, conversations, messages, and sending messages.
+ * Auth: CLI holds identity + token; browser only talks to localhost. No token in browser.
+ */
+
+interface ProfileEntry {
+    id: string;
+    did?: string;
+    identityPath: string;
+    storePath: string;
+}
+interface WebServerOptions {
+    /** Root dir to scan for profiles (e.g. ~/.pingagent). When set, user selects profile on page. */
+    rootDir?: string;
+    /** When set, use this identity only (no profile picker). Overrides rootDir. */
+    fixedIdentityPath?: string;
+    fixedStorePath?: string;
+    serverUrl: string;
+    port?: number;
+}
+declare function startWebServer(opts: WebServerOptions): Promise<http.Server>;
+
+export { type ProfileEntry, type WebServerOptions, startWebServer };