openclaw-ringcentral 2026.1.29-beta1

package/src/openclaw.d.ts

@@ -0,0 +1,68 @@
+declare module "openclaw/plugin-sdk" {
+  import { z } from "zod";
+
+  // Types
+  export type OpenClawConfig = {
+    channels?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+
+  export type OpenClawPluginApi = {
+    runtime: PluginRuntime;
+    registerChannel(opts: { plugin: ChannelPlugin; dock: ChannelDock }): void;
+    [key: string]: unknown;
+  };
+
+  export type PluginRuntime = {
+    log: {
+      info(msg: string, ...args: unknown[]): void;
+      warn(msg: string, ...args: unknown[]): void;
+      error(msg: string, ...args: unknown[]): void;
+      debug(msg: string, ...args: unknown[]): void;
+    };
+    [key: string]: unknown;
+  };
+
+  export type ChannelPlugin = {
+    id: string;
+    [key: string]: unknown;
+  };
+
+  export type ChannelDock = {
+    id: string;
+    [key: string]: unknown;
+  };
+
+  export type DmPolicy = "open" | "allowlist" | "disabled";
+  export type GroupPolicy = "open" | "allowlist" | "disabled";
+  export type MarkdownConfig = {
+    enabled?: boolean;
+    [key: string]: unknown;
+  };
+
+  // Constants
+  export const DEFAULT_ACCOUNT_ID: string;
+
+  // Functions
+  export function normalizeAccountId(accountId: string | undefined): string;
+  export function emptyPluginConfigSchema(): z.ZodObject<Record<string, never>>;
+  export function resolveMentionGatingWithBypass(opts: unknown): unknown;
+  export function requireOpenAllowFrom(opts: unknown): void;
+  export function applyAccountNameToChannelSection(opts: unknown): unknown;
+  export function buildChannelConfigSchema(opts: unknown): unknown;
+  export function deleteAccountFromConfigSection(opts: unknown): unknown;
+  export function formatPairingApproveHint(opts: unknown): string;
+  export function migrateBaseNameToDefaultAccount(opts: unknown): unknown;
+  export function missingTargetError(opts: unknown): Error;
+  export function setAccountEnabledInConfigSection(opts: unknown): unknown;
+  export function resolveChannelMediaMaxBytes(opts: unknown): number;
+
+  // Constants for messages
+  export const PAIRING_APPROVED_MESSAGE: string;
+
+  // Zod Schemas
+  export const BlockStreamingCoalesceSchema: z.ZodType<unknown>;
+  export const DmPolicySchema: z.ZodType<DmPolicy>;
+  export const GroupPolicySchema: z.ZodType<GroupPolicy>;
+  export const MarkdownConfigSchema: z.ZodType<MarkdownConfig>;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setRingCentralRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getRingCentralRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("RingCentral runtime not initialized");
+  }
+  return runtime;
+}

