@siafoundation/sia-storage 0.0.14 → 0.1.1

package/README.md

@@ -70,11 +70,85 @@ await packed.add(fileB.stream())
 for (const obj of await packed.finalize()) await sdk.pinObject(obj)
 ```
 
+## Streaming files
+
+Play video and audio without loading the whole file first, and save large files without holding them in memory. A service worker reads each object in ranges and answers the page with an ordinary URL, so `<video>` seeks on its own and a download goes to the browser's download manager. Where service workers are unavailable, the same calls read the object in the page instead, so the code is the same everywhere.
+
+```ts
+import { openStreams } from '@siafoundation/sia-storage'
+
+// An Sdk, with the indexer URL and app metadata its Builder was made with.
+const streams = openStreams(sdk, { indexerUrl, appMeta })
+
+// Or a SharedSdk, with the indexer URL and seed it was connected with.
+const sharedStreams = openStreams(sharedSdk, { indexerUrl, seed })
+
+// Any element or fetch that takes a URL.
+const video = await streams.url(object, { name: 'clip.mp4', type: 'video/mp4' })
+videoElement.src = video.url
+// When the element goes away:
+video.release()
+
+// From a click handler, so the browser allows the save.
+button.onclick = () => streams.download(object, { name: 'clip.mp4' })
+
+// When you're done with the SDK:
+streams.close()
+```
+
+### Serve the worker
+
+The worker is one file, `sia-storage-sw.js`, served from your site's root. Use the line for your setup.
+
+**Vite** (React, Vue, Svelte, Solid and others): add the plugin. It serves the worker in `vite dev`, emits it with the build, and excludes the SDK from dependency pre-bundling.
+
+```js
+// vite.config.js
+import { siaStorage } from '@siafoundation/sia-storage/vite'
+
+export default defineConfig({ plugins: [siaStorage()] })
+```
+
+**Next.js (App Router)**: add one route file.
+
+```ts
+// app/sia-storage-sw.js/route.ts
+export { GET } from '@siafoundation/sia-storage/next'
+export const dynamic = 'force-static'
+```
+
+**Anything else** (webpack, Rollup, esbuild, Parcel, the Next.js Pages Router, a static host): copy the worker into the folder served at your site's root. The file changes with each SDK version, so copy it on every install and leave it out of git.
+
+```json
+// package.json
+"scripts": { "postinstall": "sia-storage-worker public" }
+```
+
+### Good to know
+
+- **HTTPS or localhost.** Browsers only run service workers there. Anywhere else the page reads objects itself.
+- **A site served from a sub-path**, such as `/app/`, serves the worker there too and says where, before the first `openStreams`: `enableStreaming({ workerUrl: '/app/sia-storage-sw.js' })`.
+- **A site with its own service worker** can't add a second one, since a page has only one. Call `installStreams(self)` from `@siafoundation/sia-storage/stream-worker` inside yours, and point `enableStreaming` at it: `enableStreaming({ workerUrl: '/sw.js', type: 'module' })`.
+- **A Content Security Policy** needs `worker-src 'self'`.
+- **The credentials stay in memory.** The worker connects its own SDK, so it needs what yours was made with: a `SharedSdk`'s seed, or an `Sdk`'s app key, which it takes from `sdk.appKey()`. The page hands them over a message port, and the worker never writes them anywhere.
+- **Keep the tab open** until a download finishes. If the browser restarts the worker, it gets the credentials back from the page.
+- **The first download click** within a few seconds of `openStreams`, before the worker is ready, uses the save picker or an in-memory save instead.
+
+## iCloud Private Relay
+
+The SDK does not work through iCloud Private Relay. `detectPrivateRelay()` resolves true for a Safari visitor on it, so you can ask them to turn it off in iCloud settings. Other browsers resolve false without a request.
+
+```ts
+import { detectPrivateRelay } from '@siafoundation/sia-storage'
+
+if (await detectPrivateRelay()) showRelayNotice()
+```
+
 ## Framework notes
 
 The browser build is WebAssembly — most bundlers handle it directly, a few need a small hint.
 
-**Vite** — production builds work as-is. For `vite dev`, exclude the package from the dep pre-bundler so its `import.meta.url`-relative WASM path resolves correctly:
+**Vite**: the `siaStorage()` plugin from [Serve the worker](#serve-the-worker) covers this. Without it, production builds work as-is, and `vite dev` needs the package excluded from the dep pre-bundler so its `import.meta.url`-relative WASM path resolves correctly:
 
 ```js
 // vite.config.js
