@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/channels/connections.controller.d.ts

@@ -1,59 +1,68 @@
-import { z } from "zod";
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { z } from "zod";
 import type { JsonSchema } from "../extensions/config-json-schema.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { type ConnectionGuideState, PluginGuides, type SetupGuideRef } from "../extensions/plugin-guides.js";
+import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { ChannelConnections, type ChannelConnectionView } from "./connections.service.js";
-declare const CreateBody: z.ZodObject<{
-    plugin: z.ZodString;
-    name: z.ZodString;
-    agentId: z.ZodString;
-    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    unboundPolicy: z.ZodOptional<z.ZodEnum<{
-        anonymous: "anonymous";
-        bind: "bind";
-    }>>;
-}, z.core.$strict>;
-declare const PatchBody: z.ZodObject<{
-    name: z.ZodOptional<z.ZodString>;
-    agentId: z.ZodOptional<z.ZodString>;
-    unboundPolicy: z.ZodOptional<z.ZodEnum<{
-        anonymous: "anonymous";
-        bind: "bind";
-    }>>;
-    status: z.ZodOptional<z.ZodEnum<{
-        active: "active";
-        disabled: "disabled";
-    }>>;
-    inboundMode: z.ZodOptional<z.ZodEnum<{
-        long_connection: "long_connection";
-        webhook: "webhook";
-    }>>;
-    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strict>;
+import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody } from "./channels.schemas.js";
+import { ChannelConnections, type ChannelConnectionView, type ChannelInboundInfo } from "./connections.service.js";
+/**
+ * A connection as the org's pages show it: its plugin's display name (null when it has none) and
+ * the URL of its plugin's icon on the org's catalog route (null without one, or when the org may
+ * not see the plugin's catalog item; maintainer decision 2026-11-08), and its plugin's setup guide
+ * with the drift since the connection was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-09-setup-guides-v2-design.md §11).
+ */
+export type ChannelConnectionPage = ChannelConnectionView & ConnectionGuideState & {
+    pluginDisplayName: LocalizedName | null;
+    pluginIcon: string | null;
+};
 /**
  * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
  * 响应只回显非密钥配置与密钥是否已设置。
  */
 export declare class ChannelConnectionsController {
     private readonly channels;
-    constructor(channels: ChannelConnections);
+    private readonly displayNames;
+    private readonly icons;
+    private readonly guides;
+    constructor(channels: ChannelConnections, displayNames: ExtensionDisplayNames, icons: PluginIcons, guides: PluginGuides);
+    /** The connections with their plugins' display names, icons and guides (batched reads). */
+    private withPlugins;
+    private withPlugin;
     list(org: OrgContext): Promise<{
-        channels: ChannelConnectionView[];
+        channels: ChannelConnectionPage[];
     }>;
-    schema(plugin: string): {
+    /**
+     * The connection form's JSON Schema, where the plugin's setup guide is (`guide`, null when the
+     * plugin has none the org may see): 新建渠道 shows it once the plugin is picked; and whether its
+     * connections can use webhook inbound (`inbound`, channel inbound mode fields spec §4).
+     */
+    schema(org: OrgContext, plugin: string): Promise<{
         plugin: string;
         schema: JsonSchema;
-    };
+        guide: Omit<SetupGuideRef, "version"> | null;
+        inbound: ChannelInboundInfo;
+    }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
     }>;
     get(org: OrgContext, id: string): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
     }>;
     update(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof PatchBody>): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
         verifySkipped: boolean;
     }>;
+    /**
+     * 「我已更新应用」: the person updated the platform app to the plugin's current setup guide
+     * (`{ hash }` of the guide shown) -> 200 `{ channel }`; 409 `channel.guide_changed` when the guide
+     * moved on since, 404 `catalog.guide_not_found` without a guide.
+     */
+    ackGuide(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof GuideAckBody>): Promise<{
+        channel: ChannelConnectionPage;
+    }>;
     remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
 }
-export {};

package/dist/channels/connections.controller.js

