gui.do
Barazo AppView backend
barazo.forum
1import type { Logger } from '../logger.js'
2
3/** Scoped database access for plugins -- queries are restricted to plugin-owned tables. */
4export interface ScopedDatabase {
5 execute(query: unknown): Promise<unknown>
6 query(tableName: string): unknown
7}
8
9/** Scoped AT Protocol operations (only available if plugin has pds:read or pds:write permission). */
10export interface ScopedAtProto {
11 getRecord(did: string, collection: string, rkey: string): Promise<unknown>
12 putRecord(did: string, collection: string, rkey: string, record: unknown): Promise<void>
13 deleteRecord(did: string, collection: string, rkey: string): Promise<void>
14}
15
16/** Scoped Valkey cache -- keys are auto-prefixed with plugin:<name>: */
17export interface ScopedCache {
18 get(key: string): Promise<string | null>
19 set(key: string, value: string, ttlSeconds?: number): Promise<void>
20 del(key: string): Promise<void>
21}
22
23/** Scoped HTTP client (only available if plugin has http:outbound permission). */
24export interface ScopedHttp {
25 fetch(url: string, init?: RequestInit): Promise<Response>
26}
27
28/** Read-only access to plugin settings configured by the community admin. */
29export interface PluginSettings {
30 get(key: string): unknown
31 getAll(): Record<string, unknown>
32}
33
34/** The sandbox API surface provided to every plugin. */
35export interface PluginContext {
36 readonly pluginName: string
37 readonly pluginVersion: string
38 readonly db: ScopedDatabase
39 readonly settings: PluginSettings
40 readonly atproto?: ScopedAtProto
41 readonly cache?: ScopedCache
42 readonly http?: ScopedHttp
43 readonly logger: Logger
44 readonly communityDid: string
45}
46
47/** Lifecycle hooks that a plugin can implement. */
48export interface PluginHooks {
49 onInstall?(ctx: PluginContext): Promise<void>
50 onUninstall?(ctx: PluginContext): Promise<void>
51 onEnable?(ctx: PluginContext): Promise<void>
52 onDisable?(ctx: PluginContext): Promise<void>
53 onProfileSync?(ctx: PluginContext, userDid: string): Promise<void>
54}
55
56/** A validated plugin ready for initialization. */
57export interface LoadedPlugin {
58 name: string
59 displayName: string
60 version: string
61 description: string
62 source: 'core' | 'official' | 'community' | 'experimental'
63 category: string
64 manifest: Record<string, unknown>
65 packagePath: string
66 hooks?: PluginHooks
67 routesPath?: string
68 migrationsPath?: string
69}
70
71/** Thrown when a plugin attempts an operation it lacks permission for. */
72export class PluginPermissionError extends Error {
73 constructor(pluginName: string, operation: string) {
74 super(`Plugin "${pluginName}" does not have permission for: ${operation}`)
75 this.name = 'PluginPermissionError'
76 }
77}