Primitive Docs

Appearance

js-bao-wss-client

js-bao-wss-client / DocumentsAPI

Interface: DocumentsAPI ​

Properties ​

aliases ​

aliases: DocumentAliasesAPI

Methods ​

acceptInvitation() ​

acceptInvitation(documentId): Promise<DocumentAccessResult>

Accept a pending invitation to access a document.

Parameters ​

documentId ​

string

The unique identifier of the document whose invitation to accept

Returns ​

Promise<DocumentAccessResult>

Deprecated ​

The per-document accept concept has been removed. Document shares to existing users take effect immediately via documents.updatePermissions — no accept call is needed. For not-yet-registered users, deferred grants resolve when the recipient accepts the app-level invitation via client.invitations.accept(inviteToken). The inviteToken is provided in the deferred-grant response of documents.updatePermissions on the inviter side, not via any invitee-callable on documents.*.

addTag() ​

addTag(documentId, tag): Promise<string[]>

Add a tag to a document.

Parameters ​

documentId ​

string

The unique identifier of the document to tag

tag ​

string

The tag string to add

Returns ​

Promise<string[]>

approveAccessRequest() ​

approveAccessRequest(documentId, requestId, options?): Promise<{ message: string; request: DocumentAccessRequest; success: boolean; }>

Approve a pending access request. Only document owners and app admins may call this.

Parameters ​

documentId ​

string

The unique identifier of the document

requestId ​

string

The identifier of the request to approve

options? ​

Options

documentUrl? ​

string

URL included in the notification email to the requester

permission? ​

"read-write" | "reader"

Optionally override the requested permission level

Returns ​

Promise<{ message: string; request: DocumentAccessRequest; success: boolean; }>

blobs() ​

blobs(documentId): DocumentBlobContext

Get the blob API context for a specific document.

Parameters ​

documentId ​

string

The document whose blob context to retrieve

Returns ​

DocumentBlobContext

cancelPendingCreate() ​

cancelPendingCreate(documentId, opts?): Promise<void>

Cancel a pending local document create and optionally evict its local data.

Parameters ​

documentId ​

string

The unique identifier of the pending document to cancel

opts? ​

Cancellation options

evictLocal? ​

boolean

If true, also removes the document's local data from storage after cancellation

Returns ​

Promise<void>

close() ​

close(documentId, options?): Promise<{ evicted: boolean; }>

Close an open document and optionally evict its local data. When evictLocal is true, the server is first checked to confirm it has all the client's writes. If it doesn't, eviction is skipped and { evicted: false } is returned.

Parameters ​

documentId ​

string

The unique identifier of the document to close

options? ​

Close options

evictLocal? ​

boolean

If true, also removes the document's local data from storage after closing

Returns ​

Promise<{ evicted: boolean; }>

  • Whether local data was actually evicted

commitOfflineCreate() ​

commitOfflineCreate(documentId, opts?): Promise<{ created: boolean; linked?: boolean; reason?: string; }>

Commit a locally created document to the server.

Parameters ​

documentId ​

string

The unique identifier of the locally created document to commit

opts? ​

Commit options

onExists? ​

"link" | "fail"

Behavior when the document already exists on the server: "link" associates the local document with the existing server document, "fail" throws an error

Returns ​

Promise<{ created: boolean; linked?: boolean; reason?: string; }>

create() ​

create(options): Promise<{ metadata: any; }>

Create a new document, optionally as local-only with automatic server commit.

Parameters ​

options ​

CreateDocumentOptions

Options for document creation

Returns ​

Promise<{ metadata: any; }>

createInvitation() ​

createInvitation(documentId, email, permission, options?): Promise<DocumentInvitationResponse>

Create an invitation to share a document with a user by email.

Parameters ​

documentId ​

string

The unique identifier of the document to share

email ​

string

The email address of the user to invite

permission ​

The permission level to grant the invitee

"read-write" | "reader"

options? ​

Optional email notification settings

documentUrl? ​

string

URL included in the invitation email so the recipient can navigate to the document

note? ​

string

A personal message included in the invitation email

sendEmail? ​

boolean

If true, sends an email notification to the invitee

Returns ​

Promise<DocumentInvitationResponse>

Deprecated ​

Use documents.updatePermissions(documentId, { email, permission, sendEmail, documentUrl, note }). updatePermissions returns DirectPermissionGrant | DeferredPermissionGrant — for not-yet-registered emails the deferred branch carries invitationId + inviteToken. The legacy method writes to the per-document DocumentInvitation model, which is invisible to listPendingInvitations.

See ​

DocumentsAPI.updatePermissions

createOffline() ​

createOffline(_options): Promise<Doc>

Parameters ​

_options ​

CreateOfflineOptions

Returns ​

Promise<Doc>

Deprecated ​

Use documents.create({ localOnly: true }) followed by documents.open(id, { waitForLoad: 'local', enableNetworkSync: false }) instead.

See ​

CreateDocumentOptions

createWithAlias() ​

createWithAlias(options): Promise<{ alias: DocumentAliasInfo; createdAt: string; createdBy: string; documentId: string; modifiedAt: string; title: string; }>

Create a document with an alias atomically, failing if the alias already exists.

Parameters ​

options ​

CreateWithAliasOptions

Options for document and alias creation

Returns ​

Promise<{ alias: DocumentAliasInfo; createdAt: string; createdBy: string; documentId: string; modifiedAt: string; title: string; }>

The created document's documentId, title, createdBy, timestamps, and the assigned alias

declineInvitation() ​

declineInvitation(documentId, invitationId): Promise<{ message: string; success: boolean; }>

Decline a pending invitation to access a document.

Parameters ​

documentId ​

string

The unique identifier of the document whose invitation to decline

invitationId ​

string

The identifier of the specific invitation to decline

Returns ​

Promise<{ message: string; success: boolean; }>

Deprecated ​

No invitee-side decline verb. Pending invitations expire automatically, so a recipient who hasn't accepted can simply ignore the invite. To remove yourself from an already-accepted share, call documents.removePermission(documentId, { userId: <your userId> }). See issue #619.

delete() ​

delete(documentId, opts?): Promise<void>

Delete a document from the server and evict its local data.

Parameters ​

documentId ​

string

The unique identifier of the document to delete

opts? ​

DeleteDocumentOptions

Options for document deletion

Returns ​

Promise<void>

deleteInvitation() ​

deleteInvitation(documentId, invitationId): Promise<{ message: string; success: boolean; }>

Delete a document invitation.

Parameters ​

documentId ​

string

The unique identifier of the document whose invitation to delete

invitationId ​

string

The identifier of the specific invitation to delete

Returns ​

Promise<{ message: string; success: boolean; }>

Deprecated ​

Use documents.removePermission(documentId, { email }) to cancel a pending grant by email, or client.invitations.delete(invitationId) for app-level cancel.

See ​

denyAccessRequest() ​

denyAccessRequest(documentId, requestId, options?): Promise<{ message: string; request: DocumentAccessRequest; success: boolean; }>

Deny a pending access request. Only document owners and app admins may call this.

Parameters ​

documentId ​

string

The unique identifier of the document

requestId ​

string

The identifier of the request to deny

options? ​

Options

documentUrl? ​

string

URL included in the notification email to the requester

Returns ​

Promise<{ message: string; request: DocumentAccessRequest; success: boolean; }>

evict() ​

evict(documentId, opts?): Promise<void>

Evict a document's local data from the device.

Parameters ​

documentId ​

string

The unique identifier of the document to evict

opts? ​

EvictDocumentOptions

Eviction options

Returns ​

Promise<void>

evictAll() ​

evictAll(opts?): Promise<void>

Evict all locally stored document data from the device.

Parameters ​

opts? ​

EvictAllDocumentsOptions

Eviction options

Returns ​

Promise<void>

for() ​

for(documentId): DocumentContext

Get a DocumentContext scoped to a specific document.

Parameters ​

documentId ​

string

The document to create a scoped context for

Returns ​

DocumentContext

get() ​

get(documentId): Promise<DocumentInfo>

Fetch document metadata from the server.

Parameters ​

documentId ​

string

The unique identifier of the document to fetch

Returns ​

Promise<DocumentInfo>

getAwarenessStates() ​

getAwarenessStates(documentId): Map<string, any>

Get all current awareness states for a document.

Parameters ​

documentId ​

string

The unique identifier of the document to get awareness states from

Returns ​

Map<string, any>

getDocumentPermission() ​

getDocumentPermission(documentId): "owner" | "read-write" | "reader" | "admin" | null

Get the current user's permission level for a document.

Parameters ​

documentId ​

string

The unique identifier of the document to check permissions for

Returns ​

"owner" | "read-write" | "reader" | "admin" | null

getInvitation() ​

getInvitation(documentId, email): Promise<DocumentInvitation | null>

Get a specific invitation for a document by email address.

Parameters ​

documentId ​

string

The unique identifier of the document to search invitations for

email ​

string

The email address of the invitee to look up

Returns ​

Promise<DocumentInvitation | null>

Deprecated ​

Use client.invitations.get(invitationId) for direct lookup, or documents.listPendingInvitations(documentId) filtered by email.

See ​

getLocalMetadata() ​

getLocalMetadata(documentId): Promise<LocalMetadataEntry | null>

Get locally cached metadata for a document.

Parameters ​

documentId ​

string

The unique identifier of the document whose local metadata to retrieve

Returns ​

Promise<LocalMetadataEntry | null>

getOrCreateWithAlias() ​

getOrCreateWithAlias(options): Promise<{ alias: DocumentAliasInfo; created: boolean; createdAt?: string; createdBy?: string; documentId: string; modifiedAt?: string; title?: string; }>

Get an existing document by alias, or create a new one if the alias does not exist.

Parameters ​

options ​

GetOrCreateWithAliasOptions

Options for alias lookup and fallback creation

Returns ​

Promise<{ alias: DocumentAliasInfo; created: boolean; createdAt?: string; createdBy?: string; documentId: string; modifiedAt?: string; title?: string; }>

The document's documentId, metadata, alias, and a created flag indicating whether a new document was created

getPermissions() ​

getPermissions(documentId): Promise<DocumentPermissionEntry[]>

Get the list of user permissions for a document.

Parameters ​

documentId ​

string

The unique identifier of the document whose permissions to retrieve

Returns ​

Promise<DocumentPermissionEntry[]>

getRoot() ​

getRoot(): Promise<DocumentInfo>

Get metadata for the app's root document.

Returns ​

Promise<DocumentInfo>

getUploadConcurrency() ​

getUploadConcurrency(): number

Get the current maximum number of concurrent blob uploads.

Returns ​

number

grantGroupPermission() ​

grantGroupPermission(documentId, params): Promise<DocumentGroupPermissionEntry>

Grant a group permission on a document.

Parameters ​

documentId ​

string

The unique identifier of the document to grant access to

params ​

GrantGroupPermissionParams

The group permission to grant

Returns ​

Promise<DocumentGroupPermissionEntry>

hasLocalCopy() ​

hasLocalCopy(documentId): boolean

Check whether a document has a local copy stored on this device.

Parameters ​

documentId ​

string

The unique identifier of the document to check

Returns ​

boolean

includesWrites() ​

includesWrites(documentId, timeoutMs?): Promise<boolean>

Check whether the server has all of this client's writes for a document. Performs a state vector comparison via WebSocket. Returns false if the WebSocket is disconnected or the check times out.

Parameters ​

documentId ​

string

The document to check

timeoutMs? ​

number

Timeout in milliseconds (default 5000)

Returns ​

Promise<boolean>

inSync() ​

inSync(documentId, timeoutMs?): Promise<boolean>

Check whether the client and server have identical document state. Returns false if the WebSocket is disconnected or the check times out.

Parameters ​

documentId ​

string

The document to check

timeoutMs? ​

number

Timeout in milliseconds (default 5000)

Returns ​

Promise<boolean>

isOpen() ​

isOpen(documentId): boolean

Check whether a document is currently open.

Parameters ​

documentId ​

string

The unique identifier of the document to check

Returns ​

boolean

isPendingCreate() ​

isPendingCreate(documentId): boolean

Check whether a document has a pending local create that has not been committed.

Parameters ​

documentId ​

string

The unique identifier of the document to check

Returns ​

boolean

isReadOnly() ​

isReadOnly(documentId): boolean

Check whether the document is read-only for the current user.

Parameters ​

documentId ​

string

The unique identifier of the document to check

Returns ​

boolean

isSynced() ​

isSynced(documentId): boolean

