@alfe.ai/integration-manifest 0.0.11 → 0.2.0

package/README.md

@@ -61,6 +61,46 @@ hooks:
 
 Only `id`, `name`, `version`, `description`, and `author` are required — everything else has sensible defaults.
 
+## Custom Connections — `expected_credentials`
+
+For manifests consumed by [Custom Connections](../../services/connect/DEVELOPING.md#custom-connections-pr-8a-of-channels-and-credential-driven-integrations) (`requires_connection: ["custom"]`), the manifest declares the credential fields it needs the tenant operator to fill in via an `expected_credentials` block:
+
+```yaml
+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 `type`s — 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
 
 ```typescript

package/dist/index.d.ts

@@ -1,208 +1,54 @@
 import { z } from "zod";
 
-//#region src/types.d.ts
+//#region src/schema.d.ts
 
 /**
- * TypeScript types for the Alfe integration manifest (`alfe-integration.yaml`).
+ * Connect provider ids that a manifest's `requires_connection` field may
+ * reference. The source of truth lives in `services/connect/src/providers/`
+ * (one `ProviderDefinition` per id) — this list mirrors that registry so
+ * the manifest schema can validate references statically.
  *
- * These are the canonical types used by all packages that interact with
- * integration manifests -- registry, lifecycle manager, CLI, etc.
+ * **Keep in sync** with `services/connect/src/providers/index.ts`. Adding a
+ * new connect provider requires updating both: add the provider definition
+ * there, then add its id here so manifests can declare `requires_connection`
+ * against it. Drift in the other direction (id here without provider) is
+ * caught at runtime when the integrations service tries to resolve the
+ * provider and gets nothing back.
  */
-type ConfigFieldType = 'secret' | 'string' | 'number' | 'boolean' | 'enum' | 'select' | 'multi_select' | 'oauth_connect';
-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;
-  /** If true, this field is not shown in the dashboard UI (install wizard or configure modal) */
-  hidden?: boolean;
-  /** 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 McpServerDeclaration {
-  /** Unique identifier within this integration */
-  id: string;
-  /** Command to spawn (e.g., 'npx', 'node', 'xero-mcp-proxy') */
-  command: string;
-  /** Arguments for the command */
-  args?: string[];
-  /** Environment variables — supports {{config.KEY}} interpolation from config + secrets */
-  env?: Record<string, string>;
-  /** Working directory (optional) */
-  cwd?: string;
-  /** If true, applier skips auto-application — a lifecycle hook manages this MCP server instead */
-  hook_managed?: boolean;
-}
-interface CommandDeclaration {
-  /** Dot-namespaced command name (e.g. "support.diagnostic") */
-  name: string;
-  /** Relative path to handler file within integration directory */
-  handler: string;
-  /** Exported function name (default: "handle") */
-  method?: string;
-  /** Timeout in milliseconds (default: 30000) */
-  timeout_ms?: number;
-  /** Human-readable description */
-  description?: string;
-}
-interface SkillInstall {
-  /** Relative path within the integration repo to the skill directory */
-  path?: string;
-  /** ClawHub skill slug to install from the registry */
-  clawhub?: 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;
-  post_activate?: 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' | 'usage';
-  /** Single price (shorthand for integrations with one plan) */
-  price?: number;
-  currency?: string;
-  interval?: 'month' | 'year';
-  /** Description of usage-based pricing (for type: 'usage') */
-  description?: string;
-  /** 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;
-  commands: CommandDeclaration[];
-  /** MCP servers to configure in the agent runtime */
-  mcp_servers: McpServerDeclaration[];
-  /** Git repository URL (HTTPS) — not present in YAML, injected by the publish API */
-  repository?: string;
-  /**
-   * 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[];
-  /**
-   * Scopes where this integration can be installed.
-   * Default: ['agent'] (per-agent only).
-   * 'org' means it can be installed at the org level and cascades to all agents.
-   */
-  supported_scopes?: ('agent' | 'org')[];
-  /** Marketplace metadata */
-  publisherId?: string;
-  icon?: string;
-  pricing?: IntegrationPricing;
-  preview_images?: string[];
-  /** Long-form features list for the detail view */
-  features?: string[];
-}
-interface PublishedVersion {
-  version: string;
-  commit_hash: string;
-  changelog?: string;
-  published_at: string;
-}
-interface PublishedIntegration {
-  manifest: IntegrationManifest;
-  versions: PublishedVersion[];
-  /** Resolved asset URLs baked at publish time */
-  resolved_assets: {
-    icon?: string;
-    preview_images?: string[];
-  };
-}
-type IntegrationStatus = 'installing' | 'installed' | 'configured' | 'active' | 'error';
-interface IntegrationStateEntry {
-  status: IntegrationStatus;
-  version: string;
-  installedAt: string;
-  config: Record<string, unknown>;
-  error?: string;
-  /** Number of consecutive auto-reinstall attempts. Reset on success or explicit reinstall. */
-  reinstallAttempts?: number;
-}
-interface IntegrationsStateFile {
-  version: number;
-  integrations: Record<string, IntegrationStateEntry>;
-}
-interface HealthCheckResult {
-  id: string;
-  name?: string;
-  healthy: boolean;
-  status: IntegrationStatus;
-  version?: string;
-  message?: string;
-  stdout?: string;
-  stderr?: string;
-}
-interface HealthReport {
-  overall: boolean;
-  results: HealthCheckResult[];
-  checkedAt: string;
-}
-//#endregion
-//#region src/schema.d.ts
+declare const KNOWN_CONNECT_PROVIDER_IDS: readonly ["atlassian", "custom", "discord", "github", "google", "microsoft", "mobile", "myob", "notion", "slack", "xero"];
+type KnownConnectProviderId = (typeof KNOWN_CONNECT_PROVIDER_IDS)[number];
+/**
+ * `custom` is a special provider id: it doesn't correspond to a fixed
+ * external service. Instead, every Custom Connection carries its own
+ * manifest URL (a GitHub repo path) on its `providerMetadata`, and the
+ * integration framework resolves the manifest at install time.
+ *
+ * Custom manifests therefore declare `requires_connection: ['custom']`
+ * and ship an `expected_credentials` schema (below) describing the
+ * credential fields the user must fill out when creating the Connection.
+ */
+/**
+ * Channel types are the inbound-message-route taxonomy used by
+ * `ChannelEntity` (added in PR 2 of the channels-and-credential-driven-
+ * integrations plan). A manifest under the submodule's `channels/<id>/`
+ * folder declares which channel type it maps to via `channel_type`, and
+ * `getDesiredState` activates the manifest when at least one Channel of
+ * that type exists in the agent's resolved view.
+ *
+ * The enum is locked — channel adapters and the dashboard's compatibility
+ * matrix both depend on this exact list.
+ */
+declare const LOCKED_CHANNEL_TYPES: readonly ["whatsapp", "sms", "voice", "google_chat", "slack", "discord", "teams"];
+type ChannelType = (typeof LOCKED_CHANNEL_TYPES)[number];
+declare const ChannelTypeSchema: z.ZodEnum<{
+  discord: "discord";
+  slack: "slack";
+  whatsapp: "whatsapp";
+  sms: "sms";
+  voice: "voice";
+  google_chat: "google_chat";
+  teams: "teams";
+}>;
 declare const ConfigFieldTypeSchema: z.ZodEnum<{
   string: "string";
   number: "number";
@@ -251,12 +97,49 @@ declare const ConfigSchemaFieldSchema: z.ZodObject<{
   }, z.core.$strip>]>>;
   depends_on_integration: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * A field a manifest's owner expects the user to fill in when creating
