@alfe.ai/integration-manifest

Type definitions, Zod validation schemas, and YAML parsing for Alfe integration manifests.

What It Does

Defines the schema and types for integration manifests (alfe-integration.yaml) — the standard format describing what an integration provides (capabilities, config fields, install targets, hooks, marketplace metadata, etc.).

Used by services/integrations to validate and parse integration configurations, by frontend apps to render integration setup UIs, and by the CLI for manifest validation.

Key Files

src/
├── index.ts          # Public re-exports
├── types.ts          # Manifest type definitions (IntegrationManifest, state, health reports)
├── schema.ts         # Zod validation schemas + buildConfigValidationSchema()
├── parser.ts         # YAML parsing and validation (parseManifestString, parseManifestFile)
├── schema.test.ts    # Schema tests
└── parser.test.ts    # Parser tests

Example Manifest

# alfe-integration.yaml
id: discord
name: Alfe Discord
version: 1.0.0
description: Discord bot integration for Alfe agents
author: alfe
license: MIT
depends_on: []
min_gateway_version: 1.0.0

installs:
  skills:
    - path: skills/discord-notify
  plugins:
    - package: "@alfe.ai/openclaw-discord"

config_schema:
  - key: bot_token
    type: secret
    label: "Discord Bot Token"
    description: "Bot token from Discord Developer Portal"
    required: true
  - key: guild_id
    type: string
    label: "Guild ID"
    required: false

capabilities:
  - discord.send_message
  - discord.receive_message

hooks:
  post_install: scripts/post-install.sh
  health_check: scripts/health.sh

Only id, name, version, description, and author are required — everything else has sensible defaults.

Custom Connections — expected_credentials

For manifests consumed by Custom Connections (requires_connection: ["custom"]), the manifest declares the credential fields it needs the tenant operator to fill in via an expected_credentials block:

requires_connection: ["custom"]
expected_credentials:
  - key: api_key
    type: secret
    label: "API Key"
    description: "From the upstream dashboard"
    required: true
  - key: base_url
    type: url
    label: "Base URL"
    placeholder: "https://api.example.com"
    required: false
  - key: workspace_id
    type: string
    label: "Workspace ID"
    pattern: "^[a-zA-Z0-9_-]+$"
    required: true

Supported field types — same vocabulary as the dashboard form renderer:

| Type | Stored as | Notes | |-----------|------------------------------------|-----------------------------------------| | secret | KMS-encrypted (encryptedAccessToken) | Joined into a JSON bundle by services/connect at write time | | string | providerMetadata.{key} | Plain string | | url | providerMetadata.{key} | Plain string; URL validation client-side | | number | providerMetadata.{key} | Stored as JS number | | boolean | providerMetadata.{key} | Stored as JS boolean |

When adding a new credential field type:

1. Extend CredentialFieldTypeSchema in src/schema.ts.
2. Extend CredentialFieldType consumers — the dashboard form renderer in PR 8b and the storage projection in services/connect/src/providers/custom.ts's buildCredentialsResponse (if the storage shape differs).
3. Document the new type here.

Usage

import {
  type IntegrationManifest,
  parseManifestFile,
  parseManifestString,
  IntegrationManifestSchema,
  buildConfigValidationSchema,
} from '@alfe.ai/integration-manifest';

// Parse and validate a manifest file
const manifest = parseManifestFile('./alfe-integration.yaml');

// Or parse a raw YAML string
const manifest = parseManifestString(yamlString);

// Build a Zod schema from a manifest's config_schema to validate user config
const configSchema = buildConfigValidationSchema(manifest.config_schema);
const result = configSchema.safeParse(userProvidedConfig);

Development

pnpm install
pnpm --filter @alfe.ai/integration-manifest build
pnpm --filter @alfe.ai/integration-manifest test

Dependencies

• yaml — YAML parsing
• zod — Schema validation