Check whether a document's local state is synced with the server.

Parameters ​

documentId ​

string

The unique identifier of the document to check sync status for

Returns ​

boolean

list() ​

Call Signature ​

list(options?): Promise<DocumentInfo[]>

List documents accessible to the current user with configurable loading and pagination.

Parameters ​
options? ​

DocumentListOptions

Controls which documents are returned, how they are loaded, and pagination

Returns ​

Promise<DocumentInfo[]>

Call Signature ​

list(options): Promise<DocumentListPage>

List documents accessible to the current user with configurable loading and pagination.

Parameters ​
options ​

DocumentListOptions & object

Controls which documents are returned, how they are loaded, and pagination

Returns ​

Promise<DocumentListPage>

listAccessRequests() ​

listAccessRequests(documentId): Promise<DocumentAccessRequest[]>

List pending access requests for a document. Only document owners and app admins may call this.

Parameters ​

documentId ​

string

The unique identifier of the document whose access requests to list

Returns ​

Promise<DocumentAccessRequest[]>

listGroupPermissions() ​

listGroupPermissions(documentId, options?): Promise<DocumentGroupPermissionEntry[]>

List all group-based permissions for a document.

By default, platform-managed internal groups (those whose groupType is prefixed with _, e.g. _col-reader / _col-writer backing collection sharing) are excluded — they are not user-meaningful. Pass { includeSystem: true } to include them (typically only useful for admin tooling).

Parameters ​

documentId ​

string

The unique identifier of the document whose group permissions to list

options? ​

Optional list options. Set includeSystem to true to include platform-managed internal groups in the result.

includeSystem? ​

boolean

Returns ​

Promise<DocumentGroupPermissionEntry[]>

listInvitations() ​

listInvitations(documentId): Promise<DocumentInvitation[]>

List all invitations for a document.

Parameters ​

documentId ​

string

The unique identifier of the document whose invitations to list

Returns ​

Promise<DocumentInvitation[]>

Deprecated ​

Use documents.listPendingInvitations(documentId). Note: listPendingInvitations reads only DeferredDocumentPermission. Documents that received legacy invitations via createInvitation are stored in the per-document DocumentInvitation model and will not appear in listPendingInvitations.

See ​

DocumentsAPI.listPendingInvitations

listOpen() ​

listOpen(): string[]

List the IDs of all currently open documents.

Returns ​

string[]

listPendingCreates() ​

listPendingCreates(): Promise<object[]>

List all documents that were created locally but not yet committed to the server.

Returns ​

Promise<object[]>

listPendingInvitations() ​

listPendingInvitations(documentId): Promise<PendingInvitationEntry[]>

List pending (unresolved, non-expired) invitations scoped to this document.

Returns denormalized rows suitable for rendering alongside the existing getPermissions() list in a sharing UI — callers never need to touch the internal deferred-grants surface.

Parameters ​

documentId ​

string

The unique identifier of the document

Returns ​

Promise<PendingInvitationEntry[]>

open() ​

open(documentId, options?): Promise<{ doc: Doc | null; metadata: any; }>

Open a document for editing with configurable loading and sync behavior.

Parameters ​

documentId ​

string

The unique identifier of the document to open

options? ​

Controls how the document is loaded and synced

availabilityWaitMs? ​

number

Maximum time in milliseconds to wait for the document to become available from the network

deferNetworkSync? ​

boolean

If true, opens the document locally without starting server sync until startNetworkSync() is called

enableNetworkSync? ​

boolean

If false, opens the document without establishing a server connection (defaults to true)

retainLocalCopyAfterClose? ​

boolean

If false, evicts the local copy when the document is closed (defaults to true)

waitForLoad? ​

"local" | "network" | "localIfAvailableElseNetwork"

Controls when the returned promise resolves: "local" resolves once local data is loaded, "network" waits for server sync to complete, "localIfAvailableElseNetwork" uses local data if a copy exists or falls back to a blocking server fetch

Returns ​

Promise<{ doc: Doc | null; metadata: any; }>

openAlias() ​

openAlias(params, options?): Promise<{ doc: Doc; metadata: LocalMetadataEntry | null; }>

Open a document by resolving its alias first.

Parameters ​

params ​

ResolveAliasParams

The alias to resolve before opening

options? ​

