Public JavaScript API Reference¶

Purpose

The PublicAPI class provides the primary entry point for in-vault JavaScript automation (Obsidian third-party plugins, DataviewJS blocks, Templater scripts). It grants access to an AuthorizedAPI instance upon presenting a valid token.

1. API Entry Point & Access Pattern¶

The plugin exposes an instance of PublicAPI on the Obsidian plugin registry under:

const fcPlugin = app.plugins.plugins['full-calendar'];
const publicApi = fcPlugin?.api; // Instance of PublicAPI

Third-party plugins obtain access programmatically using requestAccess(). In-vault scripts (DataviewJS / Templater) obtain access by passing a generated Personal Access Token (PAT) directly to withToken().

2. PublicAPI Class Contract¶

Source anchor: src/api/PublicAPI.ts#L225

`requestAccess(pluginId, reason, requestedScopes?)`¶

Prompts the user with an AuthorizationModal requesting access for a plugin.

public requestAccess(
  pluginId: string,
  reason: string,
  requestedScopes?: ApiScope[]
): Promise<string | null>

Parameters:
pluginId (string): Unique identifier of the calling plugin (e.g. 'my-dashboard-plugin').
reason (string): Human-readable explanation displayed in the authorization modal.
requestedScopes (ApiScope[], optional): Array of required permission scopes. Defaults to ['events:read'] via normalizeApiScopes.
Returns: Promise<string | null> - Resolves to a generated UUID token string if approved by the user, or null if rejected or cancelled.
Storage Side-Effect: Saves a new record in FullCalendarSettings.apiTokens[token] containing pluginId, reason, requestedScopes, grantedScopes, and grantedAt.

`withToken(token)`¶

Validates a token string and returns an capability-wrapped AuthorizedAPI instance.

public withToken(token: string): AuthorizedAPI | null

Parameters:
token (string): A PAT (ofc_pat_...) or plugin access token.
Returns: AuthorizedAPI | null - Returns an authorized capability object if valid, or null if invalid, missing, or revoked.
Side Effects:
Updates tokenRecord.lastUsedAt = Date.now() and asynchronously calls PluginState.saveSettings().
Legacy Migration: Automatically converts legacy authorizedTokens records into modern apiTokens records with system:full-access scope upon invocation.

3. AuthorizedAPI Interface Specification¶

Source anchor: src/api/PublicAPI.ts#L171

The table below documents every method exposed on AuthorizedAPI, its required scope assertion, parameter types, return types, and target subsystem:

Method Name	Required Scope	Parameters	Return Type	Subsystem / Action
`openCalendar()`	`ui:open-calendar`	None	`Promise<void>`	Focuses or creates main calendar tab leaf.
`openSidebar()`	`ui:open-sidebar`	None	`Promise<void>`	Focuses or opens calendar right sidebar leaf.
`changeView(viewName)`	`ui:change-view`	`viewName: string`	`Promise<void>`	Switches FullCalendar view (e.g. `timeGridWeek`).
`openCreateModal(initialData?)`	`ui:modals`	`initialData?: Partial<OFCEvent>`	`void`	Launches the event creation modal UI.
`getAllEvents()`	`events:read`	None	`unknown[]`	Returns raw cached event collections across sources.
`getEventById(id)`	`events:read`	`id: string`	`OFCEvent \\| null`	Returns normalized event object by ID.
`getEventDetails(id)`	`events:read`	`id: string`	`ApiEventDetails`	Returns event object, calendar ID, and file location.
`getEvents(criteria, sorts?)`	`events:read`	`criteria: EventFilterCriteria, sorts?: EventSortCriteria[]`	`QueryableEvent[]`	Runs structured filtering and sorting via `EventFilterSortEngine`.
`createEvent(calendarId, event, options?)`	`events:write`	`calendarId: string, event: OFCEvent, options?: { silent?: boolean }`	`Promise<boolean>`	Adds event to calendar source & writes vault note.
`updateEvent(eventId, event, options?)`	`events:write`	`eventId: string, event: OFCEvent, options?: { silent?: boolean }`	`Promise<boolean>`	Updates event data in storage.
`deleteEvent(eventId, options?)`	`events:write`	`eventId: string, options?: { silent?: boolean; instanceDate?: string; force?: boolean }`	`Promise<void>`	Deletes or suppresses event instance.
`moveEvent(eventId, newCalendarId, newEventData?)`	`events:write`	`eventId: string, newCalendarId: string, newEventData?: OFCEvent`	`Promise<void>`	Transfers event to a different calendar source.
`processEvent(eventId, processor, options?)`	`events:write`	`eventId: string, processor: (e: OFCEvent) => OFCEvent, options?: { silent?: boolean }`	`Promise<boolean>`	Atomic read-modify-write event transaction.
`toggleRecurringInstance(eventId, instanceDate, isDone)`	`events:write`	`eventId: string, instanceDate: string, isDone: boolean`	`Promise<void>`	Toggles completion state for recurring instance.
`modifyRecurringInstance(eventId, instanceDate, newEvent)`	`events:write`	`eventId: string, instanceDate: string, newEvent: OFCEvent`	`Promise<void>`	Overrides recurring event instance details.
`scheduleTask(taskId, date, allDay?)`	`events:write`	`taskId: string, date: Date, allDay?: boolean`	`Promise<void>`	Schedules task item to calendar date.
`validateTaskSchedule(taskId, date)`	`events:write`	`taskId: string, date: Date`	`Promise<{ isValid: boolean; reason?: string }>`	Validates task scheduling feasibility.
`getCalendarSources()`	`providers:read`	None	`CalendarInfo[]`	Returns all registered calendar source configurations.
`getProviderCapabilities(calendarId)`	`providers:read`	`calendarId: string`	`ProviderCapabilities`	Returns capability flags for provider source.
`revalidateRemoteCalendars(force?)`	`providers:write`	`force?: boolean`	`void`	Triggers background reload of remote calendars.
`reloadProviderNow(calendarId)`	`providers:write`	`calendarId: string`	`void`	Forces immediate reload of specific calendar.
`getSettings()`	`settings:read`	None	`FullCalendarSettings`	Returns cloned deep copy of current settings.
`updateSettings(partial, options?)`	`settings:write`	`partial: Partial<FullCalendarSettings>, options?: { save?: boolean }`	`Promise<void>`	Updates and persists plugin configuration.
`saveSettings()`	`settings:write`	None	`Promise<void>`	Persists current plugin settings to disk.
`loadSettings()`	`settings:read`	None	`Promise<void>`	Reloads plugin settings from disk.
`getInternalState()`	`system:full-access`	None	`InternalState`	Returns raw singletons (`plugin`, `cache`, `registry`, etc.).

4. Scope Assertion & Error Handling¶

Each method invocation on AuthorizedAPI internally calls assertScope(grantedScopes, requiredScope):

function assertScope(grantedScopes: ApiScope[], required: ApiScope) {
  if (!hasApiScope(grantedScopes, required)) {
    throw new Error(`Full Calendar API: Missing required scope: ${required}`);
  }
}

Scope Error Handling

If an integration script attempts to invoke a method without holding the required scope (or system:full-access), an exception is thrown immediately:

try {
  api.createEvent("work-cal", eventData);
} catch (err) {
  console.error(err.message); 
  // Output: "Full Calendar API: Missing required scope: events:write"
}

Back to API Index · Overview · REST Server · Scopes & Permissions