@elisym/sdk 0.1.3 → 0.2.0

package/dist/index.d.cts

@@ -1,16 +1,45 @@
+import { P as PaymentRequestData, a as PaymentValidationError, V as VerifyOptions, b as VerifyResult, S as SubCloser, N as Network, A as Agent, E as ElisymIdentity, C as CapabilityCard, c as SubmitJobOptions, J as JobSubscriptionOptions, d as Job, e as PingResult, f as ElisymClientConfig, g as AgentConfig } from './types-CII4k_8d.cjs';
+export { h as Capability, I as Identity, i as JobStatus, j as JobUpdateCallbacks, L as LlmConfig, k as NetworkStats, l as PaymentAddress, m as PaymentInfo, n as PaymentValidationCode, W as WalletConfig } from './types-CII4k_8d.cjs';
 import { Filter, Event } from 'nostr-tools';
-import { PublicKey, Transaction } from '@solana/web3.js';
+import { Transaction } from '@solana/web3.js';
+
+/**
+ * Pluggable payment strategy interface.
+ * Implement this for each payment chain (Solana, Lightning, Cashu, EVM).
+ */
+interface PaymentStrategy {
+    readonly chain: string;
+    /** Calculate protocol fee using basis-point math. */
+    calculateFee(amount: number): number;
+    /** Create a payment request with auto-calculated protocol fee. */
+    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+    /**
+     * Validate that a payment request has the correct recipient and protocol fee.
+     * Returns a typed validation error if invalid, null if OK.
+     */
+    validatePaymentRequest(requestJson: string, expectedRecipient?: string): PaymentValidationError | null;
+    /**
+     * Build an unsigned transaction from a payment request.
+     * Returns chain-specific transaction type. The caller is responsible for signing and sending.
+     * @example For Solana: `const tx = await strategy.buildTransaction(...) as Transaction;`
+     */
+    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<unknown>;
+    /**
+     * Verify a payment on-chain.
+     * @param connection Chain-specific connection (e.g. Solana `Connection`).
+     */
+    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+}
 
