# File storage

Blossom methods and request options.

[Read the file storage guide](/docs/storage/). Signatures below come from the published SDK declarations. Access SDK services through `db`; use their constructors only when integrating at a lower level.

## StorageOptions


```ts
interface StorageOptions {
  fetch?: typeof globalThis.fetch;
  timeout?: number;
  imageProcessor?: ImageProcessor;
  /** Optional durable adapter for queued file uploads. */
  uploadQueue?: StorageUploadQueueAdapter;
}
```

## StorageRequestOptions


```ts
interface StorageRequestOptions {
  signal?: AbortSignal;
  timeout?: number;
}
```

## StorageDownloadOptions


```ts
interface StorageDownloadOptions extends StorageRequestOptions {
  /** Send a scoped get token. Public downloads do not require a signer. */ authenticated?: boolean;
  transform?: ImageTransformOptions;
}
```

## StorageUploadOptions


```ts
interface StorageUploadOptions extends StorageRequestOptions {
  transform?: ImageTransformOptions;
  resumable?: ResumableUploadOptions;
}
```

## ResumableUploadOptions


```ts
interface ResumableUploadOptions {
  /** Stable id used by the server to identify a partial upload. */
  id?: string;
  /** Chunk size in bytes. Defaults to 1 MiB. */
  chunkSize?: number;
  onProgress?: (progress: UploadProgress) => void;
}
```

## UploadProgress


```ts
interface UploadProgress {
  uploaded: number;
  total: number;
  /** True when the server has accepted the complete object. */
  complete: boolean;
}
```

## StorageUploadQueueAdapter


```ts
interface StorageUploadQueueAdapter {
  load(server?: string): Promise<StorageUploadQueueEntry[]>;
  put(entry: StorageUploadQueueEntry): Promise<void>;
  remove(id: string): Promise<void>;
  close?(): void | Promise<void>;
}
```

## QueuedUpload


```ts
interface QueuedUpload {
  id: string;
  name: string;
  server: string;
  createdAt: number;
  size: number;
}
```

## MemoryStorageUploadQueueAdapter


```ts
/** In-memory upload queue. Supply a durable adapter for restart recovery. */
declare class MemoryStorageUploadQueueAdapter implements StorageUploadQueueAdapter {}
```

### load


```ts
load(server?: string): Promise<StorageUploadQueueEntry[]>;
```

### put


```ts
put(entry: StorageUploadQueueEntry): Promise<void>;
```

### remove


```ts
remove(id: string): Promise<void>;
```

## IndexedDBStorageUploadQueueAdapter


```ts
/** Durable browser upload queue. Entries are removed only after a verified upload succeeds. */
declare class IndexedDBStorageUploadQueueAdapter implements StorageUploadQueueAdapter {}
```

### constructor


```ts
constructor(name?: string, factory?: IDBFactory | undefined);
```

### load


```ts
load(server?: string): Promise<StorageUploadQueueEntry[]>;
```

### put


```ts
put(entry: StorageUploadQueueEntry): Promise<void>;
```

### remove


```ts
remove(id: string): Promise<void>;
```

### close


```ts
close(): Promise<void>;
```

## StorageListOptions


```ts
interface StorageListOptions extends StorageRequestOptions {
  cursor?: string;
  limit?: number;
}
```

## BlobDescriptor


```ts
interface BlobDescriptor {
  url: string;
  sha256: string;
  size: number;
  type: string;
  uploaded: number;
}
```

## StoredBlob


```ts
interface StoredBlob extends BlobDescriptor {
  /** Display metadata only; Blossom objects use the SHA-256 hash as their key. */ name: string;
}
```

## BlobRemoval


```ts
interface BlobRemoval {
  sha256: string;
  ok: boolean;
  error: NostrbaseError | null;
}
```

## FileEncryptionMetadata


```ts
interface FileEncryptionMetadata {
  version: 1;
  algorithm: "AES-256-GCM";
  nonce: string;
  type: string;
  size: number;
  name: string;
}
```

## PrivateStoredBlob


```ts
interface PrivateStoredBlob extends StoredBlob {
  encryption: FileEncryptionMetadata;
  /** Base64url encoded 32-byte AES key. Keep this with the app's Nostr record. */
  key: string;
}
```

## FileKey


```ts
type FileKey = Uint8Array | string;
```

## NostrbaseStorage


```ts
/** Blossom uses an explicitly selected file server alongside Nostr relays. */
declare class NostrbaseStorage<DB extends SchemaShape<DB>> {}
```

### constructor


```ts
constructor(host: NostrbaseClient<DB>, options?: StorageOptions);
```

### from


```ts
from(server: string): BlossomBucket<DB>;
```

### processImage


```ts
/** Process image bytes locally. This method does not contact a server. */
processImage(blob: Blob, options?: ImageProcessingOptions): Promise<Result<Blob>>;
```


## Supporting declarations

These types appear in public signatures but are not package exports.

### StorageUploadQueueEntry


```ts
interface StorageUploadQueueEntry {
  id: string;
  server: string;
  name: string;
  blob: Blob;
  options?: Omit<StorageUploadOptions, "signal">;
  createdAt: number;
}
```

### BlossomBucket


```ts
declare class BlossomBucket<DB extends SchemaShape<DB>> {}
```

### Properties


```ts
readonly server: string;
```

### constructor


```ts
constructor(host: NostrbaseClient<DB>, origin: URL, options: StorageOptions);
```

### upload


```ts
upload(
  name: string,
  blob: Blob,
  options?: StorageUploadOptions,
): Promise<Result<StoredBlob>>;
```

### uploadPrivate


```ts
/** Upload an encrypted attachment. The returned key must be shared separately through Nostr. */
uploadPrivate(
  name: string,
  blob: Blob,
  options?: StorageUploadOptions & {
    key?: FileKey;
  },
): Promise<Result<PrivateStoredBlob>>;
```

### downloadPrivate


```ts
/** Download and authenticate an encrypted attachment. Metadata is authenticated as AAD. */
downloadPrivate(
  hash: string,
  encryption: FileEncryptionMetadata,
  key: FileKey,
  options?: StorageDownloadOptions,
): Promise<Result<Blob>>;
```

### queueUpload


```ts
/** Queue an upload in the configured adapter. Blob bytes are retained locally until replay. */
queueUpload(
  name: string,
  blob: Blob,
  options?: Omit<StorageUploadOptions, "signal">,
): Promise<Result<QueuedUpload>>;
```

### listQueuedUploads


```ts
listQueuedUploads(): Promise<Result<QueuedUpload[]>>;
```

### replayUploads


```ts
replayUploads(options?: StorageRequestOptions): Promise<Result<StoredBlob[]>>;
```

### download


```ts
download(hash: string, options?: StorageDownloadOptions): Promise<Result<Blob>>;
```

### remove


```ts
remove(
  hashes: readonly string[],
  options?: StorageRequestOptions,
): Promise<Result<BlobRemoval[]>>;
```

### list


```ts
list(
  pubkey?: string,
  options?: StorageListOptions,
): Promise<Result<BlobDescriptor[]>>;
```