API reference

defineConfig({
  engine?: 'yjs' | 'automerge' | 'partykit' | 'partyserver'
  engineFor?: (docName: string) => CollaborationEngine | Promise<CollaborationEngine>
  documents?: Record<string, CollabDocumentDeclaration>
  authorize?: (ctx: CollabConnectionContext, docName: string) => Promise<CollabPermission>
  storage?: CollaborationStorage
  path?: string
  debounce?: number
  redisUrl?: string
  tokenSecret?: string
  partykit?: PartyKitConfig
  routes?: {
    enabled?: boolean
    prefix?: string
    middleware?: unknown[]
    resolveUser?: ResolveUserFn
  }
})

{
  roomHost: string          // 'my-app.partykit.dev' or 'localhost:1999'
  party?: string            // default 'main'
  jwtSecret?: string        // HS256 secret shared with the worker
  fetchTimeoutMs?: number   // default 10000
}

type CollabDocumentDeclaration<P> = {
  engine?: CollaborationEngine
  authorize?: (
    ctx: CollabConnectionContext,
    info: { docName: string; params: P },
  ) => Promise<CollabPermission>
  load?: (info: { docName: string; params: P }) => Promise<CollabDocumentSeed>
}

type CollabDocumentSeed = Uint8Array | Y.Doc | null | undefined

type DocumentParams<Pattern extends string>
// 'researches/:id/writing'  → { id: string }
// 'a/:x/b/:y'               → { x: string; y: string }
// 'announcements'           → {}
// string                    → Record<string, string>

'researches/:id/writing': {
  async authorize(ctx, { docName, params }) { /* params.id is a string; params.foo is an error */ },
}

defineCollection<Prefix extends string>(
  prefix: Prefix,
  declaration?: CollabDocumentDeclaration<{ id: string }>,
): { [K in `${Prefix}/:id`]: CollabDocumentDeclaration<{ id: string }> }

documents: {
  ...defineCollection('whiteboards', { engine: 'automerge', authorize }),
  ...defineCollection('announcements'),           // globals apply
  'researches/:id/writing': { authorize },        // any other shape: write the pattern
}

import collaboration from '@adonis-agora/collaboration/services/main'

const manager = collaboration.current   // ← note `.current`

type CollaborationEngine = 'yjs' | 'automerge' | 'partykit' | 'partyserver'

interface CollabConnectionContext {
  userId: string
  user?: { name?: string; avatarUrl?: string | null }
}

interface CollabPermission {
  canRead: boolean      // enforced by the library
  canWrite: boolean     // false ⇒ the connection is read-only; version writes 403
  canComment: boolean   // false ⇒ the comment write endpoints 403
}

type CommentAnchor =
  | { kind: 'text-range'; start: number; end: number; selectedText: string }
  | { kind: 'canvas-object'; shapeId: string; relativeX: number; relativeY: number }
  | { kind: 'timestamp'; at: number; end?: number }

interface CollabComment {
  id: string
  documentName: string
  space: string
  anchor: CommentAnchor
  body: string
  userId: string
  authorName?: string | null
  resolvedAt: string | null
  createdAt: string
  updatedAt: string | null
}

interface CollabVersion {
  id: string            // UUID on Yjs; the document heads on Automerge
  seq: number           // friendly 1, 2, 3…
  label: string | null
  createdBy: string | null
  createdAt: string
}

interface PresenceMember {
  userId: string
  name?: string | null
  avatarUrl?: string | null
}

type LiveDocumentResult<T> =
  | { live: true; value: T }
  | { live: false; reason: LiveDocumentAbsence }

type LiveDocumentAbsence =
  | 'not-loaded'                    // this engine keeps documents here; nobody has this one open
  | 'engine-has-no-live-document'   // the engine syncs elsewhere (partykit), or is not Yjs

interface CollaborationStorage {
  loadDocument(docName: string): Promise<{ state: Uint8Array } | null>
  saveDocument(docName: string, state: Uint8Array, meta?: Record<string, unknown>): Promise<void>