package/src/targets.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeRingCentralTarget,
+  isRingCentralChatTarget,
+  isRingCentralUserTarget,
+  formatRingCentralChatTarget,
+  formatRingCentralUserTarget,
+  parseRingCentralTarget,
+} from "./targets.js";
+
+describe("normalizeRingCentralTarget", () => {
+  it("returns null for empty string", () => {
+    expect(normalizeRingCentralTarget("")).toBeNull();
+    expect(normalizeRingCentralTarget("  ")).toBeNull();
+  });
+
+  it("removes ringcentral: prefix", () => {
+    expect(normalizeRingCentralTarget("ringcentral:12345")).toBe("12345");
+    expect(normalizeRingCentralTarget("RINGCENTRAL:12345")).toBe("12345");
+  });
+
+  it("removes rc: prefix", () => {
+    expect(normalizeRingCentralTarget("rc:12345")).toBe("12345");
+    expect(normalizeRingCentralTarget("RC:12345")).toBe("12345");
+  });
+
+  it("removes chat: prefix", () => {
+    expect(normalizeRingCentralTarget("chat:12345")).toBe("12345");
+  });
+
+  it("removes user: prefix", () => {
+    expect(normalizeRingCentralTarget("user:12345")).toBe("12345");
+  });
+
+  it("removes combined prefixes", () => {
+    expect(normalizeRingCentralTarget("rc:chat:12345")).toBe("12345");
+    expect(normalizeRingCentralTarget("ringcentral:user:12345")).toBe("12345");
+  });
+
+  it("trims whitespace", () => {
+    expect(normalizeRingCentralTarget("  12345  ")).toBe("12345");
+  });
+
+  it("returns plain ID as-is", () => {
+    expect(normalizeRingCentralTarget("12345")).toBe("12345");
+  });
+});
+
+describe("isRingCentralChatTarget", () => {
+  it("returns true for numeric IDs", () => {
+    expect(isRingCentralChatTarget("12345")).toBe(true);
+    expect(isRingCentralChatTarget("rc:12345")).toBe(true);
+    expect(isRingCentralChatTarget("chat:12345")).toBe(true);
+  });
+
+  it("returns false for non-numeric IDs", () => {
+    expect(isRingCentralChatTarget("abc")).toBe(false);
+    expect(isRingCentralChatTarget("12345abc")).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isRingCentralChatTarget("")).toBe(false);
+  });
+});
+
+describe("isRingCentralUserTarget", () => {
+  it("returns true for numeric IDs", () => {
+    expect(isRingCentralUserTarget("12345")).toBe(true);
+    expect(isRingCentralUserTarget("rc:12345")).toBe(true);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isRingCentralUserTarget("")).toBe(false);
+  });
+});
+
+describe("formatRingCentralChatTarget", () => {
+  it("formats chat ID with rc:chat: prefix", () => {
+    expect(formatRingCentralChatTarget("12345")).toBe("rc:chat:12345");
+  });
+});
+
+describe("formatRingCentralUserTarget", () => {
+  it("formats user ID with rc:user: prefix", () => {
+    expect(formatRingCentralUserTarget("12345")).toBe("rc:user:12345");
+  });
+});
+
+describe("parseRingCentralTarget", () => {
+  it("parses chat: prefix", () => {
+    expect(parseRingCentralTarget("chat:12345")).toEqual({ type: "chat", id: "12345" });
+    expect(parseRingCentralTarget("rc:chat:12345")).toEqual({ type: "chat", id: "12345" });
+    expect(parseRingCentralTarget("ringcentral:chat:12345")).toEqual({ type: "chat", id: "12345" });
+  });
+
+  it("parses user: prefix", () => {
+    expect(parseRingCentralTarget("user:12345")).toEqual({ type: "user", id: "12345" });
+    expect(parseRingCentralTarget("rc:user:12345")).toEqual({ type: "user", id: "12345" });
+  });
+
+  it("parses group: prefix as chat", () => {
+    expect(parseRingCentralTarget("group:12345")).toEqual({ type: "chat", id: "12345" });
+    expect(parseRingCentralTarget("team:12345")).toEqual({ type: "chat", id: "12345" });
+  });
+
+  it("defaults numeric IDs to chat type", () => {
+    expect(parseRingCentralTarget("12345")).toEqual({ type: "chat", id: "12345" });
+    expect(parseRingCentralTarget("rc:12345")).toEqual({ type: "chat", id: "12345" });
+  });
+
+  it("returns unknown for non-numeric IDs without type prefix", () => {
+    expect(parseRingCentralTarget("abc")).toEqual({ type: "unknown", id: "abc" });
+  });
+
+  it("trims whitespace", () => {
+    expect(parseRingCentralTarget("  chat:12345  ")).toEqual({ type: "chat", id: "12345" });
+  });
+});

package/src/targets.ts