-type SubCloser = {
-    close: (reason?: string) => void;
-};
 declare class NostrPool {
     private pool;
     private relays;
+    private activeSubscriptions;
     constructor(relays?: string[]);
+    /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
     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[]>;
+    queryBatched(filter: Omit<Filter, 'authors'>, keys: string[], batchSize?: number, maxConcurrency?: number): Promise<Event[]>;
+    queryBatchedByTag(filter: Filter, tagName: string, values: string[], batchSize?: number, maxConcurrency?: 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>;
@@ -20,11 +49,15 @@ declare class NostrPool {
      * is active (EOSE). Resolves on the first relay that responds.
      * Essential for ephemeral events where the subscription must be live
      * before publishing.
+     *
+     * Note: resolves on timeout even if no relay sent EOSE. The caller
+     * cannot distinguish timeout from success - this is intentional for
+     * best-effort ephemeral event delivery.
      */
     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
+     * Works around nostr-tools `onerror - skipReconnection = true` bug
      * that permanently kills subscriptions. Callers must re-subscribe.
      */
     reset(): void;
@@ -36,95 +69,20 @@ declare class NostrPool {
     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. */
+/** Convert a capability name to its Nostr d-tag form (ASCII-only, lowercase, hyphen-separated). */
 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).
+     *
+     * Unlike `fetchAgents`, this method does NOT enrich agents with
+     * kind:0 metadata (name, picture, about) or update `lastSeen` from
+     * recent job activity. Call `enrichWithMetadata()` separately if needed.
      */
     fetchAgentsPage(network?: Network, limit?: number, until?: number): Promise<{
         agents: Agent[];
@@ -135,10 +93,14 @@ declare class DiscoveryService {
     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. */
+    /**
+     * Publish a capability card (kind:31990) as a provider.
+     * Solana address is validated for Base58 format only - full decode
+     * validation (32-byte public key) happens at payment time.
+     */
     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>;
+    publishProfile(identity: ElisymIdentity, name: string, about: string, picture?: string, banner?: string): Promise<string>;
     /**
      * Delete a capability by publishing a tombstone replacement.
      * Since kind:31990 is a parameterized replaceable event,
@@ -148,18 +110,6 @@ declare class DiscoveryService {
     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);
@@ -167,22 +117,48 @@ declare class MarketplaceService {
     submitJobRequest(identity: ElisymIdentity, options: SubmitJobOptions): Promise<string>;
     /**
      * Subscribe to job updates (feedback + results) for a given job.
-     * Returns a cleanup function.
+     * Creates 3 subscriptions per call (feedback, result by #e, result by #p+#e)
+     * to cover different relay indexing strategies. 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;
+    subscribeToJobUpdates(options: JobSubscriptionOptions): () => 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. */
+    /**
+     * Subscribe to incoming job requests for specific kinds.
+     * Automatically decrypts NIP-44 encrypted content.
+     * Note: decrypted events have modified `content` - do not call `verifyEvent()` on them.
+     * Signature verification is performed before decryption.
+     */
     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 a job result with retry and exponential backoff.
+     * Retries on publish failures (e.g. relay disconnects).
+     * With maxAttempts=3: try, ~1s, try, ~2s, try, throw.
+     * Jitter: 0.5x-1.0x of calculated delay.
+     */
+    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: 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. */
+    /** Submit processing feedback to notify customer that work has started. */
+    submitProcessingFeedback(identity: ElisymIdentity, requestEvent: Event): Promise<void>;
+    /** Submit error feedback to notify customer of a failure. */
+    submitErrorFeedback(identity: ElisymIdentity, requestEvent: Event, message: string): Promise<void>;
+    /** Query job results by request IDs and decrypt NIP-44 content. */
+    queryJobResults(identity: ElisymIdentity, requestIds: string[], kindOffsets?: number[], providerPubkey?: string): Promise<Map<string, {
+        content: string;
+        amount?: number;
+        senderPubkey: string;
+        decryptionFailed: boolean;
+    }>>;
+    /**
+     * Fetch recent jobs from the network.
+     * NOTE: Job.result contains raw event content. For encrypted jobs,
+     * this will be NIP-44 ciphertext - use queryJobResults() for decryption.
+     */
     fetchRecentJobs(agentPubkeys?: Set<string>, limit?: number, since?: number, 
     /** Kind offsets to query (default [100]). */
     kindOffsets?: number[]): Promise<Job[]>;
@@ -190,12 +166,36 @@ declare class MarketplaceService {
     subscribeToEvents(kinds: number[], onEvent: (event: Event) => void): SubCloser;
 }
 
+declare class MediaService {
+    private uploadUrl;
+    constructor(uploadUrl?: string);
+    /**
+     * Upload a file with NIP-98 authentication.
+     * Works with browser File objects and Node.js/Bun Blobs.
+     *
+     * @param identity - Nostr identity used to sign the NIP-98 auth event.
+     * @param file - File or Blob to upload.
+     * @param filename - Optional filename for the upload (defaults to "upload").
+     * @returns URL of the uploaded file.
+     */
+    upload(identity: ElisymIdentity, file: Blob, filename?: string): Promise<string>;
+}
+
+/**
+ * Ping/pong and NIP-17 DM service.
+ *
+ * Uses a session identity (random keypair) for ping operations to avoid
+ * relay rate-limiting. The session identity persists for the lifetime of
+ * this instance - recreating the service generates a new keypair.
+ *
+ * Requires `globalThis.crypto` (Node 20+, Bun, browsers).
+ */
 declare class MessagingService {
     private pool;
+    private static readonly PING_CACHE_MAX;
     private sessionIdentity;
     private pingCache;
     private pendingPings;
-    private static PING_CACHE_TTL;
     constructor(pool: NostrPool);
     /**
      * Ping an agent via ephemeral Nostr events (kind 20200/20201).
@@ -203,7 +203,8 @@ declare class MessagingService {
      * 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>;
+    pingAgent(agentPubkey: string, timeoutMs?: number, signal?: AbortSignal, retries?: number): Promise<PingResult>;
+    private _doPingWithRetry;
     private _doPing;
     /**
      * Subscribe to incoming ephemeral ping events (kind 20200).
@@ -225,34 +226,81 @@ declare class MessagingService {
     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;
+interface ElisymClientFullConfig extends ElisymClientConfig {
+    payment?: PaymentStrategy;
+    /** Custom upload URL for file uploads (defaults to nostr.build). */
+    uploadUrl?: string;
+}
+declare class ElisymClient {
+    readonly pool: NostrPool;
+    readonly discovery: DiscoveryService;
+    readonly marketplace: MarketplaceService;
+    readonly messaging: MessagingService;
+    readonly media: MediaService;
+    readonly payment: PaymentStrategy;
+    constructor(config?: ElisymClientFullConfig);
+    close(): void;
+}
+
+declare class SolanaPaymentStrategy implements PaymentStrategy {
+    readonly chain = "solana";
+    calculateFee(amount: number): number;
+    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+    validatePaymentRequest(requestJson: string, expectedRecipient?: string): PaymentValidationError | null;
     /**
-     * Create a payment request with auto-calculated protocol fee.
-     * Used by providers to generate payment requests for customers.
+     * Build an unsigned transaction from a payment request.
+     * The caller must set `recentBlockhash` and `feePayer` on the
+     * returned Transaction before signing and sending.
      */
-    static createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<Transaction>;
+    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+    private _verifyBySignature;
+    private _verifyByReference;
 }
 
+/** Assert that a value is a non-negative integer (lamports). */
+declare function assertLamports(value: number, field: string): void;
+/**
+ * Calculate protocol fee using Decimal basis-point math (no floats).
+ * Returns ceil(amount * PROTOCOL_FEE_BPS / 10000).
+ * Safe for amounts up to Number.MAX_SAFE_INTEGER - Decimal handles intermediate values.
+ */
+declare function calculateProtocolFee(amount: number): number;
+/** Validate payment request timestamps. Returns error message or null if valid. */
+declare function validateExpiry(createdAt: number, expirySecs: number): string | null;
+/** Assert that payment request timestamps are valid and not expired. Throws on failure. */
+declare function assertExpiry(createdAt: number, expirySecs: number): void;
+
+/** Encrypt plaintext using NIP-44 v2 (sender secret key + recipient public key). */
+declare function nip44Encrypt(plaintext: string, senderSk: Uint8Array, recipientPubkey: string): string;
+/** Decrypt ciphertext using NIP-44 v2 (receiver secret key + sender public key). */
+declare function nip44Decrypt(ciphertext: string, receiverSk: Uint8Array, senderPubkey: string): string;
+
 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;
+/**
+ * Shared agent config - validation and serialization.
+ * Browser-safe - no Node.js imports.
+ * parseConfig lives in config-node.ts (exported from @elisym/sdk/node).
+ */
+
+declare function validateAgentName(name: string): void;
+/** Serialize an AgentConfig to JSON string. */
+declare function serializeConfig(config: AgentConfig): string;
+
+/** A Set that evicts the oldest entries when it exceeds maxSize. Uses a ring buffer for O(1) eviction. */
+declare class BoundedSet<T> {
+    private maxSize;
+    private items;
+    private set;
+    private head;
+    private count;
+    constructor(maxSize: number);
+    has(item: T): boolean;
+    add(item: T): void;
+}
 
 declare const RELAYS: string[];
 declare const KIND_APP_HANDLER = 31990;
@@ -277,14 +325,34 @@ declare const LAMPORTS_PER_SOL = 1000000000;
 declare const PROTOCOL_FEE_BPS = 300;
 /** Solana address of the protocol treasury. */
 declare const PROTOCOL_TREASURY = "GY7vnWMkKpftU4nQ16C2ATkj1JwrQpHhknkaBUn67VTy";
+/** Default values for timeouts, retries, and batch sizes. */
+declare const DEFAULTS: {
+    readonly SUBSCRIPTION_TIMEOUT_MS: 120000;
+    readonly PING_TIMEOUT_MS: 15000;
+    readonly PING_RETRIES: 2;
+    readonly PING_CACHE_TTL_MS: 30000;
+    readonly PAYMENT_EXPIRY_SECS: 600;
+    readonly BATCH_SIZE: 250;
+    readonly QUERY_TIMEOUT_MS: 15000;
+    readonly EOSE_TIMEOUT_MS: 3000;
+    readonly VERIFY_RETRIES: 10;
+    readonly VERIFY_INTERVAL_MS: 3000;
+    readonly VERIFY_BY_REF_RETRIES: 15;
+    readonly VERIFY_BY_REF_INTERVAL_MS: 2000;
+    readonly RESULT_RETRY_COUNT: 3;
+    readonly RESULT_RETRY_BASE_MS: 1000;
+    readonly QUERY_MAX_CONCURRENCY: 6;
+    readonly VERIFY_SIGNATURE_LIMIT: 25;
+};
+/** Protocol limits for input validation. */
+declare const LIMITS: {
+    readonly MAX_INPUT_LENGTH: 100000;
+    readonly MAX_TIMEOUT_SECS: 600;
+    readonly MAX_CAPABILITIES: 20;
+    readonly MAX_DESCRIPTION_LENGTH: 500;
+    readonly MAX_AGENT_NAME_LENGTH: 64;
+    readonly MAX_MESSAGE_LENGTH: 10000;
+    readonly MAX_CAPABILITY_LENGTH: 64;
+};
 
-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 };
+export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, Job, JobSubscriptionOptions, 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, LIMITS, MarketplaceService, MediaService, MessagingService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, calculateProtocolFee, formatSol, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };