blossom-client-sdk 5.0.0-0 → 5.0.0-2

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
@@ -117,7 +117,9 @@ cleanup();
117
117
  Media elements can use `blossom:` URIs directly in the `src` attribute. The fallback handler will automatically resolve the URI to HTTP URLs using the server hints:
118
118
 
119
119
  ```html
120
- <img src="blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?xs=https://cdn1.com&xs=https://cdn2.com" />
120
+ <img
121
+ src="blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?xs=https://cdn1.com&xs=https://cdn2.com"
122
+ />
121
123
  ```
122
124
 
123
125
  When the browser can't load the `blossom:` protocol, the error handler parses the URI, resolves server URLs from `xs` and `as` hints, and sets the first working URL.
@@ -55,7 +55,7 @@ export async function deleteBlob(server, hash, opts) {
55
55
  throw new Error("Missing payment handler");
56
56
  const { getEncodedToken } = await import("@cashu/cashu-ts");
57
57
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
58
- const request = getPaymentRequestFromHeaders(res.headers);
58
+ const request = await getPaymentRequestFromHeaders(res.headers);
59
59
  const token = await opts.onPayment(server, hash, request);
60
60
  const payment = getEncodedToken(token);
61
61
  // Try delete with payment
@@ -53,7 +53,7 @@ export async function downloadBlob(server, hash, opts) {
53
53
  throw new Error("Missing payment handler");
54
54
  const { getEncodedToken } = await import("@cashu/cashu-ts");
55
55
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
56
- const request = getPaymentRequestFromHeaders(download.headers);
56
+ const request = await getPaymentRequestFromHeaders(download.headers);
57
57
  const token = await opts.onPayment(server, hash, request);
58
58
  const payment = getEncodedToken(token);
59
59
  // Try download with payment
@@ -55,7 +55,7 @@ export async function listBlobs(server, pubkey, opts) {
55
55
  throw new Error("Missing payment handler");
56
56
  const { getEncodedToken } = await import("@cashu/cashu-ts");
57
57
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
58
- const request = getPaymentRequestFromHeaders(list.headers);
58
+ const request = await getPaymentRequestFromHeaders(list.headers);
59
59
  const token = await opts.onPayment(server, request);
60
60
  const payment = getEncodedToken(token);
61
61
  // Try list with payment
@@ -75,7 +75,7 @@ export async function uploadMedia(server, blob, opts) {
75
75
  throw new Error("Missing payment handler");
76
76
  const { getEncodedToken } = await import("@cashu/cashu-ts");
77
77
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
78
- const request = getPaymentRequestFromHeaders(firstTry.headers);
78
+ const request = await getPaymentRequestFromHeaders(firstTry.headers);
79
79
  const token = await opts.onPayment(server, sha256, blob, request);
80
80
  const payment = getEncodedToken(token);
81
81
  // Try upload with payment
@@ -63,7 +63,7 @@ export async function mirrorBlob(server, blob, opts) {
63
63
  throw new Error("Missing payment handler");
64
64
  const { getEncodedToken } = await import("@cashu/cashu-ts");
65
65
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
66
- const request = getPaymentRequestFromHeaders(mirror.headers);
66
+ const request = await getPaymentRequestFromHeaders(mirror.headers);
67
67
  const token = await opts.onPayment(server, blob.sha256, blob, request);
68
68
  const payment = getEncodedToken(token);
69
69
  // Try mirror with payment
@@ -78,7 +78,7 @@ export async function uploadBlob(server, blob, opts) {
78
78
  throw new Error("Missing payment handler");
79
79
  const { getEncodedToken } = await import("@cashu/cashu-ts");
80
80
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
81
- const request = getPaymentRequestFromHeaders(firstTry.headers);
81
+ const request = await getPaymentRequestFromHeaders(firstTry.headers);
82
82
  const token = await opts.onPayment(server, sha256, blob, request);
83
83
  const payment = getEncodedToken(token);
84
84
  // Try upload with payment
@@ -1,5 +1,5 @@
1
1
  import { PaymentRequest } from "../types.js";
2
- /** Extracts a cashu-ts PaymentRequest from Headers */
3
- export declare function getPaymentRequestFromHeaders(headers: Headers): PaymentRequest;
4
- export declare function getPaymentRequestFromHeaders(headers: Headers, quite: false): PaymentRequest;
5
- export declare function getPaymentRequestFromHeaders(headers: Headers, quite: true): PaymentRequest | undefined;
2
+ /** Extracts a cashu-ts PaymentRequest from Headers. Loads @cashu/cashu-ts on demand. */
3
+ export declare function getPaymentRequestFromHeaders(headers: Headers): Promise<PaymentRequest>;
4
+ export declare function getPaymentRequestFromHeaders(headers: Headers, quite: false): Promise<PaymentRequest>;
5
+ export declare function getPaymentRequestFromHeaders(headers: Headers, quite: true): Promise<PaymentRequest | undefined>;
@@ -1,5 +1,4 @@
1
- import { decodePaymentRequest } from "@cashu/cashu-ts";
2
- export function getPaymentRequestFromHeaders(headers, quite = false) {
1
+ export async function getPaymentRequestFromHeaders(headers, quite = false) {
3
2
  const header = headers.get("X-Cashu");
4
3
  if (!header) {
5
4
  if (!quite)
@@ -7,6 +6,7 @@ export function getPaymentRequestFromHeaders(headers, quite = false) {
7
6
  else
8
7
  return undefined;
9
8
  }
9
+ const { decodePaymentRequest } = await import("@cashu/cashu-ts");
10
10
  const request = decodePaymentRequest(header);
11
11
  // Clear the transport, since NUT-23 is only in-band payments
12
12
  request.transport = [];
package/lib/media.js CHANGED
@@ -1,6 +1,6 @@
1
- import { getHashFromURL } from "./helpers/url.js";
2
- import { parseBlossomURI } from "./helpers/blossom-uri.js";
3
1
  import { getBlobUrls } from "./actions/resolve.js";
2
+ import { parseBlossomURI } from "./helpers/blossom-uri.js";
3
+ import { getHashFromURL } from "./helpers/url.js";
4
4
  /**
5
5
  * Attaches an "error" event listener to a media element (img, video, audio) to handle server fallbacks.
6
6
  *
@@ -22,9 +22,7 @@ export function handleMediaFallbacks(element, getServers, overridePubkey) {
22
22
  const resolveBlossomUri = async (src) => {
23
23
  const parsed = parseBlossomURI(src);
24
24
  return getBlobUrls(parsed, {
25
- getServers: getServers
26
- ? async (pubkey) => (await getServers(pubkey)) ?? undefined
27
- : undefined,
25
+ getServers: getServers ? async (pubkey) => (await getServers(pubkey)) ?? undefined : undefined,
28
26
  });
29
27
  };
30
28
  /** Resolve an HTTP blob URL into fallback URLs via pubkey server lookup */
@@ -33,7 +31,6 @@ export function handleMediaFallbacks(element, getServers, overridePubkey) {
33
31
  if (!hash)
34
32
  return undefined;
35
33
  const url = new URL(element.src);
36
- const ext = url.pathname.match(/\.\w+$/i);
37
34
  let pubkey = overridePubkey;
38
35
  // walk up the tree looking for pubkey
39
36
  let el = element;
@@ -50,15 +47,7 @@ export function handleMediaFallbacks(element, getServers, overridePubkey) {
50
47
  const servers = (await getServers(pubkey))?.map((s) => (s instanceof URL ? s : new URL(s)));
51
48
  if (!servers)
52
49
  return undefined;
53
- return servers
54
- .filter((s) => s.hostname !== url.hostname)
55
- .map((s) => {
56
- const u = new URL(url);
57
- u.hostname = s.hostname;
58
- u.protocol = s.protocol;
59
- u.pathname = "/" + hash + (ext?.[0] ?? "");
60
- return u.toString();
61
- });
50
+ return servers.filter((s) => s.hostname !== url.hostname).map((s) => new URL(url.pathname, s).toString());
62
51
  };
63
52
  const onError = async () => {
64
53
  // Already resolved — try the next URL in the list
@@ -88,8 +77,23 @@ export function handleMediaFallbacks(element, getServers, overridePubkey) {
88
77
  }
89
78
  };
90
79
  element.addEventListener("error", onError);
80
+ // Trigger resolution immediately if:
81
+ // - src is a blossom: URI (browser can't load it natively)
82
+ // - element already failed to load before we attached the listener
83
+ const rawSrc = element.getAttribute("src") || "";
84
+ if (rawSrc.startsWith("blossom:") || hasFailedToLoad(element)) {
85
+ onError();
86
+ }
91
87
  return () => element.removeEventListener("error", onError);
92
88
  }
89
+ /** Returns true if a media element has already finished loading and failed */
90
+ function hasFailedToLoad(element) {
91
+ if (element instanceof HTMLImageElement) {
92
+ return element.complete && element.naturalWidth === 0;
93
+ }
94
+ // video/audio — check if loading resulted in an error
95
+ return element.error !== null;
96
+ }
93
97
  const MEDIA_SELECTOR = "img[src], video[src], audio[src]";
94
98
  function isMediaElement(node) {
95
99
  return node instanceof HTMLImageElement || node instanceof HTMLVideoElement || node instanceof HTMLAudioElement;
package/lib/types.d.ts CHANGED
@@ -5,7 +5,6 @@ import { MirrorOptions } from "./actions/mirror.js";
5
5
  import { UploadOptions } from "./actions/upload.js";
6
6
  export type ServerType = string | URL;
7
7
  export type UploadType = Blob | File | Buffer;
8
- import { type PaymentRequest as CashuPaymentRequest } from "@cashu/cashu-ts";
9
8
  export type EventTemplate = {
10
9
  created_at: number;
11
10
  kind: number;
@@ -34,8 +33,39 @@ export type BlobDescriptor = {
34
33
  size: number;
35
34
  url: string;
36
35
  };
37
- export type PaymentRequest = CashuPaymentRequest;
38
36
  export type RejectionAction = "skip" | "cancel";
37
+ export type PaymentRequestTransport = {
38
+ type: string;
39
+ target: string;
40
+ tags?: Array<Array<string>>;
41
+ };
42
+ export type RawTransport = {
43
+ t: string;
44
+ a: string;
45
+ g?: Array<Array<string>>;
46
+ };
47
+ export type RawPaymentRequest = {
48
+ i?: string;
49
+ a?: number;
50
+ u?: string;
51
+ s?: boolean;
52
+ m?: Array<string>;
53
+ d?: string;
54
+ t: Array<RawTransport>;
55
+ };
56
+ /** Copy of the PaymentRequest class shape from cashu-ts */
57
+ export type PaymentRequest = {
58
+ transport: Array<PaymentRequestTransport>;
59
+ id?: string;
60
+ amount?: number;
61
+ unit?: string;
62
+ mints?: Array<string>;
63
+ description?: string;
64
+ singleUse: boolean;
65
+ toRawRequest(): RawPaymentRequest;
66
+ toEncodedRequest(): string;
67
+ getTransport(type: string): PaymentRequestTransport | undefined;
68
+ };
39
69
  type SerializedDLEQ = {
40
70
  s: string;
41
71
  e: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "blossom-client-sdk",
3
- "version": "5.0.0-0",
3
+ "version": "5.0.0-2",
4
4
  "description": "Client SDK for talking to blossom servers",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -54,18 +54,22 @@
54
54
  "node": ">=18"
55
55
  },
56
56
  "dependencies": {
57
- "@cashu/cashu-ts": "^2.4.3",
58
57
  "@noble/hashes": "^1.8.0"
59
58
  },
60
59
  "peerDependencies": {
60
+ "@cashu/cashu-ts": "^2.4.3",
61
61
  "hls.js": "^1.6.16"
62
62
  },
63
63
  "peerDependenciesMeta": {
64
+ "@cashu/cashu-ts": {
65
+ "optional": true
66
+ },
64
67
  "hls.js": {
65
68
  "optional": true
66
69
  }
67
70
  },
68
71
  "devDependencies": {
72
+ "@cashu/cashu-ts": "^2.4.3",
69
73
  "@changesets/cli": "^2.29.3",
70
74
  "@testing-library/dom": "^10.4.0",
71
75
  "@types/node": "^22.15.14",
@@ -84,7 +84,7 @@ export async function deleteBlob<S extends ServerType>(server: S, hash: string,
84
84
  if (!opts?.onPayment) throw new Error("Missing payment handler");
85
85
  const { getEncodedToken } = await import("@cashu/cashu-ts");
86
86
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
87
- const request = getPaymentRequestFromHeaders(res.headers);
87
+ const request = await getPaymentRequestFromHeaders(res.headers);
88
88
 
89
89
  const token = await opts.onPayment(server, hash, request);
90
90
  const payment = getEncodedToken(token);
@@ -83,7 +83,7 @@ export async function downloadBlob<S extends ServerType>(server: S, hash: string
83
83
  if (!opts?.onPayment) throw new Error("Missing payment handler");
84
84
  const { getEncodedToken } = await import("@cashu/cashu-ts");
85
85
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
86
- const request = getPaymentRequestFromHeaders(download.headers);
86
+ const request = await getPaymentRequestFromHeaders(download.headers);
87
87
 
88
88
  const token = await opts.onPayment(server, hash, request);
89
89
  const payment = getEncodedToken(token);
@@ -86,7 +86,7 @@ export async function listBlobs<S extends ServerType>(
86
86
  if (!opts?.onPayment) throw new Error("Missing payment handler");
87
87
  const { getEncodedToken } = await import("@cashu/cashu-ts");
88
88
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
89
- const request = getPaymentRequestFromHeaders(list.headers);
89
+ const request = await getPaymentRequestFromHeaders(list.headers);
90
90
 
91
91
  const token = await opts.onPayment(server, request);
92
92
  const payment = getEncodedToken(token);
@@ -90,7 +90,7 @@ export async function uploadMedia<S extends ServerType, B extends UploadType>(
90
90
  if (!opts?.onPayment) throw new Error("Missing payment handler");
91
91
  const { getEncodedToken } = await import("@cashu/cashu-ts");
92
92
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
93
- const request = getPaymentRequestFromHeaders(firstTry.headers);
93
+ const request = await getPaymentRequestFromHeaders(firstTry.headers);
94
94
 
95
95
  const token = await opts.onPayment(server, sha256, blob, request);
96
96
  const payment = getEncodedToken(token);
@@ -97,7 +97,7 @@ export async function mirrorBlob<S extends ServerType>(
97
97
  if (!opts?.onPayment) throw new Error("Missing payment handler");
98
98
  const { getEncodedToken } = await import("@cashu/cashu-ts");
99
99
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
100
- const request = getPaymentRequestFromHeaders(mirror.headers);
100
+ const request = await getPaymentRequestFromHeaders(mirror.headers);
101
101
 
102
102
  const token = await opts.onPayment(server, blob.sha256, blob, request);
103
103
  const payment = getEncodedToken(token);
@@ -66,10 +66,7 @@ export type GetBlobUrlsOptions = {
66
66
  *
67
67
  * Accepts a blossom URI string, URL, or pre-parsed BlossomURI.
68
68
  */
69
- export async function getBlobUrls(
70
- uri: string | URL | BlossomURI,
71
- opts?: GetBlobUrlsOptions,
72
- ): Promise<string[]> {
69
+ export async function getBlobUrls(uri: string | URL | BlossomURI, opts?: GetBlobUrlsOptions): Promise<string[]> {
73
70
  const parsed = parseInput(uri);
74
71
  const collector = createServerCollector(buildBlobPath(parsed.sha256, parsed.ext));
75
72
  const urls: string[] = [];
@@ -115,7 +115,7 @@ export async function uploadBlob<S extends ServerType, B extends UploadType>(
115
115
  if (!opts?.onPayment) throw new Error("Missing payment handler");
116
116
  const { getEncodedToken } = await import("@cashu/cashu-ts");
117
117
  const { getPaymentRequestFromHeaders } = await import("../helpers/cashu.js");
118
- const request = getPaymentRequestFromHeaders(firstTry.headers);
118
+ const request = await getPaymentRequestFromHeaders(firstTry.headers);
119
119
 
120
120
  const token = await opts.onPayment(server, sha256, blob, request);
121
121
  const payment = getEncodedToken(token);
@@ -1,18 +1,18 @@
1
- import { decodePaymentRequest } from "@cashu/cashu-ts";
2
1
  import { PaymentRequest } from "../types.js";
3
2
 
4
- /** Extracts a cashu-ts PaymentRequest from Headers */
5
- export function getPaymentRequestFromHeaders(headers: Headers): PaymentRequest;
6
- export function getPaymentRequestFromHeaders(headers: Headers, quite: false): PaymentRequest;
7
- export function getPaymentRequestFromHeaders(headers: Headers, quite: true): PaymentRequest | undefined;
8
- export function getPaymentRequestFromHeaders(headers: Headers, quite = false) {
3
+ /** Extracts a cashu-ts PaymentRequest from Headers. Loads @cashu/cashu-ts on demand. */
4
+ export async function getPaymentRequestFromHeaders(headers: Headers): Promise<PaymentRequest>;
5
+ export async function getPaymentRequestFromHeaders(headers: Headers, quite: false): Promise<PaymentRequest>;
6
+ export async function getPaymentRequestFromHeaders(headers: Headers, quite: true): Promise<PaymentRequest | undefined>;
7
+ export async function getPaymentRequestFromHeaders(headers: Headers, quite = false) {
9
8
  const header = headers.get("X-Cashu");
10
9
  if (!header) {
11
10
  if (!quite) throw new Error("Missing cashu header");
12
11
  else return undefined;
13
12
  }
14
13
 
15
- const request = decodePaymentRequest(header);
14
+ const { decodePaymentRequest } = await import("@cashu/cashu-ts");
15
+ const request = decodePaymentRequest(header) as PaymentRequest;
16
16
 
17
17
  // Clear the transport, since NUT-23 is only in-band payments
18
18
  request.transport = [];
package/src/media.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { getHashFromURL } from "./helpers/url.js";
2
- import { parseBlossomURI } from "./helpers/blossom-uri.js";
3
1
  import { getBlobUrls } from "./actions/resolve.js";
2
+ import { parseBlossomURI } from "./helpers/blossom-uri.js";
3
+ import { getHashFromURL } from "./helpers/url.js";
4
4
 
5
5
  type MediaElement = HTMLImageElement | HTMLVideoElement | HTMLAudioElement;
6
6
 
@@ -28,9 +28,7 @@ export function handleMediaFallbacks(element: MediaElement, getServers: GetServe
28
28
  const resolveBlossomUri = async (src: string): Promise<string[]> => {
29
29
  const parsed = parseBlossomURI(src);
30
30
  return getBlobUrls(parsed, {
31
- getServers: getServers
32
- ? async (pubkey) => (await getServers(pubkey)) ?? undefined
33
- : undefined,
31
+ getServers: getServers ? async (pubkey) => (await getServers(pubkey)) ?? undefined : undefined,
34
32
  });
35
33
  };
36
34
 
@@ -40,7 +38,6 @@ export function handleMediaFallbacks(element: MediaElement, getServers: GetServe
40
38
  if (!hash) return undefined;
41
39
 
42
40
  const url = new URL(element.src);
43
- const ext = url.pathname.match(/\.\w+$/i);
44
41
 
45
42
  let pubkey = overridePubkey;
46
43
 
@@ -59,15 +56,7 @@ export function handleMediaFallbacks(element: MediaElement, getServers: GetServe
59
56
  const servers = (await getServers(pubkey))?.map((s) => (s instanceof URL ? s : new URL(s)));
60
57
  if (!servers) return undefined;
61
58
 
62
- return servers
63
- .filter((s) => s.hostname !== url.hostname)
64
- .map((s) => {
65
- const u = new URL(url);
66
- u.hostname = s.hostname;
67
- u.protocol = s.protocol;
68
- u.pathname = "/" + hash + (ext?.[0] ?? "");
69
- return u.toString();
70
- });
59
+ return servers.filter((s) => s.hostname !== url.hostname).map((s) => new URL(url.pathname, s).toString());
71
60
  };
72
61
 
73
62
  const onError = async () => {
@@ -100,9 +89,26 @@ export function handleMediaFallbacks(element: MediaElement, getServers: GetServe
100
89
 
101
90
  element.addEventListener("error", onError);
102
91
 
92
+ // Trigger resolution immediately if:
93
+ // - src is a blossom: URI (browser can't load it natively)
94
+ // - element already failed to load before we attached the listener
95
+ const rawSrc = element.getAttribute("src") || "";
96
+ if (rawSrc.startsWith("blossom:") || hasFailedToLoad(element)) {
97
+ onError();
98
+ }
99
+
103
100
  return () => element.removeEventListener("error", onError);
104
101
  }
105
102
 
103
+ /** Returns true if a media element has already finished loading and failed */
104
+ function hasFailedToLoad(element: MediaElement): boolean {
105
+ if (element instanceof HTMLImageElement) {
106
+ return element.complete && element.naturalWidth === 0;
107
+ }
108
+ // video/audio — check if loading resulted in an error
109
+ return element.error !== null;
110
+ }
111
+
106
112
  const MEDIA_SELECTOR = "img[src], video[src], audio[src]";
107
113
 
108
114
  function isMediaElement(node: Node): node is MediaElement {
package/src/types.ts CHANGED
@@ -5,7 +5,6 @@ import { MirrorOptions } from "./actions/mirror.js";
5
5
  import { UploadOptions } from "./actions/upload.js";
6
6
  export type ServerType = string | URL;
7
7
  export type UploadType = Blob | File | Buffer;
8
- import { type PaymentRequest as CashuPaymentRequest } from "@cashu/cashu-ts";
9
8
 
10
9
  export type EventTemplate = {
11
10
  created_at: number;
@@ -39,11 +38,47 @@ export type BlobDescriptor = {
39
38
  url: string;
40
39
  };
41
40
 
42
- export type PaymentRequest = CashuPaymentRequest;
43
-
44
41
  export type RejectionAction = "skip" | "cancel";
45
42
 
46
- // NOTE: hack for Token type not being exported from cashu-ts
43
+ // NOTE: structural copies of cashu-ts types so @cashu/cashu-ts can stay an
44
+ // optional peer dependency. Keep field shapes in sync with cashu-ts upstream.
45
+
46
+ export type PaymentRequestTransport = {
47
+ type: string;
48
+ target: string;
49
+ tags?: Array<Array<string>>;
50
+ };
51
+
52
+ export type RawTransport = {
53
+ t: string;
54
+ a: string;
55
+ g?: Array<Array<string>>;
56
+ };
57
+
58
+ export type RawPaymentRequest = {
59
+ i?: string;
60
+ a?: number;
61
+ u?: string;
62
+ s?: boolean;
63
+ m?: Array<string>;
64
+ d?: string;
65
+ t: Array<RawTransport>;
66
+ };
67
+
68
+ /** Copy of the PaymentRequest class shape from cashu-ts */
69
+ export type PaymentRequest = {
70
+ transport: Array<PaymentRequestTransport>;
71
+ id?: string;
72
+ amount?: number;
73
+ unit?: string;
74
+ mints?: Array<string>;
75
+ description?: string;
76
+ singleUse: boolean;
77
+ toRawRequest(): RawPaymentRequest;
78
+ toEncodedRequest(): string;
79
+ getTransport(type: string): PaymentRequestTransport | undefined;
80
+ };
81
+
47
82
  type SerializedDLEQ = {
48
83
  s: string;
49
84
  e: string;