@@ -113,6 +187,10 @@ Near-identical surfaces. Real differences:
 
 - App identifier: `appMeta.appId: string (hex)` on browser, `appMeta.id: Buffer(32)` on Node.
 - Numeric sizes are `number` on browser, `bigint` on Node. Byte arrays are `Uint8Array` on browser, `Buffer` on Node (`Buffer` is a `Uint8Array` subclass; both accept either as input).
+- Sharing key seeds are hex `string` on browser, `Buffer` on Node. This covers `SharingKey.seed()`, `SharingKey.fromSeed(seed)`, and `SharedSdk.connect(indexerUrl, seed)`.
+- `sdk.unshareObject(key, object)` takes a `PinnedObject` on browser and an object id `string` on Node.
+- `sdk.hosts(query?)` and `sharedSdk.hosts(query?)` accept a `HostQuery` on browser; on Node they take no arguments.
+- `openStreams` gives a browser page URLs that a service worker serves. Node reads objects with `sdk.download(object, { offset, length })`, which already streams a range, so it needs no worker. On Node, `enableStreaming()` resolves false, and `url` and `download` on an `openStreams` handle reject.
 
 ## API
 
@@ -125,10 +203,11 @@ Near-identical surfaces. Real differences:
 | `validateRecoveryPhrase(phrase)` | Throws on invalid. |
 | `setLogger(callback, level)` | Receive SDK logs. |
 | `encodedSize(size, dataShards, parityShards)` | Encoded size after erasure coding. |
+| `detectPrivateRelay()` | Whether a Safari visitor is on iCloud Private Relay, which the SDK does not work through. |
 
 ### `Sdk`
 
-Returned from `Builder.register()` or `Builder.connected()`.
+Returned from `Builder.register()`, `Builder.connected()`, or `Builder.connectPreAuthorized()`.
 
 | | |
 |---|---|
@@ -138,9 +217,14 @@ Returned from `Builder.register()` or `Builder.connected()`.
 | `uploadPacked(options?)` | `PackedUpload` for batching small files into shared slabs. |
 | `object(key)` / `deleteObject(key)` / `pinObject(object)` | Object CRUD. |
 | `updateObjectMetadata(object)` | Push local metadata changes to the indexer. |
-| `shareObject(object, validUntil)` / `sharedObject(url)` | Create / consume share URLs. |
+| `objectShareUrl(object, validUntil)` / `objectFromShareUrl(url)` | Create / consume share URLs. |
 | `objectEvents(cursor?, limit)` | Paginated change feed. |
-| `hosts()` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+| `hosts(query?)` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+| `createSharingKey(description, expiresAt?)` | Create a `SharingKey` for read-only sharing. |
+| `sharingKeys(offset, limit)` / `sharingKey(key)` | List keys / fetch one key's `KeyRecord`. |
+| `shareObject(key, object)` / `unshareObject(key, object)` | Attach / detach an object on a sharing key. |
+| `sharedObjects(key, offset, limit)` | Objects attached to a sharing key. |
+| `revokeSharingKey(key)` | Delete the key and detach all of its objects. |
 
 ### `Builder`
 
