@alfe.ai/integrations 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,695 @@
+//#region src/registry.d.ts
+/**
+ * Registry — fetches the integration registry index from the integrations service.
+ *
+ * Calls GET /integrations/registry (public, no auth required) and caches the result.
+ * The API URL can be passed explicitly or set via ALFE_API_URL env var.
+ */
+interface RegistryEntry {
+  /** Human-readable display name (e.g. 'Alfe Voice') */
+  name?: string;
+  repo: string;
+  /** GitHub repository URL (HTTPS, no .git suffix) for public clone */
+  repository?: string;
+  /** Pinned commit SHA — when present, install uses this exact commit instead of a tag */
+  commit?: string;
+  /** Subdirectory within the repo where the integration lives (for monorepos) */
+  subdir?: string;
+  versions: string[];
+  latest: string;
+  description: string;
+  /** Agent runtimes this integration supports. Empty/absent = universal. */
+  supported_agents?: string[];
+}
+interface RegistryIndex {
+  version: number;
+  integrations: Record<string, RegistryEntry>;
+}
+declare class Registry {
+  private index;
+  private apiUrl;
+  /**
+   * @param apiUrl - Base URL for the Alfe API (e.g. "https://api.alfe.ai").
+   *                 Falls back to ALFE_API_URL env var, then the production URL.
+   */
+  constructor(apiUrl?: string);
+  /**
+   * Load the registry index. Uses cache if already loaded.
+   */
+  load(): Promise<RegistryIndex>;
+  /**
+   * Force reload the index (bypass cache).
+   */
+  reload(): Promise<RegistryIndex>;
+  /**
+   * Get a specific integration entry by name.
+   */
+  get(id: string): Promise<RegistryEntry | undefined>;
+  /**
+   * List all integrations in the registry.
+   */
+  list(): Promise<({
+    id: string;
+  } & RegistryEntry)[]>;
+  /**
+   * Search integrations by name or description substring.
+   */
+  search(query: string): Promise<({
+    id: string;
+  } & RegistryEntry)[]>;
+}
+//#endregion
+//#region src/resolver.d.ts
+interface ResolvedIntegration {
+  id: string;
+  name?: string;
+  repo: string;
+  version: string;
+  tag: string;
+  /** Pinned commit SHA — when present, installer uses this instead of tag */
+  commit?: string;
+  /** Subdirectory within the repo where the integration lives (for monorepos) */
+  subdir?: string;
+  description: string;
+}
+declare class RegistryResolveError extends Error {
+  constructor(message: string);
+}
+declare class Resolver {
+  private registry;
+  constructor(registry: Registry);
+  /**
+   * Resolve an integration name (+ optional version) to a git clone target.
+   *
+   * @param name - Integration name (e.g. "discord")
+   * @param version - Specific version (e.g. "1.0.0") or undefined for latest
+   * @returns Resolved integration with repo URL and git tag
+   */
+  resolve(id: string, version?: string): Promise<ResolvedIntegration>;
+  /**
+   * Check if an integration exists in the registry.
+   */
+  exists(id: string): Promise<boolean>;
+  /**
+   * Get all available versions for an integration.
+   */
+  versions(id: string): Promise<string[]>;
+}
+//#endregion
+//#region src/installer.d.ts
+interface InstalledInfo {
+  id: string;
+  name?: string;
+  version: string;
+  path: string;
+}
+declare class InstallerError extends Error {
+  constructor(message: string);
+}
+declare class Installer {
+  private basePath;
+  /** Tracks subdir overrides per integration id */
+  private subdirs;
+  /**
+   * @param basePath - Override the integrations directory (for testing).
+   *                   Defaults to ~/.alfe/integrations/
+   */
+  constructor(basePath?: string);
+  /**
+   * Get the path where an integration's content lives.
+   * When a subdir is set, returns the subdir within the clone.
+   */
+  getInstallPath(name: string): string;
+  /**
+   * Get the root clone path (without subdir).
+   */
+  getClonePath(name: string): string;
+  /**
+   * Install an integration by cloning its git repo and checking out the version tag.
+   * Returns the effective install path (with subdir if present).
+   */
+  install(resolved: ResolvedIntegration): Promise<string>;
+  /**
+   * Update an installed integration to a new version.
+   */
+  update(name: string, resolved: ResolvedIntegration): Promise<string>;
+  /**
+   * Remove an installed integration.
+   */
+  remove(name: string): Promise<void>;
+  /**
+   * List all locally installed integrations.
+   */
+  list(): InstalledInfo[];
+  /**
+   * Check if an integration is installed.
+   */
+  isInstalled(name: string): boolean;
+}
+//#endregion
+//#region ../integration-manifest/dist/index.d.ts
+//#region src/types.d.ts
+
+/**
+ * TypeScript types for the Alfe integration manifest (`alfe-integration.yaml`).
+ *
+ * These are the canonical types used by all packages that interact with
+ * integration manifests -- registry, lifecycle manager, CLI, etc.
+ */
+type ConfigFieldType = 'secret' | 'string' | 'number' | 'boolean' | 'enum' | 'select' | 'multi_select' | 'oauth_connect' | 'phone_number_picker';
+interface SelectOption {
+  value: string;
+  label: string;
+}
+interface ConfigSchemaField {
+  key: string;
+  type: ConfigFieldType;
+  label: string;
+  description?: string;
+  required: boolean;
+  default?: string | number | boolean;
+  /** Who can mutate this field at runtime. Default: 'admin' */
+  editable: 'admin' | 'agent';
+  /** Only used when type === 'enum' */
+  options?: string[];
+  /** Structured options for select/multi_select fields */
+  select_options?: SelectOption[];
+  /** OAuth provider identifier for oauth_connect fields */
+  oauth_provider?: string;
+  /** Only show this field if another field has a truthy value (string) or matches a specific value (object) */
+  depends_on_field?: string | {
+    key: string;
+    value: string | number | boolean;
+  };
+  /** Only show this field if a specific integration is installed */
+  depends_on_integration?: string;
+}
+interface SkillInstall {
+  /** Relative path within the integration repo to the skill directory */
+  path: string;
+}
+interface PluginInstall {
+  /** npm package name to install */
+  package: string;
+}
+type AgentRuntime = 'openclaw' | 'nanoclaw' | (string & {});
+interface RuntimeInstall {
+  plugins?: PluginInstall[];
+  skills?: SkillInstall[];
+  /** Deep-merged into the runtime's agent config on activation */
+  config?: Record<string, unknown>;
+}
+interface InstallTargets {
+  /** Universal skills — applied to all runtimes */
+  skills?: SkillInstall[];
+  /** Universal plugins — applied to all runtimes */
+  plugins?: PluginInstall[];
+  /** Per-runtime installs */
+  runtimes?: Record<AgentRuntime, RuntimeInstall>;
+}
+interface IntegrationHooks {
+  pre_install?: string;
+  post_install?: string;
+  pre_uninstall?: string;
+  post_uninstall?: string;
+  health_check?: string;
+}
+interface IntegrationPricingPlan {
+  name: string;
+  price: number;
+  currency?: string;
+  interval?: 'month' | 'year';
+}
+interface IntegrationPricing {
+  type: 'free' | 'paid';
+  /** Single price (shorthand for integrations with one plan) */
+  price?: number;
+  currency?: string;
+  interval?: 'month' | 'year';
+  /** Multiple plans/tiers (e.g., starter, growth, scale) */
+  plans?: Record<string, IntegrationPricingPlan>;
+}
+interface IntegrationAuthor {
+  name: string;
+  url?: string;
+}
+interface IntegrationManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  /** Simple author string (legacy) or structured author object */
+  author: string | IntegrationAuthor;
+  license: string;
+  depends_on: string[];
+  min_gateway_version: string;
+  installs: InstallTargets;
+  config_schema: ConfigSchemaField[];
+  capabilities: string[];
+  hooks: IntegrationHooks;
+  /**
+   * Agent runtimes this integration supports.
+   * If omitted or empty, the integration is considered universal (all runtimes).
+   * Example: ['openclaw'] means this integration only works with OpenClaw.
+   */
+  supported_agents?: AgentRuntime[];
+  /** Marketplace metadata */
+  publisherId?: string;
+  icon?: string;
+  pricing?: IntegrationPricing;
+  preview_images?: string[];
+  /** Long-form features list for the detail view */
+  features?: string[];
+}
+type IntegrationStatus = 'installing' | 'installed' | 'configured' | 'active' | 'error';
+interface IntegrationStateEntry {
+  status: IntegrationStatus;
+  version: string;
+  installedAt: string;
+  config: Record<string, unknown>;
+  error?: string;
+}
+interface IntegrationsStateFile {
+  version: number;
+  integrations: Record<string, IntegrationStateEntry>;
+}
+//#endregion
+//#region src/runtime-applier.d.ts
+/**
+ * RuntimeApplier — interface for applying/removing plugins and skills
+ * to a specific agent runtime (OpenClaw, NanoClaw, etc.).
+ */
+interface RuntimeApplier {
+  /** The runtime identifier (e.g. 'openclaw', 'nanoclaw') */
+  readonly runtime: string;
+  /** Install a plugin package into this runtime */
+  applyPlugin(pkg: string, integrationInstallPath: string): Promise<void>;
+  /** Remove a plugin package from this runtime */
+  removePlugin(pkg: string): Promise<void>;
+  /** Copy a skill directory into this runtime's skills location */
+  applySkill(name: string, srcPath: string): Promise<void>;
+  /** Remove a skill directory from this runtime */
+  removeSkill(name: string): Promise<void>;
+  /** Deep-merge config into the runtime's agent configuration */
+  applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
+  /** Remove config previously applied by an integration */
+  removeConfig(integrationId: string): Promise<void>;
+  /** Check if this runtime is available (e.g. workspace directory exists) */
+  isAvailable(): Promise<boolean>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Integration command parameter types.
+ *
+ * These define the payloads for integration lifecycle operations.
+ */
+interface IntegrationInstallParams {
+  name: string;
+  version?: string;
+  config?: Record<string, unknown>;
+}
+interface IntegrationRemoveParams {
+  name: string;
+}
+interface IntegrationConfigureParams {
+  name: string;
+  config: Record<string, unknown>;
+}
+interface IntegrationHealthParams {
+  name?: string;
+}
+//#endregion
+//#region src/integration-manager.d.ts
+interface IntegrationManagerOptions {
+  /** @deprecated Logger is now created internally via @auriclabs/logger */
+  logger?: unknown;
+  statePath?: string;
+  integrationsDir?: string;
+  skillsDir?: string;
+  /** Runtime appliers keyed by runtime name */
+  runtimeAppliers?: Map<string, RuntimeApplier>;
+  /** Override lock file path (defaults to ~/.alfe/runtime-lock.json) */
+  lockPath?: string;
+}
+interface ManagerResponse {
+  ok: boolean;
+  payload?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+interface IntegrationInfo {
+  id: string;
+  name?: string;
+  version?: string;
+  status: IntegrationStatus;
+  installedAt?: string;
+  config?: Record<string, unknown>;
+  error?: string;
+}
+/**
+ * Merge universal installs with runtime-specific installs from the manifest.
+ */
+declare function resolveInstallsForRuntime(manifest: IntegrationManifest, runtime: string): {
+  plugins: PluginInstall[];
+  skills: SkillInstall[];
+  config?: Record<string, unknown>;
+};
+declare class IntegrationManager {
+  private log;
+  private state;
+  private registry;
+  private resolver;
+  private installer;
+  private runtimeAppliers;
+  private lockManager;
+  /** In-memory secret store — NEVER persisted to disk */
+  private secrets;
+  constructor(options?: IntegrationManagerOptions);
+  /**
+   * Install an integration from the registry.
+   *
+   * 1. Resolve from registry
+   * 2. Git clone via registry installer
+   * 3. Parse + validate alfe-integration.yaml
+   * 4. Check depends_on are already installed
+   * 5. Run pre_install hook
+   * 6. Run post_install hook
+   * 7. Persist state to integrations.json
+   *
+   * Note: Skills and plugins are NOT applied during install.
+   * They are applied during activate() via runtime appliers.
+   */
+  install(params: IntegrationInstallParams): Promise<ManagerResponse>;
+  /**
+   * Configure an installed integration.
+   *
+   * 1. Load manifest for this integration
+   * 2. Validate config against config_schema
+   * 3. Store non-secret values in state file
+   * 4. Store secret values in memory only (NEVER disk)
+   */
+  configure(params: IntegrationConfigureParams): ManagerResponse;
+  /**
+   * Activate an installed + configured integration.
+   *
+   * 1. Check integration is installed + configured
+   * 2. For each registered runtime applier, apply plugins + skills
+   * 3. Update lock file
+   * 4. Run health_check hook if present
+   * 5. Mark as active in state
+   */
+  activate(integrationId: string): Promise<ManagerResponse>;
+  /**
+   * Deactivate a running integration.
+   *
+   * 1. Read lock file to find all entries for this integration
+   * 2. For each runtime's applier, remove plugins + skills
+   * 3. Update lock file
+   * 4. Set state to configured
+   */
+  deactivate(integrationId: string): Promise<ManagerResponse>;
+  /**
+   * Uninstall an integration completely.
+   *
+   * 1. Deactivate first (removes plugins/skills via appliers)
+   * 2. Run pre_uninstall hook
+   * 3. Run post_uninstall hook
+   * 4. Remove git clone from ~/.alfe/integrations/
+   * 5. Remove from state file
+   */
+  uninstall(params: IntegrationRemoveParams): Promise<ManagerResponse>;
+  /**
+   * Run health checks for one or all integrations.
+   */
+  health(params: IntegrationHealthParams): Promise<ManagerResponse>;
+  /**
+   * List all installed integrations.
+   */
+  list(): IntegrationInfo[];
+  /**
+   * Get a specific integration by name.
+   */
+  get(name: string): IntegrationInfo | undefined;
+  /**
+   * Clear in-memory secrets (called on daemon restart).
+   */
+  clear(): void;
+  private checkHealth;
+  private err;
+}
+//#endregion
+//#region src/state.d.ts
+declare class StateManager {
+  private filePath;
+  private lockHeld;
+  constructor(filePath?: string);
+  /**
+   * Read the current state file. Returns empty state if file doesn't exist.
+   */
+  read(): IntegrationsStateFile;
+  /**
+   * Write the state file atomically.
+   */
+  write(state: IntegrationsStateFile): void;
+  /**
+   * Get a specific integration's state.
+   */
+  get(name: string): IntegrationStateEntry | undefined;
+  /**
+   * Set an integration's state (read-modify-write).
+   */
+  set(name: string, entry: IntegrationStateEntry): void;
+  /**
+   * Update only specific fields of an integration's state.
+   */
+  update(name: string, partial: Partial<IntegrationStateEntry>): void;
+  /**
+   * Update integration status.
+   */
+  setStatus(name: string, status: IntegrationStatus, error?: string): void;
+  /**
+   * Remove an integration from the state file.
+   */
+  remove(name: string): void;
+  /**
+   * List all integrations in the state file.
+   */
+  list(): ({
+    id: string;
+  } & IntegrationStateEntry)[];
+  /**
+   * Check if an integration is in a given status.
+   */
+  hasStatus(name: string, ...statuses: IntegrationStatus[]): boolean;
+}
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Hook Runner — executes integration lifecycle hook scripts.
+ *
+ * Hooks are shell scripts defined in the integration manifest.
+ * They run as child processes with a 30-second timeout.
+ * stdout/stderr are captured and returned.
+ *
+ * The runner injects standard environment variables:
+ * - ALFE_INTEGRATION_DIR — path to the integration install directory
+ * - ALFE_STATE_DIR — path to the integration state directory (created if needed)
+ * - ALFE_<NAME>_<KEY> — config values (non-secret AND secret, both injected as env vars)
+ *
+ * Secrets are acceptable as env vars because:
+ * - Child process env is ephemeral (dies with the process)
+ * - Same security model as Docker secrets / systemd credentials
+ * - Never written to disk
+ */
+interface HookResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+interface HookEnvOptions {
+  /** Integration name (e.g. "voice") */
+  integrationName: string;
+  /** Non-secret config key-value pairs */
+  config?: Record<string, unknown>;
+  /** Secret key-value pairs (in-memory only, injected as env vars) */
+  secrets?: Map<string, unknown>;
+}
+/**
+ * Build the environment variables for a hook script execution.
+ *
+ * Injects:
+ * - ALFE_INTEGRATION_DIR=~/.alfe/integrations/{name}/
+ * - ALFE_STATE_DIR=~/.alfe/state/{name}/ (creates dir if needed)
+ * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each config entry
+ * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each secret entry
+ */
+declare function buildHookEnv(options: HookEnvOptions, additionalEnv?: Record<string, string>): Record<string, string>;
+/**
+ * Run a hook script from an integration directory.
+ *
+ * @param integrationPath - Base path of the integration (where alfe-integration.yaml lives)
+ * @param hookScript - Relative path to the hook script (e.g. "scripts/activate.sh")
+ * @param env - Additional environment variables to pass to the script
+ * @returns Hook execution result
+ */
+declare function runHook(integrationPath: string, hookScript: string, env?: Record<string, string>): Promise<HookResult>;
+/**
+ * Run a hook script with full integration context (config + secrets as env vars).
+ *
+ * This is the preferred method for running lifecycle hooks (activate, deactivate, health).
+ * It builds the complete environment including ALFE_INTEGRATION_DIR, ALFE_STATE_DIR,
+ * and all config/secret values as ALFE_<NAME>_<KEY> env vars.
+ *
+ * @param integrationPath - Base path of the integration
+ * @param hookScript - Relative path to the hook script
+ * @param options - Integration name, config, and secrets
+ * @returns Hook execution result
+ */
+declare function runHookWithContext(integrationPath: string, hookScript: string, options: HookEnvOptions): Promise<HookResult>;
+//#endregion
+//#region src/appliers/openclaw-applier.d.ts
+interface OpenClawApplierOptions {
+  /** Path to the OpenClaw workspace directory (e.g. ~/.openclaw) */
+  workspace: string;
+  /** Override skills directory (defaults to ~/.alfe/skills/) */
+  skillsDir?: string;
+  /** Path to the OpenClaw agent config file (defaults to {workspace}/config.json) */
+  configPath?: string;
+}
+/**
+ * Resolve LLM provider runtime config based on mode.
+ *
+ * - "alfe_credits": keep manifest config as-is (baseUrl points to local proxy,
+ *   apiKey is a dummy — the proxy injects the real key)
+ * - "byok": remove baseUrl (SDK uses provider default), set apiKey from
+ *   decrypted secret
+ *
+ * Non-LLM integrations pass through unchanged.
+ */
+
+declare class OpenClawApplier implements RuntimeApplier {
+  readonly runtime = "openclaw";
+  private workspace;
+  private skillsDir;
+  private configPath;
+  constructor(options: OpenClawApplierOptions);
+  applyPlugin(pkg: string): Promise<void>;
+  removePlugin(pkg: string): Promise<void>;
+  applySkill(name: string, srcPath: string): Promise<void>;
+  removeSkill(name: string): Promise<void>;
+  /**
+   * Deep-merge integration config into the OpenClaw agent config file.
+   *
+   * Each integration's config contribution is tracked in
+   * `_integrations.{integrationId}` within the config file so it can be
+   * cleanly removed later.
+   */
+  applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
+  /**
+   * Remove config previously applied by an integration.
+   *
+   * Rebuilds the config by re-merging all remaining integrations' configs,
+   * ensuring clean removal without orphaned keys.
+   */
+  removeConfig(integrationId: string): Promise<void>;
+  isAvailable(): Promise<boolean>;
+  private readConfig;
+  private writeConfig;
+  /**
+   * Extract the base config by stripping all keys that were contributed
+   * by integrations. This is done by removing each integration's keys
+   * from the current config.
+   */
+  private getBaseConfig;
+}
+//#endregion
+//#region src/lock.d.ts
+interface RuntimePluginEntry {
+  package: string;
+  sourceIntegration: string;
+  integrationVersion: string;
+}
+interface RuntimeSkillEntry {
+  name: string;
+  sourcePath: string;
+  sourceIntegration: string;
+  integrationVersion: string;
+}
+interface RuntimeDesiredState {
+  plugins: RuntimePluginEntry[];
+  skills: RuntimeSkillEntry[];
+}
+interface RuntimeLockFile {
+  version: 1;
+  runtimes: Record<string, RuntimeDesiredState>;
+  updatedAt: string;
+}
+declare class LockManager {
+  private filePath;
+  constructor(filePath?: string);
+  /**
+   * Read the current lock file. Returns empty lock if file doesn't exist.
+   */
+  read(): RuntimeLockFile;
+  /**
+   * Write the lock file atomically.
+   */
+  write(lock: RuntimeLockFile): void;
+  /**
+   * Add entries for an integration activation in a specific runtime.
+   */
+  addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string): void;
+  /**
+   * Remove all entries for a given integration across all runtimes.
+   * Returns what was removed, keyed by runtime.
+   */
+  removeEntries(integrationId: string): Record<string, {
+    plugins: RuntimePluginEntry[];
+    skills: RuntimeSkillEntry[];
+  }>;
+  /**
+   * Get the full desired state for a specific runtime.
+   */
+  getDesiredState(runtime: string): RuntimeDesiredState;
+}
+//#endregion
+//#region src/adapter.d.ts
+/**
+ * Minimal interface for the integration manager that the reconciliation engine depends on.
+ * This abstraction allows testing without the full IntegrationManager.
+ */
+interface IIntegrationManager {
+  /** Get all currently installed integration IDs with their versions */
+  getInstalledIntegrations(): Promise<{
+    id: string;
+    version: string;
+    status: string;
+  }[]>;
+  /** Install an integration at a specific version with config */
+  install(integrationId: string, version: string, config: unknown): Promise<void>;
+  /** Activate an installed integration */
+  activate(integrationId: string): Promise<void>;
+  /** Deactivate a running integration */
+  deactivate(integrationId: string): Promise<void>;
+  /** Uninstall an integration */
+  uninstall(integrationId: string): Promise<void>;
+}
+declare class IntegrationManagerAdapter implements IIntegrationManager {
+  private readonly manager;
+  constructor(manager: IntegrationManager);
+  getInstalledIntegrations(): Promise<{
+    id: string;
+    version: string;
+    status: string;
+  }[]>;
+  install(integrationId: string, version: string, config: unknown): Promise<void>;
+  activate(integrationId: string): Promise<void>;
+  deactivate(integrationId: string): Promise<void>;
+  uninstall(integrationId: string): Promise<void>;
+}
+//#endregion
+export { type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, LockManager, OpenClawApplier, type OpenClawApplierOptions, Registry, type RegistryEntry, type RegistryIndex, RegistryResolveError, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };