@treeline-money/plugin-sdk 0.1.55 → 0.1.57
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +106 -10
- package/dist/index.d.ts.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -27,15 +27,35 @@ export interface PluginManifest {
|
|
|
27
27
|
}
|
|
28
28
|
/**
|
|
29
29
|
* Permissions a plugin can request.
|
|
30
|
+
*
|
|
31
|
+
* Plugins automatically have full read/write access to their own schema (plugin_<id>).
|
|
32
|
+
* These permissions are for accessing tables OUTSIDE the plugin's own schema.
|
|
30
33
|
*/
|
|
31
34
|
export interface PluginPermissions {
|
|
32
|
-
/**
|
|
35
|
+
/**
|
|
36
|
+
* Tables this plugin can SELECT from (outside its own schema).
|
|
37
|
+
* Use "*" for unrestricted read access (e.g., query plugin).
|
|
38
|
+
*
|
|
39
|
+
* @example ["transactions", "accounts", "sys_balance_snapshots"]
|
|
40
|
+
*/
|
|
41
|
+
read?: string[];
|
|
42
|
+
/**
|
|
43
|
+
* Tables this plugin can explicitly write to (outside its own schema).
|
|
44
|
+
* Most plugins don't need this - they only write to their own schema.
|
|
45
|
+
*
|
|
46
|
+
* @example ["sys_transactions"] // tagging plugin modifies transaction tags
|
|
47
|
+
*/
|
|
48
|
+
write?: string[];
|
|
49
|
+
/**
|
|
50
|
+
* Optional schema name override.
|
|
51
|
+
* Default: plugin_<id with hyphens replaced by underscores>
|
|
52
|
+
*
|
|
53
|
+
* @example "plugin_cashflow" for plugin ID "treeline-cashflow"
|
|
54
|
+
*/
|
|
55
|
+
schemaName?: string;
|
|
33
56
|
tables?: {
|
|
34
|
-
/** Tables this plugin can SELECT from */
|
|
35
57
|
read?: string[];
|
|
36
|
-
/** Tables this plugin can INSERT/UPDATE/DELETE */
|
|
37
58
|
write?: string[];
|
|
38
|
-
/** Tables this plugin can CREATE/DROP (must match sys_plugin_{id}_* pattern) */
|
|
39
59
|
create?: string[];
|
|
40
60
|
};
|
|
41
61
|
}
|
|
@@ -86,8 +106,8 @@ export interface PluginSDK {
|
|
|
86
106
|
*/
|
|
87
107
|
query: <T = Record<string, unknown>>(sql: string, params?: QueryParam[]) => Promise<T[]>;
|
|
88
108
|
/**
|
|
89
|
-
* Execute a write SQL query (INSERT/UPDATE/DELETE).
|
|
90
|
-
*
|
|
109
|
+
* Execute a write SQL query (INSERT/UPDATE/DELETE/CREATE/DROP).
|
|
110
|
+
* Plugins have full write access to their own schema (plugin_<id>).
|
|
91
111
|
* Use parameterized queries (?) for user-provided values to prevent SQL injection.
|
|
92
112
|
*
|
|
93
113
|
* @param sql - SQL write query with ? placeholders
|
|
@@ -95,15 +115,27 @@ export interface PluginSDK {
|
|
|
95
115
|
* @returns Object with rowsAffected count
|
|
96
116
|
*
|
|
97
117
|
* @example
|
|
98
|
-
* // Parameterized insert (SAFE)
|
|
118
|
+
* // Parameterized insert to own schema (SAFE)
|
|
119
|
+
* const schema = sdk.getSchemaName();
|
|
99
120
|
* await sdk.execute(
|
|
100
|
-
*
|
|
101
|
-
* ['
|
|
121
|
+
* `INSERT INTO ${schema}.goals (id, name) VALUES (?, ?)`,
|
|
122
|
+
* [crypto.randomUUID(), 'Emergency Fund']
|
|
102
123
|
* );
|
|
103
124
|
*/
|
|
104
125
|
execute: (sql: string, params?: QueryParam[]) => Promise<{
|
|
105
126
|
rowsAffected: number;
|
|
106
127
|
}>;
|
|
128
|
+
/**
|
|
129
|
+
* Get the schema name for this plugin.
|
|
130
|
+
* Tables should be created in this schema: `${sdk.getSchemaName()}.table_name`
|
|
131
|
+
*
|
|
132
|
+
* @returns The plugin's schema name (e.g., "plugin_goals", "plugin_budget")
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* const schema = sdk.getSchemaName(); // "plugin_goals"
|
|
136
|
+
* await sdk.execute(`CREATE TABLE IF NOT EXISTS ${schema}.goals (...)`);
|
|
137
|
+
*/
|
|
138
|
+
getSchemaName: () => string;
|
|
107
139
|
/**
|
|
108
140
|
* Toast notification methods.
|
|
109
141
|
*/
|
|
@@ -282,13 +314,77 @@ export interface PluginContext {
|
|
|
282
314
|
/** Open a view */
|
|
283
315
|
openView: (viewId: string, props?: Record<string, unknown>) => void;
|
|
284
316
|
}
|
|
317
|
+
/**
|
|
318
|
+
* A single database migration for a plugin.
|
|
319
|
+
* Migrations are run in order by version number when the plugin loads.
|
|
320
|
+
*
|
|
321
|
+
* The app automatically creates `plugin_<id>.schema_migrations` to track
|
|
322
|
+
* which migrations have been run.
|
|
323
|
+
*
|
|
324
|
+
* @example
|
|
325
|
+
* ```typescript
|
|
326
|
+
* const migrations: PluginMigration[] = [
|
|
327
|
+
* {
|
|
328
|
+
* version: 1,
|
|
329
|
+
* name: "create_goals_table",
|
|
330
|
+
* up: `
|
|
331
|
+
* CREATE TABLE plugin_goals.goals (
|
|
332
|
+
* id VARCHAR PRIMARY KEY,
|
|
333
|
+
* name VARCHAR NOT NULL
|
|
334
|
+
* )
|
|
335
|
+
* `
|
|
336
|
+
* },
|
|
337
|
+
* {
|
|
338
|
+
* version: 2,
|
|
339
|
+
* name: "add_priority_column",
|
|
340
|
+
* up: `ALTER TABLE plugin_goals.goals ADD COLUMN priority INTEGER DEFAULT 0`
|
|
341
|
+
* }
|
|
342
|
+
* ];
|
|
343
|
+
* ```
|
|
344
|
+
*/
|
|
345
|
+
export interface PluginMigration {
|
|
346
|
+
/**
|
|
347
|
+
* Unique version number. Must be a positive integer.
|
|
348
|
+
* Migrations run in order of version number.
|
|
349
|
+
*/
|
|
350
|
+
version: number;
|
|
351
|
+
/**
|
|
352
|
+
* Human-readable name for this migration.
|
|
353
|
+
* Used in logs and the schema_migrations table.
|
|
354
|
+
*/
|
|
355
|
+
name: string;
|
|
356
|
+
/**
|
|
357
|
+
* SQL to execute for this migration.
|
|
358
|
+
* Can be a single statement or multiple statements separated by semicolons.
|
|
359
|
+
* The plugin's schema is created automatically before migrations run.
|
|
360
|
+
*/
|
|
361
|
+
up: string;
|
|
362
|
+
}
|
|
285
363
|
/**
|
|
286
364
|
* Plugin interface that all plugins must implement.
|
|
287
365
|
*/
|
|
288
366
|
export interface Plugin {
|
|
289
367
|
/** Plugin manifest */
|
|
290
368
|
manifest: PluginManifest;
|
|
291
|
-
/**
|
|
369
|
+
/**
|
|
370
|
+
* Database migrations for this plugin.
|
|
371
|
+
* Run in order by version number when the plugin loads.
|
|
372
|
+
* The app creates the plugin's schema automatically before running migrations.
|
|
373
|
+
*
|
|
374
|
+
* @example
|
|
375
|
+
* ```typescript
|
|
376
|
+
* export const plugin: Plugin = {
|
|
377
|
+
* manifest: { ... },
|
|
378
|
+
* migrations: [
|
|
379
|
+
* { version: 1, name: "initial", up: "CREATE TABLE plugin_goals.goals (...)" },
|
|
380
|
+
* { version: 2, name: "add_index", up: "CREATE INDEX ..." },
|
|
381
|
+
* ],
|
|
382
|
+
* activate(ctx) { ... }
|
|
383
|
+
* }
|
|
384
|
+
* ```
|
|
385
|
+
*/
|
|
386
|
+
migrations?: PluginMigration[];
|
|
387
|
+
/** Called when plugin is activated (after migrations complete) */
|
|
292
388
|
activate: (ctx: PluginContext) => void | Promise<void>;
|
|
293
389
|
/** Called when plugin is deactivated */
|
|
294
390
|
deactivate?: () => void | Promise<void>;
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IAEX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAEhB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|