Open options forwarded to openDocument after the alias is resolved

availabilityWaitMs? ​

number

deferNetworkSync? ​

boolean

enableNetworkSync? ​

boolean

requestSyncPerf? ​

boolean

retainLocal? ​

boolean

waitForLoad? ​

"local" | "network" | "localIfAvailableElseNetwork"

Returns ​

Promise<{ doc: Doc; metadata: LocalMetadataEntry | null; }>

openRoot() ​

openRoot(): Promise<Doc>

Open the app's root document for editing.

Returns ​

Promise<Doc>

pauseAllUploads() ​

pauseAllUploads(documentId?): void

Pause all blob uploads, optionally filtered by document.

Parameters ​

documentId? ​

string

If provided, only pauses uploads for this document; otherwise pauses all uploads

Returns ​

void

pauseUpload() ​

pauseUpload(documentId, blobId): boolean

Pause a specific blob upload.

Parameters ​

documentId ​

string

The document the blob belongs to

blobId ​

string

The identifier of the blob upload to pause

Returns ​

boolean

removeAwareness() ​

removeAwareness(documentId, clientIds, reason?): void

Remove awareness states for specific clients from a document.

Parameters ​

documentId ​

string

The unique identifier of the document to remove awareness from

clientIds ​

string[]

The client IDs whose awareness states to remove

reason? ​

string

An optional reason string describing why the awareness states are being removed (e.g., "timeout")

Returns ​

void

removePermission() ​

removePermission(documentId, target): Promise<void>

Remove a user's permission from a document, or cancel a pending (deferred) invitation by email.

  • Pass a string userId to remove an existing user's direct permission.
  • Pass { userId } to do the same via the structured form.
  • Pass { email } to cancel a pending invitation (or, if the email resolves to an app member, remove their direct permission).

When the caller's own permission is removed, the document is also evicted locally.

Parameters ​

documentId ​

string

The unique identifier of the document to revoke access from

target ​

Either a user ID string, or an object with userId / email

string | { email?: undefined; userId: string; } | { email: string; userId?: undefined; }

Returns ​

Promise<void>

removeTag() ​

removeTag(documentId, tag): Promise<string[]>

Remove a tag from a document.

Parameters ​

documentId ​

string

The unique identifier of the document to untag

tag ​

string

The tag string to remove

Returns ​

Promise<string[]>

requestAccess() ​

requestAccess(documentId, options): Promise<DocumentAccessRequestResponse>

Request access to a document you currently don't have permission to.

Parameters ​

documentId ​

string

The unique identifier of the document to request access to

options ​

Request options

documentUrl? ​

string

URL included in the notification email so owners can navigate to the document

message? ​

string

Optional note (max 500 chars) to include with the request

permission ​

"read-write" | "reader"

The permission level being requested ("read-write" or "reader")

reviewUrl? ​

string

URL included in the notification email for owners to review the request

sendEmail? ​

boolean

If false, skip sending the owner notification email (default: true)

Returns ​

Promise<DocumentAccessRequestResponse>

resumeAllUploads() ​

resumeAllUploads(documentId?): void

Resume all paused blob uploads, optionally filtered by document.

Parameters ​

documentId? ​

string

If provided, only resumes uploads for this document; otherwise resumes all uploads

Returns ​

void

resumeUpload() ​

resumeUpload(documentId, blobId): boolean

Resume a specific paused blob upload.

Parameters ​

documentId ​

string

The document the blob belongs to

blobId ​

string

The identifier of the paused blob upload to resume

Returns ​

boolean

revokeGroupPermission() ​

revokeGroupPermission(documentId, groupType, groupId): Promise<{ success: boolean; }>

Revoke a group's permission on a document.

Parameters ​

documentId ​

string

The unique identifier of the document to revoke access from

groupType ​

string

The type of group whose permission to revoke

groupId ​

string

The identifier of the group whose permission to revoke

Returns ​

Promise<{ success: boolean; }>

setAwareness() ​

setAwareness(documentId, state): void

Set the local user's awareness state for a document (e.g., cursor position).

Parameters ​

documentId ​

string

The unique identifier of the document to set awareness on

state ​

any

The awareness state object to broadcast to other connected clients

Returns ​

void

setUploadConcurrency() ​

