js-bao-wss-client / DocumentsAPI
Interface: DocumentsAPI
Client API for documents — collaborative documents with sharing, permissions, tags, aliases, blob attachments, and presence (awareness). Accessed as client.documents.
Properties
aliases
aliases:
DocumentAliasesAPI
ingests
ingests:
DocumentIngestsAPI
Bulk loads of a large document.
snapshots
snapshots:
DocumentSnapshotsAPI
Snapshot builds of a large document.
Methods
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
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>
clearLinkAccess()
clearLinkAccess(
documentId):Promise<LinkAccessResult>
Turn off "anyone with the link" access for a document. Existing explicit grants are unaffected; link-only viewers lose access.
Parameters
documentId
string
The document to stop sharing via link.
Returns
Promise<LinkAccessResult>
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:LocalMetadataEntry; }>
Create a new document. Local-first: the document is writable locally immediately, and the server commit races in the background — unless options.localOnly is set, in which case it never syncs.
Parameters
options
Options for document creation
Returns
Promise<{ metadata: LocalMetadataEntry; }>
See
CreateDocumentOptions.localOnly
createOffline()
createOffline(
_options):Promise<Doc>
Parameters
_options
Returns
Promise<Doc>
Deprecated
Use documents.create({ localOnly: true }) followed by documents.open(id, { waitForLoad: 'local', enableNetworkSync: false }) instead.
See
createWithAlias()
createWithAlias(
options):Promise<{alias:DocumentAliasInfo;createdAt:string;createdBy:string;documentFormat?:number;documentId:string;metadata?:unknown;modifiedAt:string;tags?:string[];title:string; }>
Create a document with an alias atomically, failing if the alias already exists.
Parameters
options
Options for document and alias creation
Returns
Promise<{ alias: DocumentAliasInfo; createdAt: string; createdBy: string; documentFormat?: number; documentId: string; metadata?: unknown; modifiedAt: string; tags?: string[]; title: string; }>
The created document's documentId, title, createdBy, timestamps, and the assigned alias
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?
Options for document deletion
Returns
Promise<void>
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?
Eviction options
Returns
Promise<void>
evictAll()
evictAll(
opts?):Promise<void>
Evict all locally stored document data from the device.
Parameters
opts?
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
get()
get<
M>(documentId):Promise<DocumentInfo<M>>
Fetch document metadata from the server.
Type Parameters
M
M = unknown
Parameters
documentId
string
The unique identifier of the document to fetch
Returns
Promise<DocumentInfo<M>>
getAwarenessStates()
getAwarenessStates<
S>(documentId):Map<string,S>
Get all current awareness states for a document.
Type Parameters
S
S = unknown
Parameters
documentId
string
The unique identifier of the document to get awareness states from
Returns
Map<string, S>
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
getLinkAccess()
getLinkAccess(
documentId):Promise<LinkAccessResult>
Read the current "anyone with the link" access state for a document. Authorized for any caller who can read the document OR manage its sharing (document owner, app owner, or read-write editor) — so an app owner can inspect the state even without a content grant. Returns { documentId, linkAccess: null } when link access is off.
Parameters
documentId
string
The document to read link access for.
Returns
Promise<LinkAccessResult>
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;documentFormat?:number;documentId:string;metadata?:unknown;modifiedAt?:string;tags?:string[];title?:string; }>
Get an existing document by alias, or create a new one if the alias does not exist.
Parameters
options
Options for alias lookup and fallback creation
Returns
Promise<{ alias: DocumentAliasInfo; created: boolean; createdAt?: string; createdBy?: string; documentFormat?: number; documentId: string; metadata?: unknown; modifiedAt?: string; tags?: 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<unknown>>
Get metadata for the app's root document.
Returns
Promise<DocumentInfo<unknown>>
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
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
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[]>
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:LocalMetadataEntry|null; }>
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: LocalMetadataEntry | null; }>
openAlias()
openAlias(
params,options?):Promise<{doc:Doc;metadata:LocalMetadataEntry|null; }>
Open a document by resolving its alias first.
Parameters
params
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
userIdto 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
string | { email?: undefined; userId: string; } | { email: string; userId?: undefined; }
Either a user ID string, or an object with userId / email
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<
S>(documentId,state):void
Set the local user's awareness state for a document (e.g., cursor position).
Type Parameters
S
S = unknown
Parameters
documentId
string
The unique identifier of the document to set awareness on
state
S
The awareness state object to broadcast to other connected clients
Returns
void
setLinkAccess()
setLinkAccess(
documentId,level):Promise<LinkAccessResult>
Turn on "anyone with the link" access for a document. Any signed-in app user who has the document ID then resolves to at least level without an explicit grant. Requires document owner, app owner, or read-write editor.
Parameters
documentId
string
The document to share via link.
level
"read-write" | "reader"
The shared level: "reader" or "read-write".
Returns
Promise<LinkAccessResult>
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<unknown>>
Update document metadata such as its title.
Parameters
documentId
string
The unique identifier of the document to update
data
The document metadata fields to update
Returns
Promise<DocumentInfo<unknown>>
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
{ documentUrl?: string; email?: string; note?: string; permission: string; sendEmail?: boolean; userId?: string; } | { 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
Type Literal
{ 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)
Type Literal
{ 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
validateAccess()
validateAccess(
documentId,options?):Promise<DocumentAccessResult>
Validate a user's access to a document.
With no options this answers the CURRENT user's access, as it always has. { userId } names a subject instead, and the answer is what the document routes would enforce for them — direct grants, group grants (collection membership included) and "anyone with the link" access. Naming a subject is admitted for an app owner or admin, for a member naming themself, and for a server function's dispatch; anyone else is refused (DOCUMENT_ACCESS_SUBJECT_FORBIDDEN).
Parameters
documentId
string
The unique identifier of the document to validate access for
options?
{ userId } to ask about that user instead of the caller
userId?
string
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>