  listVersions(docName: string, page?: ListPageOptions): Promise<CollabVersion[]>
  saveVersion(docName: string, version: CollabVersion, snapshot: Uint8Array): Promise<void>
  loadVersionSnapshot(docName: string, versionId: string): Promise<Uint8Array | null>
  pruneVersions(options: { keep: number; docName?: string; dryRun?: boolean }): Promise<number>

  listComments(docName: string, space?: string, page?: ListPageOptions): Promise<CollabComment[]>
  getComment?(docName: string, commentId: string): Promise<CollabComment | null>  // optional
  saveComment(docName: string, comment: CollabComment): Promise<void>
  deleteComment(docName: string, commentId: string): Promise<void>
}

interface ListPageOptions {
  page?: number  // 1-based, default 1
  size?: number  // default 50, capped at 200
}

issueToken(config, user, docName, authorize?): Promise<{ token; wsUrl; engine; expiresAt }>
buildWsUrl(config, docName): string

// One signed format for every engine; the key is what differs.
signCollabToken(payload, secret, expiresInSeconds?): string
verifyCollabToken(token, secret, expectedDocName): { userId; docName; user?; exp } | null
verifySelfHostedToken(token, docName, secret?): Promise<CollabConnectionContext | null>
signPartyKitToken   // = signCollabToken, signed with partykit.jwtSecret
verifyPartyKitToken // = verifyCollabToken

// The signing key: explicit → config/collaboration.ts → appKey → throw.
resolveTokenSecret(secret?): Promise<string>
COLLAB_TOKEN_TTL_SECONDS // 300

class CollabForbiddenError extends Error         // authorize denied canRead
class CollabAuthorizationError extends Error     // authorize itself threw — retryable, not a denial
class CollabUnauthorizedError extends Error      // no user resolved
class CollabTokenSecretMissingError extends Error // no signing key anywhere — issue and verify both refuse

issueCollaborationToken(
  { docName: string; user?: { id: string; name?: string | null }; ctx?: HttpContext },
  options?: { authorize?; manager?; engine?; path?; partykit?; resolveUser? },
): Promise<{ token: string; wsUrl: string; engine: string; expiresAt?: number }>

onCollaborationError(listener): () => void        // subscribe; returns unsubscribe
setCollaborationLogger(logger | undefined): void  // the provider installs the Adonis logger
reportCollaborationError(event): void             // report your own; never throws
collaborationEvents                               // the EventEmitter
COLLAB_ERROR_EVENT                                // its event name — deliberately not 'error'

interface CollabErrorEvent {
  scope: 'storage' | 'authorize'
  operation: string      // e.g. 'saveDocument', 'onAuthenticate'
  docName?: string
  error: unknown
}

collaborationRoutes(router, {
  prefix?: string
  middleware?: unknown[]
  resolveUser?: ResolveUserFn
  authorize?: AuthorizeFn
  manager?: CollabManagerLike | (() => Promise<CollabManagerLike>)
  engine?: string
  path?: string
  partykit?: { roomHost?; jwtSecret?; party? }
}): void

InferCollabDocumentNames<typeof collaborationConfig>  // union of declared patterns
CollabDocumentNameFor<'researches/:id/writing'>       // `researches/${string}/writing`

<CollaborationProvider
  baseUrl?={string}          // optional — falls back to location.origin
  getHeaders?={() => Record<string, string> | Promise<Record<string, string>>}
  createTransport?={(info, doc, docName) => CollabTransport}
  fetchImpl?={typeof fetch}
  initialTokens?={Record<string, CollabTokenInfo>}  // pre-issued, by docName
/>

useCollabDoc({ docName, token? }): {   // token: pre-issued, first connection only
  doc: Y.Doc                 // stable for the provider's lifetime
  collabDoc: CollabDoc       // the same document behind read/write/onUpdate
  status: CollabStatus
  synced: boolean            // the server's initial state has been applied
  error: Error | null
}

