disband 0.1.0 → 0.2.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.
package/README.md CHANGED
@@ -87,6 +87,26 @@ try {
87
87
  }
88
88
  ```
89
89
 
90
+ ### Receive a webhook
91
+
92
+ ```ts
93
+ import { verifyWebhook } from "disband";
94
+
95
+ await disband.separations.create(song, {
96
+ stems: ["vocals"],
97
+ webhook: "https://example.com/disband",
98
+ });
99
+
100
+ // at https://example.com/disband
101
+ export default {
102
+ async fetch(request: Request, env: { DISBAND_WEBHOOK_SECRET: string }) {
103
+ const separation = await verifyWebhook(request, env.DISBAND_WEBHOOK_SECRET);
104
+ if (separation === undefined) return new Response(null, { status: 400 });
105
+ return new Response(null, { status: 204 });
106
+ },
107
+ };
108
+ ```
109
+
90
110
  ## Requirements
91
111
 
92
112
  - Node.js 22.12 or later
package/dist/create.d.ts CHANGED
@@ -8,5 +8,7 @@ export type CreateOptions = RequestOptions & {
8
8
  formats?: Format[];
9
9
  /** The File's name when omitted. */
10
10
  name?: string;
11
+ /** An `https` URL the separation is posted to once it is `ready` or `failed`. */
12
+ webhook?: string;
11
13
  };
12
- export declare function create(api: Api, audio: Audio, { stems, formats, name, signal }: CreateOptions): Promise<Separation>;
14
+ export declare function create(api: Api, audio: Audio, { stems, formats, name, webhook, signal }: CreateOptions): Promise<Separation>;
package/dist/create.js CHANGED
@@ -2,7 +2,7 @@ import { read, separationPath } from "./read.js";
2
2
  import { errorOf } from "./error.js";
3
3
  // the largest file sent as the request body
4
4
  const bodyLimit = 100_000_000;
5
- export async function create(api, audio, { stems, formats = [], name, signal }) {
5
+ export async function create(api, audio, { stems, formats = [], name, webhook, signal }) {
6
6
  const query = new URLSearchParams();
7
7
  for (const stem of stems)
8
8
  query.append("stems", stem);
@@ -11,17 +11,19 @@ export async function create(api, audio, { stems, formats = [], name, signal })
11
11
  const named = name ?? nameOf(audio);
12
12
  if (named !== undefined)
13
13
  query.set("name", named);
14
+ // a header, as request logs record query strings and a webhook URL may carry a token
15
+ const headers = webhook === undefined ? {} : { "disband-webhook": webhook };
14
16
  const bytes = audio instanceof Blob ? audio.size : audio.byteLength;
15
17
  if (bytes <= bodyLimit) {
16
18
  return api.json(`/v1/separations?${query}`, {
17
19
  method: "POST",
18
- headers: { "content-type": "application/octet-stream" },
20
+ headers: { ...headers, "content-type": "application/octet-stream" },
19
21
  body: audio,
20
22
  signal,
21
23
  });
22
24
  }
23
25
  query.set("bytes", String(bytes));
24
- const reserved = await api.json(`/v1/separations?${query}`, { method: "POST", signal });
26
+ const reserved = await api.json(`/v1/separations?${query}`, { method: "POST", headers, signal });
25
27
  try {
26
28
  // a presigned URL, so the key isn't sent
27
29
  const upload = await fetch(reserved.upload_url, { method: "PUT", body: audio, signal });
package/dist/index.d.ts CHANGED
@@ -8,3 +8,4 @@ export type { CreateOptions } from "./create.ts";
8
8
  export type { RequestOptions } from "./api.ts";
9
9
  export type { Audio } from "./types/audio.ts";
10
10
  export { ApiError } from "./error.ts";
11
+ export { verifyWebhook, webhookSecret } from "./webhook.ts";
package/dist/index.js CHANGED
@@ -1,2 +1,3 @@
1
1
  export { Disband } from "./client.js";
2
2
  export { ApiError } from "./error.js";
3
+ export { verifyWebhook, webhookSecret } from "./webhook.js";
@@ -0,0 +1,5 @@
1
+ import type { Failed, Ready } from "./types/separation.ts";
2
+ /** The webhook secret of an API key, the same as when the key was created. */
3
+ export declare function webhookSecret(apiKey: string): Promise<string>;
4
+ /** The separation a webhook posted, or `undefined` when its signature or timestamp doesn't verify. */
5
+ export declare function verifyWebhook(request: Request, secret: string): Promise<Ready | Failed | undefined>;
@@ -0,0 +1,32 @@
1
+ // Standard Webhooks: HMAC-SHA256 over `id.timestamp.body`, a secret written as `whsec_` and its base64
2
+ const encoder = new TextEncoder();
3
+ const tolerance = 5 * 60;
4
+ const decode = (base64) => Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
5
+ const encode = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes)));
6
+ const hmac = (key) => crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
7
+ /** The webhook secret of an API key, the same as when the key was created. */
8
+ export async function webhookSecret(apiKey) {
9
+ const mac = await crypto.subtle.sign("HMAC", await hmac(encoder.encode(apiKey)), encoder.encode("disband webhooks"));
10
+ return `whsec_${encode(mac)}`;
11
+ }
12
+ /** The separation a webhook posted, or `undefined` when its signature or timestamp doesn't verify. */
13
+ export async function verifyWebhook(request, secret) {
14
+ const id = request.headers.get("webhook-id");
15
+ const timestamp = request.headers.get("webhook-timestamp");
16
+ const signatures = request.headers.get("webhook-signature");
17
+ if (id === null || timestamp === null || signatures === null)
18
+ return undefined;
19
+ if (Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerance)
20
+ return undefined;
21
+ const body = await request.text();
22
+ // with or without its prefix, as Standard Webhooks libraries take it
23
+ const key = await hmac(decode(secret.replace(/^whsec_/, "")));
24
+ const content = encoder.encode(`${id}.${timestamp}.${body}`);
25
+ for (const entry of signatures.split(" ")) {
26
+ const [version, mac] = entry.split(",");
27
+ if (version === "v1" && mac !== undefined && (await crypto.subtle.verify("HMAC", key, decode(mac), content))) {
28
+ return JSON.parse(body);
29
+ }
30
+ }
31
+ return undefined;
32
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "disband",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "TypeScript client for the Disband stem separation API",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -45,6 +45,7 @@
45
45
  "eslint-config-prettier": "^10.1.8",
46
46
  "eslint-plugin-perfectionist": "^5.13.0",
47
47
  "prettier": "^3.10.1",
48
+ "standardwebhooks": "^1.1.1",
48
49
  "typescript": "^6.0.3",
49
50
  "typescript-eslint": "^8.72.2",
50
51
  "vitest": "^4.1.12"