97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
# Extension Interface Reference
|
|
|
|
Source: `lib/extensions/types.ts`
|
|
|
|
## Extension Interface
|
|
|
|
```typescript
|
|
interface Extension {
|
|
id: string; name: string; version: string; sector?: SectorSlug
|
|
routes?: RouteDefinition[]
|
|
apiRoutes?: ApiRouteDefinition[]
|
|
sidebarItems?: SidebarItem[]
|
|
eventHandlers?: ExtensionEventHandler[]
|
|
mappingRuleTypes?: MappingRuleTypeDefinition[]
|
|
reportTypes?: ReportDefinition[]
|
|
settingsPanel?: SettingsPanelDefinition
|
|
taxCodes?: TaxCodeDefinition[]
|
|
dimensionTypes?: DimensionDefinition[]
|
|
services?: Record<string, (...args: any[]) => Promise<any>>
|
|
onInstall?(ctx: ExtensionContext): Promise<void>
|
|
onUninstall?(ctx: ExtensionContext): Promise<void>
|
|
}
|
|
```
|
|
|
|
All surfaces are optional. An extension can provide any combination.
|
|
|
|
## Key Supporting Types
|
|
|
|
```typescript
|
|
interface ApiRouteDefinition {
|
|
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
|
|
path: string // e.g., "/:id/confirm"
|
|
handler: (request: Request, ctx?: ExtensionContext) => Promise<Response>
|
|
}
|
|
|
|
interface ExtensionEventHandler {
|
|
eventType: CoreEventType
|
|
handler: (payload: any, ctx?: ExtensionContext) => Promise<void> | void
|
|
}
|
|
|
|
interface SidebarItem { label: string; icon?: string; path: string; order?: number }
|
|
interface SettingsPanelDefinition { label: string; path: string }
|
|
interface MappingRuleTypeDefinition { id: string; name: string; description: string }
|
|
interface RouteDefinition { path: string; label: string }
|
|
```
|
|
|
|
## ExtensionContext
|
|
|
|
```typescript
|
|
interface ExtensionContext {
|
|
userId: string; extensionId: string; supabase: SupabaseClient
|
|
emit(event: CoreEvent): Promise<void>
|
|
settings: { get<T>(key?: string): Promise<T | null>; set<T>(key: string, value: T): Promise<void> }
|
|
storage: { download(bucket, path); upload(bucket, path, data, options?); getPublicUrl(bucket, path) }
|
|
log: { info(msg, ...args); warn(msg, ...args); error(msg, ...args) } // Prefixed ext:{id}
|
|
services: { ingestTransactions(supabase, userId, raw): Promise<IngestResult> }
|
|
}
|
|
```
|
|
|
|
Settings stored in `extension_data` table with composite key `(user_id, extension_id, key)`.
|
|
|
|
## Complexity Spectrum
|
|
|
|
**Level 1 — Pure UI** (no surfaces, workspace reads core data):
|
|
```typescript
|
|
export const calendarExtension: Extension = { id: 'calendar', name: 'Kalender', version: '1.0.0' }
|
|
```
|
|
|
|
**Level 2 — Event handler only:**
|
|
```typescript
|
|
export const loggerExtension: Extension = {
|
|
id: 'example-logger', name: 'Logger', version: '1.0.0',
|
|
eventHandlers: [{ eventType: 'journal_entry.committed', handler: handleCommitted }],
|
|
}
|
|
```
|
|
|
|
**Level 3 — Service provider** (registers at module load):
|
|
```typescript
|
|
registerEmailService(new ResendEmailService())
|
|
export const emailExtension: Extension = { id: 'email', name: 'Email', version: '1.0.0' }
|
|
```
|
|
|
|
**Level 4 — Full extension** (events + API + settings + mappingRules + onInstall):
|
|
```typescript
|
|
export const receiptOcrExtension: Extension = {
|
|
id: 'receipt-ocr', name: 'Receipt OCR', version: '1.0.0', sector: 'general',
|
|
apiRoutes: receiptOcrApiRoutes,
|
|
eventHandlers: [
|
|
{ eventType: 'document.uploaded', handler: handleDocumentUploaded },
|
|
{ eventType: 'transaction.synced', handler: handleTransactionSynced },
|
|
],
|
|
mappingRuleTypes: [{ id: 'receipt-ocr-merchant', name: 'OCR Merchant Match', description: '...' }],
|
|
settingsPanel: { label: 'Receipt OCR', path: '/settings/extensions/receipt-ocr' },
|
|
async onInstall(ctx) { await ctx.settings.set('settings', DEFAULT_SETTINGS) },
|
|
}
|
|
```
|