@@ -153,6 +237,9 @@ Returned from `Builder.register()` or `Builder.connected()`.
 | `waitForApproval()` | Resolves once the user approves. |
 | `register(phrase)` | Finish onboarding with a new recovery phrase → `Sdk`. |
 | `connected(appKey)` | Reconnect with a saved `AppKey` → `Sdk \| null`. |
+| `reconnecting()` | Whether the approved connect key already has an account. |
+| `matchesExistingAppKey(phrase)` | Whether a phrase derives an already-registered app key. |
+| `connectPreAuthorized(seed, phrase)` | Skip the approval flow with a pre-authorized key's 32-byte seed → `Sdk`. |
 
 ### `AppKey`
 
@@ -164,7 +251,7 @@ Returned from `Builder.register()` or `Builder.connected()`.
 
 `new PinnedObject()` for new uploads, or `sdk.object(key)`.
 
-`id()` · `size()` · `encodedSize()` · `slabs()` · `metadata()` · `updateMetadata(bytes)` · `createdAt()` · `updatedAt()` · `seal(appKey)` · `PinnedObject.open(appKey, sealed)`
+`id()` · `size()` · `encodedSize()` · `slabs()` · `metadata()` · `updateMetadata(bytes)` · `truncate(length: bigint)` · `createdAt()` · `updatedAt()` · `seal(appKey)` · `PinnedObject.open(appKey, sealed)`
 
 ### `PackedUpload`
 
@@ -172,6 +259,46 @@ From `sdk.uploadPacked()`.
 
 `add(stream)` · `finalize()` · `cancel()` · `remaining()` · `length()` · `slabs()`
 
+### `SharingKey`
+
+From `sdk.createSharingKey()`, or `SharingKey.fromSeed(seed)` to import one.
+
+`publicKey` · `seed()` · `SharingKey.fromSeed(seed)`
+
+### `KeyRecord`
+
+The indexer's record for a sharing key, from `sdk.sharingKey()` or `sdk.sharingKeys()`.
+
+`key` · `description` · `stats`
+
+### `SharedSdk`
+
+`SharedSdk.connect(indexerUrl, seed)` — read-only access for a recipient holding a
+sharing key's seed. Downloads are paid for by the key's owner.
+
+| | |
+|---|---|
+| `stats()` | The key's `KeyStats` snapshot. |
+| `object(id)` / `objects(offset, limit)` | Read the objects the key grants access to. |
+| `download(object, options?)` | Returns a `ReadableStream`. |
+| `hosts(query?)` | Hosts serving this key's objects. |
+
+### Streaming
+
+| | |
+|---|---|
+| `openStreams(sdk, credentials)` | `Streams` for one SDK's objects. An `Sdk` takes `{ indexerUrl, appMeta }` and a `SharedSdk` takes `{ indexerUrl, seed }`, typed by which one you pass. |
+| `streams.url(object, options)` | `{ url, blob?, release() }`. Streams where it can, else reads the whole object into `blob`. |
+| `streams.download(object, options)` | Saves the object. Resolves `'streaming'`, `'saved'` or `'cancelled'`. Call it from a click handler. |
+| `streams.close()` | Cancels this handle's streams. Other handles on the same SDK keep theirs. |
+| `enableStreaming(options?)` | Registers the worker and resolves whether streaming is on. `openStreams` calls it for you, so call it only to pass `workerUrl`, `scope` or `type`. |
+
+`options` for `url` and `download`: `name`, `type` (MIME), `onError(message)` for failures after streaming starts (logged when omitted), `onProgress(bytes)` when the page reads the object itself, and `signal` for `url`.
+
+### `@siafoundation/sia-storage/stream-worker`
+
+`installStreams(self, { wasm? })` adds streaming to a service worker of your own. `wasm` is the SDK's WebAssembly as a URL, bytes or module, for bundlers that don't emit it.
+
 ## License
 
 MIT

package/dist/chunk-QYQQIWFH.js

