liuyu/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 05:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document discord sdk facade contracts

Browse Source
This commit is contained in:
Peter Steinberger
2026-06-04 22:42:23 -04:00
parent 82710b4f1f
commit 5613a0fb6e
1 changed files with 29 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
src/plugin-sdk/discord.ts
View File

@@ -43,8 +43,10 @@ export {
} from "./channel-status.js";
export { DiscordConfigSchema } from "./bundled-channel-config-schema.js";
/** Discord channel config shape for one account in OpenClaw config. */
export type DiscordAccountConfig = NonNullable<NonNullable<OpenClawConfig["channels"]>["discord"]>;
/** Component-message request accepted by the deprecated Discord SDK facade. */
export type DiscordComponentMessageSpec = {
text?: string;
reusable?: boolean;
@@ -56,12 +58,14 @@ export type DiscordComponentMessageSpec = {
modal?: unknown;
};
/** Built Discord component payload plus registration metadata. */
export type DiscordComponentBuildResult = {
components: unknown[];
entries: unknown[];
modals: unknown[];
};
/** Send/edit options for Discord component messages. */
export type DiscordComponentSendOpts = {
cfg?: OpenClawConfig;
accountId?: string;
@@ -76,12 +80,14 @@ export type DiscordComponentSendOpts = {
[key: string]: unknown;
};
/** Minimal Discord API message result returned by component send/edit helpers. */
export type DiscordComponentSendResult = {
id?: string;
channel_id?: string;
[key: string]: unknown;
};
/** Resolved Discord account with token source metadata for status and runtime checks. */
export type ResolvedDiscordAccount = {
accountId: string;
enabled: boolean;
@@ -91,12 +97,15 @@ export type ResolvedDiscordAccount = {
config: DiscordAccountConfig;
};
/** Normalized outbound target result for Discord channel ids and DM targets. */
export type DiscordOutboundTargetResolution =
| { ok: true; to: string }
| { ok: false; error: Error };
/** Supported thread binding owners for Discord session routing. */
export type ThreadBindingTargetKind = "subagent" | "acp";
/** Persisted Discord thread-to-session binding record. */
export type ThreadBindingRecord = {
accountId: string;
threadId: string;
@@ -206,22 +215,26 @@ function resolveCompatRuntimeConfig(params: { cfg?: OpenClawConfig }): OpenClawC
return params.cfg ?? getRuntimeConfigSnapshot() ?? getRuntimeConfig();
}
/** Lazy Discord setup adapter retained for deprecated subpath compatibility. */
export const discordOnboardingAdapter = createLazyFacadeObjectValue(
() => loadDiscordApiFacadeModule().discordOnboardingAdapter ?? {},
);
/** Collect Discord account status issues from account snapshots. */
export function collectDiscordStatusIssues(
accounts: ChannelAccountSnapshot[],
): ChannelStatusIssue[] {
return loadDiscordApiFacadeModule().collectDiscordStatusIssues(accounts);
}
/** Build Discord component payloads without sending them. */
export const buildDiscordComponentMessage: DiscordApiFacadeModule["buildDiscordComponentMessage"] =
((...args) =>
loadDiscordApiFacadeModule().buildDiscordComponentMessage(
...args,
)) as DiscordApiFacadeModule["buildDiscordComponentMessage"];
/** Inspect one configured Discord account for setup/status output. */
export function inspectDiscordAccount(params: {
cfg: OpenClawConfig;
accountId?: string | null;
@@ -229,38 +242,46 @@ export function inspectDiscordAccount(params: {
return loadDiscordApiFacadeModule().inspectDiscordAccount(params);
}
/** List configured Discord account ids from OpenClaw config. */
export function listDiscordAccountIds(cfg: OpenClawConfig): string[] {
return loadDiscordApiFacadeModule().listDiscordAccountIds(cfg);
}
/** List Discord directory group records from static config. */
export function listDiscordDirectoryGroupsFromConfig(
params: DirectoryConfigParams,
): unknown[] | Promise<unknown[]> {
return loadDiscordApiFacadeModule().listDiscordDirectoryGroupsFromConfig(params);
}
/** List Discord directory peer records from static config. */
export function listDiscordDirectoryPeersFromConfig(
params: DirectoryConfigParams,
): unknown[] | Promise<unknown[]> {
return loadDiscordApiFacadeModule().listDiscordDirectoryPeersFromConfig(params);
}
/** Check whether a raw value has Discord target-id shape. */
export function looksLikeDiscordTargetId(raw: string): boolean {
return loadDiscordApiFacadeModule().looksLikeDiscordTargetId(raw);
}
/** Normalize a Discord messaging target for send helpers. */
export function normalizeDiscordMessagingTarget(raw: string): string | undefined {
return loadDiscordApiFacadeModule().normalizeDiscordMessagingTarget(raw);
}
/** Normalize a Discord outbound target and return a typed error on failure. */
export function normalizeDiscordOutboundTarget(to?: string): DiscordOutboundTargetResolution {
return loadDiscordApiFacadeModule().normalizeDiscordOutboundTarget(to);
}
/** Resolve the default Discord account id from config. */
export function resolveDefaultDiscordAccountId(cfg: OpenClawConfig): string {
return loadDiscordApiFacadeModule().resolveDefaultDiscordAccountId(cfg);
}
/** Resolve a Discord account config plus token source for runtime use. */
export function resolveDiscordAccount(params: {
cfg: OpenClawConfig;
accountId?: string | null;
@@ -268,16 +289,19 @@ export function resolveDiscordAccount(params: {
return loadDiscordApiFacadeModule().resolveDiscordAccount(params);
}
/** Resolve group mention policy for a Discord channel context. */
export function resolveDiscordGroupRequireMention(
params: ChannelGroupContext,
): boolean | undefined {
return loadDiscordApiFacadeModule().resolveDiscordGroupRequireMention(params);
}
/** Resolve group tool policy for a Discord channel context. */
export function resolveDiscordGroupToolPolicy(params: ChannelGroupContext): unknown {
return loadDiscordApiFacadeModule().resolveDiscordGroupToolPolicy(params);
}
/** Collect configured Discord audit channel ids for runtime status checks. */
export function collectDiscordAuditChannelIds(params: {
cfg: OpenClawConfig;
accountId?: string | null;
@@ -285,18 +309,21 @@ export function collectDiscordAuditChannelIds(params: {
return loadDiscordRuntimeFacadeModule().collectDiscordAuditChannelIds(params);
}
/** Edit an already-sent Discord component message. */
export const editDiscordComponentMessage: DiscordRuntimeFacadeModule["editDiscordComponentMessage"] =
((...args) =>
loadDiscordRuntimeFacadeModule().editDiscordComponentMessage(
...args,
)) as DiscordRuntimeFacadeModule["editDiscordComponentMessage"];
/** Register a built component message after Discord assigns its message id. */
export const registerBuiltDiscordComponentMessage: DiscordRuntimeFacadeModule["registerBuiltDiscordComponentMessage"] =
((...args) =>
loadDiscordRuntimeFacadeModule().registerBuiltDiscordComponentMessage(
...args,
)) as DiscordRuntimeFacadeModule["registerBuiltDiscordComponentMessage"];
/** Bind a spawned subagent session to the current Discord thread when possible. */
export async function autoBindSpawnedDiscordSubagent(params: {
cfg?: OpenClawConfig;
accountId?: string;
@@ -314,6 +341,7 @@ export async function autoBindSpawnedDiscordSubagent(params: {
});
}
/** List Discord thread bindings for a target session key. */
export function listThreadBindingsBySessionKey(params: {
targetSessionKey: string;
accountId?: string;
@@ -322,6 +350,7 @@ export function listThreadBindingsBySessionKey(params: {
return loadDiscordRuntimeFacadeModule().listThreadBindingsBySessionKey(params);
}
/** Remove Discord thread bindings for a target session key. */
export function unbindThreadBindingsBySessionKey(params: {
targetSessionKey: string;
accountId?: string;