@elisym/sdk 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,290 @@
+import { Filter, Event } from 'nostr-tools';
+import { PublicKey, Transaction } from '@solana/web3.js';
+
+type SubCloser = {
+    close: (reason?: string) => void;
+};
+declare class NostrPool {
+    private pool;
+    private relays;
+    constructor(relays?: string[]);
+    querySync(filter: Filter): Promise<Event[]>;
+    queryBatched(filter: Omit<Filter, "authors">, keys: string[], batchSize?: number): Promise<Event[]>;
+    queryBatchedByTag(filter: Filter, tagName: string, values: string[], batchSize?: number): Promise<Event[]>;
+    publish(event: Event): Promise<void>;
+    /** Publish to all relays and wait for all to settle. Throws if none accepted. */
+    publishAll(event: Event): Promise<void>;
+    subscribe(filter: Filter, onEvent: (event: Event) => void): SubCloser;
+    /**
+     * Subscribe and wait until at least one relay confirms the subscription
+     * is active (EOSE). Resolves on the first relay that responds.
+     * Essential for ephemeral events where the subscription must be live
+     * before publishing.
+     */
+    subscribeAndWait(filter: Filter, onEvent: (event: Event) => void, timeoutMs?: number): Promise<SubCloser>;
+    /**
+     * Tear down pool and create a fresh one.
+     * Works around nostr-tools `onerror → skipReconnection = true` bug
+     * that permanently kills subscriptions. Callers must re-subscribe.
+     */
+    reset(): void;
+    /**
+     * Lightweight connectivity probe. Returns true if at least one relay responds.
+     */
+    probe(timeoutMs?: number): Promise<boolean>;
+    getRelays(): string[];
+    close(): void;
+}
+
+declare class ElisymIdentity {
+    readonly secretKey: Uint8Array;
+    readonly publicKey: string;
+    readonly npub: string;
+    private constructor();
+    static generate(): ElisymIdentity;
+    static fromSecretKey(sk: Uint8Array): ElisymIdentity;
+    static fromHex(hex: string): ElisymIdentity;
+}
+
+interface PaymentInfo {
+    chain: string;
+    network: string;
+    address: string;
+    job_price?: number;
+}
+interface CapabilityCard {
+    name: string;
+    description: string;
+    capabilities: string[];
+    payment?: PaymentInfo;
+    image?: string;
+    static?: boolean;
+}
+interface Agent {
+    pubkey: string;
+    npub: string;
+    cards: CapabilityCard[];
+    eventId: string;
+    supportedKinds: number[];
+    lastSeen: number;
+    picture?: string;
+    name?: string;
+    about?: string;
+}
+type JobStatus = "payment-required" | "payment-completed" | "processing" | "error" | "success" | "partial";
+interface Job {
+    eventId: string;
+    customer: string;
+    agentPubkey?: string;
+    capability?: string;
+    bid?: number;
+    status: JobStatus | string;
+    result?: string;
+    resultEventId?: string;
+    amount?: number;
+    txHash?: string;
+    createdAt: number;
+}
+interface NetworkStats {
+    totalAgentCount: number;
+    agentCount: number;
+    jobCount: number;
+    totalLamports: number;
+}
+type Network = "mainnet" | "devnet";
+interface PingResult {
+    online: boolean;
+    /** The identity used for the ping session — reuse for job submission so pubkeys match. */
+    identity: ElisymIdentity | null;
+}
+interface PaymentRequestData {
+    recipient: string;
+    amount: number;
+    reference: string;
+    description?: string;
+    fee_address?: string;
+    fee_amount?: number;
+    /** Creation timestamp (Unix seconds). */
+    created_at: number;
+    /** Expiry duration in seconds. */
+    expiry_secs: number;
+}
+interface ElisymClientConfig {
+    relays?: string[];
+}
+
+/** Convert a capability name to its Nostr d-tag form. */
+declare function toDTag(name: string): string;
+declare class DiscoveryService {
+    private pool;
+    private allSeenAgents;
+    constructor(pool: NostrPool);
+    /** Count elisym agents (kind:31990 with "elisym" tag). */
+    fetchAllAgentCount(): Promise<number>;
+    /**
+     * Fetch a single page of elisym agents with relay-side pagination.
+     * Uses `until` cursor for Nostr cursor-based pagination.
+     * Does NOT fetch activity (faster than fetchAgents).
+     */
+    fetchAgentsPage(network?: Network, limit?: number, until?: number): Promise<{
+        agents: Agent[];
+        oldestCreatedAt: number | null;
+        rawEventCount: number;
+    }>;
+    /** Enrich agents with kind:0 metadata (name, picture, about). Mutates in place and returns the same array. */
+    enrichWithMetadata(agents: Agent[]): Promise<Agent[]>;
+    /** Fetch elisym agents filtered by network. */
+    fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
+    /** Publish a capability card (kind:31990) as a provider. */
+    publishCapability(identity: ElisymIdentity, card: CapabilityCard, kinds?: number[]): Promise<string>;
+    /** Publish a Nostr profile (kind:0) as a provider. */
+    publishProfile(identity: ElisymIdentity, name: string, about: string, picture?: string): Promise<string>;
+    /**
+     * Delete a capability by publishing a tombstone replacement.
+     * Since kind:31990 is a parameterized replaceable event,
+     * publishing a new event with the same `d` tag and `"deleted":true`
+     * content replaces the old one on all relays.
+     */
+    deleteCapability(identity: ElisymIdentity, capabilityName: string): Promise<string>;
+}
+
+interface SubmitJobOptions {
+    input: string;
+    capability: string;
+    providerPubkey?: string;
+    /** Kind offset (default 100 → kind 5100). */
+    kindOffset?: number;
+}
+interface JobUpdateCallbacks {
+    onFeedback?: (status: string, amount?: number, paymentRequest?: string) => void;
+    onResult?: (content: string, eventId: string) => void;
+    onError?: (error: string) => void;
+}
+declare class MarketplaceService {
+    private pool;
+    constructor(pool: NostrPool);
+    /** Submit a job request with NIP-44 encrypted input. Returns the event ID. */
+    submitJobRequest(identity: ElisymIdentity, options: SubmitJobOptions): Promise<string>;
+    /**
+     * Subscribe to job updates (feedback + results) for a given job.
+     * Returns a cleanup function.
+     */
+    subscribeToJobUpdates(jobEventId: string, providerPubkey: string | undefined, customerPublicKey: string, callbacks: JobUpdateCallbacks, timeoutMs?: number, customerSecretKey?: Uint8Array, 
+    /** Kind offsets to listen for (default [100]). */
+    kindOffsets?: number[]): () => void;
+    /** Submit payment confirmation feedback. */
+    submitPaymentConfirmation(identity: ElisymIdentity, jobEventId: string, providerPubkey: string, txSignature: string): Promise<void>;
+    /** Submit rating feedback for a job. */
+    submitFeedback(identity: ElisymIdentity, jobEventId: string, providerPubkey: string, positive: boolean, capability?: string): Promise<void>;
+    /** Subscribe to incoming job requests for specific kinds. */
+    subscribeToJobRequests(identity: ElisymIdentity, kinds: number[], onRequest: (event: Event) => void): SubCloser;
+    /** Submit a job result with NIP-44 encrypted content. Result kind is derived from the request kind. */
+    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number): Promise<string>;
+    /** Submit payment-required feedback with a payment request. */
+    submitPaymentRequiredFeedback(identity: ElisymIdentity, requestEvent: Event, amount: number, paymentRequestJson: string): Promise<void>;
+    /** Fetch recent jobs from the network. */
+    fetchRecentJobs(agentPubkeys?: Set<string>, limit?: number, since?: number, 
+    /** Kind offsets to query (default [100]). */
+    kindOffsets?: number[]): Promise<Job[]>;
+    /** Subscribe to live elisym events (requests, results, feedback). */
+    subscribeToEvents(kinds: number[], onEvent: (event: Event) => void): SubCloser;
+}
+
+declare class MessagingService {
+    private pool;
+    private sessionIdentity;
+    private pingCache;
+    private pendingPings;
+    private static PING_CACHE_TTL;
+    constructor(pool: NostrPool);
+    /**
+     * Ping an agent via ephemeral Nostr events (kind 20200/20201).
+     * Uses a persistent session identity to avoid relay rate-limiting.
+     * Publishes to ALL relays for maximum delivery reliability.
+     * Caches results for 30s to prevent redundant publishes.
+     */
+    pingAgent(agentPubkey: string, timeoutMs?: number, signal?: AbortSignal): Promise<PingResult>;
+    private _doPing;
+    /**
+     * Subscribe to incoming ephemeral ping events (kind 20200).
+     * No `since` filter needed - ephemeral events are never stored.
+     */
+    subscribeToPings(identity: ElisymIdentity, onPing: (senderPubkey: string, nonce: string) => void): SubCloser;
+    /** Send an ephemeral pong response to ALL relays. */
+    sendPong(identity: ElisymIdentity, recipientPubkey: string, nonce: string): Promise<void>;
+    /** Send a NIP-17 DM. */
+    sendMessage(identity: ElisymIdentity, recipientPubkey: string, content: string): Promise<void>;
+    /** Fetch historical NIP-17 DMs from relays. Returns decrypted messages sorted by time. */
+    fetchMessageHistory(identity: ElisymIdentity, since: number): Promise<{
+        senderPubkey: string;
+        content: string;
+        createdAt: number;
+        rumorId: string;
+    }[]>;
+    /** Subscribe to incoming NIP-17 DMs. */
+    subscribeToMessages(identity: ElisymIdentity, onMessage: (senderPubkey: string, content: string, createdAt: number, rumorId: string) => void, since?: number): SubCloser;
+}
+
+declare class PaymentService {
+    /**
+     * Calculate protocol fee using Decimal basis-point math (no floats).
+     * Returns ceil(amount * PROTOCOL_FEE_BPS / 10000).
+     */
+    static calculateProtocolFee(amount: number): number;
+    /**
+     * Validate that a payment request has the correct recipient and protocol fee.
+     * Returns an error message if invalid, null if OK.
+     */
+    static validatePaymentFee(requestJson: string, expectedRecipient?: string): string | null;
+    /**
+     * Build a Solana transaction from a payment request.
+     * The caller must sign and send via wallet adapter.
+     */
+    static buildPaymentTransaction(payerPubkey: PublicKey, paymentRequest: PaymentRequestData): Transaction;
+    /**
+     * Create a payment request with auto-calculated protocol fee.
+     * Used by providers to generate payment requests for customers.
+     */
+    static createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+}
+
+declare function formatSol(lamports: number): string;
+declare function timeAgo(unix: number): string;
+declare function truncateKey(hex: string, chars?: number): string;
+
+declare function makeNjumpUrl(eventId: string, relays?: string[]): string;
+
+declare const RELAYS: string[];
+declare const KIND_APP_HANDLER = 31990;
+declare const KIND_JOB_REQUEST_BASE = 5000;
+declare const KIND_JOB_RESULT_BASE = 6000;
+declare const KIND_JOB_FEEDBACK = 7000;
+declare const DEFAULT_KIND_OFFSET = 100;
+declare const KIND_GIFT_WRAP = 1059;
+/** Default job request kind (5000 + 100). */
+declare const KIND_JOB_REQUEST: number;
+/** Default job result kind (6000 + 100). */
+declare const KIND_JOB_RESULT: number;
+/** Compute a job request kind from an offset (5000 + offset). */
+declare function jobRequestKind(offset: number): number;
+/** Compute a job result kind from an offset (6000 + offset). */
+declare function jobResultKind(offset: number): number;
+/** Ephemeral ping/pong kinds (not stored by relays, forwarded in real-time). */
+declare const KIND_PING = 20200;
+declare const KIND_PONG = 20201;
+declare const LAMPORTS_PER_SOL = 1000000000;
+/** Protocol fee in basis points (300 = 3%). */
+declare const PROTOCOL_FEE_BPS = 300;
+/** Solana address of the protocol treasury. */
+declare const PROTOCOL_TREASURY = "GY7vnWMkKpftU4nQ16C2ATkj1JwrQpHhknkaBUn67VTy";
+
+declare class ElisymClient {
+    readonly pool: NostrPool;
+    readonly discovery: DiscoveryService;
+    readonly marketplace: MarketplaceService;
+    readonly messaging: MessagingService;
+    constructor(config?: ElisymClientConfig);
+    close(): void;
+}
+
+export { type Agent, type CapabilityCard, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, ElisymIdentity, type Job, type JobStatus, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_GIFT_WRAP, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, MarketplaceService, MessagingService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_TREASURY, type PaymentInfo, type PaymentRequestData, PaymentService, type PingResult, RELAYS, type SubCloser, type SubmitJobOptions, formatSol, jobRequestKind, jobResultKind, makeNjumpUrl, timeAgo, toDTag, truncateKey };