@@ -0,0 +1,70 @@
+// Target ID normalization and resolution for RingCentral
+
+export function normalizeRingCentralTarget(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  // Remove common prefixes
+  let normalized = trimmed
+    .replace(/^(ringcentral|rc):/i, "")
+    .replace(/^(chat|user|group|team):/i, "")
+    .trim();
+
+  if (!normalized) return null;
+  return normalized;
+}
+
+export function isRingCentralChatTarget(target: string): boolean {
+  const normalized = normalizeRingCentralTarget(target);
+  if (!normalized) return false;
+  // RingCentral chat IDs are typically numeric strings
+  return /^\d+$/.test(normalized);
+}
+
+export function isRingCentralUserTarget(target: string): boolean {
+  const normalized = normalizeRingCentralTarget(target);
+  if (!normalized) return false;
+  // User IDs can be numeric or prefixed
+  return /^\d+$/.test(normalized) || normalized.toLowerCase().startsWith("user:");
+}
+
+export function formatRingCentralChatTarget(chatId: string): string {
+  return `rc:chat:${chatId}`;
+}
+
+export function formatRingCentralUserTarget(userId: string): string {
+  return `rc:user:${userId}`;
+}
+
+export function parseRingCentralTarget(target: string): {
+  type: "chat" | "user" | "unknown";
+  id: string;
+} {
+  const trimmed = target.trim();
+  
+  // Check for explicit type prefixes
+  const chatMatch = trimmed.match(/^(?:ringcentral|rc)?:?chat:(.+)$/i);
+  if (chatMatch) {
+    return { type: "chat", id: chatMatch[1].trim() };
+  }
+
+  const userMatch = trimmed.match(/^(?:ringcentral|rc)?:?user:(.+)$/i);
+  if (userMatch) {
+    return { type: "user", id: userMatch[1].trim() };
+  }
+
+  const groupMatch = trimmed.match(/^(?:ringcentral|rc)?:?(?:group|team):(.+)$/i);
+  if (groupMatch) {
+    return { type: "chat", id: groupMatch[1].trim() };
+  }
+
+  // Remove any remaining prefix
+  const cleaned = trimmed.replace(/^(?:ringcentral|rc):/i, "").trim();
+  
+  // Default to chat for numeric IDs
+  if (/^\d+$/.test(cleaned)) {
+    return { type: "chat", id: cleaned };
+  }
+
+  return { type: "unknown", id: cleaned };
+}

package/src/types.ts

