api.commentary

Interface: ICommentaryApi

Implementation tier: T1 (reads) / T2 (provider, iterate)

Read commentary entries, list commentary modules, iterate over entries, and register custom commentary providers.

Permissions

• commentary:read
• commentary:provide (for registerProvider)

Methods

listModules

listModules(): Promise<CommentaryModuleInfoDto[]>

Returns: Promise<CommentaryModuleInfoDto[]>

---

getEntry

getEntry(moduleId: string, verseId: number): Promise<CommentaryEntryDto | null>

Parameters:

Name	Type	Required	Description
moduleId	string	Yes
verseId	number	Yes

Returns: Promise<CommentaryEntryDto | null>

---

getEntriesForRange

getEntriesForRange(
  moduleId: string,
  startVerseId: number,
  endVerseId: number,
): Promise<CommentaryEntryDto[]>

Get all entries that touch a verse range. Useful for "show all commentary on Romans 8" or for building an index.

Parameters:

Name	Type	Required	Description
moduleId	string	Yes
startVerseId	number	Yes
endVerseId	number	Yes

Returns: Promise<CommentaryEntryDto[]>

---

iterateEntries

iterateEntries(opts: IterateCommentaryOpts): Promise<CommentaryIterationResult>

Cursor-based iteration over all entries in a module.

Parameters:

Name	Type	Required	Description
opts	IterateCommentaryOpts	Yes

Returns: Promise<CommentaryIterationResult>

---

registerProvider

registerProvider(provider: CommentaryProviderDescriptor): Promise<DisposableHandle>

Register a custom commentary provider. The host treats it as another module.

Parameters:

Name	Type	Required	Description
provider	CommentaryProviderDescriptor	Yes

Returns: Promise<DisposableHandle>

---

Events

onDidChangeActiveCommentary

onDidChangeActiveCommentary: IEventApi<{ moduleId: string } | null>

Payload type: { moduleId: string } | null

Subscribe to this event:

const handle = await api.commentary.onDidChangeActiveCommentary.subscribe((payload) => {
  // Handle event
});

// Later, to unsubscribe:
await handle.dispose();

---