docs: document channel plugin setup types

steipete · steipete · commit cc73ef8ba59a · 2026-06-04T10:42:48.000-04:00
diff --git a/src/channels/plugins/setup-wizard-helpers.ts b/src/channels/plugins/setup-wizard-helpers.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup wizard helper functions.
+ *
+ * Prompts account ids, credentials, allowlists, and account-scoped setup config updates.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   normalizeStringEntries,
diff --git a/src/channels/plugins/setup-wizard-proxy.ts b/src/channels/plugins/setup-wizard-proxy.ts
@@ -1,3 +1,8 @@
+/**
+ * Lazy setup wizard proxy helpers.
+ *
+ * Delegates setup wizard status, credential, allowlist, and finalization hooks to loaded wizards.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { createDelegatedSetupWizardStatusResolvers } from "./setup-wizard-binary.js";
 import type { ChannelSetupDmPolicy } from "./setup-wizard-types.js";
diff --git a/src/channels/plugins/setup-wizard-types.ts b/src/channels/plugins/setup-wizard-types.ts
@@ -1,3 +1,8 @@
+/**
+ * Declarative channel setup wizard contract.
+ *
+ * Defines status, credentials, prompts, group access, and finalization types for setup flows.
+ */
 import type { DmPolicy } from "../../config/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { RuntimeEnv } from "../../runtime.js";
@@ -11,9 +16,6 @@ import type {
   ChannelSetupInput,
 } from "./types.core.js";
 