@@ -8,66 +8,95 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post } from "@nestjs/common";
-import { z } from "zod";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { PluginGuides, } from "../extensions/plugin-guides.js";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { ChannelConnections } from "./connections.service.js";
-const Config = z.record(z.string().max(200), z.unknown());
-const Policy = z.enum(["bind", "anonymous"]);
-const CreateBody = z
-    .object({
-    plugin: z.string().min(1).max(214),
-    name: z.string().trim().min(1).max(100),
-    agentId: z.string().min(1).max(100),
-    config: Config,
-    unboundPolicy: Policy.optional(),
-})
-    .strict();
-const PatchBody = z
-    .object({
-    name: z.string().trim().min(1).max(100).optional(),
-    agentId: z.string().min(1).max(100).optional(),
-    unboundPolicy: Policy.optional(),
-    status: z.enum(["active", "disabled"]).optional(),
-    // webhook needs plugin support and channels.webhookBaseUrl (409 channel.webhook_unavailable)
-    inboundMode: z.enum(["long_connection", "webhook"]).optional(),
-    config: Config.optional(),
-})
-    .strict();
+import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody, } from "./channels.schemas.js";
+import { ChannelConnections, } from "./connections.service.js";
 class ChannelCreateBody extends createZodDto(CreateBody, "ChannelCreateBody") {
 }
 class ChannelPatchBody extends createZodDto(PatchBody, "ChannelPatchBody") {
 }
