@elisym/sdk 0.25.1 → 0.25.4

package/dist/index.d.cts

@@ -227,6 +227,70 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         transports: unknown[];
         seedingExpiresAt?: number | undefined;
     }>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+        name: z.ZodString;
+        /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+        size: z.ZodNumber;
+        mime: z.ZodString;
+        /**
+         * Ordered by sender preference; at least one KNOWN transport. Parsed leniently: unknown
+         * transport `kind`s are dropped (not rejected) so adding a new transport never makes an older
+         * decoder throw away the whole envelope - it just ignores the kinds it doesn't know and uses
+         * the ones it does. At least one known transport must survive, else the attachment is invalid.
+         */
+        transports: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnknown, "many">, ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[], unknown[]>, ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[], unknown[]>;
+        /** Optional provider hint (unix seconds) for when seeding may stop. */
+        seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[];
+        seedingExpiresAt?: number | undefined;
+    }, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: unknown[];
+        seedingExpiresAt?: number | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     v: "elisym-job/1";
     text?: string | undefined;
@@ -249,6 +313,25 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         })[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
+    attachments?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[];
+        seedingExpiresAt?: number | undefined;
+    }[] | undefined;
 }, {
     v: "elisym-job/1";
     text?: string | undefined;
@@ -259,6 +342,13 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         transports: unknown[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
+    attachments?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: unknown[];
+        seedingExpiresAt?: number | undefined;
+    }[] | undefined;
 }>;
 type FileTransport = z.infer<typeof FileTransportSchema>;
 type FileAttachment = z.infer<typeof FileAttachmentSchema>;
@@ -279,11 +369,20 @@ declare function buildAcceptTransportsTag(kinds: TransportKind[]): string[];
  * so this never strands a job.
  */
 declare function readAcceptedTransports(tags: string[][]): TransportKind[] | undefined;
-/** Decoded job payload: a free-text note and/or a file attachment. */
+/** Decoded job payload: a free-text note and/or file attachment(s). */
 interface DecodedJobPayload {
     text?: string;
+    /** Legacy single attachment (also mirrors `attachments[0]`). */
     attachment?: FileAttachment;
+    /** All attachments when a job carries multiple files. */
+    attachments?: FileAttachment[];
 }
+/**
+ * Normalize a decoded payload to the full attachment list, treating the legacy
+ * single `attachment` as a 1-element list. Use this everywhere instead of reading
+ * `.attachment`/`.attachments` directly, so single- and multi-file are uniform.
+ */
+declare function attachmentsOf(decoded: DecodedJobPayload): FileAttachment[];
 /**
  * Serialize a job payload into the envelope string that goes (encrypted) into a
  * Nostr event's `content`. Used only when an attachment is present; plain-text
@@ -325,6 +424,13 @@ interface CapabilityCard {
     inputMime?: string;
     /** MIME of a file result the capability produces (from `output_mime`). */
     outputMime?: string;
