@elisym/sdk 0.24.1 → 0.25.1

package/dist/index.d.ts

@@ -50,6 +50,51 @@ declare const FileTransportSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<
 }, {
     kind: "iroh";
     ticket: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"blossom">;
+    /** Public HTTP(S) URL of the CIPHERTEXT blob on a Blossom relay. */
+    url: z.ZodString;
+    /** sha256 (lowercase hex) of the ciphertext - what the relay stores and addresses. */
+    sha256: z.ZodString;
+    /**
+     * Hybrid-encryption parameters. The file bytes are AES-256-GCM encrypted with a random
+     * content key; that key is NIP-44-wrapped to the recipient. `name`/`mime`/`size` on the
+     * attachment describe the PLAINTEXT and live only inside the (encrypted) envelope - never
+     * sent to the relay (the relay only ever sees opaque ciphertext).
+     */
+    enc: z.ZodObject<{
+        alg: z.ZodLiteral<"AES-256-GCM">;
+        /** base64 12-byte GCM IV (non-secret). */
+        iv: z.ZodString;
+        /** NIP-44-wrapped content key. */
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        alg: "AES-256-GCM";
+        iv: string;
+        key: string;
+    }, {
+        alg: "AES-256-GCM";
+        iv: string;
+        key: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    kind: "blossom";
+    url: string;
+    sha256: string;
+    enc: {
+        alg: "AES-256-GCM";
+        iv: string;
+        key: string;
+    };
+}, {
+    kind: "blossom";
+    url: string;
+    sha256: string;
+    enc: {
+        alg: "AES-256-GCM";
+        iv: string;
+        key: string;
+    };
 }>]>;
 declare const FileAttachmentSchema: z.ZodObject<{
     /** Display name only. Never used to derive a filesystem path (callers sanitize). */
@@ -57,37 +102,62 @@ declare const FileAttachmentSchema: z.ZodObject<{
     /** 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. */
-    transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
-        kind: z.ZodLiteral<"iroh">;
-        /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
-        ticket: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    /**
+     * 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;
-    }>]>, "many">;
+    } | {
+        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: {
+    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: {
-        kind: "iroh";
-        ticket: string;
-    }[];
+    transports: unknown[];
     seedingExpiresAt?: number | undefined;
 }>;
 declare const JobPayloadEnvelopeSchema: z.ZodObject<{
@@ -99,37 +169,62 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         /** 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. */
-        transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
-            kind: z.ZodLiteral<"iroh">;
-            /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
-            ticket: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
+        /**
+         * 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;
-        }>]>, "many">;
+        } | {
+            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: {
+        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: {
-            kind: "iroh";
-            ticket: string;
-        }[];
+        transports: unknown[];
         seedingExpiresAt?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -139,10 +234,19 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         name: string;
         size: number;
         mime: string;
-        transports: {
+        transports: ({
             kind: "iroh";
             ticket: string;
-        }[];
+        } | {
+            kind: "blossom";
+            url: string;
+            sha256: string;
+            enc: {
+                alg: "AES-256-GCM";
+                iv: string;
+                key: string;
+            };
+        })[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
 }, {
@@ -152,16 +256,29 @@ declare const JobPayloadEnvelopeSchema: z.ZodObject<{
         name: string;
         size: number;
         mime: string;
-        transports: {
-            kind: "iroh";
-            ticket: string;
-        }[];
+        transports: unknown[];
         seedingExpiresAt?: number | undefined;
     } | undefined;
 }>;
 type FileTransport = z.infer<typeof FileTransportSchema>;
 type FileAttachment = z.infer<typeof FileAttachmentSchema>;
 type JobPayloadEnvelope = z.infer<typeof JobPayloadEnvelopeSchema>;
+/** The kinds of file transport a job can use ('iroh' | 'blossom'). */
+type TransportKind = FileTransport['kind'];
+/** Public job-request tag advertising which transports a customer can RECEIVE output on. */
+declare const ACCEPT_TRANSPORTS_TAG = "accept";
+/**
+ * Build the `['accept', ...kinds]` job-request tag from a client's RECEIVE-capable transports.
+ * Drops unknown kinds and dedupes, preserving the client's preference order.
+ */
+declare function buildAcceptTransportsTag(kinds: TransportKind[]): string[];
+/**
+ * Read accepted transports from an event's tags. Returns the ordered, deduped, known kinds, or
+ * `undefined` when there is no `accept` tag or it carries no known kind - both normalize to the
+ * provider's default (seed all transports). Lenient: unknown kinds (from a newer client) are ignored
+ * 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. */
 interface DecodedJobPayload {
     text?: string;
@@ -329,6 +446,12 @@ interface SubmitJobOptions {
      * itself travels out-of-band (P2P via iroh), not in the Nostr event.
      */
     attachment?: FileAttachment;
+    /**
+     * Ordered (by client preference) transports this customer can RECEIVE output on. Published as a
+     * public `accept` tag. When omitted, providers default to seeding all transports (back-compat);
+     * advertising `['iroh']` makes a provider skip the (encrypted-Blossom) upload it can't use.
+     */
+    acceptTransports?: TransportKind[];
 }
 interface JobUpdateCallbacks {
     onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
@@ -527,6 +650,53 @@ interface BuildTransactionOptions {
     programId?: Address;
 }
 
+/** Result of an upload. */
+interface BlobDescriptor {
+    /**
+     * Publicly GET-able URL. Content-addressed (https://<host>/<sha256>.<ext>) ONLY when
+     * `provider === 'blossom'`; on `'fallback'` it is a provider-assigned nostr.build URL
+     * that may NOT be addressed by `sha256` (the host may re-encode the bytes).
+     */
+    url: string;
+    /**
+     * Lowercase-hex SHA-256 of the bytes the caller uploaded. On `'blossom'` it is also
+     * verified to equal what the server stored (integrity check). On `'fallback'` it is the
+     * local hash only - do NOT assume `url` resolves to it.
+     */
+    sha256: string;
+    size: number;
+    type: string;
+    /** Unix seconds; only the Blossom path returns it. */
+    uploaded?: number;
+    provider: 'blossom' | 'fallback';
+}
+/** Fallback uploader invoked when the Blossom upload fails; returns the stored URL. */
+type BlossomUploadFallback = (identity: ElisymIdentity, file: Blob) => Promise<string>;
+declare class BlossomService {
+    private serverUrl;
+    private fallback?;
+    constructor(serverUrl?: string, fallback?: BlossomUploadFallback | undefined);
+    /**
+     * 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
+     * `provider: 'fallback'`. Works with browser File objects and Node.js/Bun Blobs.
+     */
+    upload(identity: ElisymIdentity, file: Blob): Promise<BlobDescriptor>;
+    /** 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(url: string, opts?: {
+        maxBytes?: number;
+        timeoutMs?: number;
+        expectedSha256?: string;
+    }): Promise<Uint8Array>;
+    private uploadToBlossom;
+    private authHeader;
+}
+
 declare class NostrPool {
     private pool;
     private relays;
@@ -855,6 +1025,8 @@ interface ElisymClientFullConfig extends ElisymClientConfig {
     payment?: PaymentStrategy;
     /** Custom upload URL for file uploads (defaults to nostr.build). */
     uploadUrl?: string;
+    /** Custom Blossom server base URL for blob uploads (defaults to files.elisym.network). */
+    blossomUrl?: string;
 }
 declare class ElisymClient {
     readonly pool: NostrPool;
@@ -862,12 +1034,87 @@ declare class ElisymClient {
     readonly marketplace: MarketplaceService;
     readonly ping: PingService;
     readonly media: MediaService;
+    readonly blossom: BlossomService;
     readonly policies: PoliciesService;
     readonly payment: PaymentStrategy;
     constructor(config?: ElisymClientFullConfig);
     close(): void;
 }
 
+type BlossomTransport = Extract<FileTransport, {
+    kind: 'blossom';
+}>;
+interface BlossomBlobTransport {
+    /** Encrypt `bytes` to `recipientPubkey`, upload the ciphertext, return a `blossom` transport member. */
+    seedBytes(args: {
+        bytes: Uint8Array;
+        recipientPubkey: string;
+    }): Promise<BlossomTransport>;
+    /** Download the ciphertext (bounded + sha256-verified) and decrypt it (sent by `senderPubkey`). */
+    fetchToBytes(args: {
+        transport: BlossomTransport;
+        senderPubkey: string;
+        maxBytes?: number;
+    }): Promise<Uint8Array>;
+}
+declare function createBlossomTransport(opts: {
+    blossom: BlossomService;
+    identity: ElisymIdentity;
+}): 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.
+ *
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+declare function buildEncryptedFileInput(args: {
+    file: Blob & {
+        name?: string;
+    };
+    providerPubkey: string;
+    identity: ElisymIdentity;
+    blossom: BlossomService;
+}): Promise<FileAttachment>;
+/**
+ * Download + decrypt a `blossom` file output from an attachment (sent by `providerPubkey`). Returns the
+ * plaintext bytes plus the envelope-carried name/mime. Throws if there is no blossom transport.
+ */
+declare function fetchEncryptedFileOutput(args: {
+    attachment: FileAttachment;
+    providerPubkey: string;
+    identity: ElisymIdentity;
+    blossom: BlossomService;
+    maxBytes?: number;
+}): Promise<{
+    bytes: Uint8Array;
+    name: string;
+    mime: string;
+}>;
+
+interface EncryptedBytes {
+    /** AES-256-GCM ciphertext with the 16-byte auth tag appended (WebCrypto layout). */
+    ciphertext: Uint8Array;
+    /** NIP-44-wrapped content key (sender secret key -> recipient pubkey). */
+    wrappedKey: string;
+    /** base64 GCM IV (non-secret). */
+    iv: string;
+}
+/** Encrypt `bytes` so that only `recipientPubkey` (with the sender's pubkey) can decrypt. */
+declare function encryptBytesForRecipient(bytes: Uint8Array, senderSk: Uint8Array, recipientPubkey: string): Promise<EncryptedBytes>;
+/**
+ * Decrypt bytes produced by `encryptBytesForRecipient`. Throws on any tamper (GCM auth tag), a
+ * corrupted/forged wrapped key (NIP-44 MAC), or the wrong receiver/sender key pair.
+ */
+declare function decryptBytesFromSender(ciphertext: Uint8Array, wrappedKey: string, iv: string, receiverSk: Uint8Array, senderPubkey: string): Promise<Uint8Array>;
+
 /**
  * Customer-facing error feedback that arrives via `subscribeToJobUpdates`'s
  * `onError` callback can come from many places:
@@ -1478,6 +1725,8 @@ declare const DEFAULTS: {
     readonly QUERY_MAX_CONCURRENCY: 6;
     readonly VERIFY_SIGNATURE_LIMIT: 25;
     readonly IROH_FETCH_TIMEOUT_MS: 300000;
+    readonly BLOSSOM_UPLOAD_TIMEOUT_MS: 300000;
+    readonly BLOSSOM_FETCH_TIMEOUT_MS: 300000;
 };
 /** Protocol limits for input validation. */
 declare const LIMITS: {
@@ -1486,6 +1735,7 @@ declare const LIMITS: {
     readonly MAX_ENCRYPTED_INLINE_BYTES: 60000;
     readonly MAX_REINLINE_TEXT_BYTES: 4194304;
     readonly MAX_FILE_SIZE: 1073741824;
+    readonly MAX_BLOSSOM_ENCRYPTED_BYTES: 104857600;
     readonly MAX_TIMEOUT_SECS: 600;
     readonly MAX_EXECUTION_SECS: 2147483;
     readonly MAX_CAPABILITIES: 20;
@@ -1506,4 +1756,4 @@ declare const LIMITS: {
  */
 declare function utf8ByteLength(value: string): number;
 
-export { type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, 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 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 VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, decodeJobPayload, encodeJobPayload, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, 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, 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 };