setUploadConcurrency(concurrency): void

Set the maximum number of concurrent blob uploads.

Parameters ​

concurrency ​

number

The maximum number of blob uploads that can run simultaneously

Returns ​

void

transferOwnership() ​

transferOwnership(documentId, newOwnerId): Promise<void>

Transfer document ownership to another user.

Parameters ​

documentId ​

string

The unique identifier of the document to transfer

newOwnerId ​

string

The user ID of the new owner

Returns ​

Promise<void>

update() ​

update(documentId, data): Promise<DocumentInfo>

Update document metadata such as its title.

Parameters ​

documentId ​

string

The unique identifier of the document to update

data ​

UpdateDocumentData

The document metadata fields to update

Returns ​

Promise<DocumentInfo>

updateInvitation() ​

updateInvitation(documentId, email, permission, options?): Promise<DocumentInvitationResponse>

Update an existing invitation's permission level.

Parameters ​

documentId ​

string

The unique identifier of the document whose invitation to update

email ​

string

The email address of the invitee whose permission to change

permission ​

The new permission level to grant

"read-write" | "reader"

options? ​

Optional email notification settings

documentUrl? ​

string

URL included in the notification email so the recipient can navigate to the document

note? ​

string

A personal message included in the notification email

sendEmail? ​

boolean

If true, sends an email notification about the updated permission

Returns ​

Promise<DocumentInvitationResponse>

Deprecated ​

Use documents.updatePermissions(documentId, { email, permission, ... }). updatePermissions is idempotent — re-calling with the same email updates the existing grant.

See ​

DocumentsAPI.updatePermissions

updatePermissions() ​

updatePermissions(documentId, data): Promise<PermissionUpdateResult>

Update user permissions on a document.

Parameters ​

documentId ​

string

The unique identifier of the document to update permissions on

data ​

Single or batch permission update; provide either userId+permission for a single user, or permissions array for bulk updates

{ documentUrl?: string; email?: string; note?: string; permission: string; sendEmail?: boolean; userId?: string; }

Single or batch permission update; provide either userId+permission for a single user, or permissions array for bulk updates

documentUrl? ​

string

URL included in the notification email so recipients can navigate to the document

email? ​

string

note? ​

string

A personal message included in the notification email

permission ​

string

The permission level to grant (e.g., "read-write", "reader")

sendEmail? ​

boolean

If true, sends an email notification to the affected user(s)

userId? ​

string

The user whose permission to set (single-user form)

|

{ documentUrl?: string; note?: string; permissions: object[]; sendEmail?: boolean; }

Single or batch permission update; provide either userId+permission for a single user, or permissions array for bulk updates

documentUrl? ​

string

URL included in the notification email so recipients can navigate to the document

note? ​

string

A personal message included in the notification email

permissions ​

object[]

Array of user/permission pairs for bulk updates (batch form)

sendEmail? ​

boolean

If true, sends an email notification to the affected user(s)

Returns ​

Promise<PermissionUpdateResult>

uploads() ​

uploads(documentId?): BlobUploadStatus[]

List active blob uploads, optionally filtered by document.

Parameters ​

documentId? ​

string

If provided, only returns uploads for this document; otherwise returns all uploads

Returns ​

BlobUploadStatus[]

validateAccess() ​

validateAccess(documentId): Promise<DocumentAccessResult>

Validate the current user's access to a document.

Parameters ​

documentId ​

string

The unique identifier of the document to validate access for

Returns ​

Promise<DocumentAccessResult>

waitForInSync() ​

waitForInSync(documentId, timeoutMs?, pollMs?): Promise<void>

Wait until the client and server have identical document state.

Parameters ​

documentId ​

string

The document to check

timeoutMs? ​

number

Maximum time to wait (ms, default 5000)

pollMs? ​

number

Polling interval (ms, default 50)

Returns ​

Promise<void>

waitForWriteConfirmation() ​

waitForWriteConfirmation(documentId, timeoutMs?, pollMs?): Promise<boolean>

Wait until the server confirms it has all of this client's writes.

Parameters ​

documentId ​

string

The document to check

timeoutMs? ​

number

Maximum time to wait (ms, default 5000)

pollMs? ​

number

Polling interval (ms, default 50)

Returns ​

Promise<boolean>