+    /**
+     * Whether a file-input capability ALSO accepts a text prompt (from `input_text`):
+     * `'none'` = file only, `'optional'` = file + optional note, `'required'` = both.
+     * Discovery hint; the web app shows/hides its text box accordingly. Only meaningful
+     * with `inputMime`. Untrusted - gate on it, never render the raw value.
+     */
+    inputText?: 'required' | 'optional' | 'none';
 }
 /** Payment info embedded in capability card (legacy format for on-network events). */
 interface PaymentInfo {
@@ -457,11 +563,12 @@ interface JobUpdateCallbacks {
     onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
     /**
      * Fired on a job result. `content` is the result text (for a file result, the
-     * envelope's text note, or `''`); `attachment` is the file descriptor when the
-     * result carries a file. The file is fetched separately (P2P via iroh), never
-     * inlined here.
+     * envelope's text note, or `''`); `attachment` is the FIRST file descriptor
+     * (= `attachments[0]`, kept for back-compat); `attachments` is the full list for
+     * a multi-file result. Files are fetched separately (P2P via iroh / Blossom),
+     * never inlined here.
      */
-    onResult?: (content: string, eventId: string, attachment?: FileAttachment) => void;
+    onResult?: (content: string, eventId: string, attachment?: FileAttachment, attachments?: FileAttachment[]) => void;
     onError?: (error: string) => void;
     /**
      * Fired when the result wait window expires without a result - a distinct,
@@ -676,6 +783,15 @@ declare class BlossomService {
     private serverUrl;
     private fallback?;
     constructor(serverUrl?: string, fallback?: BlossomUploadFallback | undefined);
+    /**
+     * The content-addressed GET URL for a blob, derivable from its sha256 BEFORE
+     * upload (BUD-01: `<serverUrl>/<sha256>`, no extension for our octet-stream
+     * ciphertext uploads - same form `delete` addresses by). Lets a caller build a
+     * complete attachment descriptor and defer the actual byte upload (the descriptor
+     * is submitted first, the bytes PUT later). `upload()` re-verifies the server
+     * returns this exact url.
+     */
+    contentUrl(sha256: string): string;
     /**
      * Upload a file to the Blossom server, returning its descriptor. On any failure, falls
      * back to the configured uploader (if any) and returns a normalized descriptor with
@@ -685,13 +801,22 @@ declare class BlossomService {
     /** Delete a blob by sha256 (BUD-02). Blossom only - there is no fallback for deletes. */
     delete(identity: ElisymIdentity, sha256: string): Promise<void>;
     /**
-     * Download a public blob (BUD-01 GET, no auth). Bounds memory on the ACTUAL streamed bytes (never
-     * the declared Content-Length) and verifies the sha256 when `expectedSha256` is given. Browser-safe.
+     * Download a content-addressed blob from THIS Blossom server (BUD-01 GET, no auth). Bounds memory
+     * on the ACTUAL streamed bytes (never the declared Content-Length) and verifies the sha256 when
+     * `expectedSha256` is given. Browser-safe.
+     *
+     * SSRF guard: `url` typically arrives inside a remote counterparty's encrypted job envelope, so it
+     * is untrusted. elisym blobs are content-addressed on the single configured server (`seedBytes`
+     * refuses non-content-addressed fallbacks), so a legitimate URL is always `<serverUrl>/<sha256>`.
+     * The origin is pinned to `serverUrl` and redirects are refused, so a crafted url (or a 30x from
+     * the host) can't coerce a fetch to loopback, cloud-metadata, or internal addresses. Federation
+     * across Blossom servers would replace this single-origin pin with an explicit allowlist.
      */
     download(url: string, opts?: {
         maxBytes?: number;
         timeoutMs?: number;
         expectedSha256?: string;
+        signal?: AbortSignal;
     }): Promise<Uint8Array>;
     private uploadToBlossom;
     private authHeader;
@@ -895,14 +1020,14 @@ declare class MarketplaceService {
      */
     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, attachment?: FileAttachment): Promise<string>;
+    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, attachments?: FileAttachment[]): 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, attachment?: FileAttachment): Promise<string>;
+    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number, attachments?: FileAttachment[]): Promise<string>;
     /** Submit payment-required feedback with a payment request. */
     submitPaymentRequiredFeedback(identity: ElisymIdentity, requestEvent: Event, amount: number, paymentRequestJson: string): Promise<void>;
     /** Submit processing feedback to notify customer that work has started. */
