blossom-client-sdk 2.1.1 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,7 +16,7 @@ async function signer(event) {
16
16
  }
17
17
 
18
18
  // create an upload auth event
19
- const uploadAuth = await BlossomClient.getUploadAuth(file, server, "Upload bitcoin.pdf");
19
+ const uploadAuth = await BlossomClient.createUploadAuth(file, server, "Upload bitcoin.pdf");
20
20
 
21
21
  // encode it using base64
22
22
  const encodedAuthHeader = BlossomClient.encodeAuthorizationHeader(auth);
@@ -188,7 +188,7 @@ async function signer(event) {
188
188
  const servers = ["https://cdn.example.com", "https://cdn.other.com"];
189
189
  const file = new File(["testing"], "test.txt");
190
190
 
191
- const auth = await BlossomClient.createUploadAuth(file, signer, "Upload test.txt");
191
+ const auth = await BlossomClient.createUploadAuth(file, signer, { message: "Upload test.txt" });
192
192
 
193
193
  for (let server of servers) {
194
194
  await BlossomClient.uploadBlob(server, file, auth);
@@ -214,7 +214,7 @@ const file = new File(["testing"], "test.txt");
214
214
 
215
215
  // create async generator for upload
216
216
  const results = await multiServerUpload(servers, file, {
217
- onAuth: async (server, blob) => createUploadAuth(signer, blob),
217
+ onAuth: async (server, sha256, type) => createUploadAuth(signer, sha256, { type }),
218
218
  onUpload: (server, blob) => {},
219
219
  onError: (server, blob, error) => {
220
220
  console.log("Failed to upload to", server);
@@ -223,6 +223,38 @@ const results = await multiServerUpload(servers, file, {
223
223
  });
224
224
  ```
225
225
 
226
+ ### Uploading media and mirroring
227
+
228
+ The `multiServerUpload` method can also be used to upload media blobs and mirror them
229
+
230
+ ```ts
231
+ import { multiServerUpload, createUploadAuth } from "blossom-server-sdk";
232
+
233
+ async function signer(event: any) {
234
+ // @ts-expect-error
235
+ return await window.nostr.signEvent(event);
236
+ }
237
+
238
+ const servers = ["https://cdn.server-a.com", "https://cdn.example.com", "https://cdn.other.com"];
239
+ const media = new File(["image data"], "image.png");
240
+
241
+ // create async generator for upload
242
+ const results = await multiServerUpload(servers, media, {
243
+ // use media upload endpoint
244
+ isMedia: true,
245
+ // use any servers media endpoint
246
+ mediaUploadBehavior: "any",
247
+ // if the media endpoint isn't found fallback to the /upload endpoint
248
+ mediaUploadFallback: true,
249
+ // handle auth requests
250
+ onAuth: async (server, sha256, type) => createUploadAuth(signer, sha256, { type }),
251
+ onError: (server, blob, error) => {
252
+ console.log("Failed to upload to", server);
253
+ console.log(error);
254
+ },
255
+ });
256
+ ```
257
+
226
258
  ### Upload and Mirror manually
227
259
 
228
260
  ```js
@@ -236,7 +268,7 @@ const mainServer = "https://cdn.server-a.com";
236
268
  const mirrorServers = ["https://cdn.example.com", "https://cdn.other.com"];
237
269
  const file = new File(["testing"], "test.txt");
238
270
 
239
- const auth = await BlossomClient.createUploadAuth(file, signer, "Upload test.txt");
271
+ const auth = await BlossomClient.createUploadAuth(file, signer, { message: "Upload test.txt" });
240
272
 
241
273
  // first upload blob to main server
242
274
  const blob = await BlossomClient.uploadBlob(mainServer, file, auth);
@@ -2,10 +2,25 @@ import { type Token } from "@cashu/cashu-ts";
2
2
  import { ServerType } from "../client.js";
3
3
  import { PaymentRequest, SignedEvent } from "../types.js";
4
4
  export type DeleteOptions<S extends ServerType> = {
5
+ /** AbortSignal to cancel the action */
5
6
  signal?: AbortSignal;
7
+ /** Override auth event to use */
6
8
  auth?: SignedEvent;
7
- onPayment?: (server: S, hash: string, request: PaymentRequest) => Promise<Token>;
8
- onAuth?: (server: S, hash: string) => Promise<SignedEvent>;
9
+ /** Request timeout */
10
+ timeout?: number;
11
+ /**
12
+ * A method used to request payment when deleting
13
+ * @param server the server requiring payment
14
+ * @param sha256 the sha256 of the blob being uploaded or mirrored
15
+ * @param request the payment request
16
+ */
17
+ onPayment?: (server: S, sha256: string, request: PaymentRequest) => Promise<Token>;
18
+ /**
19
+ * A method used to request a signed auth event for a server and sha256
20
+ * @param server the server requesting the auth
21
+ * @param sha256 the sha256 of the blob being upload or mirror to the server
22
+ */
23
+ onAuth?: (server: S, sha256: string) => Promise<SignedEvent>;
9
24
  };
10
25
  /** Deletes a blob to a server */
11
26
  export declare function deleteBlob<S extends ServerType>(server: S, hash: string, opts?: DeleteOptions<S>): Promise<boolean>;
@@ -1,10 +1,20 @@
1
1
  import HTTPError from "../error.js";
2
2
  import { encodeAuthorizationHeader } from "../auth.js";
3
- import { getPaymentRequestFromHeaders } from "../helpers.js";
3
+ import { getPaymentRequestFromHeaders } from "../helpers/cachu.js";
4
+ import { fetchWithTimeout } from "../helpers/fetch.js";
4
5
  /** Deletes a blob to a server */
5
6
  export async function deleteBlob(server, hash, opts) {
6
7
  const url = new URL("/" + hash, server);
7
- let res = await fetch(url, { signal: opts?.signal, method: "DELETE" });
8
+ const headers = {};
9
+ // attach the auth if its already set
10
+ if (opts?.auth)
11
+ headers["Authorization"] = encodeAuthorizationHeader(opts.auth);
12
+ let res = await fetchWithTimeout(url, {
13
+ method: "DELETE",
14
+ headers,
15
+ signal: opts?.signal,
16
+ timeout: opts?.timeout,
17
+ });
8
18
  // handle auth and payment
9
19
  switch (res.status) {
10
20
  case 401: {
@@ -12,10 +22,11 @@ export async function deleteBlob(server, hash, opts) {
12
22
  if (!auth)
13
23
  throw new Error("Missing auth handler");
14
24
  // Try delete with auth
15
- res = await fetch(url, {
25
+ res = await fetchWithTimeout(url, {
16
26
  signal: opts?.signal,
17
27
  method: "DELETE",
18
- headers: { Authorization: encodeAuthorizationHeader(auth) },
28
+ headers: { ...headers, Authorization: encodeAuthorizationHeader(auth) },
29
+ timeout: opts?.timeout,
19
30
  });
20
31
  break;
21
32
  }
@@ -27,10 +38,11 @@ export async function deleteBlob(server, hash, opts) {
27
38
  const token = await opts.onPayment(server, hash, request);
28
39
  const payment = getEncodedToken(token);
29
40
  // Try delete with payment
30
- res = await fetch(url, {
41
+ res = await fetchWithTimeout(url, {
31
42
  signal: opts?.signal,
32
43
  method: "DELETE",
33
- headers: { "X-Cashu": payment },
44
+ headers: { ...headers, "X-Cashu": payment },
45
+ timeout: opts?.timeout,
34
46
  });
35
47
  break;
36
48
  }
@@ -2,10 +2,25 @@ import { type Token } from "@cashu/cashu-ts";
2
2
  import { ServerType } from "../client.js";
3
3
  import { PaymentRequest, SignedEvent } from "../types.js";
4
4
  export type DownloadOptions<S extends ServerType> = {
5
+ /** AbortSignal to cancel the action */
5
6
  signal?: AbortSignal;
7
+ /** Override auth event to use */
6
8
  auth?: SignedEvent;
7
- onPayment?: (server: S, hash: string, request: PaymentRequest) => Promise<Token>;
8
- onAuth?: (server: S, hash: string) => Promise<SignedEvent>;
9
+ /** Request timeout */
10
+ timeout?: number;
11
+ /**
12
+ * A method used to request payment when downloading
13
+ * @param server the server requiring payment
14
+ * @param sha256 the sha256 of the blob being uploaded or mirrored
15
+ * @param request the payment request
16
+ */
17
+ onPayment?: (server: S, sha256: string, request: PaymentRequest) => Promise<Token>;
18
+ /**
19
+ * A method used to request a signed auth event for a server and sha256
20
+ * @param server the server requesting the auth
21
+ * @param sha256 the sha256 of the blob being upload or mirror to the server
22
+ */
23
+ onAuth?: (server: S, sha256: string) => Promise<SignedEvent>;
9
24
  };
10
25
  /** Downloads a blob from a server and returns the Response */
11
26
  export declare function downloadBlob<S extends ServerType>(server: S, hash: string, opts?: DownloadOptions<S>): Promise<Response>;
@@ -1,10 +1,18 @@
1
1
  import HTTPError from "../error.js";
2
2
  import { encodeAuthorizationHeader } from "../auth.js";
3
- import { getPaymentRequestFromHeaders } from "../helpers.js";
3
+ import { fetchWithTimeout, getPaymentRequestFromHeaders } from "../helpers/index.js";
4
4
  /** Downloads a blob from a server and returns the Response */
5
5
  export async function downloadBlob(server, hash, opts) {
6
6
  const url = new URL("/" + hash, server);
7
- let download = await fetch(url, { signal: opts?.signal });
7
+ const headers = {};
8
+ // attach the auth if its already set
9
+ if (opts?.auth)
10
+ headers["Authorization"] = encodeAuthorizationHeader(opts.auth);
11
+ let download = await fetchWithTimeout(url, {
12
+ headers,
13
+ signal: opts?.signal,
14
+ timeout: opts?.timeout,
15
+ });
8
16
  // handle auth and payment
9
17
  switch (download.status) {
10
18
  case 401: {
@@ -12,9 +20,10 @@ export async function downloadBlob(server, hash, opts) {
12
20
  if (!auth)
13
21
  throw new Error("Missing auth handler");
14
22
  // Try download with auth
15
- download = await fetch(url, {
23
+ download = await fetchWithTimeout(url, {
24
+ headers: { ...headers, Authorization: encodeAuthorizationHeader(auth) },
16
25
  signal: opts?.signal,
17
- headers: { Authorization: encodeAuthorizationHeader(auth) },
26
+ timeout: opts?.timeout,
18
27
  });
19
28
  break;
20
29
  }
@@ -26,9 +35,10 @@ export async function downloadBlob(server, hash, opts) {
26
35
  const token = await opts.onPayment(server, hash, request);
27
36
  const payment = getEncodedToken(token);
28
37
  // Try download with payment
29
- download = await fetch(url, {
38
+ download = await fetchWithTimeout(url, {
39
+ headers: { ...headers, "X-Cashu": payment },
30
40
  signal: opts?.signal,
31
- headers: { "X-Cashu": payment },
41
+ timeout: opts?.timeout,
32
42
  });
33
43
  break;
34
44
  }
@@ -3,3 +3,5 @@ export * from "./mirror.js";
3
3
  export * from "./list.js";
4
4
  export * from "./delete.js";
5
5
  export * from "./download.js";
6
+ export * from "./multi-server.js";
7
+ export * from "./media.js";
@@ -3,3 +3,5 @@ export * from "./mirror.js";
3
3
  export * from "./list.js";
4
4
  export * from "./delete.js";
5
5
  export * from "./download.js";
6
+ export * from "./multi-server.js";
7
+ export * from "./media.js";
@@ -2,11 +2,24 @@ import { type Token } from "@cashu/cashu-ts";
2
2
  import { ServerType } from "../client.js";
3
3
  import { BlobDescriptor, PaymentRequest, SignedEvent } from "../types.js";
4
4
  export type ListOptions<S extends ServerType> = {
5
+ /** AbortSignal to cancel the action */
5
6
  signal?: AbortSignal;
7
+ /** Override auth event to use */
6
8
  auth?: SignedEvent;
9
+ /** Request timeout */
10
+ timeout?: number;
7
11
  since?: number;
8
12
  until?: number;
13
+ /**
14
+ * A method used to request payment
15
+ * @param server the server requiring payment
16
+ * @param request the payment request
17
+ */
9
18
  onPayment?: (server: S, request: PaymentRequest) => Promise<Token>;
19
+ /**
20
+ * A method used to request a signed auth event for a server
21
+ * @param server the server requesting the auth
22
+ */
10
23
  onAuth?: (server: S) => Promise<SignedEvent>;
11
24
  };
12
25
  /** Mirrors a blob to a server */
@@ -1,6 +1,6 @@
1
1
  import HTTPError from "../error.js";
2
2
  import { encodeAuthorizationHeader } from "../auth.js";
3
- import { getPaymentRequestFromHeaders } from "../helpers.js";
3
+ import { fetchWithTimeout, getPaymentRequestFromHeaders } from "../helpers/index.js";
4
4
  /** Mirrors a blob to a server */
5
5
  export async function listBlobs(server, pubkey, opts) {
6
6
  const url = new URL(`/list/` + pubkey, server);
@@ -8,7 +8,7 @@ export async function listBlobs(server, pubkey, opts) {
8
8
  url.searchParams.append("since", String(opts.since));
9
9
  if (opts?.until)
10
10
  url.searchParams.append("until", String(opts.until));
11
- let list = await fetch(url, { signal: opts?.signal });
11
+ let list = await fetchWithTimeout(url, { signal: opts?.signal, timeout: opts?.timeout });
12
12
  // handle auth and payments
13
13
  switch (list.status) {
14
14
  case 401: {
@@ -16,9 +16,10 @@ export async function listBlobs(server, pubkey, opts) {
16
16
  if (!auth)
17
17
  throw new Error("Missing auth handler");
18
18
  // Try list with auth
19
- list = await fetch(url, {
20
- signal: opts?.signal,
19
+ list = await fetchWithTimeout(url, {
21
20
  headers: { Authorization: encodeAuthorizationHeader(auth) },
21
+ signal: opts?.signal,
22
+ timeout: opts?.timeout,
22
23
  });
23
24
  break;
24
25
  }
@@ -30,9 +31,10 @@ export async function listBlobs(server, pubkey, opts) {
30
31
  const token = await opts.onPayment(server, request);
31
32
  const payment = getEncodedToken(token);
32
33
  // Try list with payment
33
- list = await fetch(url, {
34
- signal: opts?.signal,
34
+ list = await fetchWithTimeout(url, {
35
35
  headers: { "X-Cashu": payment },
36
+ signal: opts?.signal,
37
+ timeout: opts?.timeout,
36
38
  });
37
39
  break;
38
40
  }
@@ -0,0 +1,9 @@
1
+ import { ServerType, UploadType } from "../client.js";
2
+ import { BlobDescriptor } from "../types.js";
3
+ import { UploadOptions } from "./upload.js";
4
+ /** Error thrown when /media endpoint is not present on a server */
5
+ export declare class MediaEndpointMissingError extends Error {
6
+ }
7
+ export type UploadMediaOptions<S extends ServerType, B extends UploadType> = UploadOptions<S, B>;
8
+ /** Upload a media blob to a server using the /media endpoint, handles payment and auth */
9
+ export declare function uploadMedia<S extends ServerType, B extends UploadType>(server: S, blob: B, opts?: UploadMediaOptions<S, B>): Promise<BlobDescriptor>;
@@ -0,0 +1,82 @@
1
+ import { getBlobSha256, getBlobSize, getBlobType, getPaymentRequestFromHeaders } from "../helpers/index.js";
2
+ import HTTPError from "../error.js";
3
+ import { encodeAuthorizationHeader } from "../auth.js";
4
+ /** Error thrown when /media endpoint is not present on a server */
5
+ export class MediaEndpointMissingError extends Error {
6
+ }
7
+ /** Upload a media blob to a server using the /media endpoint, handles payment and auth */
8
+ export async function uploadMedia(server, blob, opts) {
9
+ const url = new URL("/media", server);
10
+ const sha256 = await getBlobSha256(blob);
11
+ const headers = {
12
+ "X-SHA-256": sha256,
13
+ };
14
+ // attach the auth if its already set
15
+ if (opts?.auth)
16
+ headers["Authorization"] = encodeAuthorizationHeader(opts.auth);
17
+ // build check headers
18
+ const checkHeaders = {
19
+ ...headers,
20
+ "X-Content-Length": String(getBlobSize(blob)),
21
+ };
22
+ const type = getBlobType(blob);
23
+ if (type)
24
+ checkHeaders["X-Content-Type"] = type;
25
+ // check upload with HEAD /media
26
+ let firstTry = await fetch(url, {
27
+ method: "HEAD",
28
+ signal: opts?.signal,
29
+ headers: checkHeaders,
30
+ });
31
+ let upload = undefined;
32
+ if (firstTry.status === 404) {
33
+ // HEAD endpoint is not supported. abort
34
+ throw new MediaEndpointMissingError("/media endpoint not supported");
35
+ }
36
+ // handle auth and payment
37
+ switch (firstTry.status) {
38
+ case 401: {
39
+ const auth = opts?.auth || (await opts?.onAuth?.(server, sha256, "media", blob));
40
+ if (!auth)
41
+ throw new Error("Missing auth handler");
42
+ // Try upload with auth
43
+ upload = await fetch(url, {
44
+ signal: opts?.signal,
45
+ method: "PUT",
46
+ body: blob,
47
+ headers: { ...headers, Authorization: encodeAuthorizationHeader(auth) },
48
+ });
49
+ break;
50
+ }
51
+ case 402: {
52
+ if (!opts?.onPayment)
53
+ throw new Error("Missing payment handler");
54
+ const { getEncodedToken } = await import("@cashu/cashu-ts");
55
+ const request = getPaymentRequestFromHeaders(firstTry.headers);
56
+ const token = await opts.onPayment(server, sha256, blob, request);
57
+ const payment = getEncodedToken(token);
58
+ // Try upload with payment
59
+ upload = await fetch(url, {
60
+ signal: opts?.signal,
61
+ method: "PUT",
62
+ body: blob,
63
+ headers: { ...headers, "X-Cashu": payment },
64
+ });
65
+ break;
66
+ }
67
+ }
68
+ if (firstTry.status >= 500)
69
+ throw new Error("Server error");
70
+ // check passed, upload
71
+ if (!upload)
72
+ upload = await fetch(url, {
73
+ signal: opts?.signal,
74
+ method: "PUT",
75
+ body: blob,
76
+ headers: { ...headers },
77
+ });
78
+ // handle errors
79
+ await HTTPError.handleErrorResponse(upload);
80
+ // return blob descriptor
81
+ return upload.json();
82
+ }
@@ -2,10 +2,27 @@ import { type Token } from "@cashu/cashu-ts";
2
2
  import { ServerType } from "../client.js";
3
3
  import { BlobDescriptor, SignedEvent, PaymentRequest } from "../types.js";
4
4
  export type MirrorOptions<S extends ServerType> = {
5
+ /** AbortSignal to cancel the action */
5
6
  signal?: AbortSignal;
7
+ /** Override auth event to use */
6
8
  auth?: SignedEvent;
7
- onPayment?: (server: S, blob: BlobDescriptor, request: PaymentRequest) => Promise<Token>;
8
- onAuth?: (server: S, blob: BlobDescriptor) => Promise<SignedEvent>;
9
+ /** Request timeout */
10
+ timeout?: number;
11
+ /**
12
+ * A method used to request payment when uploading or mirroring a blob
13
+ * @param server the server requiring payment
14
+ * @param sha256 the sha256 of the blob being uploaded or mirrored
15
+ * @param blob the original blob
16
+ * @param request the payment request
17
+ */
18
+ onPayment?: (server: S, sha256: string, blob: BlobDescriptor, request: PaymentRequest) => Promise<Token>;
19
+ /**
20
+ * A method used to request a signed auth event for a server and sha256
21
+ * @param server the server requesting the auth
22
+ * @param sha256 the sha256 of the blob being upload or mirror to the server
23
+ * @param blob the original blob passed to the method
24
+ */
25
+ onAuth?: (server: S, sha256: string, blob: BlobDescriptor) => Promise<SignedEvent>;
9
26
  };
10
27
  /** Mirrors a blob to a server */
11
28
  export declare function mirrorBlob<S extends ServerType>(server: S, blob: BlobDescriptor, opts?: MirrorOptions<S>): Promise<BlobDescriptor>;
@@ -1,33 +1,39 @@
1
1
  import HTTPError from "../error.js";
2
2
  import { encodeAuthorizationHeader } from "../auth.js";
3
- import { getPaymentRequestFromHeaders } from "../helpers.js";
3
+ import { fetchWithTimeout, getPaymentRequestFromHeaders } from "../helpers/index.js";
4
4
  /** Mirrors a blob to a server */
5
5
  export async function mirrorBlob(server, blob, opts) {
6
6
  const url = new URL("/mirror", server);
7
7
  const headers = {
8
8
  "X-SHA-256": blob.sha256,
9
9
  "X-Content-Length": String(blob.size),
10
+ "Content-Type": "application/json",
10
11
  };
11
12
  if (blob.type)
12
13
  headers["X-Content-Type"] = blob.type;
14
+ // attach the auth if its already set
15
+ if (opts?.auth)
16
+ headers["Authorization"] = encodeAuthorizationHeader(opts.auth);
13
17
  const body = JSON.stringify({ url: blob.url });
14
- let mirror = await fetch(url, {
18
+ let mirror = await fetchWithTimeout(url, {
15
19
  method: "PUT",
16
20
  signal: opts?.signal,
17
21
  headers,
18
22
  body,
23
+ timeout: opts?.timeout,
19
24
  });
20
25
  switch (mirror.status) {
21
26
  case 401: {
22
- const auth = opts?.auth || (await opts?.onAuth?.(server, blob));
27
+ const auth = opts?.auth || (await opts?.onAuth?.(server, blob.sha256, blob));
23
28
  if (!auth)
24
29
  throw new Error("Missing auth handler");
25
30
  // Try mirror with auth
26
- mirror = await fetch(url, {
31
+ mirror = await fetchWithTimeout(url, {
27
32
  signal: opts?.signal,
28
33
  method: "PUT",
29
34
  body,
30
- headers: { Authorization: encodeAuthorizationHeader(auth) },
35
+ headers: { ...headers, Authorization: encodeAuthorizationHeader(auth) },
36
+ timeout: opts?.timeout,
31
37
  });
32
38
  break;
33
39
  }
@@ -36,14 +42,15 @@ export async function mirrorBlob(server, blob, opts) {
36
42
  throw new Error("Missing payment handler");
37
43
  const { getEncodedToken } = await import("@cashu/cashu-ts");
38
44
  const request = getPaymentRequestFromHeaders(mirror.headers);
39
- const token = await opts.onPayment(server, blob, request);
45
+ const token = await opts.onPayment(server, blob.sha256, blob, request);
40
46
  const payment = getEncodedToken(token);
41
47
  // Try mirror with payment
42
- mirror = await fetch(url, {
48
+ mirror = await fetchWithTimeout(url, {
43
49
  signal: opts?.signal,
44
50
  method: "PUT",
45
51
  body,
46
- headers: { "X-Cashu": payment },
52
+ headers: { ...headers, "X-Cashu": payment },
53
+ timeout: opts?.timeout,
47
54
  });
48
55
  break;
49
56
  }
@@ -0,0 +1,66 @@
1
+ import { ServerType, UploadType } from "../client.js";
2
+ import { BlobDescriptor } from "../types.js";
3
+ import { UploadOptions } from "./upload.js";
4
+ export type MultiServerUploadOptions<S extends ServerType, B extends UploadType> = UploadOptions<S, B> & {
5
+ /**
6
+ * Signals this blob should be treated as a media file and should attempt to use BUD-05 /media endpoint for upload on first server
7
+ * @default false
8
+ */
9
+ isMedia?: boolean;
10
+ /**
11
+ * If isMedia is enabled, this determines how /media endpoints should be prioritized
12
+ * - "first" Only use the first server in the list to optimize the media
13
+ * - "any" Use any server in the list to optimize the media
14
+ * @default "first"
15
+ */
16
+ mediaUploadBehavior?: "first" | "any";
17
+ /**
18
+ * If isMedia is enabled, should the raw blob be uploaded if no /media endpoint can be found
19
+ * @default false
20
+ */
21
+ mediaUploadFallback?: boolean;
22
+ /**
23
+ * Timeout for mirror requests
24
+ * @default 5000
25
+ */
26
+ mirrorTimeout?: number;
27
+ /**
28
+ * called on blob when uploaded to started to a server
29
+ * @param server
30
+ * @param sha256 the hash of the blob being uploaded or mirrored
31
+ * @param blob the original blob
32
+ */
33
+ onStart?: (server: S, sha256: string, blob: B) => void;
34
+ /** called when upload to a server is complete */
35
+ onUpload?: (server: S, sha256: string, blob: B) => void;
36
+ /** called when upload to a server fails */
37
+ onError?: (server: S, sha256: string, blob: B, error: Error) => void;
38
+ };
39
+ /**
40
+ * Creates an AsyncGenerator that can be used to upload a blob to multiple servers
41
+ * @param servers A Set or Array of servers to upload to
42
+ * @param blob The blob to be uploaded
43
+ * @param signer An async function used for signing nostr events
44
+ * @returns The BlobDescriptor if successful
45
+ *
46
+ * ```mermaid
47
+ * flowchart LR
48
+ * isMedia{"isMedia"} -- yes --> media["/media"]
49
+ * isMedia -- no --> upload["/upload"]
50
+ * media --> ifmedia{"Successful"}
51
+ * ifmedia -- yes --> next["Next server"]
52
+ * ifmedia -- no --> iffallback{"fallback"}
53
+ * iffallback -- yes --> upload
54
+ * iffallback -- no --> abort
55
+ * upload -- complete --> next
56
+ * next --> uploaded{"Uploaded"}
57
+ * uploaded -- yes --> mirror["/mirror"]
58
+ * uploaded -- no --> upload
59
+ * mirror --> isMirror{"Successful"}
60
+ * isMirror -- yes --> next
61
+ * isMirror -- no --> ifMediaAbort{"isMedia"}
62
+ * ifMediaAbort -- no --> upload
63
+ * ifMediaAbort -- yes --> next
64
+ * ```
65
+ */
66
+ export declare function multiServerUpload<S extends ServerType, B extends UploadType>(servers: Iterable<S>, blob: B, opts?: MultiServerUploadOptions<S, B>): Promise<Map<S, BlobDescriptor>>;