+class ChannelGuideAckBody extends createZodDto(GuideAckBody, "ChannelGuideAckBody") {
+}
 /**
  * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
  * 响应只回显非密钥配置与密钥是否已设置。
  */
 let ChannelConnectionsController = class ChannelConnectionsController {
     channels;
-    constructor(channels) {
+    displayNames;
+    icons;
+    guides;
+    constructor(channels, displayNames, icons, guides) {
         this.channels = channels;
+        this.displayNames = displayNames;
+        this.icons = icons;
+        this.guides = guides;
+    }
+    /** The connections with their plugins' display names, icons and guides (batched reads). */
+    async withPlugins(org, views) {
+        const plugins = views.map((v) => v.plugin);
+        const [names, icons, guides] = await Promise.all([
+            this.displayNames.many(plugins),
+            this.icons.many(plugins, orgIconScope(org)),
+            this.guides.connectionStates(views, org),
+        ]);
+        return views.map((v) => ({
+            ...v,
+            pluginDisplayName: names.get(v.plugin) ?? null,
+            pluginIcon: icons.get(v.plugin) ?? null,
+            setupGuide: guides.get(v.id)?.setupGuide ?? null,
+            guideDrift: guides.get(v.id)?.guideDrift ?? null,
+        }));
+    }
+    async withPlugin(org, view) {
+        const [page] = await this.withPlugins(org, [view]);
+        return page;
     }
     async list(org) {
-        return { channels: await this.channels.list(org.orgId) };
+        return { channels: await this.withPlugins(org, await this.channels.list(org.orgId)) };
     }
-    schema(plugin) {
-        return { plugin, schema: this.channels.jsonSchema(plugin) };
+    /**
+     * The connection form's JSON Schema, where the plugin's setup guide is (`guide`, null when the
+     * plugin has none the org may see): 新建渠道 shows it once the plugin is picked; and whether its
+     * connections can use webhook inbound (`inbound`, channel inbound mode fields spec §4).
+     */
+    async schema(org, plugin) {
+        const schema = this.channels.jsonSchema(plugin);
+        const inbound = this.channels.inboundInfo(plugin);
+        const g = (await this.guides.channelGuides([plugin], org)).get(plugin);
+        return { plugin, schema, guide: g ? { itemId: g.itemId, guideId: g.guideId } : null, inbound };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
         return {
-            channel: await this.channels.create(org.orgId, body, p.account.id, patTokenId(p)),
+            channel: await this.withPlugin(org, await this.channels.create(org.orgId, body, p.account.id, patTokenId(p))),
         };
     }
     async get(org, id) {
-        return { channel: await this.channels.get(org.orgId, id) };
+        return { channel: await this.withPlugin(org, await this.channels.get(org.orgId, id)) };
     }
     async update(principal, org, id, body) {
         const p = requireUser(principal);
-        // verifySkipped：插件在该组织停用时轮换凭据不调用插件校验（重新启用后按新凭据连接）
-        return this.channels.update(org.orgId, id, body, p.account.id, patTokenId(p));
+        // verifySkipped: with the plugin off in the org, rotated credentials are not verified by the
+        // plugin (it connects with them once it is on again)
+        const r = await this.channels.update(org.orgId, id, body, p.account.id, patTokenId(p));
+        return { ...r, channel: await this.withPlugin(org, r.channel) };
+    }
+    /**
+     * 「我已更新应用」: the person updated the platform app to the plugin's current setup guide
+     * (`{ hash }` of the guide shown) -> 200 `{ channel }`; 409 `channel.guide_changed` when the guide
+     * moved on since, 404 `catalog.guide_not_found` without a guide.
+     */
+    async ackGuide(principal, org, id, body) {
+        const p = requireUser(principal);
+        const view = await this.channels.ackGuide({ orgId: org.orgId, role: org.role }, id, body.hash, p.account.id, patTokenId(p));
+        return { channel: await this.withPlugin(org, view) };
     }
     async remove(principal, org, id) {
         const p = requireUser(principal);
@@ -82,7 +111,8 @@ __decorate([
 __decorate([
     Get("schema/:plugin"),
     OrgAction("channels.manage"),
-    __param(0, Param("plugin"))
+    __param(0, CurrentOrg()),
+    __param(1, Param("plugin"))
 ], ChannelConnectionsController.prototype, "schema", null);
 __decorate([
     Post(),
@@ -105,6 +135,15 @@ __decorate([
     __param(2, Param("connectionId")),
     __param(3, ZBody(ChannelPatchBody))
 ], ChannelConnectionsController.prototype, "update", null);
+__decorate([
+    Post(":connectionId/guide-ack"),
+    HttpCode(200),
+    OrgAction("channels.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectionId")),
+    __param(3, ZBody(ChannelGuideAckBody))
+], ChannelConnectionsController.prototype, "ackGuide", null);
 __decorate([
     Delete(":connectionId"),
     HttpCode(204),
@@ -115,6 +154,9 @@ __decorate([
 ], ChannelConnectionsController.prototype, "remove", null);
 ChannelConnectionsController = __decorate([
     Controller("api/v1/orgs/:orgId/channels"),
-    __param(0, Inject(ChannelConnections))
+    __param(0, Inject(ChannelConnections)),
+    __param(1, Inject(ExtensionDisplayNames)),
+    __param(2, Inject(PluginIcons)),
+    __param(3, Inject(PluginGuides))
 ], ChannelConnectionsController);
 export { ChannelConnectionsController };

package/dist/channels/connections.service.d.ts

@@ -4,6 +4,7 @@ import type { Redis } from "ioredis";
 import { type Keyring } from "../ctx/secrets.js";
 import { type JsonSchema } from "../extensions/config-json-schema.js";
 import type { InflightTracker } from "../extensions/inflight.js";
+import { type GuideAck, PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -11,7 +12,14 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { type KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { ChannelJobs } from "./jobs.js";
+import type { ChannelLocale } from "./phrases.js";
+/**
+ * A public https address: https, and the host is not loopback, a private / link-local / reserved
+ * IP, `localhost`, `*.localhost`, `*.local`, `*.internal` or a single label (no DNS lookup).
+ */
+export declare function isPublicHttpsUrl(url: string): boolean;
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
 export declare const connectionSecretKey: (connectionId: string) => string;
 /**
@@ -46,6 +54,11 @@ export interface ChannelConnectionView {
     lastError: string | null;
     botUserId: string | null;
     tenantId: string | null;
+    /**
+     * The plugin's setup guide the connection was last set up with (recorded on create, on a mode
+     * switch and by `guide-ack`); null when unknown.
+     */
+    guideAck: GuideAck | null;
     config: Record<string, unknown>;
     secrets: {
         path: string;
@@ -74,6 +87,18 @@ export interface CreateChannelInput {
     agentId: string;
     config: Record<string, unknown>;
     unboundPolicy?: UnboundPolicy | undefined;
+    /** Default `long_connection`; `webhook` needs plugin support and `channels.webhookBaseUrl`. */
+    inboundMode?: InboundMode | undefined;
+}
+/**
+ * Whether a channel plugin's connections can use webhook inbound (channel inbound mode fields spec
+ * §4): the plugin implements `Channel.webhook`; the kernel accepts webhook mode (a usable
+ * `channels.webhookBaseUrl`); and that base URL is a public https address.
+ */
+export interface ChannelInboundInfo {
+    webhookSupported: boolean;
+    webhookAvailable: boolean;
+    webhookPublic: boolean;
 }
 /** `config` 里的密钥字段：缺省 = 保留原值、`null` = 清除、其他值 = 新值（同组织插件配置）。 */
 export interface UpdateChannelInput {
@@ -105,7 +130,11 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     private readonly log;
     readonly txHost: TransactionHost;
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    private readonly guides;
     private readonly unsubscribe;
+    /** `<plugin>@<version>` whose invalid connection hints were warned about (a log dedupe only). */
+    private readonly hintsWarned;
     constructor(db: KernelDb, 
     /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
     orgLock: Pick<OrgLock, "lockAndAuthorize">, keyring: Keyring, registry: Pick<ExtensionRegistry, "list">, bus: ExtensionContext["bus"], redis: Pick<Redis, "del">, 
@@ -114,7 +143,9 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
     config: Pick<KernelConfigService, "get">, events: Pick<KernelEvents, "on">, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
-    log: Pick<KernelLogger, "warn" | "addOrgSecrets">, txHost: TransactionHost);
+    log: Pick<KernelLogger, "warn" | "addOrgSecrets">, txHost: TransactionHost, 
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides: Pick<PluginGuides, "currentAck" | "ackDrifted">);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
     /** The extension's `channel@1`; not loaded or not provided -> `extension.not_found`. */
@@ -122,8 +153,21 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     private channelEntry;
     /** The extension is not enabled in this organization -> `extension.not_enabled`. */
     private assertEnabled;
-    /** `connectionSchema` 的 JSON Schema（同组织插件配置的转换：密钥字段带 `x-secret`、不输出取值）。 */
+    /**
+     * The connection schema's form JSON Schema (secret fields carry `x-secret`, no values), a copy.
+     * Never throws: when even the plain conversion fails, an empty object schema (a save is still
+     * validated here).
+     */
     jsonSchema(plugin: string): JsonSchema;
+    /**
+     * The connection schema's form JSON Schema; invalid hints are stripped and warned about once per
+     * `<plugin>@<version>` on this replica (spec §4.1: the connection level is checked at its first
+     * conversion, not at load). Never throws: a hint conversion that throws serves the plain schema,
+     * else null, with one warning per schema.
+     */
+    private formSchema;
+    /** The loaded version of a channel extension, for warnings ("unknown" when not provided). */
+    private versionOf;
     private parse;
     private verify;
     private reportSecrets;
@@ -136,6 +180,15 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * `channels.webhookBaseUrl` (otherwise there is no URL to give the platform): 409 otherwise.
      */
     private assertWebhookAvailable;
+    /**
+     * The fields the inbound mode requires (`x-ui.inboundModes`, channel inbound mode fields spec
+     * §3) must have a value in `full` (the parsed config, stored secrets included): 400
+     * `extension.config_invalid` with one issue per missing field otherwise. A plugin without the
+     * hint passes.
+     */
+    private assertModeFields;
+    /** Whether the plugin's connections can use webhook inbound (spec §4); `extension.not_found`. */
+    inboundInfo(plugin: string): ChannelInboundInfo;
     private viewOf;
     private live;
     list(orgId: string): Promise<ChannelConnectionView[]>;
@@ -144,18 +197,37 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     create(orgId: string, input: CreateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
     /** The rows of {@link create}, in their own transaction (the caller publishes after the commit). */
     private insertIn;
+    /** The read-only refusals of {@link update} that need no write (the Platform tool's precheck). */
+    checkUpdate(orgId: string, id: string, patch: UpdateChannelInput): Promise<void>;
     /**
      * 修改名称、agent、未绑定策略、启停，或轮换凭据（新配置同样先 `verify`，失败什么都不改）。
      * 插件在该组织停用时仍可轮换凭据，此时不 verify，返回 `verifySkipped: true`。
      */
-    update(orgId: string, id: string, patch: UpdateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<{
+    update(orgId: string, id: string, patch: UpdateChannelInput, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<{
         channel: ChannelConnectionView;
         verifySkipped: boolean;
     }>;
     /** The rows of {@link update}, in their own transaction (the caller publishes after the commit). */
     private updateIn;
+    /**
+     * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
+     * mode as the one it is set up with. `hash` is the drift hash of the guide the person was
+     * shown; when the plugin has moved on since, 409 `channel.guide_changed` (show the new guide
+     * first). A plugin without a guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    /** The row of {@link ackGuide}, in its own transaction. */
+    private ackIn;
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
-    remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /** The rows of {@link remove}, in their own transaction (the caller publishes after the commit). */
     private removeIn;
     /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
@@ -170,6 +242,18 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * 持有长连接的副本立即断开（扫描复核只是兜底）。只广播，失败只记日志。
      */
     notifyOrgChanged(orgId: string, plugin?: string): Promise<void>;
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a live connection of the org
+     * on `plugin`: the `updated_at` of its row and of its secrets row (ISO), never a value. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`.
+     */
+    checkRevision(orgId: string, plugin: string, id: string): Promise<string>;
+    /**
+     * For setup checks (setup guides v2 §10.8): the stored secret values of a live connection of the
+     * org on `plugin` (every secret field, decrypted), what a check's result is redacted by. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`. Never echo them.
+     */
+    checkSecrets(orgId: string, plugin: string, id: string): Promise<string[]>;
     /**
      * The extension implementation and full config a connection needs to run (decrypted secrets
      * included, validated against `connectionSchema`). Connection missing / deleted ->
@@ -190,8 +274,12 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * `redact` 按该连接的密钥打码（插件异常信息写进 `last_error` 前使用）。
      */
     outbound(connectionId: string): Promise<ChannelOutboundSession>;
-    /** 经连接的插件直接发一条消息（入站处理回绑定卡片、固定话术，卡片操作回说明）；`idempotencyKey` 原样交给插件。 */
-    send(connectionId: string, target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+    /**
+     * Sends one message through the connection's extension (inbound replies: bind cards, fixed
+     * phrases, card-action notes); `idempotencyKey` is passed through as is, `locale` is the
+     * recipient's language (else the org's).
+     */
+    send(connectionId: string, target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<{
         messageId: string;
     }>;
 }
@@ -200,10 +288,14 @@ export interface ChannelOutboundSession {
     row: ChannelConnectionRow;
     features: Channel["features"];
     redact: (s: string) => string;
-    /** `idempotencyKey` 原样交给插件（见 `ChannelSendArgs.idempotencyKey`）。 */
-    send(target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+    /**
+     * `idempotencyKey` is passed through (see `ChannelSendArgs.idempotencyKey`); `locale` is the
+     * recipient's language for the extension's own wording and the card text fallback (default: the
+     * org's).
+     */
+    send(target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<{
         messageId: string;
     }>;
-    /** 只在 `features.edit` 为 true 时调用。 */
-    update(target: ChannelTarget, messageId: string, message: OutboundMessage, idempotencyKey?: string): Promise<void>;
+    /** Called only when `features.edit` is true; `locale` as for `send`. */
+    update(target: ChannelTarget, messageId: string, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<void>;
 }