useAutomergeDoc<T>({ docName, WebSocketImpl? }): {
  doc: A.Doc<T> | null
  status: CollabStatus
  synced: boolean            // the server's state has been merged on THIS connection
  pendingChanges: number     // local changes not yet written to the socket
  error: Error | null
  change(fn: A.ChangeFn<T>): void
}

useAwareness({ docName, user? }): {
  peers: CollabPeer[]                              // everyone except you
  status: CollabStatus
  awareness: Awareness | null                      // the channel; null until connected
  setLocalState(state: Record<string, unknown> | null): void
  setLocalStateField(field: string, value: unknown): void
}

// `user` is your identity, published into the awareness `user` field — the
// field every other client's `peers` reads. Without it the room is anonymous.
interface CollabLocalUser {
  userId?: string
  name?: string
  avatarUrl?: string | null
  [key: string]: unknown
}

useCollabEditor<S>({ docName, editorId, adapter, doc? }): {
  state: S
  update(next: S): void
  status: CollabStatus
  synced: boolean
  peers: CollabPeer[]
}

useExcalidrawSync({ doc, excalidrawAPI, editorId? }): void
// doc: CollabDoc | Y.Doc | null — either of the two useCollabDoc returns
// editorId defaults to 'excalidraw'; the scene is last-write-wins on one key

useComments({ docName, space? }): {
  comments: CollabComment[]
  loading: boolean
  error: Error | null
  refresh(): Promise<void>
  create(input): Promise<CollabComment>
  resolve(commentId, resolved?): Promise<void>
  remove(commentId): Promise<void>
}

useVersions({ docName }): {
  versions: CollabVersion[]
  loading: boolean
  error: Error | null
  refresh(): Promise<void>
  create(label?): Promise<CollabVersion>
  restore(versionId): Promise<void>
}

createExcalidrawAdapter<S>(): CollabEditorAdapter<{ elements: S[]; appState?: Record<string, unknown> }>
createTldrawAdapter<S>(): CollabEditorAdapter<{ snapshot: S }>
createTextAdapter(): CollabEditorAdapter<string>

interface CollabEditorAdapter<S> {
  empty(): S
  create(doc: CollabDoc, editorId: string): { state: S; update(next: S): void }
}

interface CollabDoc {
  read<T>(key: string): T | undefined
  write(key: string, value: unknown): void
  onUpdate(callback: () => void): () => void
}

class DocSession {
  constructor(
    docName: string,
    config: CollaborationClientConfig,
    options?: { registry?: DocSessionRegistry },   // the provider passes its map
  )
  readonly doc: Y.Doc
  readonly docName: string
  get transport(): CollabTransport | undefined
  get engine(): string | undefined
  get error(): Error | null
  get synced(): boolean          // initial state applied, not just "socket open"
  get refCount(): number         // mounted consumers holding it open
  get isDestroyed(): boolean
  getStatus(): CollabStatus
  getSnapshot(): DocSessionSnapshot             // { status, error, synced }
  subscribe(listener: () => void): () => void   // also starts the session
  start(): Promise<void>                        // idempotent
  retain(): () => void   // hold it open; returns its own release
  release(): void        // the last one calls stop()
  stop(): void           // tears down the transport, KEEPS the Y.Doc
  destroy(): void        // terminal: destroys the Y.Doc, evicts from the map
}

fetchToken(config, docName)
listComments(config, docName, space?)
createComment(config, input)
resolveComment(config, docName, commentId, resolved)
deleteComment(config, docName, commentId)
listVersions(config, docName)
createVersion(config, docName, label)
restoreVersion(config, docName, versionId)
collabFetch<T>(config, path, init?)

class CollabRestError extends Error { status: number; body: string }

interface CollabTransport {
  readonly doc: Y.Doc
  readonly awareness?: Awareness | null
  getStatus(): CollabStatus
  isSynced?(): boolean          // optional; the session falls back to the status
  subscribe(listener: () => void): () => void
  destroy(): void
}