File storage

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

StorageOptions

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

StorageRequestOptions

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

StorageDownloadOptions

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

StorageUploadOptions

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

ResumableUploadOptions

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

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

StorageUploadQueueAdapter

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

QueuedUpload

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

MemoryStorageUploadQueueAdapter

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

load

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

put

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

remove

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

IndexedDBStorageUploadQueueAdapter

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

constructor

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

load

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

put

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

remove

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

close

close(): Promise<void>;

StorageListOptions

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

BlobDescriptor

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

StoredBlob

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

BlobRemoval

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

FileEncryptionMetadata

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

PrivateStoredBlob

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

FileKey

type FileKey = Uint8Array | string;

NostrbaseStorage

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

constructor

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

from

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

processImage

/** 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

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

BlossomBucket

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

Properties

readonly server: string;

constructor

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

upload

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

uploadPrivate

/** 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

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

queueUpload

/** 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

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

replayUploads

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

download

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

remove

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

list

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