client.storage

See the Files guide for the model. For small structured values, use client.kv.

Files are chunked, AES-256-GCM-encrypted, and Reed–Solomon-erasure-coded into a global, open, content-addressed shard store; the manifest (per-chunk keys + shard hashes) is the capability. Files are written to a SharedSpace (metered against it) and mirrored into the caller’s own space for discovery.

Methods

`writeFile(input)`

writeFile(input: {
  spaceId: string;
  data: Uint8Array | Blob | File;
  metadata: { name: string; type: string; path?: string; lastModified?: number };
}): Promise<{ stat: FileStat; manifest: FileManifest }>

Chunk + encrypt + erasure-code the data into the global shard store, write the manifest into spaceId’s gated store, and mirror it into the caller’s personal index. spaceId is required — files live in a Space (get one from client.space). Returns the stat and the manifest (share the manifest to let others read the file).

`readFile(spaceId, fileId)`

readFile(spaceId: string, fileId: string): Promise<{ data: Uint8Array; stat: FileStat }>

Fetch the manifest from the space, then reassemble the file from shards.

`readByManifest(manifest)`

readByManifest(manifest: FileManifest): Promise<{ data: Uint8Array; stat: FileStat }>

The capability read: reassemble a file straight from a manifest, reading the global shards. No space membership required — this is how a shared file is opened by a recipient.

`listFiles(opts?)`

listFiles(opts?: { spaceId?: string }): Promise<FileStat[]>

With no argument, lists the caller’s own shared files (from the personal discovery mirror). With { spaceId }, lists that space’s files.

`deleteFile(spaceId, fileId)`

deleteFile(spaceId: string, fileId: string): Promise<boolean>

Removes the manifest from the space and the caller’s mirror entry. Resolves to whether the file existed. Shards are content-addressed and may be referenced by other manifests, so they are not deleted here (server-side GC is separate).

`getManifest(spaceId, fileId)`

getManifest(spaceId: string, fileId: string): Promise<FileManifest>

Fetch a manifest without downloading the file — e.g. to share it.

Types

interface FileStat {
  id: string;
  name: string;
  size: number;        // total plaintext bytes
  type: string;        // MIME type the app supplied
  path?: string;
  lastModified: number;
  createdAt: number;
  chunkCount: number;
  shardCount: number;
}

interface FileManifest {
  id: string;
  name: string;
  size: number;
  type: string;
  path?: string;
  lastModified: number;
  createdAt: number;
  chunks: ChunkManifest[]; // per-chunk keys, IVs, RS params, shard hashes
  version: 1;
}