every-plugin 0.1.0 → 0.1.2
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/README.md +1 -329
- package/dist/errors.d.ts +11 -7
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +3 -14
- package/dist/index.d.ts +2 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -3
- package/dist/plugin.d.ts +149 -103
- package/dist/plugin.d.ts.map +1 -1
- package/dist/plugin.js +155 -23
- package/dist/runtime/errors.d.ts +41 -53
- package/dist/runtime/errors.d.ts.map +1 -1
- package/dist/runtime/errors.js +48 -8
- package/dist/runtime/index.d.ts +17 -66
- package/dist/runtime/index.d.ts.map +1 -1
- package/dist/runtime/index.js +22 -126
- package/dist/runtime/services/module-federation.service.d.ts +10 -38
- package/dist/runtime/services/module-federation.service.d.ts.map +1 -1
- package/dist/runtime/services/module-federation.service.js +131 -124
- package/dist/runtime/services/plugin.service.d.ts +21 -67
- package/dist/runtime/services/plugin.service.d.ts.map +1 -1
- package/dist/runtime/services/plugin.service.js +265 -328
- package/dist/runtime/services/secrets.service.d.ts +9 -29
- package/dist/runtime/services/secrets.service.js +26 -30
- package/dist/runtime/services.d.ts +1 -1
- package/dist/runtime/streaming/index.d.ts +4 -0
- package/dist/runtime/streaming/index.d.ts.map +1 -0
- package/dist/runtime/streaming/index.js +2 -0
- package/dist/runtime/streaming/state-effects.d.ts +28 -0
- package/dist/runtime/streaming/state-effects.d.ts.map +1 -0
- package/dist/runtime/streaming/state-effects.js +30 -0
- package/dist/runtime/streaming/streaming.d.ts +8 -0
- package/dist/runtime/streaming/streaming.d.ts.map +1 -0
- package/dist/runtime/streaming/streaming.js +113 -0
- package/dist/runtime/streaming/types.d.ts +19 -0
- package/dist/runtime/streaming/types.d.ts.map +1 -0
- package/dist/runtime/streaming/types.js +1 -0
- package/dist/runtime/test-utils.d.ts +1 -1
- package/dist/runtime/test-utils.js +4 -10
- package/dist/runtime/types.d.ts +28 -28
- package/dist/runtime/types.d.ts.map +1 -1
- package/dist/runtime/validation.d.ts +2 -7
- package/dist/runtime/validation.js +11 -14
- package/dist/testing/index.d.ts +25 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +40 -0
- package/dist/testing/mocks/module-federation.service.d.ts +8 -0
- package/dist/testing/mocks/module-federation.service.d.ts.map +1 -0
- package/dist/testing/mocks/module-federation.service.js +35 -0
- package/package.json +27 -14
- package/dist/runtime/mf.test.d.ts +0 -2
- package/dist/runtime/mf.test.d.ts.map +0 -1
- package/dist/runtime/mf.test.js +0 -135
- package/dist/runtime/runtime.test.d.ts +0 -2
- package/dist/runtime/runtime.test.d.ts.map +0 -1
- package/dist/runtime/runtime.test.js +0 -378
- package/dist/runtime/streaming.d.ts +0 -29
- package/dist/runtime/streaming.d.ts.map +0 -1
- package/dist/runtime/streaming.js +0 -59
- package/dist/runtime/streaming.test.d.ts +0 -2
- package/dist/runtime/streaming.test.d.ts.map +0 -1
- package/dist/runtime/streaming.test.js +0 -271
- package/dist/source.d.ts +0 -70
- package/dist/source.d.ts.map +0 -1
- package/dist/source.js +0 -37
package/README.md
CHANGED
|
@@ -1,329 +1 @@
|
|
|
1
|
-
# every-plugin
|
|
2
|
-
|
|
3
|
-
A modular plugin runtime & system built with [Effect.TS](https://effect.website/) for loading, initializing, and executing remote plugins via [Module Federation](https://module-federation.io/).
|
|
4
|
-
|
|
5
|
-
## Installation
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install every-plugin
|
|
9
|
-
# or
|
|
10
|
-
bun add every-plugin
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Quick Start
|
|
14
|
-
|
|
15
|
-
### Basic Plugin Usage
|
|
16
|
-
|
|
17
|
-
```typescript
|
|
18
|
-
import { Effect } from "effect";
|
|
19
|
-
import { createPluginRuntime, PluginRuntime } from "every-plugin/runtime";
|
|
20
|
-
|
|
21
|
-
// Create a managed runtime (do this once per application/worker)
|
|
22
|
-
const runtime = createPluginRuntime({
|
|
23
|
-
registry: {
|
|
24
|
-
"@my-org/data-processor": {
|
|
25
|
-
version: "1.0.0",
|
|
26
|
-
remoteUrl: "https://cdn.example.com/plugins/data-processor@latest/remoteEntry.js",
|
|
27
|
-
description: "Processes data items",
|
|
28
|
-
type: "pipeline"
|
|
29
|
-
}
|
|
30
|
-
},
|
|
31
|
-
secrets: {
|
|
32
|
-
API_KEY: "your-secret-key",
|
|
33
|
-
DATABASE_URL: "postgresql://..."
|
|
34
|
-
},
|
|
35
|
-
logger: customLogger // optional
|
|
36
|
-
});
|
|
37
|
-
|
|
38
|
-
// Use the runtime to execute plugins
|
|
39
|
-
const result = await runtime.runPromise(
|
|
40
|
-
Effect.gen(function* () {
|
|
41
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
42
|
-
|
|
43
|
-
// Load, instantiate and initialize a plugin
|
|
44
|
-
const plugin = yield* pluginRuntime.usePlugin("@my-org/data-processor", {
|
|
45
|
-
apiKey: "{{API_KEY}}", // Will be hydrated from secrets
|
|
46
|
-
batchSize: 100
|
|
47
|
-
});
|
|
48
|
-
|
|
49
|
-
const output = yield* pluginRuntime.executePlugin(plugin, {
|
|
50
|
-
items: ["item1", "item2", "item3"]
|
|
51
|
-
});
|
|
52
|
-
|
|
53
|
-
return output;
|
|
54
|
-
})
|
|
55
|
-
);
|
|
56
|
-
|
|
57
|
-
console.log(result);
|
|
58
|
-
|
|
59
|
-
// Clean up when done
|
|
60
|
-
await runtime.dispose();
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
### Alternative: Direct Layer Construction
|
|
64
|
-
|
|
65
|
-
If you prefer more explicit control over the runtime construction:
|
|
66
|
-
|
|
67
|
-
```typescript
|
|
68
|
-
import { Effect, ManagedRuntime } from "effect";
|
|
69
|
-
import { PluginRuntime } from "every-plugin/runtime";
|
|
70
|
-
|
|
71
|
-
// This is equivalent to createPluginRuntime(config)
|
|
72
|
-
const runtime = ManagedRuntime.make(PluginRuntime.Live({
|
|
73
|
-
registry: { /* ... */ },
|
|
74
|
-
secrets: { /* ... */ }
|
|
75
|
-
}));
|
|
76
|
-
|
|
77
|
-
const result = await runtime.runPromise(
|
|
78
|
-
Effect.gen(function* () {
|
|
79
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
80
|
-
const plugin = yield* pluginRuntime.usePlugin(pluginId, config);
|
|
81
|
-
return yield* pluginRuntime.executePlugin(plugin, input);
|
|
82
|
-
})
|
|
83
|
-
);
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
### Advanced Usage - Granular Control
|
|
87
|
-
|
|
88
|
-
```typescript
|
|
89
|
-
import { Effect } from "effect";
|
|
90
|
-
import { PluginRuntime } from "every-plugin/runtime";
|
|
91
|
-
|
|
92
|
-
const processWithGranularControl = Effect.gen(function* () {
|
|
93
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
94
|
-
|
|
95
|
-
// Step-by-step plugin lifecycle
|
|
96
|
-
const constructor = yield* pluginRuntime.loadPlugin("@my-org/data-processor");
|
|
97
|
-
const instance = yield* pluginRuntime.instantiatePlugin(constructor);
|
|
98
|
-
const initialized = yield* pluginRuntime.initializePlugin(instance, config);
|
|
99
|
-
const output = yield* pluginRuntime.executePlugin(initialized, input);
|
|
100
|
-
|
|
101
|
-
return output;
|
|
102
|
-
});
|
|
103
|
-
|
|
104
|
-
await runtime.runPromise(processWithGranularControl);
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### Worker Integration
|
|
108
|
-
|
|
109
|
-
Perfect for BullMQ workers or similar job processing systems:
|
|
110
|
-
|
|
111
|
-
```typescript
|
|
112
|
-
import { Job } from "bullmq";
|
|
113
|
-
import { Effect } from "effect";
|
|
114
|
-
import { createPluginRuntime, PluginRuntime } from "every-plugin/runtime";
|
|
115
|
-
|
|
116
|
-
// Initialize runtime once per worker
|
|
117
|
-
const runtime = createPluginRuntime({
|
|
118
|
-
registry: pluginRegistry,
|
|
119
|
-
secrets: await loadSecrets(),
|
|
120
|
-
});
|
|
121
|
-
|
|
122
|
-
// Job processor
|
|
123
|
-
const processJob = (job: Job) =>
|
|
124
|
-
runtime.runPromise(
|
|
125
|
-
Effect.gen(function* () {
|
|
126
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
127
|
-
const { pluginId, config, input } = job.data;
|
|
128
|
-
|
|
129
|
-
const plugin = yield* pluginRuntime.usePlugin(pluginId, config);
|
|
130
|
-
return yield* pluginRuntime.executePlugin(plugin, input);
|
|
131
|
-
})
|
|
132
|
-
);
|
|
133
|
-
|
|
134
|
-
// Worker setup
|
|
135
|
-
const worker = new Worker("my-queue", processJob);
|
|
136
|
-
|
|
137
|
-
// Cleanup on shutdown
|
|
138
|
-
process.on("SIGTERM", async () => {
|
|
139
|
-
await worker.close();
|
|
140
|
-
await runtime.dispose();
|
|
141
|
-
});
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
```typescript
|
|
145
|
-
import { Effect } from "effect";
|
|
146
|
-
import { createPluginRuntime, PluginRuntime } from "every-plugin/runtime";
|
|
147
|
-
|
|
148
|
-
// Create a managed runtime (do this once per application/worker)
|
|
149
|
-
const runtime = createPluginRuntime({
|
|
150
|
-
registry: {
|
|
151
|
-
"@my-org/data-processor": {
|
|
152
|
-
version: "1.0.0",
|
|
153
|
-
remoteUrl: "https://cdn.example.com/plugins/data-processor@latest/remoteEntry.js",
|
|
154
|
-
description: "Processes data items",
|
|
155
|
-
type: "pipeline"
|
|
156
|
-
}
|
|
157
|
-
},
|
|
158
|
-
secrets: {
|
|
159
|
-
API_KEY: "your-secret-key",
|
|
160
|
-
DATABASE_URL: "postgresql://..."
|
|
161
|
-
},
|
|
162
|
-
logger: customLogger // optional
|
|
163
|
-
});
|
|
164
|
-
|
|
165
|
-
// Use the runtime to execute plugins
|
|
166
|
-
const result = await runtime.runPromise(
|
|
167
|
-
Effect.gen(function* () {
|
|
168
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
169
|
-
|
|
170
|
-
return yield* pluginRuntime.streamPlugin(
|
|
171
|
-
"test-source-plugin",
|
|
172
|
-
TEST_CONFIG,
|
|
173
|
-
TEST_SEARCH_INPUT,
|
|
174
|
-
).pipe(
|
|
175
|
-
Effect.flatMap(stream => stream.pipe(Stream.runCollect)),
|
|
176
|
-
Effect.catchAll((error: unknown) => {
|
|
177
|
-
// Should handle callback errors
|
|
178
|
-
expect(error).toBeDefined();
|
|
179
|
-
return Effect.succeed("callback-error-handled");
|
|
180
|
-
}),
|
|
181
|
-
);
|
|
182
|
-
|
|
183
|
-
// Load, instantiate and initialize a plugin
|
|
184
|
-
const plugin = yield* pluginRuntime.usePlugin("@my-org/data-processor", {
|
|
185
|
-
apiKey: "{{API_KEY}}", // Will be hydrated from secrets
|
|
186
|
-
batchSize: 100
|
|
187
|
-
});
|
|
188
|
-
|
|
189
|
-
// I want to do this in the source stream
|
|
190
|
-
const output = yield* pluginRuntime.executePlugin(plugin, {
|
|
191
|
-
items: ["item1", "item2", "item3"]
|
|
192
|
-
});
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
return output;
|
|
197
|
-
})
|
|
198
|
-
);
|
|
199
|
-
|
|
200
|
-
console.log(result);
|
|
201
|
-
|
|
202
|
-
// Clean up when done
|
|
203
|
-
await runtime.dispose();
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
### React/Next.js Integration
|
|
207
|
-
|
|
208
|
-
```typescript
|
|
209
|
-
import { createPluginRuntime, PluginRuntime } from "every-plugin/runtime";
|
|
210
|
-
import { Effect } from "effect";
|
|
211
|
-
|
|
212
|
-
// Create runtime at app level
|
|
213
|
-
const pluginRuntime = createPluginRuntime({
|
|
214
|
-
registry: clientSideRegistry,
|
|
215
|
-
secrets: {} // No secrets on client side
|
|
216
|
-
});
|
|
217
|
-
|
|
218
|
-
// In a React component or API route
|
|
219
|
-
export async function executePlugin(pluginId: string, config: any, input: any) {
|
|
220
|
-
return pluginRuntime.runPromise(
|
|
221
|
-
Effect.gen(function* () {
|
|
222
|
-
const runtime = yield* PluginRuntime;
|
|
223
|
-
const plugin = yield* runtime.usePlugin(pluginId, config);
|
|
224
|
-
return yield* runtime.executePlugin(plugin, input);
|
|
225
|
-
})
|
|
226
|
-
);
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
// Cleanup in app teardown
|
|
230
|
-
export function cleanup() {
|
|
231
|
-
return pluginRuntime.dispose();
|
|
232
|
-
}
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
## Core Concepts
|
|
236
|
-
|
|
237
|
-
### Plugin Registry
|
|
238
|
-
|
|
239
|
-
The registry defines available plugins and their remote locations:
|
|
240
|
-
|
|
241
|
-
```typescript
|
|
242
|
-
type PluginRegistry = {
|
|
243
|
-
[pluginId: string]: {
|
|
244
|
-
version: string;
|
|
245
|
-
remoteUrl: string;
|
|
246
|
-
description?: string;
|
|
247
|
-
type?: string;
|
|
248
|
-
};
|
|
249
|
-
};
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
### Secret Hydration
|
|
253
|
-
|
|
254
|
-
Secrets are automatically hydrated using Mustache-style templating:
|
|
255
|
-
|
|
256
|
-
```typescript
|
|
257
|
-
const config = {
|
|
258
|
-
apiKey: "{{API_KEY}}", // Will be replaced with actual secret
|
|
259
|
-
endpoint: "https://api.example.com"
|
|
260
|
-
};
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
### Plugin Lifecycle
|
|
264
|
-
|
|
265
|
-
1. **Load**: Download and cache the remote plugin module
|
|
266
|
-
2. **Instantiate**: Create a new instance of the plugin class
|
|
267
|
-
3. **Initialize**: Configure the plugin with validated config and secrets
|
|
268
|
-
4. **Execute**: Run the plugin with validated input, return validated output
|
|
269
|
-
|
|
270
|
-
### Error Handling
|
|
271
|
-
|
|
272
|
-
All operations return Effect types with proper error handling:
|
|
273
|
-
|
|
274
|
-
```typescript
|
|
275
|
-
const result = await runtime.runPromise(
|
|
276
|
-
Effect.gen(function* () {
|
|
277
|
-
const pluginRuntime = yield* PluginRuntime;
|
|
278
|
-
return yield* pluginRuntime.usePlugin(pluginId, config);
|
|
279
|
-
}).pipe(
|
|
280
|
-
Effect.catchAll((error) => {
|
|
281
|
-
console.error("Plugin execution failed:", error);
|
|
282
|
-
return Effect.succeed(null); // Fallback value
|
|
283
|
-
})
|
|
284
|
-
)
|
|
285
|
-
);
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
## API Reference
|
|
289
|
-
|
|
290
|
-
### `createPluginRuntime(config)`
|
|
291
|
-
|
|
292
|
-
Creates a managed runtime for plugin execution.
|
|
293
|
-
|
|
294
|
-
**Parameters:**
|
|
295
|
-
|
|
296
|
-
- `config.registry`: Plugin registry mapping
|
|
297
|
-
- `config.secrets`: Secret values for hydration (optional)
|
|
298
|
-
- `config.logger`: Custom logger implementation (optional)
|
|
299
|
-
|
|
300
|
-
**Returns:** `ManagedRuntime` instance
|
|
301
|
-
|
|
302
|
-
### `PluginRuntime`
|
|
303
|
-
|
|
304
|
-
Effect service tag for accessing the plugin runtime within Effect workflows.
|
|
305
|
-
|
|
306
|
-
### Plugin Runtime Methods
|
|
307
|
-
|
|
308
|
-
- `loadPlugin(pluginId)`: Load plugin constructor from registry
|
|
309
|
-
- `instantiatePlugin(constructor)`: Create plugin instance
|
|
310
|
-
- `initializePlugin(instance, config)`: Initialize with config and secrets
|
|
311
|
-
- `executePlugin(plugin, input)`: Execute plugin with input
|
|
312
|
-
- `usePlugin(pluginId, config)`: Load + instantiate + initialize in one step (does not execute)
|
|
313
|
-
|
|
314
|
-
## Development
|
|
315
|
-
|
|
316
|
-
```bash
|
|
317
|
-
# Install dependencies
|
|
318
|
-
bun install
|
|
319
|
-
|
|
320
|
-
# Build the package
|
|
321
|
-
bun run build
|
|
322
|
-
|
|
323
|
-
# Run tests
|
|
324
|
-
bun test
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
## License
|
|
328
|
-
|
|
329
|
-
MIT
|
|
1
|
+
# every-plugin
|
package/dist/errors.d.ts
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
declare const PluginConfigurationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
|
|
2
|
+
readonly _tag: "PluginConfigurationError";
|
|
3
|
+
} & Readonly<A>;
|
|
4
|
+
export declare class PluginConfigurationError extends PluginConfigurationError_base<{
|
|
5
|
+
readonly message: string;
|
|
6
|
+
readonly retryable: boolean;
|
|
7
|
+
readonly cause?: Error;
|
|
8
|
+
}> {
|
|
9
|
+
get name(): string;
|
|
4
10
|
}
|
|
5
|
-
export
|
|
6
|
-
|
|
7
|
-
}
|
|
8
|
-
//# sourceMappingURL=errors.d.ts.map
|
|
11
|
+
export {};
|
|
12
|
+
//# sourceMappingURL=errors.d.ts.map
|
package/dist/errors.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAEA,qBAAa,wBAAyB,SAAQ,8BAA6C;IAC1F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACvB,CAAC;IACD,IAAa,IAAI,WAAyC;CAC1D"}
|
package/dist/errors.js
CHANGED
|
@@ -1,15 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
export class
|
|
3
|
-
|
|
4
|
-
constructor(message, retryable = true) {
|
|
5
|
-
super(message);
|
|
6
|
-
this.retryable = retryable;
|
|
7
|
-
this.name = "PluginExecutionError";
|
|
8
|
-
}
|
|
9
|
-
}
|
|
10
|
-
export class ConfigurationError extends PluginExecutionError {
|
|
11
|
-
constructor(message) {
|
|
12
|
-
super(message, false); // Configuration errors are not retryable
|
|
13
|
-
this.name = "ConfigurationError";
|
|
14
|
-
}
|
|
1
|
+
import { Data } from "effect";
|
|
2
|
+
export class PluginConfigurationError extends Data.TaggedError("PluginConfigurationError") {
|
|
3
|
+
get name() { return "PluginConfigurationError"; }
|
|
15
4
|
}
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
|
package/dist/index.js
CHANGED
package/dist/plugin.d.ts
CHANGED
|
@@ -1,111 +1,157 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import type { ContractRouter, Meta } from "@orpc/server";
|
|
2
|
+
import { Context, Effect } from "effect";
|
|
2
3
|
import { z } from "zod";
|
|
3
|
-
import type {
|
|
4
|
-
export
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
z.ZodObject<
|
|
13
|
-
{
|
|
14
|
-
message: z.ZodString;
|
|
15
|
-
details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
16
|
-
stack: z.ZodOptional<z.ZodString>;
|
|
17
|
-
},
|
|
18
|
-
z.core.$strip
|
|
19
|
-
>
|
|
20
|
-
>
|
|
21
|
-
>;
|
|
22
|
-
},
|
|
23
|
-
z.core.$strip
|
|
24
|
-
>;
|
|
25
|
-
export declare function createConfigSchema<
|
|
26
|
-
V extends z.ZodTypeAny,
|
|
27
|
-
S extends z.ZodTypeAny,
|
|
28
|
-
>(
|
|
29
|
-
variablesSchema?: V,
|
|
30
|
-
secretsSchema?: S,
|
|
31
|
-
): z.ZodObject<{
|
|
32
|
-
variables: z.ZodOptional<V>;
|
|
33
|
-
secrets: z.ZodOptional<S>;
|
|
34
|
-
}>;
|
|
35
|
-
export declare function createInputSchema<I extends z.ZodTypeAny>(
|
|
36
|
-
inputSchema: I,
|
|
37
|
-
): I;
|
|
38
|
-
export declare const ErrorDetailsSchema: z.ZodObject<
|
|
39
|
-
{
|
|
40
|
-
message: z.ZodString;
|
|
41
|
-
details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
42
|
-
stack: z.ZodOptional<z.ZodString>;
|
|
43
|
-
},
|
|
44
|
-
z.core.$strip
|
|
45
|
-
>;
|
|
46
|
-
export type ErrorDetails = z.infer<typeof ErrorDetailsSchema>;
|
|
47
|
-
export type Config<
|
|
48
|
-
V extends z.ZodTypeAny = z.ZodRecord<z.ZodString, z.ZodUnknown>,
|
|
49
|
-
S extends z.ZodTypeAny = z.ZodRecord<z.ZodString, z.ZodUnknown>,
|
|
50
|
-
> = z.infer<ReturnType<typeof createConfigSchema<V, S>>>;
|
|
51
|
-
export type Input<I extends z.ZodTypeAny> = z.infer<
|
|
52
|
-
ReturnType<typeof createInputSchema<I>>
|
|
53
|
-
>;
|
|
54
|
-
export type Output<T extends z.ZodTypeAny> = z.infer<
|
|
55
|
-
ReturnType<typeof createOutputSchema<T>>
|
|
56
|
-
>;
|
|
57
|
-
export interface Plugin<
|
|
58
|
-
TInputSchema extends z.ZodTypeAny,
|
|
59
|
-
TOutputSchema extends z.ZodTypeAny,
|
|
60
|
-
TConfigSchema extends z.ZodTypeAny,
|
|
61
|
-
> {
|
|
62
|
-
readonly id: string;
|
|
63
|
-
readonly type: PluginType;
|
|
64
|
-
readonly inputSchema: TInputSchema;
|
|
65
|
-
readonly outputSchema: TOutputSchema;
|
|
66
|
-
readonly configSchema: TConfigSchema;
|
|
67
|
-
initialize(
|
|
68
|
-
config?: z.infer<TConfigSchema>,
|
|
69
|
-
): Effect.Effect<void, ConfigurationError, PluginLoggerTag>;
|
|
70
|
-
execute(
|
|
71
|
-
input: z.infer<TInputSchema>,
|
|
72
|
-
): Effect.Effect<
|
|
73
|
-
z.infer<TOutputSchema>,
|
|
74
|
-
PluginExecutionError,
|
|
75
|
-
PluginLoggerTag
|
|
76
|
-
>;
|
|
77
|
-
shutdown(): Effect.Effect<void, never, PluginLoggerTag>;
|
|
78
|
-
}
|
|
4
|
+
import type { PluginConfigurationError } from "./errors";
|
|
5
|
+
export type Contract = ContractRouter<Meta>;
|
|
6
|
+
export declare function createConfigSchema<V extends z.ZodTypeAny, S extends z.ZodTypeAny>(variablesSchema: V, secretsSchema: S): z.ZodObject<{
|
|
7
|
+
variables: V;
|
|
8
|
+
secrets: S;
|
|
9
|
+
}, z.core.$strip>;
|
|
10
|
+
export declare function createStateSchema<T extends z.ZodTypeAny>(pluginStateSchema: T): z.ZodIntersection<z.ZodObject<{
|
|
11
|
+
nextPollMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
|
|
12
|
+
}, z.core.$strip>, T>;
|
|
79
13
|
export type PluginType = "transformer" | "distributor" | "source";
|
|
80
14
|
export interface PluginMetadata {
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
15
|
+
remoteUrl: string;
|
|
16
|
+
type?: PluginType;
|
|
17
|
+
version?: string;
|
|
18
|
+
description?: string;
|
|
85
19
|
}
|
|
86
20
|
export interface PluginRegistry {
|
|
87
|
-
|
|
21
|
+
[pluginId: string]: PluginMetadata;
|
|
88
22
|
}
|
|
89
23
|
export interface PluginLogger {
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
24
|
+
readonly logInfo: (message: string, context?: unknown) => Effect.Effect<void>;
|
|
25
|
+
readonly logWarning: (message: string, context?: unknown) => Effect.Effect<void>;
|
|
26
|
+
readonly logError: (message: string, error?: unknown, context?: unknown) => Effect.Effect<void>;
|
|
27
|
+
readonly logDebug: (message: string, context?: unknown) => Effect.Effect<void>;
|
|
28
|
+
}
|
|
29
|
+
declare const PluginLoggerTag_base: Context.TagClass<PluginLoggerTag, "PluginLogger", PluginLogger>;
|
|
30
|
+
export declare class PluginLoggerTag extends PluginLoggerTag_base {
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Common error schemas that all plugins can use
|
|
34
|
+
* These provide consistent error handling across the plugin ecosystem
|
|
35
|
+
*/
|
|
36
|
+
export declare const CommonPluginErrors: {
|
|
37
|
+
UNAUTHORIZED: {
|
|
38
|
+
data: z.ZodObject<{
|
|
39
|
+
apiKeyProvided: z.ZodBoolean;
|
|
40
|
+
provider: z.ZodOptional<z.ZodString>;
|
|
41
|
+
authType: z.ZodOptional<z.ZodEnum<{
|
|
42
|
+
apiKey: "apiKey";
|
|
43
|
+
oauth: "oauth";
|
|
44
|
+
token: "token";
|
|
45
|
+
}>>;
|
|
46
|
+
}, z.core.$strip>;
|
|
47
|
+
};
|
|
48
|
+
RATE_LIMITED: {
|
|
49
|
+
data: z.ZodObject<{
|
|
50
|
+
retryAfter: z.ZodNumber;
|
|
51
|
+
remainingRequests: z.ZodOptional<z.ZodNumber>;
|
|
52
|
+
resetTime: z.ZodOptional<z.ZodString>;
|
|
53
|
+
limitType: z.ZodOptional<z.ZodEnum<{
|
|
54
|
+
requests: "requests";
|
|
55
|
+
tokens: "tokens";
|
|
56
|
+
bandwidth: "bandwidth";
|
|
57
|
+
}>>;
|
|
58
|
+
}, z.core.$strip>;
|
|
59
|
+
};
|
|
60
|
+
SERVICE_UNAVAILABLE: {
|
|
61
|
+
data: z.ZodObject<{
|
|
62
|
+
retryAfter: z.ZodOptional<z.ZodNumber>;
|
|
63
|
+
maintenanceWindow: z.ZodDefault<z.ZodBoolean>;
|
|
64
|
+
estimatedUptime: z.ZodOptional<z.ZodString>;
|
|
65
|
+
}, z.core.$strip>;
|
|
66
|
+
};
|
|
67
|
+
BAD_REQUEST: {
|
|
68
|
+
data: z.ZodObject<{
|
|
69
|
+
invalidFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
70
|
+
validationErrors: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
71
|
+
field: z.ZodString;
|
|
72
|
+
message: z.ZodString;
|
|
73
|
+
code: z.ZodOptional<z.ZodString>;
|
|
74
|
+
}, z.core.$strip>>>;
|
|
75
|
+
}, z.core.$strip>;
|
|
76
|
+
};
|
|
77
|
+
NOT_FOUND: {
|
|
78
|
+
data: z.ZodObject<{
|
|
79
|
+
resource: z.ZodOptional<z.ZodString>;
|
|
80
|
+
resourceId: z.ZodOptional<z.ZodString>;
|
|
81
|
+
}, z.core.$strip>;
|
|
82
|
+
};
|
|
83
|
+
FORBIDDEN: {
|
|
84
|
+
data: z.ZodObject<{
|
|
85
|
+
requiredPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
86
|
+
action: z.ZodOptional<z.ZodString>;
|
|
87
|
+
}, z.core.$strip>;
|
|
88
|
+
};
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* Schema creators for contract-based plugins
|
|
92
|
+
*/
|
|
93
|
+
export declare function createPluginInputSchema<TContract extends Contract, TStateSchema extends z.ZodTypeAny>(contract: TContract, stateSchema: TStateSchema): z.ZodDiscriminatedUnion<[z.ZodObject<any, z.core.$strip>, ...z.ZodObject<any, z.core.$strip>[]], "procedure">;
|
|
94
|
+
export declare function createPluginOutputSchema<TContract extends Contract, TStateSchema extends z.ZodTypeAny>(contract: TContract, stateSchema: TStateSchema): z.ZodUnion<[z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, ...z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[]]>;
|
|
95
|
+
/**
|
|
96
|
+
* Unified Plugin interface for all plugin types
|
|
97
|
+
*/
|
|
98
|
+
export interface Plugin<TContract extends Contract, TConfigSchema extends z.ZodTypeAny = z.ZodTypeAny, TStateSchema extends z.ZodTypeAny = z.ZodNull> {
|
|
99
|
+
readonly id: string;
|
|
100
|
+
readonly type: PluginType;
|
|
101
|
+
readonly contract: TContract;
|
|
102
|
+
readonly configSchema: TConfigSchema;
|
|
103
|
+
readonly stateSchema: TStateSchema;
|
|
104
|
+
readonly inputSchema: ReturnType<typeof createPluginInputSchema<TContract, TStateSchema>>;
|
|
105
|
+
readonly outputSchema: ReturnType<typeof createPluginOutputSchema<TContract, TStateSchema>>;
|
|
106
|
+
initialize(config?: z.infer<TConfigSchema>): Effect.Effect<void, PluginConfigurationError, PluginLoggerTag>;
|
|
107
|
+
shutdown(): Effect.Effect<void, never, PluginLoggerTag>;
|
|
108
|
+
createRouter(): Contract;
|
|
109
|
+
isStreamable(procedureName: string): boolean;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* State transition utilities for plugins
|
|
113
|
+
* These provide a functional approach to state updates while keeping the API simple
|
|
114
|
+
*/
|
|
115
|
+
export declare const StateTransitions: {
|
|
116
|
+
/**
|
|
117
|
+
* Transition to a new phase with optional updates
|
|
118
|
+
*/
|
|
119
|
+
to: <T extends {
|
|
120
|
+
phase?: string;
|
|
121
|
+
}>(phase: string, updates?: Partial<T>) => (state: T) => T;
|
|
122
|
+
/**
|
|
123
|
+
* Add polling delay to state
|
|
124
|
+
*/
|
|
125
|
+
withPolling: <T>(delayMs: number) => (state: T) => T;
|
|
126
|
+
/**
|
|
127
|
+
* Set error state with message and stop polling
|
|
128
|
+
*/
|
|
129
|
+
withError: <T>(errorMessage: string) => (state: T) => T;
|
|
130
|
+
/**
|
|
131
|
+
* Preserve existing state with updates
|
|
132
|
+
*/
|
|
133
|
+
update: <T>(updates: Partial<T>) => (state: T) => T;
|
|
134
|
+
};
|
|
135
|
+
/**
|
|
136
|
+
* Simple pipe utility for composing state transformations
|
|
137
|
+
*/
|
|
138
|
+
export declare const pipe: <T>(value: T, ...fns: Array<(val: T) => T>) => T;
|
|
139
|
+
/**
|
|
140
|
+
* Simple plugin base class that uses pure oRPC patterns
|
|
141
|
+
* Plugin just needs to define contract, config, and create oRPC router
|
|
142
|
+
*/
|
|
143
|
+
export declare abstract class SimplePlugin<TContract extends Contract, TConfigSchema extends z.ZodTypeAny, TStateSchema extends z.ZodTypeAny = z.ZodNull> implements Plugin<TContract, TConfigSchema, TStateSchema> {
|
|
144
|
+
abstract readonly id: string;
|
|
145
|
+
abstract readonly type: PluginType;
|
|
146
|
+
abstract readonly contract: TContract;
|
|
147
|
+
abstract readonly configSchema: TConfigSchema;
|
|
148
|
+
abstract readonly stateSchema: TStateSchema;
|
|
149
|
+
get inputSchema(): z.ZodDiscriminatedUnion<[z.ZodObject<any, z.core.$strip>, ...z.ZodObject<any, z.core.$strip>[]], "procedure">;
|
|
150
|
+
get outputSchema(): z.ZodUnion<[z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, ...z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[]]>;
|
|
151
|
+
initialize(config?: z.infer<TConfigSchema>): Effect.Effect<void, PluginConfigurationError, PluginLoggerTag>;
|
|
152
|
+
abstract createRouter(): Contract;
|
|
153
|
+
shutdown(): Effect.Effect<void, never, PluginLoggerTag>;
|
|
154
|
+
isStreamable(procedureName: string): boolean;
|
|
104
155
|
}
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
"PluginLogger",
|
|
108
|
-
PluginLogger
|
|
109
|
-
>;
|
|
110
|
-
export declare class PluginLoggerTag extends PluginLoggerTag_base {}
|
|
111
|
-
//# sourceMappingURL=plugin.d.ts.map
|
|
156
|
+
export {};
|
|
157
|
+
//# sourceMappingURL=plugin.d.ts.map
|