+ * a Custom Connection. Used ONLY by manifests authored against the
+ * `custom` connect provider — built-in OAuth-based integrations don't
+ * declare these (their credential shape comes from the OAuth flow).
+ *
+ * The dashboard renders an `<AddCustomConnectionModal>` form whose
+ * fields are derived from this array; the backend's
+ * `services/connect/api/connections/custom/post.ts` (PR 8b) validates
+ * the submitted credential map against this schema before encrypting
+ * and storing it on the Connection.
+ */
+declare const CredentialFieldTypeSchema: z.ZodEnum<{
+  string: "string";
+  number: "number";
+  boolean: "boolean";
+  secret: "secret";
+  url: "url";
+}>;
+declare const CredentialFieldSpecSchema: z.ZodObject<{
+  key: z.ZodString;
+  type: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    secret: "secret";
+    url: "url";
+  }>;
+  label: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  required: z.ZodDefault<z.ZodBoolean>;
+  placeholder: z.ZodOptional<z.ZodString>;
+  pattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CredentialFieldSpec = z.infer<typeof CredentialFieldSpecSchema>;
+type CredentialFieldType = z.infer<typeof CredentialFieldTypeSchema>;
 declare const McpServerDeclarationSchema: z.ZodObject<{
   id: z.ZodString;
   command: z.ZodString;
   args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
   env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   cwd: z.ZodOptional<z.ZodString>;
+  requires_credentials: z.ZodOptional<z.ZodString>;
   hook_managed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 declare const CommandDeclarationSchema: z.ZodObject<{
@@ -397,8 +280,46 @@ declare const IntegrationManifestSchema: z.ZodObject<{
     args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     cwd: z.ZodOptional<z.ZodString>;
+    requires_credentials: z.ZodOptional<z.ZodString>;
     hook_managed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
   }, z.core.$strip>>>>;
+  requires_connection: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    atlassian: "atlassian";
+    custom: "custom";
+    discord: "discord";
+    github: "github";
+    google: "google";
+    microsoft: "microsoft";
+    mobile: "mobile";
+    myob: "myob";
+    notion: "notion";
+    slack: "slack";
+    xero: "xero";
+  }>>>;
+  channel_type: z.ZodOptional<z.ZodEnum<{
+    discord: "discord";
+    slack: "slack";
+    whatsapp: "whatsapp";
+    sms: "sms";
+    voice: "voice";
+    google_chat: "google_chat";
+    teams: "teams";
+  }>>;
+  expected_credentials: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodEnum<{
+      string: "string";
+      number: "number";
+      boolean: "boolean";
+      secret: "secret";
+      url: "url";
+    }>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    pattern: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
   repository: z.ZodOptional<z.ZodURL>;
   supported_agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
   supported_scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -442,7 +363,263 @@ declare const IntegrationManifestSchema: z.ZodObject<{
 declare function buildConfigValidationSchema(configSchema: z.infer<typeof ConfigSchemaFieldSchema>[]): z.ZodObject<Record<string, z.ZodType>>;
 type ManifestSchemaType = z.infer<typeof IntegrationManifestSchema>;
 //#endregion
+//#region src/types.d.ts
+type ConfigFieldType = 'secret' | 'string' | 'number' | 'boolean' | 'enum' | 'select' | 'multi_select' | 'oauth_connect';
+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;
+  /** Force specific scope groups for OAuth (e.g. ["chat"]) — hides other scopes in the dashboard */
+  oauth_scopes?: string[];
+  /** Integration ID to patch on OAuth callback (when using a shared OAuth provider) */
+  oauth_integration_id?: string;
+  /** If true, this field is not shown in the dashboard UI (install wizard or configure modal) */
+  hidden?: boolean;
+  /** 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 McpServerDeclaration {
+  /** Unique identifier within this integration */
+  id: string;
+  /** Command to spawn (e.g., 'npx', 'node', 'xero-mcp-proxy') */
+  command: string;
+  /** Arguments for the command */
+  args?: string[];
+  /**
+   * Environment variables. Two interpolation syntaxes are supported:
+   *
+   * - `{{config.KEY}}` — resolved from the integration's user-supplied
+   *   config + secrets via `resolveConfig()`. Existing behavior.
+   * - `{{credentials.<provider>.<field>}}` — resolved by the
+   *   `mcp-applier` via `AgentApiClient.get<Provider>Credentials()`.
+   *   `<provider>` is the OAuth provider key (`atlassian`, `github`,
+   *   `xero`, `notion`, `myob`, …); `<field>` is a top-level key on the
+   *   credentials response (`accessToken`, `clientId`, `cloudId`, …).
+   *   Used in conjunction with `requires_credentials` to signal the
+   *   precondition.
+   */
+  env?: Record<string, string>;
+  /** Working directory (optional) */
+  cwd?: string;
+  /**
+   * OAuth provider whose credentials this server requires. When set and
+   * the credentials are missing or 404, the applier logs and skips
+   * registration silently — same graceful no-op the `post_activate.mjs`
+   * hooks do today. Pair with `{{credentials.<provider>.<field>}}` env
+   * references; the explicit field is preferred over inferring from the
+   * presence of the interpolation pattern for clarity.
+   */
+  requires_credentials?: string;
+  /**
+   * @deprecated As of 2026-05-18 the `mcp-applier` handles every case
+   * end-to-end (config + credentials interpolation, requires_credentials
+   * skip-silently, manager.addServer with owner attribution). The
+   * legacy `OpenClawApplier.applyMcpServers` path has been deleted so
+   * the field is now accepted but completely ignored on parse. Drop
+   * from new manifests.
+   */
+  hook_managed?: boolean;
+}
+interface CommandDeclaration {
+  /** Dot-namespaced command name (e.g. "support.diagnostic") */
+  name: string;
+  /** Relative path to handler file within integration directory */
+  handler: string;
+  /** Exported function name (default: "handle") */
+  method?: string;
+  /** Timeout in milliseconds (default: 30000) */
+  timeout_ms?: number;
+  /** Human-readable description */
+  description?: string;
+}
+interface SkillInstall {
+  /** Relative path within the integration repo to the skill directory */
+  path?: string;
+  /** ClawHub skill slug to install from the registry */
+  clawhub?: 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;
+  post_activate?: 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' | 'usage';
+  /** Single price (shorthand for integrations with one plan) */
+  price?: number;
+  currency?: string;
+  interval?: 'month' | 'year';
+  /** Description of usage-based pricing (for type: 'usage') */
+  description?: string;
+  /** 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;
+  commands: CommandDeclaration[];
+  /** MCP servers to configure in the agent runtime */
+  mcp_servers: McpServerDeclaration[];
+  /** Git repository URL (HTTPS) — not present in YAML, injected by the publish API */
+  repository?: string;
+  /**
+   * 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[];
+  /**
+   * Scopes where this integration can be installed.
+   * Default: ['agent'] (per-agent only).
+   * 'org' means it can be installed at the org level and cascades to all agents.
+   */
+  supported_scopes?: ('agent' | 'org')[];
+  /**
+   * Connect provider ids whose credentials this integration resolves at
+   * runtime. OR-semantics: any one in the list satisfies activation. See
+   * the `requires_connection` field in `schema.ts` for full semantics.
+   * Typed as `KnownConnectProviderId[]` so consumers get compile-time
+   * narrowing matching the schema's runtime validation.
+   */
+  requires_connection?: KnownConnectProviderId[];
+  /**
+   * Channel type this integration adapts. Populated on integrations under
+   * the submodule's `channels/<id>/` folder that map to a single channel
+   * type. See `channel_type` in `schema.ts` for full semantics.
+   */
+  channel_type?: ChannelType;
+  /**
+   * Credential fields the manifest expects a Custom Connection's owner
+   * to fill in at create time. Used ONLY by manifests authored against
+   * the `custom` connect provider. See `expected_credentials` in
+   * `schema.ts` for full semantics.
+   */
+  expected_credentials?: CredentialFieldSpec[];
+  /** Marketplace metadata */
+  publisherId?: string;
+  icon?: string;
+  pricing?: IntegrationPricing;
+  preview_images?: string[];
+  /** Long-form features list for the detail view */
+  features?: string[];
+}
+interface PublishedVersion {
+  version: string;
+  commit_hash: string;
+  changelog?: string;
+  published_at: string;
+}
+interface PublishedIntegration {
+  manifest: IntegrationManifest;
+  versions: PublishedVersion[];
+  /** Resolved asset URLs baked at publish time */
+  resolved_assets: {
+    icon?: string;
+    preview_images?: string[];
+  };
+}
+type IntegrationStatus = 'installing' | 'installed' | 'configured' | 'active' | 'error';
+interface IntegrationStateEntry {
+  status: IntegrationStatus;
+  version: string;
+  installedAt: string;
+  config: Record<string, unknown>;
+  error?: string;
+  /** Number of consecutive auto-reinstall attempts. Reset on success or explicit reinstall. */
+  reinstallAttempts?: number;
+}
+interface IntegrationsStateFile {
+  version: number;
+  integrations: Record<string, IntegrationStateEntry>;
+}
+interface HealthCheckResult {
+  id: string;
+  name?: string;
+  healthy: boolean;
+  status: IntegrationStatus;
+  version?: string;
+  message?: string;
+  stdout?: string;
+  stderr?: string;
+}
+interface HealthReport {
+  overall: boolean;
+  results: HealthCheckResult[];
+  checkedAt: string;
+}
+//#endregion
 //#region src/parser.d.ts
+/**
+ * Pluggable warn-sink for parse-time advisories. Defaults to the
+ * Node `console.warn` so the message lands in the right place
+ * regardless of which logger the caller uses; callers that want
+ * structured logs can override.
+ */
+type ParseWarner = (message: string, meta?: Record<string, unknown>) => void;
+declare function setParseWarner(warner: ParseWarner): void;
 declare class ManifestParseError extends Error {
   readonly issues?: {
     path: string;
@@ -569,4 +746,4 @@ declare function migrateConfig(currentConfig: Record<string, unknown>, diff: Con
   warnings: string[];
 };
 //#endregion
-export { type AgentRuntime, type CommandContext, type CommandDeclaration, CommandDeclarationSchema, type CommandHandlerFn, type CommandResult, type ConfigFieldType, ConfigFieldTypeSchema, type ConfigSchemaDiff, type ConfigSchemaField, ConfigSchemaFieldSchema, type HealthCheckResult, type HealthReport, type InstallTargets, InstallTargetsSchema, type IntegrationHooks, IntegrationHooksSchema, type IntegrationManifest, IntegrationManifestSchema, type IntegrationPricing, type IntegrationPricingPlan, type IntegrationStateEntry, type IntegrationStatus, type IntegrationsStateFile, type InterpolationContext, ManifestParseError, type ManifestSchemaType, type McpServerDeclaration, McpServerDeclarationSchema, type PluginInstall, PluginInstallSchema, type PublishedIntegration, type PublishedVersion, type RuntimeInstall, RuntimeInstallSchema, type SelectOption, SelectOptionSchema, type SkillInstall, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl };
+export { type AgentRuntime, type ChannelType, ChannelTypeSchema, type CommandContext, type CommandDeclaration, CommandDeclarationSchema, type CommandHandlerFn, type CommandResult, type ConfigFieldType, ConfigFieldTypeSchema, type ConfigSchemaDiff, type ConfigSchemaField, ConfigSchemaFieldSchema, type CredentialFieldSpec, CredentialFieldSpecSchema, type CredentialFieldType, CredentialFieldTypeSchema, type HealthCheckResult, type HealthReport, type InstallTargets, InstallTargetsSchema, type IntegrationHooks, IntegrationHooksSchema, type IntegrationManifest, IntegrationManifestSchema, type IntegrationPricing, type IntegrationPricingPlan, type IntegrationStateEntry, type IntegrationStatus, type IntegrationsStateFile, type InterpolationContext, KNOWN_CONNECT_PROVIDER_IDS, type KnownConnectProviderId, LOCKED_CHANNEL_TYPES, ManifestParseError, type ManifestSchemaType, type McpServerDeclaration, McpServerDeclarationSchema, type ParseWarner, type PluginInstall, PluginInstallSchema, type PublishedIntegration, type PublishedVersion, type RuntimeInstall, RuntimeInstallSchema, type SelectOption, SelectOptionSchema, type SkillInstall, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl, setParseWarner };

package/dist/index.js

@@ -9,6 +9,63 @@ import { parse } from "yaml";
 * Used by the parser and by the lifecycle manager to ensure manifest
 * correctness before installation.
 */
+/**
+* Connect provider ids that a manifest's `requires_connection` field may
+* reference. The source of truth lives in `services/connect/src/providers/`
+* (one `ProviderDefinition` per id) — this list mirrors that registry so
+* the manifest schema can validate references statically.
+*
+* **Keep in sync** with `services/connect/src/providers/index.ts`. Adding a
+* new connect provider requires updating both: add the provider definition
+* there, then add its id here so manifests can declare `requires_connection`
+* against it. Drift in the other direction (id here without provider) is
+* caught at runtime when the integrations service tries to resolve the
+* provider and gets nothing back.
+*/
+const KNOWN_CONNECT_PROVIDER_IDS = [
+	"atlassian",
+	"custom",
+	"discord",
+	"github",
+	"google",
+	"microsoft",
+	"mobile",
+	"myob",
+	"notion",
+	"slack",
+	"xero"
+];
+/**
+* `custom` is a special provider id: it doesn't correspond to a fixed
+* external service. Instead, every Custom Connection carries its own
+* manifest URL (a GitHub repo path) on its `providerMetadata`, and the
+* integration framework resolves the manifest at install time.
+*
+* Custom manifests therefore declare `requires_connection: ['custom']`
+* and ship an `expected_credentials` schema (below) describing the
+* credential fields the user must fill out when creating the Connection.
+*/
+/**
+* Channel types are the inbound-message-route taxonomy used by
+* `ChannelEntity` (added in PR 2 of the channels-and-credential-driven-
+* integrations plan). A manifest under the submodule's `channels/<id>/`
+* folder declares which channel type it maps to via `channel_type`, and
+* `getDesiredState` activates the manifest when at least one Channel of
+* that type exists in the agent's resolved view.
+*
+* The enum is locked — channel adapters and the dashboard's compatibility
+* matrix both depend on this exact list.
+*/
+const LOCKED_CHANNEL_TYPES = [
+	"whatsapp",
+	"sms",
+	"voice",
+	"google_chat",
+	"slack",
+	"discord",
+	"teams"
+];
+const ChannelTypeSchema = z.enum(LOCKED_CHANNEL_TYPES);
 const ConfigFieldTypeSchema = z.enum([
 	"secret",
 	"string",
@@ -59,12 +116,41 @@ const ConfigSchemaFieldSchema = z.object({
 	if (field.type === "oauth_connect") return field.oauth_provider !== void 0 && field.oauth_provider.length > 0;
 	return true;
 }, { message: "oauth_connect fields must specify an oauth_provider" });
+/**
+* A field a manifest's owner expects the user to fill in when creating
+* a Custom Connection. Used ONLY by manifests authored against the
+* `custom` connect provider — built-in OAuth-based integrations don't
+* declare these (their credential shape comes from the OAuth flow).
+*
+* The dashboard renders an `<AddCustomConnectionModal>` form whose
+* fields are derived from this array; the backend's
+* `services/connect/api/connections/custom/post.ts` (PR 8b) validates
+* the submitted credential map against this schema before encrypting
+* and storing it on the Connection.
+*/
+const CredentialFieldTypeSchema = z.enum([
+	"string",
+	"secret",
+	"url",
+	"number",
+	"boolean"
+]);
+const CredentialFieldSpecSchema = z.object({
+	key: z.string().min(1, "Credential field key must not be empty").regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Credential field key must be a valid identifier (letters, digits, underscores; not starting with a digit)"),
+	type: CredentialFieldTypeSchema,
+	label: z.string().min(1, "Credential field label must not be empty"),
+	description: z.string().optional(),
+	required: z.boolean().default(true),
+	placeholder: z.string().optional(),
+	pattern: z.string().max(256).optional()
+});
 const McpServerDeclarationSchema = z.object({
 	id: z.string().min(1, "MCP server id must not be empty").regex(/^[a-z0-9][a-z0-9-]*$/, "MCP server id must be lowercase alphanumeric with hyphens"),
 	command: z.string().min(1, "MCP server command must not be empty"),
 	args: z.array(z.string()).optional().default([]),
 	env: z.record(z.string(), z.string()).optional(),
 	cwd: z.string().optional(),
+	requires_credentials: z.string().min(1).optional(),
 	hook_managed: z.boolean().optional().default(false)
 });
 const CommandDeclarationSchema = z.object({
@@ -148,6 +234,9 @@ const IntegrationManifestSchema = z.object({
 	hooks: IntegrationHooksSchema.optional().default({}),
 	commands: z.array(CommandDeclarationSchema).optional().default([]),
 	mcp_servers: z.array(McpServerDeclarationSchema).optional().default([]),
+	requires_connection: z.array(z.enum(KNOWN_CONNECT_PROVIDER_IDS)).optional(),
+	channel_type: ChannelTypeSchema.optional(),
+	expected_credentials: z.array(CredentialFieldSpecSchema).optional(),
 	repository: z.url().optional(),
 	supported_agents: z.array(RuntimeKeySchema).optional(),
 	supported_scopes: z.array(z.enum([
@@ -217,6 +306,13 @@ function buildConfigValidationSchema(configSchema) {
 * and validates against the Zod schema. Returns a fully typed
 * IntegrationManifest or throws a descriptive error.
 */
+let parseWarner = (msg, meta) => {
+	if (meta && Object.keys(meta).length > 0) console.warn(`[integration-manifest] ${msg}`, meta);
+	else console.warn(`[integration-manifest] ${msg}`);
+};
+function setParseWarner(warner) {
+	parseWarner = warner;
+}
 var ManifestParseError = class extends Error {
 	constructor(message, issues) {
 		super(message);
@@ -248,7 +344,22 @@ function parseManifestString(yaml, overrides) {
 		}));
 		throw new ManifestParseError(`Invalid integration manifest:\n${issues.map((i) => `  ${i.path ? `${i.path}: ` : ""}${i.message}`).join("\n")}`, issues);
 	}
-	return result.data;
+	const manifest = result.data;
+	warnDeprecatedFields(manifest);
+	return manifest;
+}
+/**
+* Emit one-time-per-parse advisories for fields that pass schema
+* validation but are deprecated. The flag is accepted-but-ignored,
+* not rejected — the warn is the only signal manifest authors get
+* since the `@deprecated` JSDoc only surfaces in TS callers' IDEs.
+*/
+function warnDeprecatedFields(manifest) {
+	const hookManagedServers = manifest.mcp_servers.filter((s) => s.hook_managed === true).map((s) => s.id);
+	if (hookManagedServers.length > 0) parseWarner(`manifest "${manifest.id}" declares mcp_servers with deprecated hook_managed:true — drop the field, the mcp-applier handles every case end-to-end now`, {
+		integration: manifest.id,
+		servers: hookManagedServers
+	});
 }
 /**
 * Read and parse an alfe-integration.yaml file from disk.
@@ -398,4 +509,4 @@ function migrateConfig(currentConfig, diff) {
 	};
 }
 //#endregion
-export { CommandDeclarationSchema, ConfigFieldTypeSchema, ConfigSchemaFieldSchema, InstallTargetsSchema, IntegrationHooksSchema, IntegrationManifestSchema, ManifestParseError, McpServerDeclarationSchema, PluginInstallSchema, RuntimeInstallSchema, SelectOptionSchema, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl };
+export { ChannelTypeSchema, CommandDeclarationSchema, ConfigFieldTypeSchema, ConfigSchemaFieldSchema, CredentialFieldSpecSchema, CredentialFieldTypeSchema, InstallTargetsSchema, IntegrationHooksSchema, IntegrationManifestSchema, KNOWN_CONNECT_PROVIDER_IDS, LOCKED_CHANNEL_TYPES, ManifestParseError, McpServerDeclarationSchema, PluginInstallSchema, RuntimeInstallSchema, SelectOptionSchema, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl, setParseWarner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integration-manifest",
-  "version": "0.0.11",
+  "version": "0.2.0",
   "description": "Integration manifest schema, types, and parser for Alfe integration platform",
   "type": "module",
   "main": "./dist/index.js",