BlobsService

Handles CRUD and traversal for hierarchical “blobs” — the platform’s core data containers. Every blob has owner-scoped permissions (read/write/delete/share) which the API enforces; children may inherit parent permissions when inherit_permissions is set. This service caches individual blobs and the top-level list for cacheTTL and emits real-time events via the shared wire-event manager.

Example

const sdk = createSDK({ networks: [...] });
const created = await sdk.blobs.create({ name: 'My Folder', type: 'folder' });
if (created.success) console.log(created.data!.id);

Constructors

Constructor

new BlobsService(context): BlobsService

Defined in: services/BlobsService.ts:83

Constructs a BlobsService bound to the given context.

Parameters

context

BlobsContext

Shared BlobsContext providing transport, cache, and event manager.

Returns

BlobsService

Methods

create()

create(input, options?): Promise<Response<Blob>>

Defined in: services/BlobsService.ts:126

Creates a new blob and caches the returned record. Invalidates the blob list cache.

Parameters

input

CreateBlobInput

Blob fields to create (name, type, parent, content, permissions).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob>>

A Response containing the created Blob with server-assigned id and timestamps.

Throws

PermissionError when the user lacks write access to the parent.

Throws

ValidationError when the input is rejected by the server.

Remarks

Mirrors the Go SDK Create method.

Example

const res = await sdk.blobs.create({ name: 'docs', type: 'folder' });

getById()

getById(id, useCache?, options?): Promise<Response<Blob>>

Defined in: services/BlobsService.ts:159

Fetches a blob by ID, served from cache when available and useCache is true.

Parameters

id

string

The blob identifier.

useCache?

boolean = true

When true (default), returns a cached value if present; pass false to force a network fetch.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob>>

A Response containing the Blob.

Throws

NotFoundError when no blob with the given ID exists.

Throws

PermissionError when the user lacks read access.

Remarks

Mirrors the Go SDK GetByID method.

Example

const res = await sdk.blobs.getById('blob_123');

list()

list(useCache?, options?): Promise<Response<Blob[]>>

Defined in: services/BlobsService.ts:195

Lists all blobs visible to the current user, served from cache when available.

Parameters

useCache?

boolean = true

When true (default), returns a cached value if present; pass false to force a network fetch.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob[]>>

A Response containing an array of Blob records visible to the caller.

Remarks

Mirrors the Go SDK List method.

update()

update(id, input, options?): Promise<Response<Blob>>

Defined in: services/BlobsService.ts:230

Updates a blob and invalidates both its individual cache entry and the list cache.

Parameters

id

string

The blob identifier.

input

UpdateBlobInput

Partial blob fields to update.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob>>

A Response containing the updated Blob.

Throws

NotFoundError when no blob with the given ID exists.

Throws

PermissionError when the user lacks write access.

Remarks

Mirrors the Go SDK Update method.

delete()

delete(id, options?): Promise<Response<void>>

Defined in: services/BlobsService.ts:261

Deletes a blob and invalidates its cache entries.

Parameters

id

string

The blob identifier.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<void>>

A Response with no payload on success.

Throws

NotFoundError when no blob with the given ID exists.

Throws

PermissionError when the user lacks delete access.

Remarks

Mirrors the Go SDK Delete method.

restore()

restore(id, options?): Promise<Response<{ blob: Blob; restored: Blob[]; restored_count: number; }>>

Defined in: services/BlobsService.ts:300

Restores a soft-deleted blob (and any descendants that were cascade-deleted in the same operation) by id.

Server-side, the original delete stamps a shared delete_batch_id on every row in the cascaded subtree. Restore looks up the batch for the target id and reverses every stamped row at once. Returns the primary restored blob along with the full restored set.

Parameters

id

string

The blob id to restore (must be currently soft-deleted).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ blob: Blob; restored: Blob[]; restored_count: number; }>>

Throws

NotFoundError when the id is unknown or not deleted.

Throws

PermissionError when the caller lacks write access.

bulkCreate()

bulkCreate(inputs, options?): Promise<Response<BulkCreateBlobsResponse>>

Defined in: services/BlobsService.ts:346

Creates many blobs in one round-trip with per-item success/failure tracking.

Each input is created independently — a permission failure or validation error on one item does not abort the others. The returned envelope mirrors pkg/bulkop on the server: total, successful, failed, plus a results array indexed by input position.

Used internally by BulkDeleteBlobsAction.undo() to atomically recreate a previously bulk-deleted set in a single request.

Parameters

inputs

CreateBlobInput[]

Array of blob inputs to create (max 100 per request).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<BulkCreateBlobsResponse>>

bulkDelete()

bulkDelete(blobIds, options?): Promise<Response<{ results: BulkDeleteBlobResult[]; }>>

Defined in: services/BlobsService.ts:371

Parameters

blobIds

string[]

options?

MultiNetworkOptions

Returns

Promise<Response<{ results: BulkDeleteBlobResult[]; }>>

getChildren()

getChildren(id, childOptions?, options?): Promise<Response<Blob[]>>

Defined in: services/BlobsService.ts:411

Lists the direct (or recursive) children of a blob.

Parameters

id

string

The parent blob identifier.

childOptions?

Optional traversal flags: summary returns lightweight projections, depth controls recursion depth.

summary?

boolean

depth?

number

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob[]>>

A Response containing the array of child Blob records.

Throws

PermissionError when the user lacks read access to the parent.

removeChild()

removeChild(parentId, childId, deleteBlob?, options?): Promise<Response<void>>

Defined in: services/BlobsService.ts:441

Removes a child blob’s link from its parent, optionally deleting the child entirely.

Parameters

parentId

string

ID of the parent blob.

childId

string

ID of the child blob to remove.

deleteBlob?

boolean = false

If true, also deletes the child blob; if false (default), only removes the parent reference.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<void>>

A Response with no payload on success.

Throws

NotFoundError when either blob does not exist.

Throws

PermissionError when the user lacks write access to the parent (or delete access when deleteBlob is true).

query()

query(filters, options?): Promise<Response<Blob[]>>

Defined in: services/BlobsService.ts:479

Queries blobs using server-side filters serialized into the URL query string.

Parameters

filters

Record<string, any>

Arbitrary key/value filters forwarded to the server (e.g. { type: 'folder', parent_id: 'x' }).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<Blob[]>>

A Response containing matching Blob records.

clearCache()

clearCache(): Promise<void>

Defined in: services/BlobsService.ts:494

Clears all blob and blob-list cache entries across every network namespace.

Returns

Promise<void>

A promise that resolves once cache entries have been removed.

subscribe(event, callback, options?): () => void

Defined in: services/BlobsService.ts:509

Subscribes to a real-time blob event by name. Delegates to the unified ctx.wireEvents manager which de-duplicates transport subscriptions across services and provides buffered replay for late subscribers. The legacy (data) => void callback signature is preserved.