@@ -0,0 +1,174 @@
+import type { DmPolicy, GroupPolicy, MarkdownConfig } from "openclaw/plugin-sdk";
+
+// RingCentral Team Messaging API types
+
+export type RingCentralUser = {
+  id?: string;
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+};
+
+export type RingCentralChat = {
+  id?: string;
+  name?: string;
+  description?: string;
+  type?: "Everyone" | "Team" | "Group" | "Personal" | "Direct" | "PersonalChat";
+  status?: "Active" | "Archived";
+  members?: string[];
+  isPublic?: boolean;
+  creationTime?: string;
+  lastModifiedTime?: string;
+};
+
+export type RingCentralPost = {
+  id?: string;
+  groupId?: string;
+  type?: "TextMessage" | "PersonJoined" | "PersonsAdded";
+  text?: string;
+  creatorId?: string;
+  addedPersonIds?: string[];
+  creationTime?: string;
+  lastModifiedTime?: string;
+  attachments?: RingCentralAttachment[];
+  activity?: string;
+  title?: string;
+  iconUri?: string;
+  iconEmoji?: string;
+  mentions?: RingCentralMention[];
+};
+
+export type RingCentralAttachment = {
+  id?: string;
+  type?: string;
+  name?: string;
+  contentUri?: string;
+  contentType?: string;
+  size?: number;
+};
+
+export type RingCentralMention = {
+  id?: string;
+  type?: "Person" | "Team" | "File" | "Link" | "Event" | "Task" | "Note" | "Card";
+  name?: string;
+};
+
+// Adaptive Cards types (Microsoft Adaptive Card schema v1.3)
+export type RingCentralAdaptiveCardElement = {
+  type: string;
+  text?: string;
+  size?: "Small" | "Default" | "Medium" | "Large" | "ExtraLarge";
+  weight?: "Lighter" | "Default" | "Bolder";
+  color?: "Default" | "Dark" | "Light" | "Accent" | "Good" | "Warning" | "Attention";
+  wrap?: boolean;
+  url?: string;
+  altText?: string;
+  columns?: RingCentralAdaptiveCardElement[];
+  items?: RingCentralAdaptiveCardElement[];
+  width?: string | number;
+  style?: string;
+  isVisible?: boolean;
+  id?: string;
+  // Input elements
+  label?: string;
+  placeholder?: string;
+  value?: string;
+  isRequired?: boolean;
+  // Action elements
+  title?: string;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+export type RingCentralAdaptiveCardAction = {
+  type: "Action.Submit" | "Action.OpenUrl" | "Action.ShowCard" | "Action.ToggleVisibility";
+  title?: string;
+  url?: string;
+  data?: Record<string, unknown>;
+  card?: RingCentralAdaptiveCard;
+  targetElements?: Array<string | { elementId: string; isVisible?: boolean }>;
+};
+
+export type RingCentralAdaptiveCard = {
+  type?: "AdaptiveCard";
+  $schema?: string;
+  version?: string;
+  body?: RingCentralAdaptiveCardElement[];
+  actions?: RingCentralAdaptiveCardAction[];
+  fallbackText?: string;
+  speak?: string;
+  lang?: string;
+  verticalContentAlignment?: "Top" | "Center" | "Bottom";
+  backgroundImage?: string | { url: string; fillMode?: string };
+  minHeight?: string;
+};
+
+export type RingCentralWebhookEvent = {
+  uuid?: string;
+  event?: string;
+  timestamp?: string;
+  subscriptionId?: string;
+  ownerId?: string;
+  body?: RingCentralEventBody;
+};
+
+export type RingCentralEventBody = {
+  id?: string;
+  groupId?: string;
+  type?: string;
+  text?: string;
+  creatorId?: string;
+  eventType?: "PostAdded" | "PostChanged" | "PostRemoved" | "GroupJoined" | "GroupLeft" | "GroupChanged";
+  creationTime?: string;
+  lastModifiedTime?: string;
+  attachments?: RingCentralAttachment[];
+  mentions?: RingCentralMention[];
+  name?: string;
+  members?: string[];
+  status?: string;
+};
+
+// Config types
+
+export type RingCentralGroupConfig = {
+  requireMention?: boolean;
+  enabled?: boolean;
+  users?: Array<string | number>;
+  systemPrompt?: string;
+};
+
+export type RingCentralCredentials = {
+  clientId?: string;
+  clientSecret?: string;
+  jwt?: string;
+  server?: string;
+};
+
+export type RingCentralAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  credentials?: RingCentralCredentials;
+  markdown?: MarkdownConfig;
+  dmPolicy?: DmPolicy;
+  allowFrom?: Array<string | number>;
+  dm?: { policy?: DmPolicy; allowFrom?: Array<string | number>; enabled?: boolean };
+  groupPolicy?: GroupPolicy;
+  groups?: Record<string, RingCentralGroupConfig>;
+  groupAllowFrom?: Array<string | number>;
+  requireMention?: boolean;
+  mediaMaxMb?: number;
+  textChunkLimit?: number;
+  chunkMode?: "length" | "newline";
+  blockStreaming?: boolean;
+  blockStreamingCoalesce?: { minChars?: number; idleMs?: number };
+  allowBots?: boolean;
+  botExtensionId?: string;
+  replyToMode?: "off" | "all";
+  selfOnly?: boolean; // JWT mode: only accept messages from the JWT user in Personal chat (default: true)
+  useAdaptiveCards?: boolean; // Use Adaptive Cards for messages with code blocks (default: false)
+};
+
+export type RingCentralConfig = RingCentralAccountConfig & {
+  accounts?: Record<string, RingCentralAccountConfig>;
+  defaultAccount?: string;
+};