@siafoundation/sia-storage 0.0.8

package/README.md

@@ -0,0 +1,175 @@
+# sia-storage
+
+TypeScript SDK for building decentralized storage apps on the [Sia](https://sia.tech) network. Works in Node.js, Bun, and the browser.
+
+## Install
+
+```bash
+npm install @siafoundation/sia-storage
+```
+
+## Quick start
+
+```ts
+import { initSia, Builder, generateRecoveryPhrase } from '@siafoundation/sia-storage'
+
+await initSia()
+
+const appMeta = {
+  appId: '0'.repeat(64),                // 32-byte app identifier (hex)
+  name: 'My App',
+  description: 'An app on the Sia network',
+  serviceUrl: 'https://myapp.com',
+}
+
+const builder = new Builder('https://sia.storage', appMeta)
+await builder.requestConnection()
+// Show builder.responseUrl() to the user — they visit it to authorize.
+await builder.waitForApproval()
+
+const phrase = generateRecoveryPhrase()
+const sdk = await builder.register(phrase)
+
+// Persist the app key so the user doesn't re-auth next time.
+const appKeyHex = sdk.appKey().export().toHex()
+```
+
+Reconnecting a returning user:
+
+```ts
+import { Builder, AppKey } from '@siafoundation/sia-storage'
+
+const sdk = await new Builder('https://sia.storage', appMeta)
+  .connected(new AppKey(Uint8Array.fromHex(appKeyHex)))
+```
+
+## Uploading
+
+```ts
+import { PinnedObject } from '@siafoundation/sia-storage'
+
+const object = await sdk.upload(new PinnedObject(), file.stream(), { maxInflight: 10 })
+await sdk.pinObject(object)
+```
+
+Downloading:
+
+```ts
+const stream = sdk.download(object)
+for await (const chunk of stream) { /* ... */ }
+```
+
+For many small files, share slabs via `uploadPacked`:
+
+```ts
+const packed = sdk.uploadPacked({ maxInflight: 10 })
+await packed.add(fileA.stream())
+await packed.add(fileB.stream())
+for (const obj of await packed.finalize()) await sdk.pinObject(obj)
+```
+
+## 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:
+
+```js
+// vite.config.js
+export default defineConfig({
+  optimizeDeps: { exclude: ['@siafoundation/sia-storage'] },
+})
+```
+
+Without this, the dev server fetches the `.wasm` from `/node_modules/.vite/deps/` where it doesn't exist, the SPA fallback returns `index.html`, and `WebAssembly.instantiate` fails with a `magic word … found 3c 21 64 6f` error.
+
+**Next.js (App Router)** — load from a Client Component, dynamically imported so the WebAssembly module isn't pulled into the server prerender:
+
+```tsx
+'use client'
+import dynamic from 'next/dynamic'
+const Storage = dynamic(() => import('./storage'), { ssr: false })
+export default function Page() { return <Storage /> }
+```
+
+**Webpack**:
+
+```js
+// webpack.config.js
+module.exports = { experiments: { asyncWebAssembly: true, topLevelAwait: true } }
+```
+
+**Rollup / esbuild** — copy the WebAssembly asset into your output directory:
+
+```bash
+cp node_modules/@siafoundation/sia-storage/wasm/sia_storage_wasm_bg.wasm dist/
+```
+
+## Node vs browser
+
+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).
+
+## API
+
+### Top-level
+
+| | |
+|---|---|
+| `initSia()` | Initialize. Call once before using the SDK. |
+| `generateRecoveryPhrase()` | 12-word BIP-39 phrase. |
+| `validateRecoveryPhrase(phrase)` | Throws on invalid. |
+| `setLogger(callback, level)` | Receive SDK logs. |
+| `encodedSize(size, dataShards, parityShards)` | Encoded size after erasure coding. |
+
+### `Sdk`
+
+Returned from `Builder.register()` or `Builder.connected()`.
+
+| | |
+|---|---|
+| `appKey()` | The `AppKey` for this session. |
+| `upload(object, stream, options?)` | Upload from a `ReadableStream`. Progress via `options.onShardUploaded`. |
+| `download(object, options?)` | Returns a `ReadableStream`. Progress via `options.onShardDownloaded`. |
+| `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. |
+| `objectEvents(cursor?, limit)` | Paginated change feed. |
+| `hosts()` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+
+### `Builder`
+
+`new Builder(indexerUrl, appMeta)`
+
+| | |
+|---|---|
+| `requestConnection()` | Start the approval flow. |
+| `responseUrl()` | URL to show the user. |
+| `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`. |
+
+### `AppKey`
+
+`new AppKey(seed)` — 32-byte `Uint8Array`.
+
+`publicKey()` · `sign(message)` · `verifySignature(message, signature)` · `export()`
+
+### `PinnedObject`
+
+`new PinnedObject()` for new uploads, or `sdk.object(key)`.
+
+`id()` · `size()` · `encodedSize()` · `slabs()` · `metadata()` · `updateMetadata(bytes)` · `createdAt()` · `updatedAt()` · `seal(appKey)` · `PinnedObject.open(appKey, sealed)`
+
+### `PackedUpload`
+
+From `sdk.uploadPacked()`.
+
+`add(stream)` · `finalize()` · `cancel()` · `remaining()` · `length()` · `slabs()`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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';
+
+/** Initialize the WASM module. Safe to call multiple times. */
+declare function initSia(): Promise<void>;
+
+export { initSia };

package/dist/index.js

@@ -0,0 +1,33 @@
+// src/index.ts
+import wasmInit from "../wasm/sia_storage_wasm.js";
+import {
+  AppKey,
+  Builder,
+  ObjectEvent,
+  PackedUpload,
+  PinnedObject,
+  Sdk,
+  encodedSize,
+  generateRecoveryPhrase,
+  setLogger,
+  validateRecoveryPhrase
+} from "../wasm/sia_storage_wasm.js";
+var initPromise = null;
+async function initSia() {
+  if (!initPromise) initPromise = wasmInit();
+  await initPromise;
+}
+export {
+  AppKey,
+  Builder,
+  ObjectEvent,
+  PackedUpload,
+  PinnedObject,
+  Sdk,
+  encodedSize,
+  generateRecoveryPhrase,
+  initSia,
+  setLogger,
+  validateRecoveryPhrase
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Browser entry; lazily initializes WASM on first use.\n\nimport wasmInit from '../wasm/sia_storage_wasm.js'\n\nlet initPromise: Promise<unknown> | null = null\n\n/** Initialize the WASM module. Safe to call multiple times. */\nexport async function initSia(): Promise<void> {\n  if (!initPromise) initPromise = wasmInit()\n  await initPromise\n}\n\nexport {\n  AppKey,\n  Builder,\n  ObjectEvent,\n  PackedUpload,\n  PinnedObject,\n  Sdk,\n  encodedSize,\n  generateRecoveryPhrase,\n  setLogger,\n  validateRecoveryPhrase,\n} from '../wasm/sia_storage_wasm.js'\nexport type {\n  Account,\n  AppMetadata,\n  DownloadOptions,\n  Host,\n  HostQuery,\n  PinnedSlab,\n  Sector,\n  SealedObject,\n  ShardProgress,\n  Slab,\n  UploadOptions,\n} from '../wasm/sia_storage_wasm.js'\n"],"mappings":";AAEA,OAAO,cAAc;AAUrB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAnBP,IAAI,cAAuC;AAG3C,eAAsB,UAAyB;AAC7C,MAAI,CAAC,YAAa,eAAc,SAAS;AACzC,QAAM;AACR;","names":[]}

package/dist/index.node.cjs

@@ -0,0 +1,96 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.node.ts
+var index_node_exports = {};
+__export(index_node_exports, {
+  AppKey: () => AppKey,
+  Builder: () => Builder,
+  ObjectEvent: () => ObjectEvent,
+  PackedUpload: () => PackedUpload,
+  PinnedObject: () => PinnedObject,
+  Sdk: () => Sdk,
+  encodedSize: () => encodedSize,
+  generateRecoveryPhrase: () => generateRecoveryPhrase,
+  initSia: () => initSia,
+  setLogger: () => setLogger,
+  validateRecoveryPhrase: () => validateRecoveryPhrase
+});
+module.exports = __toCommonJS(index_node_exports);
+
+// src/node/load.ts
+var addon = null;
+function loadNativeAddon() {
+  if (addon) return addon;
+  const platform = process.platform;
+  const arch = process.arch;
+  try {
+    if (platform === "darwin" && arch === "arm64") {
+      addon = require("@siafoundation/sia-storage-darwin-arm64");
+    } else if (platform === "darwin" && arch === "x64") {
+      addon = require("@siafoundation/sia-storage-darwin-x64");
+    } else if (platform === "linux" && arch === "x64") {
+      addon = require("@siafoundation/sia-storage-linux-x64-gnu");
+    } else if (platform === "linux" && arch === "arm64") {
+      addon = require("@siafoundation/sia-storage-linux-arm64-gnu");
+    } else if (platform === "win32" && arch === "x64") {
+      addon = require("@siafoundation/sia-storage-win32-x64-msvc");
+    }
+  } catch {
+  }
+  if (!addon) {
+    throw new Error(
+      `@siafoundation/sia-storage: Native addon not found for ${platform}-${arch}. Install @siafoundation/sia-storage-${platform}-${arch} or use the browser/WASM build.`
+    );
+  }
+  return addon;
+}
+
+// src/node/napi.ts
+var addon2 = loadNativeAddon();
+var {
+  AppKey,
+  Builder,
+  Sdk,
+  PinnedObject,
+  PackedUpload,
+  ObjectEvent,
+  generateRecoveryPhrase,
+  validateRecoveryPhrase,
+  setLogger,
+  encodedSize
+} = addon2;
+async function initSia() {
+  loadNativeAddon();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppKey,
+  Builder,
+  ObjectEvent,
+  PackedUpload,
+  PinnedObject,
+  Sdk,
+  encodedSize,
+  generateRecoveryPhrase,
+  initSia,
+  setLogger,
+  validateRecoveryPhrase
+});
+//# sourceMappingURL=index.node.cjs.map

package/dist/index.node.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.node.ts","../src/node/load.ts","../src/node/napi.ts"],"sourcesContent":["export * from './node/napi'\nexport type * from './node/napi'\n","import type * as Addon from './napi.generated'\n\nlet addon: typeof Addon | null = null\n\nexport function loadNativeAddon(): typeof Addon {\n  if (addon) return addon\n\n  const platform = process.platform\n  const arch = process.arch\n\n  try {\n    if (platform === 'darwin' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-darwin-arm64')\n    } else if (platform === 'darwin' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-darwin-x64')\n    } else if (platform === 'linux' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-linux-x64-gnu')\n    } else if (platform === 'linux' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-linux-arm64-gnu')\n    } else if (platform === 'win32' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-win32-x64-msvc')\n    }\n  } catch {}\n\n  if (!addon) {\n    throw new Error(\n      `@siafoundation/sia-storage: Native addon not found for ${platform}-${arch}. ` +\n        `Install @siafoundation/sia-storage-${platform}-${arch} or use the browser/WASM build.`,\n    )\n  }\n\n  return addon\n}\n","import { loadNativeAddon } from './load'\n\nconst addon = loadNativeAddon()\n\nexport const {\n  AppKey,\n  Builder,\n  Sdk,\n  PinnedObject,\n  PackedUpload,\n  ObjectEvent,\n  generateRecoveryPhrase,\n  validateRecoveryPhrase,\n  setLogger,\n  encodedSize,\n} = addon\n\nexport type * from './napi.generated'\n\n/** Force-load the native addon to surface missing-binary errors at startup. */\nexport async function initSia(): Promise<void> {\n  loadNativeAddon()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,IAAI,QAA6B;AAE1B,SAAS,kBAAgC;AAC9C,MAAI,MAAO,QAAO;AAElB,QAAM,WAAW,QAAQ;AACzB,QAAM,OAAO,QAAQ;AAErB,MAAI;AACF,QAAI,aAAa,YAAY,SAAS,SAAS;AAC7C,cAAQ,QAAQ,yCAAyC;AAAA,IAC3D,WAAW,aAAa,YAAY,SAAS,OAAO;AAClD,cAAQ,QAAQ,uCAAuC;AAAA,IACzD,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,0CAA0C;AAAA,IAC5D,WAAW,aAAa,WAAW,SAAS,SAAS;AACnD,cAAQ,QAAQ,4CAA4C;AAAA,IAC9D,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,2CAA2C;AAAA,IAC7D;AAAA,EACF,QAAQ;AAAA,EAAC;AAET,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR,0DAA0D,QAAQ,IAAI,IAAI,wCAClC,QAAQ,IAAI,IAAI;AAAA,IAC1D;AAAA,EACF;AAEA,SAAO;AACT;;;AC9BA,IAAMA,SAAQ,gBAAgB;AAEvB,IAAM;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,IAAIA;AAKJ,eAAsB,UAAyB;AAC7C,kBAAgB;AAClB;","names":["addon"]}

package/dist/index.node.d.ts

@@ -0,0 +1,291 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * An AppKey is used to sign requests to the indexer.
+ *
+ * AppKeys can be registered with an indexer during
+ * onboarding with a Builder. They are derived from
+ * a BIP-39 recovery phrase, which can be generated
+ * using `generateRecoveryPhrase`.
+ *
+ * It must be stored securely by the application and
+ * never shared publicly.
+ */
+export declare class AppKey {
+  /** Imports an AppKey from the provided byte array. */
+  constructor(key: Buffer)
+  /** Exports the AppKey as a 32-byte buffer. */
+  export(): Buffer
+  /** Signs a message using the AppKey. */
+  sign(message: Buffer): Buffer
+  /** Returns the public key corresponding to the AppKey. */
+  publicKey(): string
+  /** Verifies a signature for a given message using the AppKey. */
+  verifySignature(message: Buffer, signature: Buffer): boolean
+}
+
+export declare class Builder {
+  /** Creates a new SDK builder with the provided indexer URL. */
+  constructor(indexerUrl: string, appMeta: AppMetadata)
+  /**
+   * Attempts to connect using the provided app key.
+   * Returns the SDK if the app key is valid, otherwise returns null.
+   */
+  connected(appKey: AppKey): Promise<Sdk | null>
+  /** Requests connection approval for the application. */
+  requestConnection(): Promise<void>
+  /** Returns the response URL for the connection request. */
+  responseUrl(): string
+  /** Waits for the connection request to be approved. */
+  waitForApproval(): Promise<void>
+  /** Registers the application with the indexer using the provided mnemonic. */
+  register(mnemonic: string): Promise<Sdk>
+}
+
+/** An object event from the indexer. */
+export declare class ObjectEvent {
+  get id(): string
+  get deleted(): boolean
+  get updatedAt(): Date
+  get object(): PinnedObject | null
+}
+
+/**
+ * A packed upload allows multiple objects to be uploaded together in a single
+ * upload. This can be more efficient than individual uploads for many small
+ * objects since they share slabs.
+ */
+export declare class PackedUpload {
+  /**
+   * Returns the number of bytes remaining until reaching the optimal
+   * packed size. Adding objects larger than this will start a new slab.
+   */
+  remaining(): bigint
+  /** Returns the number of bytes added so far. */
+  length(): bigint
+  /** Returns the number of slabs in the upload. */
+  slabs(): bigint
+  /**
+   * Adds a new object to the upload. The data will be read until EOF and
+   * packed into the upload. Call `finalize()` after all objects have been added.
+   */
+  add(stream: ReadableStream): Promise<bigint>
+  /** Cancels the upload. */
+  cancel(): Promise<void>
+  /**
+   * Finalizes the upload and returns the resulting objects. Each object
+   * must be pinned separately with `sdk.pinObject()`.
+   */
+  finalize(): Promise<Array<PinnedObject>>
+}
+
+/** An object pinned to an indexer. */
+export declare class PinnedObject {
+  /** Creates a new empty object. */
+  constructor()
+  /** Opens a sealed object using the provided app key. */
+  static open(appKey: AppKey, sealed: SealedObject): PinnedObject
+  /** Seals the object for offline storage. */
+  seal(appKey: AppKey): SealedObject
+  /** Returns the object's ID. */
+  id(): string
+  /** Returns the total size of the object. */
+  size(): bigint
+  /** Returns the total encoded size after erasure coding. */
+  encodedSize(): bigint
+  /** Returns the slabs that make up the object. */
+  slabs(): Array<Slab>
+  /** Returns the metadata associated with the object. */
+  metadata(): Buffer
+  /** Updates the metadata associated with the object. */
+  updateMetadata(metadata: Buffer): void
+  /** Returns the time the object was created (ms since epoch). */
+  createdAt(): Date
+  /** Returns the time the object was last updated (ms since epoch). */
+  updatedAt(): Date
+}
+
+export declare class Sdk {
+  /** Returns the application key used by the SDK. */
+  appKey(): AppKey
+  /**
+   * Creates a new packed upload for efficiently uploading multiple small
+   * objects together. Returns a `PackedUpload` handle.
+   */
+  uploadPacked(options?: UploadOptions): PackedUpload
+  /**
+   * Uploads data to the Sia network.
+   *
+   * Pass a new `PinnedObject` for new uploads. To resume a previous upload,
+   * pass the object returned from the earlier call. Appending data changes
+   * an object's ID. It must be re-pinned afterward and any references to
+   * the previous ID must be updated.
+   */
+  upload(object: PinnedObject, stream: ReadableStream, options?: UploadOptions): Promise<PinnedObject>
+  /**
+   * Downloads an object from the Sia network, returning a `ReadableStream`
+   * of the object's data.
+   */
+  download(object: PinnedObject, options?: DownloadOptions | undefined | null): ReadableStream
+  /** Returns a list of all usable hosts. */
+  hosts(): Promise<Array<Host>>
+  /** Returns object events from the indexer for syncing. */
+  objectEvents(cursor: ObjectsCursor | undefined | null, limit: number): Promise<Array<ObjectEvent>>
+  /** Updates the metadata of an object stored in the indexer. */
+  updateObjectMetadata(object: PinnedObject): Promise<void>
+  /** Deletes an object from the indexer. */
+  deleteObject(key: string): Promise<void>
+  /** Returns metadata about a specific object. */
+  object(key: string): Promise<PinnedObject>
+  /** Returns metadata about a slab. */
+  slab(slabId: string): Promise<PinnedSlab>
+  /** Unpins slabs not used by any object on the account. */
+  pruneSlabs(): Promise<void>
+  /** Returns the current account. */
+  account(): Promise<Account>
+  /** Creates a signed URL for sharing an object. */
+  shareObject(object: PinnedObject, validUntil: Date): string
+  /** Retrieves a shared object from a signed URL. */
+  sharedObject(sharedUrl: string): Promise<PinnedObject>
+  /** Pins an object to the indexer. */
+  pinObject(object: PinnedObject): Promise<void>
+}
+
+/** An account registered on the indexer. */
+export interface Account {
+  accountKey: string
+  maxPinnedData: bigint
+  remainingStorage: bigint
+  pinnedData: bigint
+  pinnedSize: bigint
+  ready: boolean
+  app: App
+  lastUsed: Date
+}
+
+/** The protocol used in a network address. */
+export declare const enum AddressProtocol {
+  SiaMux = 'SiaMux',
+  Quic = 'Quic'
+}
+
+/** Application info. */
+export interface App {
+  id: string
+  name: string
+  description: string
+  serviceUrl?: string
+  logoUrl?: string
+}
+
+/** Metadata about an application connecting to the indexer. */
+export interface AppMetadata {
+  id: Buffer
+  name: string
+  description: string
+  serviceUrl: string
+  logoUrl?: string
+  callbackUrl?: string
+}
+
+/** Download options. */
+export interface DownloadOptions {
+  maxInflight?: number
+  offset?: bigint
+  length?: bigint
+  onShardDownloaded?: (progress: ShardProgress) => void
+}
+
+/** Calculates the encoded size of data given the original size and erasure coding parameters. */
+export declare function encodedSize(size: bigint, dataShards: number, parityShards: number): bigint
+
+/** Generates a new BIP-39 12-word recovery phrase. */
+export declare function generateRecoveryPhrase(): string
+
+/** Information about a storage provider on the Sia network. */
+export interface Host {
+  publicKey: string
+  addresses: Array<NetAddress>
+  countryCode: string
+  latitude: number
+  longitude: number
+  goodForUpload: boolean
+}
+
+/** A network address of a storage provider on the Sia network. */
+export interface NetAddress {
+  protocol: AddressProtocol
+  address: string
+}
+
+/** A cursor for paginating through objects. */
+export interface ObjectsCursor {
+  id: string
+  after: Date
+}
+
+/** A sector stored on a specific host. */
+export interface PinnedSector {
+  root: string
+  hostKey: string
+}
+
+/** A pinned slab from the indexer. */
+export interface PinnedSlab {
+  id: string
+  encryptionKey: Buffer
+  minShards: number
+  sectors: Array<PinnedSector>
+}
+
+/** A sealed object for offline storage. */
+export interface SealedObject {
+  id: string
+  encryptedDataKey: Buffer
+  encryptedMetadataKey: Buffer
+  slabs: Array<Slab>
+  encryptedMetadata: Buffer
+  dataSignature: Buffer
+  metadataSignature: Buffer
+  createdAt: Date
+  updatedAt: Date
+}
+
+/**
+ * Sets a logging callback to receive log messages from the SDK.
+ *
+ * The callback receives formatted log messages as strings.
+ * `level` should be one of: "off", "error", "warn", "info", "debug", "trace".
+ */
+export declare function setLogger(callback: (message: string) => void, level: "off" | "error" | "warn" | "info" | "debug" | "trace"): void
+
+/** Progress information about a successfully uploaded or downloaded shard. */
+export interface ShardProgress {
+  hostKey: string
+  shardSize: number
+  shardIndex: number
+  slabIndex: number
+  elapsedMs: number
+}
+
+/** A slab representing a contiguous erasure-coded segment of a file. */
+export interface Slab {
+  encryptionKey: Buffer
+  minShards: number
+  sectors: Array<PinnedSector>
+  offset: number
+  length: number
+}
+
+/** Upload options. */
+export interface UploadOptions {
+  maxInflight?: number
+  dataShards?: number
+  parityShards?: number
+  onShardUploaded?: (progress: ShardProgress) => void
+}
+
+/** Validates a BIP-39 recovery phrase. */
+export declare function validateRecoveryPhrase(phrase: string): void
+
+export declare function initSia(): Promise<void>

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@siafoundation/sia-storage",
+  "version": "0.0.8",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "wasm"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "bun": "./dist/index.node.cjs",
+      "node": {
+        "types": "./dist/index.node.d.ts",
+        "require": "./dist/index.node.cjs",
+        "import": "./dist/index.node.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./wasm": "./wasm/sia_storage_wasm.js",
+    "./wasm/*": "./wasm/*"
+  },
+  "scripts": {
+    "build": "bun run build-wasm && tsup && bun run scripts/build-node-types.ts",
+    "build-wasm": "bun run scripts/build-wasm.ts",
+    "setup": "bun run scripts/setup-rust.ts",
+    "setup-napi-test": "bun run scripts/setup-napi-test.ts",
+    "test": "bun test src/tests/install-integration.test.ts",
+    "test:browser": "bun test src/tests/vite-integration.test.ts src/tests/esbuild-integration.test.ts src/tests/webpack-integration.test.ts src/tests/rollup-integration.test.ts src/tests/nextjs-integration.test.ts",
+    "test:all": "bun test",
+    "prepublishOnly": "bun run build && bun test",
+    "publish-npm": "bun run scripts/publish.ts"
+  },
+  "optionalDependencies": {
+    "@siafoundation/sia-storage-darwin-arm64": "0.0.8",
+    "@siafoundation/sia-storage-darwin-x64": "0.0.8",
+    "@siafoundation/sia-storage-linux-x64-gnu": "0.0.8",
+    "@siafoundation/sia-storage-linux-arm64-gnu": "0.0.8",
+    "@siafoundation/sia-storage-win32-x64-msvc": "0.0.8"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.3.5",
+    "playwright": "^1.58.2",
+    "tsup": "^8.4.0",
+    "typescript": "~5.9.3"
+  }
+}