@alfe.ai/integrations 0.0.1
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 +103 -0
- package/dist/index.d.ts +695 -0
- package/dist/index.js +1351 -0
- package/package.json +31 -0
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# @alfe.ai/integrations
|
|
2
|
+
|
|
3
|
+
Integration lifecycle management for Alfe — registry, resolution, installation, state, and hook execution.
|
|
4
|
+
|
|
5
|
+
## What It Does
|
|
6
|
+
|
|
7
|
+
Provides the complete integration lifecycle:
|
|
8
|
+
|
|
9
|
+
- **Registry** — fetches the integration index from `GET /integrations/registry` on the integrations service, with search and lookup
|
|
10
|
+
- **Resolver** — maps an integration name + optional version to a git clone target (repo URL, tag, or pinned commit SHA)
|
|
11
|
+
- **Installer** — git clones integration repos to `~/.alfe/integrations/{name}/`, with install/update/remove/list operations
|
|
12
|
+
- **IntegrationManager** — full lifecycle orchestration: install → configure → activate → deactivate → uninstall
|
|
13
|
+
- **StateManager** — persistent state at `~/.alfe/integrations.json` with in-memory secret storage
|
|
14
|
+
- **Hooks** — runs integration lifecycle scripts (pre_install, post_install, health_check, etc.) as child processes with env var injection
|
|
15
|
+
- **Adapter** — `IntegrationManagerAdapter` bridges IntegrationManager to the `IIntegrationManager` interface used by the gateway's ReconciliationEngine
|
|
16
|
+
|
|
17
|
+
Used by `packages/gateway` (daemon owns integration lifecycle directly) and `packages/cli` for the `integration` commands.
|
|
18
|
+
|
|
19
|
+
## Key Files
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
src/
|
|
23
|
+
├── index.ts # Public re-exports
|
|
24
|
+
├── registry.ts # Registry client (fetches from integrations service API)
|
|
25
|
+
├── resolver.ts # Version resolution (name + version → git target)
|
|
26
|
+
├── installer.ts # Git clone/update/remove to ~/.alfe/integrations/
|
|
27
|
+
├── integration-manager.ts # Full lifecycle manager (install/configure/activate/health/uninstall)
|
|
28
|
+
├── state.ts # State file manager (~/.alfe/integrations.json)
|
|
29
|
+
├── hooks.ts # Hook script runner with env var injection
|
|
30
|
+
├── adapter.ts # IIntegrationManager adapter for ReconciliationEngine
|
|
31
|
+
├── types.ts # Integration command param types
|
|
32
|
+
├── resolver.test.ts # Registry + resolver tests
|
|
33
|
+
├── installer.test.ts # Installer tests
|
|
34
|
+
├── integration-manager.test.ts # Lifecycle tests
|
|
35
|
+
└── state.test.ts # State manager tests
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Usage
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
import {
|
|
42
|
+
Registry, Resolver, Installer,
|
|
43
|
+
IntegrationManager,
|
|
44
|
+
IntegrationManagerAdapter,
|
|
45
|
+
} from '@alfe.ai/integrations';
|
|
46
|
+
|
|
47
|
+
// ── Registry + Resolution ──────────────────────────────────
|
|
48
|
+
const registry = new Registry();
|
|
49
|
+
const results = await registry.search('discord');
|
|
50
|
+
|
|
51
|
+
const resolver = new Resolver(registry);
|
|
52
|
+
const resolved = await resolver.resolve('discord', '1.0.0');
|
|
53
|
+
|
|
54
|
+
const installer = new Installer();
|
|
55
|
+
const installPath = await installer.install(resolved);
|
|
56
|
+
|
|
57
|
+
// ── Lifecycle Management ───────────────────────────────────
|
|
58
|
+
const manager = new IntegrationManager({
|
|
59
|
+
logger,
|
|
60
|
+
skillsDir: '~/.alfe/skills/', // default
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
await manager.install({ name: 'discord', version: '1.0.0' });
|
|
64
|
+
await manager.configure({ name: 'discord', config: { guild_id: '123' } });
|
|
65
|
+
await manager.activate('discord');
|
|
66
|
+
await manager.health({ name: 'discord' });
|
|
67
|
+
|
|
68
|
+
// ── Gateway Adapter ────────────────────────────────────────
|
|
69
|
+
// Bridges IntegrationManager to ReconciliationEngine's interface
|
|
70
|
+
const adapter = new IntegrationManagerAdapter(manager);
|
|
71
|
+
cloudClient.setIntegrationManager(adapter);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Configuration
|
|
75
|
+
|
|
76
|
+
The `Registry` class resolves the API URL in this order:
|
|
77
|
+
|
|
78
|
+
1. Explicit `apiUrl` constructor argument
|
|
79
|
+
2. `ALFE_API_URL` environment variable
|
|
80
|
+
3. `https://api.alfe.ai` (production default)
|
|
81
|
+
|
|
82
|
+
The `IntegrationManager` accepts an options object:
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
interface IntegrationManagerOptions {
|
|
86
|
+
logger?: Logger;
|
|
87
|
+
statePath?: string; // default: ~/.alfe/integrations.json
|
|
88
|
+
integrationsDir?: string; // default: ~/.alfe/integrations/
|
|
89
|
+
skillsDir?: string; // default: ~/.alfe/skills/
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Development
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pnpm install
|
|
97
|
+
pnpm --filter @alfe.ai/integrations build
|
|
98
|
+
pnpm --filter @alfe.ai/integrations test
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Dependencies
|
|
102
|
+
|
|
103
|
+
- `@alfe.ai/integration-manifest` — manifest parsing, config validation, state types
|