@@ -0,0 +1,74 @@
+// src/stream/errors.ts
+function streamErrorMessage(error) {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown streaming failure";
+  return message.replace(/\b(?:https?|wss?|sia):\/\/[^\s"'<>]+/gi, "[URL redacted]").replace(/(?:bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(
+    /((?:seed|share|token|key|authorization)\s*[=:]\s*)[^\s,;]+/gi,
+    "$1[redacted]"
+  ).replace(/[a-f0-9]{64,}/gi, "[redacted]").replace(/[\r\n\t]/g, " ").slice(0, 1e3);
+}
+function reportStreamError(error, name, range) {
+  const message = streamErrorMessage(error);
+  const bytes = range ? ` bytes ${range.offset}-${range.offset + range.length - 1}` : "";
+  console.error(`[Sia stream] ${streamErrorMessage(name)}${bytes}: ${message}`);
+  return message;
+}
+
+// src/stream/protocol.ts
+var STREAM_PATH = /\/__sia_stream__\/([^/]+)\/([^/]+)\/[^/]+$/;
+function streamPath(scope, clientId, token) {
+  return `${scope}__sia_stream__/${clientId}/${token}/file`;
+}
+function parseStreamPath(pathname) {
+  const match = STREAM_PATH.exec(pathname);
+  return match ? { clientId: match[1], token: match[2] } : void 0;
+}
+var strings = (data, fields) => fields.every((field) => typeof data?.[field] === "string");
+function isAppMetadata(value) {
+  return strings(value, ["appId", "name", "description", "serviceUrl"]);
+}
+function isConnection(value) {
+  const data = value;
+  if (data?.kind === "shared") return strings(data, ["indexerUrl", "seed"]);
+  return data?.kind === "app" && strings(data, ["indexerUrl", "appKey"]) && isAppMetadata(data.appMeta);
+}
+function isSourceReply(reply) {
+  const data = reply;
+  return data?.type === "source" && strings(data, ["session", "objectId", "name", "mime"]) && isConnection(data.connection) && (data.connection.kind === "shared" || typeof data.sealed === "object" && data.sealed !== null) && Number.isSafeInteger(data.size) && data.size >= 0;
+}
+function requestReply(target, message, { timeout, signal }) {
+  return new Promise((resolve, reject) => {
+    const { port1, port2 } = new MessageChannel();
+    const timer = timeout === void 0 ? void 0 : setTimeout(
+      () => settle(() => reject(new Error("No reply in time."))),
+      timeout
+    );
+    const abort = () => settle(() => reject(signal?.reason));
+    function settle(outcome) {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      port1.close();
+      port2.close();
+      outcome();
+    }
+    if (signal?.aborted) return abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    port1.onmessage = ({ data }) => settle(() => resolve(data));
+    port1.onmessageerror = () => settle(() => reject(new Error("Unreadable reply.")));
+    try {
+      target.postMessage(message, [port2]);
+    } catch (error) {
+      settle(() => reject(error));
+    }
+  });
+}
+
+export {
+  streamErrorMessage,
+  reportStreamError,
+  streamPath,
+  parseStreamPath,
+  isAppMetadata,
+  isSourceReply,
+  requestReply
+};
+//# sourceMappingURL=chunk-QYQQIWFH.js.map

package/dist/chunk-QYQQIWFH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stream/errors.ts","../src/stream/protocol.ts"],"sourcesContent":["/** Only sanitized strings cross the diagnostic boundary, never raw SDK objects. */\nexport function streamErrorMessage(error: unknown): string {\n  const message =\n    error instanceof Error\n      ? error.message\n      : typeof error === 'string'\n        ? error\n        : 'Unknown streaming failure'\n  return message\n    .replace(/\\b(?:https?|wss?|sia):\\/\\/[^\\s\"'<>]+/gi, '[URL redacted]')\n    .replace(/(?:bearer\\s+)[^\\s,;]+/gi, 'Bearer [redacted]')\n    .replace(\n      /((?:seed|share|token|key|authorization)\\s*[=:]\\s*)[^\\s,;]+/gi,\n      '$1[redacted]',\n    )\n    .replace(/[a-f0-9]{64,}/gi, '[redacted]')\n    .replace(/[\\r\\n\\t]/g, ' ')\n    .slice(0, 1000)\n}\n\nexport function reportStreamError(\n  error: unknown,\n  name: string,\n  range: { offset: number; length: number } | undefined,\n) {\n  const message = streamErrorMessage(error)\n  // One string rather than an object, so it reads the same in every console.\n  const bytes = range\n    ? ` bytes ${range.offset}-${range.offset + range.length - 1}`\n    : ''\n  console.error(`[Sia stream] ${streamErrorMessage(name)}${bytes}: ${message}`)\n  return message\n}\n","/**\n * Messages between a page and its streaming service worker.\n *\n * Stream URLs carry only the page's client id and a random token. When the\n * worker meets a token it does not know, it asks the page that made it for the\n * file and the share's credentials. The page and a worker can come from\n * different deployed versions, so the worker checks the page's reply before\n * using it.\n */\nimport type {\n  AppMetadata,\n  SealedObject,\n} from '../../wasm/sia_storage_wasm.js'\n\n/**\n * What the worker connects its own SDK with. A `SharedSdk` reconnects from its\n * sharing key's seed, and an `Sdk` from its app key, as hex, and app metadata.\n */\nexport type Connection =\n  | { kind: 'shared'; indexerUrl: string; seed: string }\n  | { kind: 'app'; indexerUrl: string; appKey: string; appMeta: AppMetadata }\n\nexport type SourceDetails = {\n  // One per opened SDK, so the worker can release it as a whole.\n  session: string\n  connection: Connection\n  objectId: string\n  // An `Sdk`'s object, sealed with its app key, so the worker can open it\n  // without a lookup. A `SharedSdk`'s object is looked up by `objectId`.\n  sealed?: SealedObject\n  name: string\n  mime: string\n  size: number\n}\n\n/** Page to worker. */\nexport type PageMessage =\n  | { type: 'sia-client' }\n  | { type: 'sia-release'; token: string }\n  | { type: 'sia-release-share'; session: string }\n\n/** Worker to page. */\nexport type WorkerMessage =\n  | { type: 'sia-source'; token: string }\n  | {\n      type: 'sia-stream-error'\n      token: string\n      message: string\n      offset?: number\n      length?: number\n    }\n\n/** The worker's answer to `sia-client`. */\nexport type ClientReply = { clientId: string; supported: boolean }\n\n/** The page's answer to `sia-source`. */\nexport type SourceReply =\n  | ({ type: 'source' } & SourceDetails)\n  | { type: 'error' }\n\n// Stream URLs sit under the worker's scope, so a download's navigation, which\n// only a worker whose scope covers the URL can answer, reaches it on sites\n// served from a sub-path too.\nconst STREAM_PATH = /\\/__sia_stream__\\/([^/]+)\\/([^/]+)\\/[^/]+$/\n\n/** `scope` is the worker registration's scope URL, which ends in a slash. */\nexport function streamPath(scope: string, clientId: string, token: string) {\n  return `${scope}__sia_stream__/${clientId}/${token}/file`\n}\n\nexport function parseStreamPath(pathname: string) {\n  const match = STREAM_PATH.exec(pathname)\n  return match ? { clientId: match[1]!, token: match[2]! } : undefined\n}\n\ntype Fields = Record<string, unknown> | null | undefined\n\nconst strings = (data: Fields, fields: string[]) =>\n  fields.every((field) => typeof data?.[field] === 'string')\n\n/** Checked on both sides, so bad metadata fails in `openStreams`, not per request. */\nexport function isAppMetadata(value: unknown): value is AppMetadata {\n  return strings(value as Fields, ['appId', 'name', 'description', 'serviceUrl'])\n}\n\nfunction isConnection(value: unknown): value is Connection {\n  const data = value as Fields\n  if (data?.kind === 'shared') return strings(data, ['indexerUrl', 'seed'])\n  return (\n    data?.kind === 'app' &&\n    strings(data, ['indexerUrl', 'appKey']) &&\n    isAppMetadata(data.appMeta)\n  )\n}\n\nexport function isSourceReply(\n  reply: unknown,\n): reply is { type: 'source' } & SourceDetails {\n  const data = reply as Fields\n  return (\n    data?.type === 'source' &&\n    strings(data, ['session', 'objectId', 'name', 'mime']) &&\n    isConnection(data.connection) &&\n    (data.connection.kind === 'shared' ||\n      (typeof data.sealed === 'object' && data.sealed !== null)) &&\n    Number.isSafeInteger(data.size) &&\n    (data.size as number) >= 0\n  )\n}\n\n/**\n * Posts `message` with a reply port and resolves with the first reply. Rejects\n * after `timeout` ms, or when `signal` aborts.\n */\nexport function requestReply(\n  target: { postMessage(message: unknown, transfer: Transferable[]): void },\n  message: unknown,\n  { timeout, signal }: { timeout?: number; signal?: AbortSignal },\n): Promise<unknown> {\n  return new Promise((resolve, reject) => {\n    const { port1, port2 } = new MessageChannel()\n    const timer =\n      timeout === undefined\n        ? undefined\n        : setTimeout(\n            () => settle(() => reject(new Error('No reply in time.'))),\n            timeout,\n          )\n    const abort = () => settle(() => reject(signal?.reason))\n    function settle(outcome: () => void) {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', abort)\n      port1.close()\n      port2.close()\n      outcome()\n    }\n    if (signal?.aborted) return abort()\n    signal?.addEventListener('abort', abort, { once: true })\n    port1.onmessage = ({ data }) => settle(() => resolve(data))\n    port1.onmessageerror = () =>\n      settle(() => reject(new Error('Unreadable reply.')))\n    try {\n      target.postMessage(message, [port2])\n    } catch (error) {\n      settle(() => reject(error))\n    }\n  })\n}\n"],"mappings":";AACO,SAAS,mBAAmB,OAAwB;AACzD,QAAM,UACJ,iBAAiB,QACb,MAAM,UACN,OAAO,UAAU,WACf,QACA;AACR,SAAO,QACJ,QAAQ,0CAA0C,gBAAgB,EAClE,QAAQ,2BAA2B,mBAAmB,EACtD;AAAA,IACC;AAAA,IACA;AAAA,EACF,EACC,QAAQ,mBAAmB,YAAY,EACvC,QAAQ,aAAa,GAAG,EACxB,MAAM,GAAG,GAAI;AAClB;AAEO,SAAS,kBACd,OACA,MACA,OACA;AACA,QAAM,UAAU,mBAAmB,KAAK;AAExC,QAAM,QAAQ,QACV,UAAU,MAAM,MAAM,IAAI,MAAM,SAAS,MAAM,SAAS,CAAC,KACzD;AACJ,UAAQ,MAAM,gBAAgB,mBAAmB,IAAI,CAAC,GAAG,KAAK,KAAK,OAAO,EAAE;AAC5E,SAAO;AACT;;;AC+BA,IAAM,cAAc;AAGb,SAAS,WAAW,OAAe,UAAkB,OAAe;AACzE,SAAO,GAAG,KAAK,kBAAkB,QAAQ,IAAI,KAAK;AACpD;AAEO,SAAS,gBAAgB,UAAkB;AAChD,QAAM,QAAQ,YAAY,KAAK,QAAQ;AACvC,SAAO,QAAQ,EAAE,UAAU,MAAM,CAAC,GAAI,OAAO,MAAM,CAAC,EAAG,IAAI;AAC7D;AAIA,IAAM,UAAU,CAAC,MAAc,WAC7B,OAAO,MAAM,CAAC,UAAU,OAAO,OAAO,KAAK,MAAM,QAAQ;AAGpD,SAAS,cAAc,OAAsC;AAClE,SAAO,QAAQ,OAAiB,CAAC,SAAS,QAAQ,eAAe,YAAY,CAAC;AAChF;AAEA,SAAS,aAAa,OAAqC;AACzD,QAAM,OAAO;AACb,MAAI,MAAM,SAAS,SAAU,QAAO,QAAQ,MAAM,CAAC,cAAc,MAAM,CAAC;AACxE,SACE,MAAM,SAAS,SACf,QAAQ,MAAM,CAAC,cAAc,QAAQ,CAAC,KACtC,cAAc,KAAK,OAAO;AAE9B;AAEO,SAAS,cACd,OAC6C;AAC7C,QAAM,OAAO;AACb,SACE,MAAM,SAAS,YACf,QAAQ,MAAM,CAAC,WAAW,YAAY,QAAQ,MAAM,CAAC,KACrD,aAAa,KAAK,UAAU,MAC3B,KAAK,WAAW,SAAS,YACvB,OAAO,KAAK,WAAW,YAAY,KAAK,WAAW,SACtD,OAAO,cAAc,KAAK,IAAI,KAC7B,KAAK,QAAmB;AAE7B;AAMO,SAAS,aACd,QACA,SACA,EAAE,SAAS,OAAO,GACA;AAClB,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,EAAE,OAAO,MAAM,IAAI,IAAI,eAAe;AAC5C,UAAM,QACJ,YAAY,SACR,SACA;AAAA,MACE,MAAM,OAAO,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC,CAAC;AAAA,MACzD;AAAA,IACF;AACN,UAAM,QAAQ,MAAM,OAAO,MAAM,OAAO,QAAQ,MAAM,CAAC;AACvD,aAAS,OAAO,SAAqB;AACnC,mBAAa,KAAK;AAClB,cAAQ,oBAAoB,SAAS,KAAK;AAC1C,YAAM,MAAM;AACZ,YAAM,MAAM;AACZ,cAAQ;AAAA,IACV;AACA,QAAI,QAAQ,QAAS,QAAO,MAAM;AAClC,YAAQ,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;AACvD,UAAM,YAAY,CAAC,EAAE,KAAK,MAAM,OAAO,MAAM,QAAQ,IAAI,CAAC;AAC1D,UAAM,iBAAiB,MACrB,OAAO,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC,CAAC;AACrD,QAAI;AACF,aAAO,YAAY,SAAS,CAAC,KAAK,CAAC;AAAA,IACrC,SAAS,OAAO;AACd,aAAO,MAAM,OAAO,KAAK,CAAC;AAAA,IAC5B;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { copyFileSync, mkdirSync } from "fs";
+import { join } from "path";
+var WORKER_FILE = "sia-storage-sw.js";
+var dir = process.argv[2] ?? "public";
+mkdirSync(dir, { recursive: true });
+copyFileSync(
+  new URL(`./${WORKER_FILE}`, import.meta.url),
+  join(dir, WORKER_FILE)
+);
+console.log(`Copied ${WORKER_FILE} into ${dir}/`);

package/dist/index.d.ts

@@ -1,6 +1,94 @@
-export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
+import { AppMetadata, Sdk, SharedSdk, PinnedObject } from '../wasm/sia_storage_wasm.js';
+export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, KeyRecord, KeyStats, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, SharedSdk, SharingKey, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
+
+declare function detectPrivateRelay(): Promise<boolean>;
+
+/**
+ * The page side of streaming.
+ *
+ * `openStreams` hands out same-origin URLs that the library's service worker
+ * answers with ranged reads of an object, so a `<video>` seeks without loading
+ * the whole file and a download goes to the browser's download manager instead
+ * of the page's memory. The worker connects its own SDK of the same kind, with
+ * credentials this page hands it over a message port and it keeps in memory.
+ * Where the worker is unavailable, the same calls read the object in the page.
+ */
+
+type StreamingOptions = {
+    /** Where the site serves the worker file. Defaults to `/sia-storage-sw.js`. */
+    workerUrl?: string;
+    /** The worker's scope. Defaults to the directory `workerUrl` is in. */
+    scope?: string;
+    /** `'module'` when `workerUrl` is an ES module worker of your own. */
+    type?: WorkerType;
+};
+/** What a `SharedSdk` was connected with. */
+type SharedCredentials = {
+    indexerUrl: string;
+    seed: string;
+};
+/** What an `Sdk`'s `Builder` was made with. The key comes from `sdk.appKey()`. */
+type AppCredentials = {
+    indexerUrl: string;
+    appMeta: AppMetadata;
+};
+/** The credentials `openStreams` takes for each kind of SDK. */
+type CredentialsFor<S extends Sdk | SharedSdk> = S extends SharedSdk ? SharedCredentials : AppCredentials;
+type FileOptions = {
+    /** Used for downloads and for the browser's media handling. */
+    name: string;
+    /** The MIME type. Defaults to `application/octet-stream`. */
+    type?: string;
+    /** A failure after streaming started. Without it, failures are logged. */
+    onError?: (message: string) => void;
+    /** Bytes read so far, when the page reads the object itself. */
+    onProgress?: (bytesDownloaded: number) => void;
+};
+/** A URL for an `<img>`, `<video>`, `<audio>`, `<iframe>` or `fetch`. */
+type StreamedFile = {
+    url: string;
+    /** The whole file, when the page read it itself instead of streaming. */
+    blob?: Blob;
+    /** Frees the URL. Call it when the element showing it goes away. */
+    release(): void;
+};
+type Streams = {
+    /** A URL serving the object. Streams where it can, else reads it whole. */
+    url(object: PinnedObject, options: FileOptions & {
+        signal?: AbortSignal;
+    }): Promise<StreamedFile>;
+    /**
+     * Saves the object, from a click handler. Streams to the browser's download
+     * manager where it can, else opens the save picker, else saves a Blob.
+     * Awaits nothing before the picker opens, so the browser still counts it as
+     * part of the click.
+     */
+    download(object: PinnedObject, options: FileOptions): Promise<'streaming' | 'saved' | 'cancelled'>;
+    /**
+     * Cancels the streams this handle made. Other handles on the same SDK keep
+     * theirs. Call it when you stop using the handle.
+     */
+    close(): void;
+};
+/**
+ * Registers the streaming worker and resolves whether this page can stream.
+ * `openStreams` calls it with the defaults, so call it yourself only to pass
+ * options, and before the first `openStreams`. Later calls return the first
+ * call's answer, except when setup failed or timed out and a different worker
+ * has since taken control of the page. Then the next call tries again, with
+ * the first call's options.
+ */
+declare function enableStreaming(options?: StreamingOptions): Promise<boolean>;
+/**
+ * Previews and downloads for one SDK's objects, from an `Sdk` or a `SharedSdk`.
+ *
+ * The worker cannot use this page's SDK, so it connects its own with
+ * `credentials`: the indexer URL and seed a `SharedSdk` was connected with, or
+ * the indexer URL and app metadata an `Sdk`'s `Builder` was made with.
+ */
+declare function openStreams<S extends Sdk | SharedSdk>(sdk: S, credentials: CredentialsFor<S>): Streams;
 
 /** Initialize the WASM module. Safe to call multiple times. */
 declare function initSia(): Promise<void>;
 
-export { initSia };
+export { type AppCredentials, type CredentialsFor, type FileOptions, type SharedCredentials, type StreamedFile, type StreamingOptions, type Streams, detectPrivateRelay, enableStreaming, initSia, openStreams };