@@ -1055,6 +1180,8 @@ interface BlossomBlobTransport {
         transport: BlossomTransport;
         senderPubkey: string;
         maxBytes?: number;
+        /** Abort the in-flight download (e.g. job stop() / input-fetch budget). */
+        signal?: AbortSignal;
     }): Promise<Uint8Array>;
 }
 declare function createBlossomTransport(opts: {
@@ -1063,17 +1190,29 @@ declare function createBlossomTransport(opts: {
 }): BlossomBlobTransport;
 
 /**
- * Customer-side helpers to send/receive ENCRYPTED file jobs over Blossom with no iroh/Node dependency
- * (browser-safe). These are the seams a web app calls.
+ * Encrypt `file` to `providerPubkey` and build a complete `FileAttachment` WITHOUT uploading the bytes
+ * yet. Because Blossom is content-addressed, the blob URL is derivable from the ciphertext sha256, so the
+ * caller can submit the job request with this descriptor and DEFER the byte upload (via the returned
+ * `upload()`) until the customer commits - e.g. after the provider quotes a price, so an unresponsive
+ * provider never costs a wasted upload. TARGETED jobs only (a recipient pubkey is required to encrypt).
  *
- * Encrypted-Blossom needs a recipient pubkey, so a file INPUT is only meaningful on a TARGETED job (a
- * chosen provider) - hence `buildEncryptedFileInput` requires `providerPubkey`. Broadcast file inputs
- * are not supported here (no recipient to encrypt to); those stay on iroh.
+ * `upload()` PUTs the ciphertext and verifies the server returns the precomputed url/sha256 (the request
+ * already carries them, so a mismatch must fail loudly - pre-commit - rather than 404 the provider).
  */
-
+declare function prepareEncryptedFileInput(args: {
+    file: Blob & {
+        name?: string;
+    };
+    providerPubkey: string;
+    identity: ElisymIdentity;
+    blossom: BlossomService;
+}): Promise<{
+    attachment: FileAttachment;
+    upload: () => Promise<void>;
+}>;
 /**
- * Encrypt `file` to `providerPubkey` and upload the ciphertext to Blossom, returning a `FileAttachment`
- * with a single `blossom` transport. TARGETED jobs only (a recipient pubkey is required to encrypt).
+ * Encrypt `file` to `providerPubkey` AND upload it immediately, returning the `FileAttachment`
+ * (prepare + upload in one step). Use `prepareEncryptedFileInput` when you want to defer the upload.
  */
 declare function buildEncryptedFileInput(args: {
     file: Blob & {
@@ -1725,6 +1864,7 @@ declare const DEFAULTS: {
     readonly QUERY_MAX_CONCURRENCY: 6;
     readonly VERIFY_SIGNATURE_LIMIT: 25;
     readonly IROH_FETCH_TIMEOUT_MS: 300000;
+    readonly IROH_SEED_TIMEOUT_MS: 120000;
     readonly BLOSSOM_UPLOAD_TIMEOUT_MS: 300000;
     readonly BLOSSOM_FETCH_TIMEOUT_MS: 300000;
 };
@@ -1756,4 +1896,4 @@ declare const LIMITS: {
  */
 declare function utf8ByteLength(value: string): number;
 
-export { ACCEPT_TRANSPORTS_TAG, type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, type BlobDescriptor, type BlossomBlobTransport, BlossomService, type BlossomUploadFallback, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EncryptedBytes, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type TransportKind, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildAcceptTransportsTag, buildEncryptedFileInput, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createBlossomTransport, createPaymentRequestWithOnchainConfig, decodeJobPayload, decryptBytesFromSender, encodeJobPayload, encryptBytesForRecipient, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, fetchEncryptedFileOutput, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, readAcceptedTransports, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };
+export { ACCEPT_TRANSPORTS_TAG, type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, type BlobDescriptor, type BlossomBlobTransport, BlossomService, type BlossomUploadFallback, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EncryptedBytes, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type TransportKind, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, attachmentsOf, buildAcceptTransportsTag, buildEncryptedFileInput, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createBlossomTransport, createPaymentRequestWithOnchainConfig, decodeJobPayload, decryptBytesFromSender, encodeJobPayload, encryptBytesForRecipient, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, fetchEncryptedFileOutput, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, prepareEncryptedFileInput, readAcceptedTransports, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };

package/dist/index.d.ts

@@ -227,6 +227,70 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         transports: unknown[];
         seedingExpiresAt?: number | undefined;
     }>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+        name: z.ZodString;
+        /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+        size: z.ZodNumber;
+        mime: z.ZodString;
+        /**
+         * Ordered by sender preference; at least one KNOWN transport. Parsed leniently: unknown
+         * transport `kind`s are dropped (not rejected) so adding a new transport never makes an older
+         * decoder throw away the whole envelope - it just ignores the kinds it doesn't know and uses
+         * the ones it does. At least one known transport must survive, else the attachment is invalid.
+         */
+        transports: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnknown, "many">, ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[], unknown[]>, ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[], unknown[]>;
+        /** Optional provider hint (unix seconds) for when seeding may stop. */
+        seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[];
+        seedingExpiresAt?: number | undefined;
+    }, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: unknown[];
+        seedingExpiresAt?: number | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     v: "elisym-job/1";
     text?: string | undefined;
@@ -249,6 +313,25 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         })[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
+    attachments?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: ({
+            kind: "iroh";
+            ticket: string;
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[];
+        seedingExpiresAt?: number | undefined;
+    }[] | undefined;
 }, {
     v: "elisym-job/1";
     text?: string | undefined;
@@ -259,6 +342,13 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         transports: unknown[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
+    attachments?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: unknown[];
+        seedingExpiresAt?: number | undefined;
+    }[] | undefined;
 }>;
 type FileTransport = z.infer<typeof FileTransportSchema>;
 type FileAttachment = z.infer<typeof FileAttachmentSchema>;
@@ -279,11 +369,20 @@ declare function buildAcceptTransportsTag(kinds: TransportKind[]): string[];
  * so this never strands a job.
  */
 declare function readAcceptedTransports(tags: string[][]): TransportKind[] | undefined;
-/** Decoded job payload: a free-text note and/or a file attachment. */
+/** Decoded job payload: a free-text note and/or file attachment(s). */
 interface DecodedJobPayload {
     text?: string;
+    /** Legacy single attachment (also mirrors `attachments[0]`). */
     attachment?: FileAttachment;
+    /** All attachments when a job carries multiple files. */
+    attachments?: FileAttachment[];
 }
+/**
+ * Normalize a decoded payload to the full attachment list, treating the legacy
+ * single `attachment` as a 1-element list. Use this everywhere instead of reading
+ * `.attachment`/`.attachments` directly, so single- and multi-file are uniform.
+ */
+declare function attachmentsOf(decoded: DecodedJobPayload): FileAttachment[];
 /**
  * Serialize a job payload into the envelope string that goes (encrypted) into a
  * Nostr event's `content`. Used only when an attachment is present; plain-text
@@ -325,6 +424,13 @@ interface CapabilityCard {
     inputMime?: string;
     /** MIME of a file result the capability produces (from `output_mime`). */
     outputMime?: string;
+    /**
+     * Whether a file-input capability ALSO accepts a text prompt (from `input_text`):
+     * `'none'` = file only, `'optional'` = file + optional note, `'required'` = both.
+     * Discovery hint; the web app shows/hides its text box accordingly. Only meaningful
+     * with `inputMime`. Untrusted - gate on it, never render the raw value.
+     */
+    inputText?: 'required' | 'optional' | 'none';
 }
 /** Payment info embedded in capability card (legacy format for on-network events). */
 interface PaymentInfo {
@@ -457,11 +563,12 @@ interface JobUpdateCallbacks {
     onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
     /**
      * Fired on a job result. `content` is the result text (for a file result, the
-     * envelope's text note, or `''`); `attachment` is the file descriptor when the
-     * result carries a file. The file is fetched separately (P2P via iroh), never
-     * inlined here.
+     * envelope's text note, or `''`); `attachment` is the FIRST file descriptor
+     * (= `attachments[0]`, kept for back-compat); `attachments` is the full list for
+     * a multi-file result. Files are fetched separately (P2P via iroh / Blossom),
+     * never inlined here.
      */
-    onResult?: (content: string, eventId: string, attachment?: FileAttachment) => void;
+    onResult?: (content: string, eventId: string, attachment?: FileAttachment, attachments?: FileAttachment[]) => void;
     onError?: (error: string) => void;
     /**
      * Fired when the result wait window expires without a result - a distinct,
@@ -676,6 +783,15 @@ declare class BlossomService {
     private serverUrl;
     private fallback?;
     constructor(serverUrl?: string, fallback?: BlossomUploadFallback | undefined);
+    /**
+     * The content-addressed GET URL for a blob, derivable from its sha256 BEFORE
+     * upload (BUD-01: `<serverUrl>/<sha256>`, no extension for our octet-stream
+     * ciphertext uploads - same form `delete` addresses by). Lets a caller build a
+     * complete attachment descriptor and defer the actual byte upload (the descriptor
+     * is submitted first, the bytes PUT later). `upload()` re-verifies the server
+     * returns this exact url.
+     */
+    contentUrl(sha256: string): string;
     /**
      * Upload a file to the Blossom server, returning its descriptor. On any failure, falls
      * back to the configured uploader (if any) and returns a normalized descriptor with
@@ -685,13 +801,22 @@ declare class BlossomService {
     /** Delete a blob by sha256 (BUD-02). Blossom only - there is no fallback for deletes. */
     delete(identity: ElisymIdentity, sha256: string): Promise<void>;
     /**
-     * Download a public blob (BUD-01 GET, no auth). Bounds memory on the ACTUAL streamed bytes (never
-     * the declared Content-Length) and verifies the sha256 when `expectedSha256` is given. Browser-safe.
+     * Download a content-addressed blob from THIS Blossom server (BUD-01 GET, no auth). Bounds memory
+     * on the ACTUAL streamed bytes (never the declared Content-Length) and verifies the sha256 when
+     * `expectedSha256` is given. Browser-safe.
+     *
+     * SSRF guard: `url` typically arrives inside a remote counterparty's encrypted job envelope, so it
+     * is untrusted. elisym blobs are content-addressed on the single configured server (`seedBytes`
+     * refuses non-content-addressed fallbacks), so a legitimate URL is always `<serverUrl>/<sha256>`.
+     * The origin is pinned to `serverUrl` and redirects are refused, so a crafted url (or a 30x from
+     * the host) can't coerce a fetch to loopback, cloud-metadata, or internal addresses. Federation
+     * across Blossom servers would replace this single-origin pin with an explicit allowlist.
      */
     download(url: string, opts?: {
         maxBytes?: number;
         timeoutMs?: number;
         expectedSha256?: string;
+        signal?: AbortSignal;
     }): Promise<Uint8Array>;
     private uploadToBlossom;
     private authHeader;
@@ -895,14 +1020,14 @@ declare class MarketplaceService {
      */
     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, attachment?: FileAttachment): Promise<string>;
+    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, attachments?: FileAttachment[]): 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, attachment?: FileAttachment): Promise<string>;
+    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number, attachments?: FileAttachment[]): Promise<string>;
     /** Submit payment-required feedback with a payment request. */
     submitPaymentRequiredFeedback(identity: ElisymIdentity, requestEvent: Event, amount: number, paymentRequestJson: string): Promise<void>;
     /** Submit processing feedback to notify customer that work has started. */
@@ -1055,6 +1180,8 @@ interface BlossomBlobTransport {
         transport: BlossomTransport;
         senderPubkey: string;
         maxBytes?: number;
+        /** Abort the in-flight download (e.g. job stop() / input-fetch budget). */
+        signal?: AbortSignal;
     }): Promise<Uint8Array>;
 }
 declare function createBlossomTransport(opts: {
@@ -1063,17 +1190,29 @@ declare function createBlossomTransport(opts: {
 }): BlossomBlobTransport;
 
 /**
- * Customer-side helpers to send/receive ENCRYPTED file jobs over Blossom with no iroh/Node dependency
- * (browser-safe). These are the seams a web app calls.
+ * Encrypt `file` to `providerPubkey` and build a complete `FileAttachment` WITHOUT uploading the bytes
+ * yet. Because Blossom is content-addressed, the blob URL is derivable from the ciphertext sha256, so the
+ * caller can submit the job request with this descriptor and DEFER the byte upload (via the returned
+ * `upload()`) until the customer commits - e.g. after the provider quotes a price, so an unresponsive
+ * provider never costs a wasted upload. TARGETED jobs only (a recipient pubkey is required to encrypt).
  *
- * Encrypted-Blossom needs a recipient pubkey, so a file INPUT is only meaningful on a TARGETED job (a
- * chosen provider) - hence `buildEncryptedFileInput` requires `providerPubkey`. Broadcast file inputs
- * are not supported here (no recipient to encrypt to); those stay on iroh.
+ * `upload()` PUTs the ciphertext and verifies the server returns the precomputed url/sha256 (the request
+ * already carries them, so a mismatch must fail loudly - pre-commit - rather than 404 the provider).
  */
-
+declare function prepareEncryptedFileInput(args: {
+    file: Blob & {
+        name?: string;
+    };
+    providerPubkey: string;
+    identity: ElisymIdentity;
+    blossom: BlossomService;
+}): Promise<{
+    attachment: FileAttachment;
+    upload: () => Promise<void>;
+}>;
 /**
- * Encrypt `file` to `providerPubkey` and upload the ciphertext to Blossom, returning a `FileAttachment`
- * with a single `blossom` transport. TARGETED jobs only (a recipient pubkey is required to encrypt).
+ * Encrypt `file` to `providerPubkey` AND upload it immediately, returning the `FileAttachment`
+ * (prepare + upload in one step). Use `prepareEncryptedFileInput` when you want to defer the upload.
  */
 declare function buildEncryptedFileInput(args: {
     file: Blob & {
@@ -1725,6 +1864,7 @@ declare const DEFAULTS: {
     readonly QUERY_MAX_CONCURRENCY: 6;
     readonly VERIFY_SIGNATURE_LIMIT: 25;
     readonly IROH_FETCH_TIMEOUT_MS: 300000;
+    readonly IROH_SEED_TIMEOUT_MS: 120000;
     readonly BLOSSOM_UPLOAD_TIMEOUT_MS: 300000;
     readonly BLOSSOM_FETCH_TIMEOUT_MS: 300000;
 };
@@ -1756,4 +1896,4 @@ declare const LIMITS: {
  */
 declare function utf8ByteLength(value: string): number;
 
-export { ACCEPT_TRANSPORTS_TAG, type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, type BlobDescriptor, type BlossomBlobTransport, BlossomService, type BlossomUploadFallback, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EncryptedBytes, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type TransportKind, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildAcceptTransportsTag, buildEncryptedFileInput, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createBlossomTransport, createPaymentRequestWithOnchainConfig, decodeJobPayload, decryptBytesFromSender, encodeJobPayload, encryptBytesForRecipient, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, fetchEncryptedFileOutput, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, readAcceptedTransports, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };
+export { ACCEPT_TRANSPORTS_TAG, type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, type BlobDescriptor, type BlossomBlobTransport, BlossomService, type BlossomUploadFallback, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EncryptedBytes, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type TransportKind, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, attachmentsOf, buildAcceptTransportsTag, buildEncryptedFileInput, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createBlossomTransport, createPaymentRequestWithOnchainConfig, decodeJobPayload, decryptBytesFromSender, encodeJobPayload, encryptBytesForRecipient, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, fetchEncryptedFileOutput, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, prepareEncryptedFileInput, readAcceptedTransports, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };