blossom-client-sdk 4.0.0 → 5.0.0-0

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.
Files changed (75) hide show
  1. package/README.md +246 -92
  2. package/lib/actions/delete.d.ts +5 -3
  3. package/lib/actions/delete.js +28 -7
  4. package/lib/actions/download.d.ts +5 -3
  5. package/lib/actions/download.js +28 -7
  6. package/lib/actions/has.d.ts +9 -0
  7. package/lib/actions/has.js +10 -0
  8. package/lib/actions/index.d.ts +3 -0
  9. package/lib/actions/index.js +3 -0
  10. package/lib/actions/list.d.ts +10 -4
  11. package/lib/actions/list.js +45 -7
  12. package/lib/actions/media.d.ts +1 -1
  13. package/lib/actions/media.js +29 -7
  14. package/lib/actions/mirror.d.ts +5 -3
  15. package/lib/actions/mirror.js +28 -7
  16. package/lib/actions/multi-server.d.ts +63 -43
  17. package/lib/actions/multi-server.js +208 -88
  18. package/lib/actions/report.d.ts +11 -0
  19. package/lib/actions/report.js +35 -0
  20. package/lib/actions/resolve.d.ts +27 -0
  21. package/lib/actions/resolve.js +129 -0
  22. package/lib/actions/upload.d.ts +5 -3
  23. package/lib/actions/upload.js +28 -7
  24. package/lib/auth.d.ts +23 -2
  25. package/lib/auth.js +82 -22
  26. package/lib/error.d.ts +5 -0
  27. package/lib/error.js +11 -0
  28. package/lib/helpers/blob.d.ts +1 -1
  29. package/lib/helpers/blossom-uri.d.ts +20 -0
  30. package/lib/helpers/blossom-uri.js +77 -0
  31. package/lib/helpers/cachu.d.ts +5 -0
  32. package/lib/helpers/cachu.js +14 -0
  33. package/lib/helpers/index.d.ts +1 -0
  34. package/lib/helpers/index.js +1 -0
  35. package/lib/helpers/url.d.ts +2 -0
  36. package/lib/helpers/url.js +9 -3
  37. package/lib/helpers.d.ts +20 -0
  38. package/lib/helpers.js +73 -0
  39. package/lib/hls.d.ts +20 -0
  40. package/lib/hls.js +182 -0
  41. package/lib/index.d.ts +1 -2
  42. package/lib/index.js +1 -2
  43. package/lib/media.d.ts +37 -0
  44. package/lib/media.js +179 -0
  45. package/lib/types.d.ts +3 -1
  46. package/lib/upload.d.ts +13 -0
  47. package/lib/upload.js +37 -0
  48. package/package.json +16 -7
  49. package/src/actions/delete.ts +31 -8
  50. package/src/actions/download.ts +31 -8
  51. package/src/actions/has.ts +19 -0
  52. package/src/actions/index.ts +3 -0
  53. package/src/actions/list.ts +55 -8
  54. package/src/actions/media.ts +29 -6
  55. package/src/actions/mirror.ts +31 -8
  56. package/src/actions/multi-server.ts +268 -111
  57. package/src/actions/report.ts +54 -0
  58. package/src/actions/resolve.ts +159 -0
  59. package/src/actions/upload.ts +31 -8
  60. package/src/auth.ts +105 -19
  61. package/src/error.ts +15 -0
  62. package/src/helpers/blob.ts +1 -1
  63. package/src/helpers/blossom-uri.ts +99 -0
  64. package/src/helpers/index.ts +1 -0
  65. package/src/helpers/url.ts +10 -3
  66. package/src/hls.ts +255 -0
  67. package/src/index.ts +1 -2
  68. package/src/media.ts +200 -0
  69. package/src/types.ts +4 -1
  70. package/lib/client.d.ts +0 -61
  71. package/lib/client.js +0 -160
  72. package/lib/image.d.ts +0 -17
  73. package/lib/image.js +0 -107
  74. package/src/client.ts +0 -221
  75. package/src/image.ts +0 -122
@@ -1,79 +1,97 @@
1
- import { doseAuthMatchUpload } from "../auth.js";
2
- import { ServerType, UploadType } from "../client.js";
1
+ import { getReusableAuthEvent, storeAuthEvent } from "../auth.js";
2
+ import { ServerType, UploadType } from "../types.js";
3
3
  import { getBlobSha256 } from "../helpers/index.js";
4
- import { BlobDescriptor, PaymentRequest } from "../types.js";
4
+ import { BlobDescriptor, PaymentRequest, RejectionAction, SignedEvent } from "../types.js";
5
+ import HTTPError from "../error.js";
5
6
  import { MediaEndpointMissingError, uploadMedia } from "./media.js";
6
7
  import { mirrorBlob } from "./mirror.js";
8
+ import { hasBlob } from "./has.js";
7
9
  import { uploadBlob, UploadOptions } from "./upload.js";
8
10
 
9
- export type MultiServerUploadOptions<S extends ServerType, B extends UploadType> = UploadOptions<S, B> & {
10
- /**
11
- * Signals this blob should be treated as a media file and should attempt to use BUD-05 /media endpoint for upload on first server
12
- * @default false
13
- */
14
- isMedia?: boolean;
15
- /**
16
- * If isMedia is enabled, this determines how /media endpoints should be prioritized
17
- * - "first" Only use the first server in the list to optimize the media
18
- * - "any" Use any server in the list to optimize the media
19
- * @default "first"
20
- */
21
- mediaUploadBehavior?: "first" | "any";
22
- /**
23
- * If isMedia is enabled, should the raw blob be uploaded if no /media endpoint can be found
24
- * @default false
25
- */
26
- mediaUploadFallback?: boolean;
11
+ export type MultiServerUploadOptions<TServer extends ServerType, TUpload extends UploadType> = UploadOptions<
12
+ TServer,
13
+ TUpload
14
+ > & {
27
15
  /**
28
16
  * Timeout for mirror requests
29
17
  * @default 5000
30
18
  */
31
19
  mirrorTimeout?: number;
20
+ /**
21
+ * Run parallel HEAD /<sha256> checks on all servers before starting uploads.
22
+ * Servers that already have the blob will use /mirror to register ownership instead of /upload.
23
+ * @default true
24
+ */
25
+ preflight?: boolean;
32
26
  /**
33
27
  * called on blob when uploaded to started to a server
34
28
  * @param server
35
29
  * @param sha256 the hash of the blob being uploaded or mirrored
36
30
  * @param blob the original blob
37
31
  */
38
- onStart?: (server: S, sha256: string, blob: B) => void;
32
+ onStart?: (server: TServer, sha256: string, blob: TUpload) => void;
39
33
  /** called when upload to a server is complete */
40
- onUpload?: (server: S, sha256: string, blob: B) => void;
34
+ onUpload?: (server: TServer, sha256: string, blob: TUpload) => void;
41
35
  /** called when upload to a server fails */
42
- onError?: (server: S, sha256: string, blob: B, error: Error) => void;
36
+ onError?: (server: TServer, sha256: string, blob: TUpload, error: Error) => void;
37
+ /**
38
+ * Called when a server rejects the upload with a known BUD-02 status (409, 413, 415, 422).
39
+ * Return "skip" to skip this server and continue, or "cancel" to abort the entire upload.
40
+ * If not provided, rejections are reported via onError.
41
+ */
42
+ onRejection?: (
43
+ server: TServer,
44
+ sha256: string,
45
+ blob: TUpload,
46
+ error: HTTPError,
47
+ ) => RejectionAction | Promise<RejectionAction>;
48
+ };
49
+
50
+ export type MultiServerMediaUploadOptions<
51
+ TServer extends ServerType,
52
+ TUpload extends UploadType,
53
+ > = MultiServerUploadOptions<TServer, TUpload> & {
54
+ /**
55
+ * Determines how /media endpoints should be prioritized
56
+ * - "first" Only use the first server in the list to optimize the media
57
+ * - "any" Use any server in the list to optimize the media
58
+ * @default "first"
59
+ */
60
+ mediaUploadBehavior?: "first" | "any";
61
+ /**
62
+ * Should the raw blob be uploaded if no /media endpoint can be found
63
+ * @default false
64
+ */
65
+ mediaUploadFallback?: boolean;
43
66
  };
44
67
 
45
68
  const defaultMultiServerOptions: MultiServerUploadOptions<any, any> = {
46
- isMedia: false,
69
+ mirrorTimeout: 5000,
70
+ preflight: true,
71
+ };
72
+
73
+ const defaultMediaUploadOptions: MultiServerMediaUploadOptions<any, any> = {
74
+ ...defaultMultiServerOptions,
47
75
  mediaUploadBehavior: "first",
48
76
  mediaUploadFallback: false,
49
- mirrorTimeout: 5000,
50
77
  };
51
78
 
52
79
  /**
53
- * Creates an AsyncGenerator that can be used to upload a blob to multiple servers
54
- * @param servers A Set or Array of servers to upload to
55
- * @param blob The blob to be uploaded
56
- * @param signer An async function used for signing nostr events
57
- * @returns The BlobDescriptor if successful
80
+ * Upload a blob to multiple servers
81
+ *
82
+ * Uploads the blob to the first server, then mirrors to the remaining servers.
83
+ * Uses parallel preflight checks (HEAD /<sha256>) to detect which servers already have the blob.
58
84
  *
59
85
  * ```mermaid
60
86
  * flowchart LR
61
- * isMedia{"isMedia"} -- yes --> media["/media"]
62
- * isMedia -- no --> upload["/upload"]
63
- * media --> ifmedia{"Successful"}
64
- * ifmedia -- yes --> next["Next server"]
65
- * ifmedia -- no --> iffallback{"fallback"}
66
- * iffallback -- yes --> upload
67
- * iffallback -- no --> abort
68
- * upload -- complete --> next
69
- * next --> uploaded{"Uploaded"}
70
- * uploaded -- yes --> mirror["/mirror"]
71
- * uploaded -- no --> upload
72
- * mirror --> isMirror{"Successful"}
87
+ * preflight["HEAD /<sha256>"] --> hasBlob{"Has blob?"}
88
+ * hasBlob -- yes --> mirror["/mirror"]
89
+ * hasBlob -- no --> upload["/upload"]
90
+ * upload -- complete --> next["Next server"]
91
+ * next --> hasBlob
92
+ * mirror --> isMirror{"Successful?"}
73
93
  * isMirror -- yes --> next
74
- * isMirror -- no --> ifMediaAbort{"isMedia"}
75
- * ifMediaAbort -- no --> upload
76
- * ifMediaAbort -- yes --> next
94
+ * isMirror -- no --> upload
77
95
  * ```
78
96
  */
79
97
  export async function multiServerUpload<S extends ServerType, B extends UploadType>(
@@ -84,122 +102,261 @@ export async function multiServerUpload<S extends ServerType, B extends UploadTy
84
102
  const options = { ...defaultMultiServerOptions, ...opts };
85
103
  let initialUpload: BlobDescriptor | undefined;
86
104
  const results = new Map<S, BlobDescriptor>();
105
+ const authEvents = options.authEvents ?? new Set<SignedEvent>();
106
+ const blobSha256 = await getBlobSha256(blob);
107
+
108
+ if (typeof options.auth === "object") authEvents.add(options.auth);
87
109
 
88
- // reuse auth events
89
- let authEvents = options.auth ? [options.auth] : [];
90
110
  const handleAuthRequest = async (server: S, sha256: string, type: "upload" | "media") => {
91
- // check if any existing auth events match
92
- for (const auth of authEvents) {
93
- if (await doseAuthMatchUpload(auth, server, sha256)) return auth;
94
- }
111
+ const reused = await getReusableAuthEvent(authEvents, { server, type, blob: sha256 });
112
+ if (reused) return reused;
95
113
 
96
- // create a new auth event
97
114
  if (options.onAuth) {
98
115
  const auth = await options.onAuth(server, sha256, type, blob);
99
- authEvents.push(auth);
100
- return auth;
116
+ return storeAuthEvent(authEvents, auth);
101
117
  } else throw new Error("Missing onAuth handler");
102
118
  };
103
119
 
104
- // handle payment requests for servers
105
- const handlePaymentRequest = async (server: S, sha256: string, _blog: any, request: PaymentRequest) => {
120
+ const handlePaymentRequest = async (server: S, sha256: string, _blob: any, request: PaymentRequest) => {
106
121
  if (!options.onPayment) throw new Error("Missing payment handler");
107
-
108
122
  return options.onPayment(server, sha256, blob, request);
109
123
  };
110
124
 
111
- // servers to upload the blob to
112
- const uploadServers = Array.from(servers);
125
+ const handleRejection = async (server: S, sha256: string, error: unknown): Promise<RejectionAction | false> => {
126
+ if (!HTTPError.isRejection(error)) return false;
113
127
 
114
- // start media upload
115
- if (options.isMedia) {
116
- const mediaServers = options.mediaUploadBehavior === "any" ? Array.from(servers) : [Array.from(servers)[0]];
117
-
118
- for (const server of mediaServers) {
119
- try {
120
- const sha256 = await getBlobSha256(blob);
121
- options.onStart?.(server, sha256, blob);
128
+ if (options.onRejection) {
129
+ return await options.onRejection(server, sha256, blob, error);
130
+ }
122
131
 
123
- // attempt to upload media
124
- initialUpload = await uploadMedia(server, blob, {
125
- onAuth: handleAuthRequest,
126
- onPayment: handlePaymentRequest,
127
- });
132
+ options.onError?.(server, sha256, blob, error);
133
+ return "skip";
134
+ };
128
135
 
129
- // save result
130
- results.set(server, initialUpload);
131
-
132
- // finished upload to server
133
- options.onUpload?.(server, initialUpload.sha256, blob);
134
- } catch (error) {
135
- if (error instanceof MediaEndpointMissingError) {
136
- // ignore error
137
- } else if (error instanceof Error) {
138
- const sha256 = await getBlobSha256(blob);
139
- options.onError?.(server, sha256, blob, error);
140
- }
141
- }
136
+ const uploadServers = Array.from(servers);
142
137
 
143
- if (initialUpload) {
144
- // remove server from upload array
145
- if (uploadServers.includes(server)) uploadServers.splice(uploadServers.indexOf(server), 1);
138
+ // parallel preflight: check which servers already have the blob
139
+ const serversWithBlob = new Set<S>();
140
+ if (options.preflight !== false && uploadServers.length > 0) {
141
+ const preflightResults = await Promise.allSettled(
142
+ uploadServers.map(async (server) => {
143
+ const exists = await hasBlob(server, blobSha256, {
144
+ signal: options.signal,
145
+ timeout: options.mirrorTimeout,
146
+ });
147
+ return { server, exists };
148
+ }),
149
+ );
146
150
 
147
- // exit on first successful media upload
148
- break;
151
+ for (const result of preflightResults) {
152
+ if (result.status === "fulfilled" && result.value.exists) {
153
+ serversWithBlob.add(result.value.server);
149
154
  }
150
155
  }
151
-
152
- if (!options.mediaUploadFallback && !initialUpload) {
153
- // failed to find a /media endpoint, abort
154
- throw new Error("Failed to find media processing endpoint");
155
- }
156
156
  }
157
157
 
158
- // start server uploads
158
+ // upload to each server
159
159
  for (const server of uploadServers) {
160
+ const serverHasBlob = serversWithBlob.has(server);
161
+
160
162
  try {
161
163
  let metadata: BlobDescriptor | undefined = undefined;
162
164
 
163
- // attempt to mirror the initial upload
164
- if (initialUpload) {
165
+ // attempt to mirror if we have an initial upload or server already has the blob
166
+ if (initialUpload || serverHasBlob) {
167
+ const mirrorSource = initialUpload ?? {
168
+ url: new URL("/" + blobSha256, server).toString(),
169
+ sha256: blobSha256,
170
+ size: 0,
171
+ uploaded: 0,
172
+ };
173
+
165
174
  try {
166
- options.onStart?.(server, initialUpload.sha256, blob);
175
+ options.onStart?.(server, blobSha256, blob);
167
176
 
168
- metadata = await mirrorBlob(server, initialUpload, {
177
+ metadata = await mirrorBlob(server, mirrorSource, {
169
178
  signal: options.signal,
179
+ auth: typeof options.auth === "boolean" ? options.auth : undefined,
170
180
  onAuth: (server, sha256) => handleAuthRequest(server, sha256, "upload"),
171
181
  onPayment: handlePaymentRequest,
172
182
  timeout: options.mirrorTimeout,
173
183
  });
174
184
  } catch (error) {
175
- // mirror failed, if isMedia skip server since we don't want to upload two versions of the blob
176
- if (options.isMedia) continue;
185
+ // mirror failed, if server already has blob skip upload fallback
186
+ if (serverHasBlob) continue;
177
187
  }
178
188
  }
179
189
 
180
- // attempt to upload if first upload or mirror failed
190
+ // attempt to upload if mirror failed
181
191
  if (!metadata) {
182
- const sha256 = await getBlobSha256(blob);
183
- options.onStart?.(server, sha256, blob);
192
+ options.onStart?.(server, blobSha256, blob);
184
193
 
185
194
  metadata = await uploadBlob(server, blob, {
195
+ signal: options.signal,
196
+ auth: typeof options.auth === "boolean" ? options.auth : undefined,
186
197
  onAuth: handleAuthRequest,
187
198
  onPayment: handlePaymentRequest,
188
199
  timeout: options.mirrorTimeout,
189
200
  });
190
201
 
191
- // save first upload
192
202
  if (!initialUpload) initialUpload = metadata;
193
203
  }
194
204
 
195
- // save result
196
205
  results.set(server, metadata);
206
+ options.onUpload?.(server, metadata.sha256, blob);
207
+ } catch (error) {
208
+ const rejection = await handleRejection(server, blobSha256, error);
209
+ if (rejection === "cancel") return results;
210
+ if (!rejection && error instanceof Error) options.onError?.(server, blobSha256, blob, error);
211
+ }
212
+ }
197
213
 
198
- // finished upload to server
214
+ return results;
215
+ }
216
+
217
+ /**
218
+ * Upload media to multiple servers using BUD-05 optimization
219
+ *
220
+ * Uploads the blob to a /media endpoint on one server for optimization,
221
+ * then mirrors the optimized result to the remaining servers.
222
+ * The blob is never re-uploaded to other servers since the /media endpoint may transform it.
223
+ *
224
+ * ```mermaid
225
+ * flowchart LR
226
+ * media["/media"] --> ifmedia{"Successful?"}
227
+ * ifmedia -- yes --> preflight["HEAD /<sha256>"]
228
+ * ifmedia -- no --> iffallback{"fallback?"}
229
+ * iffallback -- yes --> upload["multiServerUpload"]
230
+ * iffallback -- no --> abort
231
+ * preflight --> mirror["/mirror"]
232
+ * mirror --> next["Next server"]
233
+ * ```
234
+ */
235
+ export async function multiServerMediaUpload<S extends ServerType, B extends UploadType>(
236
+ servers: Iterable<S>,
237
+ blob: B,
238
+ opts?: MultiServerMediaUploadOptions<S, B>,
239
+ ) {
240
+ const options = { ...defaultMediaUploadOptions, ...opts };
241
+ let initialUpload: BlobDescriptor | undefined;
242
+ const results = new Map<S, BlobDescriptor>();
243
+ const authEvents = options.authEvents ?? new Set<SignedEvent>();
244
+ const blobSha256 = await getBlobSha256(blob);
245
+
246
+ if (typeof options.auth === "object") authEvents.add(options.auth);
247
+
248
+ const handleAuthRequest = async (server: S, sha256: string, type: "upload" | "media") => {
249
+ const reused = await getReusableAuthEvent(authEvents, { server, type, blob: sha256 });
250
+ if (reused) return reused;
251
+
252
+ if (options.onAuth) {
253
+ const auth = await options.onAuth(server, sha256, type, blob);
254
+ return storeAuthEvent(authEvents, auth);
255
+ } else throw new Error("Missing onAuth handler");
256
+ };
257
+
258
+ const handlePaymentRequest = async (server: S, sha256: string, _blob: any, request: PaymentRequest) => {
259
+ if (!options.onPayment) throw new Error("Missing payment handler");
260
+ return options.onPayment(server, sha256, blob, request);
261
+ };
262
+
263
+ const handleRejection = async (server: S, sha256: string, error: unknown): Promise<RejectionAction | false> => {
264
+ if (!HTTPError.isRejection(error)) return false;
265
+
266
+ if (options.onRejection) {
267
+ return await options.onRejection(server, sha256, blob, error);
268
+ }
269
+
270
+ options.onError?.(server, sha256, blob, error);
271
+ return "skip";
272
+ };
273
+
274
+ const allServers = Array.from(servers);
275
+ const mediaServers = options.mediaUploadBehavior === "any" ? Array.from(allServers) : [allServers[0]];
276
+ let mediaUploadServer: S | undefined;
277
+
278
+ // phase 1: upload to /media on one server for optimization
279
+ for (const server of mediaServers) {
280
+ try {
281
+ options.onStart?.(server, blobSha256, blob);
282
+
283
+ initialUpload = await uploadMedia(server, blob, {
284
+ signal: options.signal,
285
+ auth: typeof options.auth === "boolean" ? options.auth : undefined,
286
+ onAuth: handleAuthRequest,
287
+ onPayment: handlePaymentRequest,
288
+ });
289
+
290
+ results.set(server, initialUpload);
291
+ mediaUploadServer = server;
292
+ options.onUpload?.(server, initialUpload.sha256, blob);
293
+ } catch (error) {
294
+ if (error instanceof MediaEndpointMissingError) {
295
+ // ignore, try next server
296
+ } else {
297
+ const rejection = await handleRejection(server, blobSha256, error);
298
+ if (rejection === "cancel") return results;
299
+ if (!rejection && error instanceof Error) {
300
+ options.onError?.(server, blobSha256, blob, error);
301
+ }
302
+ }
303
+ }
304
+
305
+ if (initialUpload) break;
306
+ }
307
+
308
+ // if no /media endpoint found, fall back to regular upload or abort
309
+ if (!initialUpload) {
310
+ if (!options.mediaUploadFallback) {
311
+ throw new Error("Failed to find media processing endpoint");
312
+ }
313
+
314
+ // fall back to regular multi-server upload
315
+ return multiServerUpload(servers, blob, options);
316
+ }
317
+
318
+ // phase 2: mirror the optimized blob to remaining servers
319
+ const remainingServers = allServers.filter((s) => s !== mediaUploadServer);
320
+
321
+ // parallel preflight on remaining servers using the optimized blob's sha256
322
+ const serversWithBlob = new Set<S>();
323
+ if (options.preflight !== false && remainingServers.length > 0) {
324
+ const preflightResults = await Promise.allSettled(
325
+ remainingServers.map(async (server) => {
326
+ const exists = await hasBlob(server, initialUpload!.sha256, {
327
+ signal: options.signal,
328
+ timeout: options.mirrorTimeout,
329
+ });
330
+ return { server, exists };
331
+ }),
332
+ );
333
+
334
+ for (const result of preflightResults) {
335
+ if (result.status === "fulfilled" && result.value.exists) {
336
+ serversWithBlob.add(result.value.server);
337
+ }
338
+ }
339
+ }
340
+
341
+ // mirror to remaining servers
342
+ for (const server of remainingServers) {
343
+ try {
344
+ options.onStart?.(server, initialUpload.sha256, blob);
345
+
346
+ const metadata = await mirrorBlob(server, initialUpload, {
347
+ signal: options.signal,
348
+ auth: typeof options.auth === "boolean" ? options.auth : undefined,
349
+ onAuth: (server, sha256) => handleAuthRequest(server, sha256, "upload"),
350
+ onPayment: handlePaymentRequest,
351
+ timeout: options.mirrorTimeout,
352
+ });
353
+
354
+ results.set(server, metadata);
199
355
  options.onUpload?.(server, metadata.sha256, blob);
200
356
  } catch (error) {
201
- // failed to upload to server
202
- if (error instanceof Error) options.onError?.(server, await getBlobSha256(blob), blob, error);
357
+ const rejection = await handleRejection(server, initialUpload.sha256, error);
358
+ if (rejection === "cancel") return results;
359
+ if (!rejection && error instanceof Error) options.onError?.(server, initialUpload.sha256, blob, error);
203
360
  }
204
361
  }
205
362
 
@@ -0,0 +1,54 @@
1
+ import HTTPError from "../error.js";
2
+ import { fetchWithTimeout } from "../helpers/fetch.js";
3
+ import { ServerType, SignedEvent } from "../types.js";
4
+
5
+ export type ReportOptions<S extends ServerType> = {
6
+ /** AbortSignal to cancel the action */
7
+ signal?: AbortSignal;
8
+ /** Request timeout */
9
+ timeout?: number;
10
+ /** Called when reporting to a server fails */
11
+ onError?: (server: S, error: Error) => void;
12
+ };
13
+
14
+ function isBlobReportEvent(report: SignedEvent) {
15
+ return report.kind === 1984 && report.tags.some((tag) => tag[0] === "x" && !!tag[1]);
16
+ }
17
+
18
+ /** Sends a signed NIP-56 report event to multiple servers */
19
+ export async function reportBlobs<S extends ServerType>(
20
+ servers: Iterable<S>,
21
+ report: SignedEvent,
22
+ opts?: ReportOptions<S>,
23
+ ): Promise<Map<S, boolean>> {
24
+ if (!isBlobReportEvent(report)) throw new Error("Invalid blob report event");
25
+
26
+ const results = new Map<S, boolean>();
27
+ const body = JSON.stringify(report);
28
+
29
+ for (const server of servers) {
30
+ try {
31
+ const res = await fetchWithTimeout(new URL("/report", server), {
32
+ method: "PUT",
33
+ headers: { "Content-Type": "application/json" },
34
+ body,
35
+ signal: opts?.signal,
36
+ timeout: opts?.timeout,
37
+ });
38
+
39
+ await HTTPError.handleErrorResponse(res);
40
+ results.set(server, true);
41
+ } catch (error) {
42
+ if (
43
+ opts?.signal?.aborted ||
44
+ (error instanceof Error &&
45
+ (error.name === "AbortError" || error.name === "TimeoutError" || error.message === "Timeout"))
46
+ ) {
47
+ throw error;
48
+ }
49
+ if (error instanceof Error) opts?.onError?.(server, error);
50
+ }
51
+ }
52
+
53
+ return results;
54
+ }
@@ -0,0 +1,159 @@
1
+ import { BlossomURI, blossomURIFromURL, parseBlossomURI } from "../helpers/blossom-uri.js";
2
+ import { fetchWithTimeout } from "../helpers/fetch.js";
3
+ import { DownloadOptions } from "./download.js";
4
+
5
+ type GetServers = (pubkey: string) => Promise<(string | URL)[] | undefined>;
6
+
7
+ export type ResolveOptions = Omit<DownloadOptions<string | URL>, "onAuth" | "onPayment"> & {
8
+ /** Callback to resolve author pubkeys to ordered server lists (e.g. kind 10063 lookup) */
9
+ getServers?: GetServers;
10
+ /** Additional fallback servers to try after URI hints */
11
+ fallbackServers?: (string | URL)[];
12
+ };
13
+
14
+ function normalizeServer(server: string | URL): string {
15
+ if (server instanceof URL) return server.origin;
16
+
17
+ // if it looks like a bare domain, try https first
18
+ if (!server.includes("://")) return `https://${server}`;
19
+
20
+ try {
21
+ return new URL(server).origin;
22
+ } catch {
23
+ return `https://${server}`;
24
+ }
25
+ }
26
+
27
+ function parseInput(uri: string | URL | BlossomURI): BlossomURI {
28
+ return uri instanceof URL ? blossomURIFromURL(uri) : typeof uri === "string" ? parseBlossomURI(uri) : uri;
29
+ }
30
+
31
+ function buildBlobPath(sha256: string, ext?: string): string {
32
+ return ext ? `/${sha256}.${ext}` : `/${sha256}`;
33
+ }
34
+
35
+ /** Deduplicating server collector — normalizes and tracks seen servers */
36
+ function createServerCollector(path: string) {
37
+ const seen = new Set<string>();
38
+ return {
39
+ get size() {
40
+ return seen.size;
41
+ },
42
+ add(sources: (string | URL)[]): string[] {
43
+ const urls: string[] = [];
44
+ for (const server of sources) {
45
+ const normalized = normalizeServer(server);
46
+ if (!seen.has(normalized)) {
47
+ seen.add(normalized);
48
+ urls.push(normalized + path);
49
+ }
50
+ }
51
+ return urls;
52
+ },
53
+ };
54
+ }
55
+
56
+ export type GetBlobUrlsOptions = {
57
+ /** Callback to resolve author pubkeys to ordered server lists (e.g. kind 10063 lookup) */
58
+ getServers?: GetServers;
59
+ /** Additional fallback servers to try after URI hints */
60
+ fallbackServers?: (string | URL)[];
61
+ };
62
+
63
+ /**
64
+ * Returns an ordered list of URLs for a blob without fetching anything.
65
+ * Resolves servers from xs hints, author hints (via getServers callback), and fallback servers.
66
+ *
67
+ * Accepts a blossom URI string, URL, or pre-parsed BlossomURI.
68
+ */
69
+ export async function getBlobUrls(
70
+ uri: string | URL | BlossomURI,
71
+ opts?: GetBlobUrlsOptions,
72
+ ): Promise<string[]> {
73
+ const parsed = parseInput(uri);
74
+ const collector = createServerCollector(buildBlobPath(parsed.sha256, parsed.ext));
75
+ const urls: string[] = [];
76
+
77
+ // 1. xs server hints (synchronous)
78
+ urls.push(...collector.add(parsed.servers));
79
+
80
+ // 2. author hints (async — requires relay queries)
81
+ if (opts?.getServers) {
82
+ for (const pubkey of parsed.authors) {
83
+ const authorServers = await opts.getServers(pubkey);
84
+ if (authorServers) urls.push(...collector.add(authorServers));
85
+ }
86
+ }
87
+
88
+ // 3. fallback servers
89
+ if (opts?.fallbackServers) urls.push(...collector.add(opts.fallbackServers));
90
+
91
+ return urls;
92
+ }
93
+
94
+ /** Resolves a blossom URI to a downloaded blob by trying servers from hints sequentially */
95
+ export async function resolveBlob(uri: string | URL | BlossomURI, opts?: ResolveOptions): Promise<Response> {
96
+ const parsed = parseInput(uri);
97
+ const collector = createServerCollector(buildBlobPath(parsed.sha256, parsed.ext));
98
+
99
+ /** Try GET on each URL, return the first successful response */
100
+ const tryUrls = async (urls: string[]): Promise<Response | undefined> => {
101
+ for (const url of urls) {
102
+ try {
103
+ const res = await fetchWithTimeout(new URL(url), {
104
+ signal: opts?.signal,
105
+ timeout: opts?.timeout,
106
+ });
107
+
108
+ if (res.ok) return res;
109
+ } catch {
110
+ // server unreachable or error — try next
111
+ continue;
112
+ }
113
+ }
114
+ return undefined;
115
+ };
116
+
117
+ // 1. try xs server hints first (fastest — no async resolution needed)
118
+ const xsUrls = collector.add(parsed.servers);
119
+ if (xsUrls.length > 0) {
120
+ const result = await tryUrls(xsUrls);
121
+ if (result) return result;
122
+ }
123
+
124
+ // 2. resolve and try author hints (deferred — requires relay queries)
125
+ if (opts?.getServers) {
126
+ for (const pubkey of parsed.authors) {
127
+ const authorServers = await opts.getServers(pubkey);
128
+ if (authorServers) {
129
+ const urls = collector.add(authorServers);
130
+ if (urls.length > 0) {
131
+ const result = await tryUrls(urls);
132
+ if (result) return result;
133
+ }
134
+ }
135
+ }
136
+ }
137
+
138
+ // 3. try fallback servers
139
+ if (opts?.fallbackServers) {
140
+ const urls = collector.add(opts.fallbackServers);
141
+ if (urls.length > 0) {
142
+ const result = await tryUrls(urls);
143
+ if (result) return result;
144
+ }
145
+ }
146
+
147
+ if (collector.size === 0) {
148
+ throw new Error("No servers available to resolve blossom URI");
149
+ }
150
+
151
+ throw new Error(`Blob ${parsed.sha256} not found on any server`);
152
+ }
153
+
154
+ /** Resolves a blossom URI and returns a blob: object URL that works anywhere a URL string is accepted */
155
+ export async function resolveToObjectURL(uri: string | URL | BlossomURI, opts?: ResolveOptions): Promise<string> {
156
+ const response = await resolveBlob(uri, opts);
157
+ const blob = await response.blob();
158
+ return URL.createObjectURL(blob);
159
+ }