-// Public setup wizard contract shared by bundled channel plugins and setup
-// orchestration. Keep these types declarative; runtime behavior lives in
-// setup-wizard.ts.
 export type ChannelSetupPlugin = {
   id: ChannelId;
   meta: ChannelMeta;
diff --git a/src/channels/plugins/setup-wizard.ts b/src/channels/plugins/setup-wizard.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup wizard adapter.
+ *
+ * Adapts declarative wizard definitions into imperative setup adapters used by onboarding.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { DEFAULT_ACCOUNT_ID } from "../../routing/session-key.js";
@@ -19,8 +24,6 @@ import type {
 } from "./setup-wizard-types.js";
 import type { ChannelSetupInput } from "./types.core.js";
 
-// Adapts declarative channel setup wizard definitions into the imperative
-// setup adapter used by onboarding and channel configuration flows.
 export type {
   ChannelSetupWizard,
   ChannelSetupWizardAllowFrom,
diff --git a/src/channels/plugins/stateful-target-builtins.ts b/src/channels/plugins/stateful-target-builtins.ts
@@ -1,7 +1,10 @@
+/**
+ * Built-in stateful binding target registration.
+ *
+ * Lazily registers ACP target drivers so non-ACP channel flows avoid ACP runtime imports.
+ */
 import { registerStatefulBindingTargetDriver } from "./stateful-target-drivers.js";
 
-// Lazily registers built-in stateful binding target drivers. Keep imports
-// dynamic so non-ACP channel flows do not load the ACP runtime boundary.
 type AcpStatefulTargetDriverModule = typeof import("./acp-stateful-target-driver.js");
 
 let builtinsRegisteredPromise: Promise<void> | null = null;
diff --git a/src/channels/plugins/stateful-target-drivers.ts b/src/channels/plugins/stateful-target-drivers.ts
@@ -1,11 +1,14 @@
+/**
+ * Stateful binding target driver registry.
+ *
+ * Stores lifecycle drivers for binding targets that carry mutable external session state.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type {
   ConfiguredBindingResolution,
   StatefulBindingTargetDescriptor,
 } from "./binding-types.js";
 
-// Registry for binding targets that carry external mutable session state, such
-// as ACP-backed channels that need per-session reset and lookup behavior.
 export type StatefulBindingTargetReadyResult = { ok: true } | { ok: false; error: string };
 export type StatefulBindingTargetSessionResult =
   | { ok: true; sessionKey: string }
diff --git a/src/channels/plugins/status-issues/shared.ts b/src/channels/plugins/status-issues/shared.ts
@@ -1,12 +1,13 @@
+/**
+ * Channel status issue helper utilities.
+ *
+ * Formats status metadata and finds enabled/configured account ids for diagnostics.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { isRecord } from "../../../utils.js";
 import type { ChannelAccountSnapshot, ChannelStatusIssue } from "../types.public.js";
 export { isRecord };
 
-/**
- * Shared helpers for channel status issue collectors.
- */
-
 /**
  * Normalizes optional string metadata in status issue helpers.
  */
diff --git a/src/channels/plugins/status.ts b/src/channels/plugins/status.ts
@@ -1,11 +1,15 @@
+/**
+ * Channel status snapshot builders.
+ *
+ * Combines plugin status hooks, account inspection, and safe account field projection.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { inspectChannelAccount } from "../account-inspection.js";
 import { projectSafeChannelAccountSnapshotFields } from "../account-snapshot-fields.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelAccountSnapshot } from "./types.public.js";
 
-// Channel docking: status snapshots flow through plugin.status hooks here.
 export async function buildChannelAccountSnapshotFromAccount<ResolvedAccount>(params: {
   plugin: ChannelPlugin<ResolvedAccount>;
   cfg: OpenClawConfig;
diff --git a/src/channels/plugins/target-parsing-loaded.ts b/src/channels/plugins/target-parsing-loaded.ts
@@ -1,3 +1,8 @@
+/**
+ * Loaded-channel target parsing helpers.
+ *
+ * Bridges deprecated explicit target parsing with modern channel route target helpers.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/channels/plugins/target-resolvers.ts b/src/channels/plugins/target-resolvers.ts
@@ -1,8 +1,9 @@
-import type { ChannelResolveResult } from "./types.adapters.js";
-
 /**
- * Shared helpers for channel target resolution flows.
+ * Channel target resolver helpers.
+ *
+ * Builds unresolved rows and token-gated resolution flows for setup/allowlist targets.
  */
+import type { ChannelResolveResult } from "./types.adapters.js";
 
 /**
  * Builds unresolved target results with one common note.
diff --git a/src/channels/plugins/thread-binding-api.ts b/src/channels/plugins/thread-binding-api.ts
@@ -1,9 +1,10 @@
-import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
-import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";
-
 /**
- * Lightweight thread-binding public artifact loader for bundled channels.
+ * Bundled channel thread-binding public artifact loader.
+ *
+ * Reads lightweight thread placement and inbound conversation hooks without full plugin loading.
  */
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";
 
 type ThreadBindingPlacement = "current" | "child";
 
diff --git a/src/channels/plugins/threading-helpers.ts b/src/channels/plugins/threading-helpers.ts
@@ -1,11 +1,12 @@
+/**
+ * Channel threading resolver helpers.
+ *
+ * Builds reply-to-mode resolvers from static, top-level, or account-scoped config.
+ */
 import type { ReplyToMode } from "../../config/types.base.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { ChannelThreadingAdapter } from "./types.core.js";
 
-/**
- * Shared reply-threading resolver helpers for channel plugins.
- */
-
 type ReplyToModeResolver = NonNullable<ChannelThreadingAdapter["resolveReplyToMode"]>;
 
 /**
diff --git a/src/channels/plugins/tts-capabilities.ts b/src/channels/plugins/tts-capabilities.ts
@@ -1,9 +1,12 @@
+/**
+ * Channel TTS voice capability resolver.
+ *
+ * Reads channel-advertised voice delivery support for prompt and runtime routing.
+ */
 import { normalizeChannelId } from "./registry.js";
 import { getChannelPlugin } from "./registry.js";
 import type { ChannelTtsVoiceDeliveryCapabilities } from "./types.core.js";
 
-// Resolves channel-advertised TTS voice delivery support for prompt/runtime
-// routing without exposing the full plugin object to callers.
 export function resolveChannelTtsVoiceDelivery(
   channel: string | undefined,
 ): ChannelTtsVoiceDeliveryCapabilities | undefined {
diff --git a/src/channels/plugins/types.adapters.ts b/src/channels/plugins/types.adapters.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel plugin adapter type contracts.
+ *
+ * Defines approval, setup, config, outbound, directory, and messaging adapter surfaces.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type { LegacyConfigRule } from "../../config/legacy.shared.js";
 import type { AgentBinding } from "../../config/types.agents.js";
diff --git a/src/channels/plugins/types.config.ts b/src/channels/plugins/types.config.ts
@@ -1,7 +1,10 @@
+/**
+ * Channel config schema type contracts.
+ *
+ * Defines JSON Schema metadata, UI hints, and runtime parser result shapes.
+ */
 import type { JsonSchemaObject } from "../../shared/json-schema.types.js";
 
-// Channel config schema metadata consumed by setup, docs, and validation UI.
-// Runtime schemas stay duck-typed so plugins can provide zod-like validators.
 /** Optional UI metadata for a JSON Schema property. */
 export type ChannelConfigUiHint = {
   label?: string;
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
@@ -1,3 +1,8 @@
+/**
+ * Core channel plugin public types.
+ *
+ * Defines channel metadata, capabilities, action discovery, setup, status, and runtime contexts.
+ */
 import type { TSchema } from "typebox";
 import type {
   GatewayClientMode,
diff --git a/src/channels/plugins/types.plugin.ts b/src/channels/plugins/types.plugin.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel plugin root type contract.
+ *
+ * Defines the full plugin object shape composed from config, runtime, setup, and adapter surfaces.
+ */
 import type { ChannelMessageAdapterShape } from "../message/types.js";
 import type { ChannelSetupWizard, ChannelSetupWizardAdapter } from "./setup-wizard-types.js";
 import type { ChannelConfigSchema } from "./types.config.js";
diff --git a/src/channels/plugins/types.public.ts b/src/channels/plugins/types.public.ts
@@ -1,7 +1,10 @@
+/**
+ * Public channel plugin type barrel.
+ *
+ * Re-exports stable plugin-facing channel types and message action names.
+ */
 import type { ChannelMessageActionName as ChannelMessageActionNameFromList } from "./message-action-names.js";
 
-// Public channel-plugin type barrel used by plugin-facing facades. Keep exports
-// type-only unless the value is part of the stable plugin contract.
 export { CHANNEL_MESSAGE_ACTION_NAMES } from "./message-action-names.js";
 export type * from "./types.core.js";
 export type * from "./types.adapters.js";
diff --git a/src/channels/plugins/types.ts b/src/channels/plugins/types.ts
@@ -1,7 +1,10 @@
+/**
+ * Internal channel plugin type barrel.
+ *
+ * Re-exports curated core-facing channel plugin types without helper-only implementation details.
+ */
 import type { ChannelMessageActionName as ChannelMessageActionNameFromList } from "./message-action-names.js";
 
-// Curated internal channel-plugin type barrel. Keep this list explicit so core
-// imports do not accidentally expose helper-only implementation types.
 export { CHANNEL_MESSAGE_ACTION_NAMES } from "./message-action-names.js";
 export { CHANNEL_MESSAGE_CAPABILITIES } from "./message-capabilities.js";
 
