api.highlights

Interface: IHighlightsApi

Implementation tier: T1 (CRUD) / T2 (styles)

Create, read, update, and delete verse highlights. Register custom highlight styles.

Permissions

• highlights:read
• highlights:write (for create/update/delete)

Methods

list

list(verseId?: number): Promise<UserHighlightDto[]>

Parameters:

Name	Type	Required	Description
verseId	number	No

Returns: Promise<UserHighlightDto[]>

---

create

create(highlight: NewHighlightDto): Promise<UserHighlightDto>

Parameters:

Name	Type	Required	Description
highlight	NewHighlightDto	Yes

Returns: Promise<UserHighlightDto>

---

update

update(id: string, patch: Partial<NewHighlightDto>): Promise<UserHighlightDto>

Parameters:

Name	Type	Required	Description
id	string	Yes
patch	Partial<NewHighlightDto>	Yes

Returns: Promise<UserHighlightDto>

---

delete

delete(id: string): Promise<void>

Parameters:

Name	Type	Required	Description
id	string	Yes

Returns: Promise<void>

---

registerStyle

registerStyle(style: HighlightStyleDescriptor): Promise<DisposableHandle>

Register a custom highlight style. The style appears in the user's highlight picker and persists across sessions. Styles can target whole verses, ranges, or sub-verse word ranges.

Parameters:

Name	Type	Required	Description
style	HighlightStyleDescriptor	Yes

Returns: Promise<DisposableHandle>

---

listStyles

listStyles(): Promise<HighlightStyleDescriptor[]>

List all registered highlight styles (built-in + extension-contributed).

Returns: Promise<HighlightStyleDescriptor[]>

---

Events

onDidChange

onDidChange: IEventApi<{ verseId: number }>

Payload type: { verseId: number }

Subscribe to this event:

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

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

---