@xfxstudio/claworld 0.2.25 → 2026.4.14-testing.2

package/src/openclaw/runtime/world-moderation-helper.js

@@ -69,6 +69,29 @@ function normalizeWorldRole(worldRole, fallback = null) {
   return ['owner', 'member'].includes(normalized) ? normalized : fallback;
 }
 
+function normalizeBroadcastAudience(value, fallback = 'members') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'admins') return 'admins';
+  if (normalized === 'admins_and_owner') return 'admins_and_owner';
+  return 'members';
+}
+
+function normalizeBroadcastReplyPolicy(value, fallback = 'zero') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'at_most_one') return 'at_most_one';
+  return 'zero';
+}
+
+function normalizeWorldBroadcastConfig(broadcast = null) {
+  if (!broadcast || typeof broadcast !== 'object' || Array.isArray(broadcast)) return null;
+  return {
+    enabled: normalizeOptionalBoolean(broadcast.enabled, null),
+    audience: normalizeBroadcastAudience(broadcast.audience, 'members'),
+    replyPolicy: normalizeBroadcastReplyPolicy(broadcast.replyPolicy, 'zero'),
+    excludeSelf: normalizeOptionalBoolean(broadcast.excludeSelf, null),
+  };
+}
+
 function normalizeManagedWorld(payload = {}) {
   return {
     worldId: normalizeText(payload.worldId, null),
@@ -82,6 +105,7 @@ function normalizeManagedWorld(payload = {}) {
     createdAt: normalizeText(payload.createdAt, null),
     updatedAt: normalizeText(payload.updatedAt, null),
     participantContextField: normalizeParticipantContextFieldPayload(payload.participantContextField),
+    broadcast: normalizeWorldBroadcastConfig(payload.broadcast),
     stats: normalizeWorldStats(payload.stats),
   };
 }
@@ -111,10 +135,62 @@ function normalizeOwnedWorldSummary(payload = {}) {
     worldRole: normalizeWorldRole(payload.worldRole, null),
     createdAt: normalizeText(payload.createdAt, null),
     updatedAt: normalizeText(payload.updatedAt, null),
+    broadcast: normalizeWorldBroadcastConfig(payload.broadcast),
     stats: normalizeWorldStats(payload.stats),
   };
 }
 
+function normalizeWorldBroadcastRequestItem(item = {}) {
+  return {
+    agentId: normalizeText(item.agentId, null),
+    status: normalizeText(item.status, null),
+    verdict: normalizeText(item.verdict, null),
+    chatRequest: item.chatRequest && typeof item.chatRequest === 'object' && !Array.isArray(item.chatRequest)
+      ? item.chatRequest
+      : null,
+    kickoff: item.kickoff && typeof item.kickoff === 'object' && !Array.isArray(item.kickoff)
+      ? item.kickoff
+      : null,
+  };
+}
+
+function normalizeWorldBroadcastFailureItem(item = {}) {
+  return {
+    agentId: normalizeText(item.agentId, null),
+    status: normalizeText(item.status, 'failed'),
+    httpStatus: normalizeOptionalInteger(item.httpStatus, null),
+    error: normalizeText(item.error, null),
+    reason: normalizeText(item.reason, null),
+    message: normalizeText(item.message, null),
+  };
+}
+
+function normalizeWorldBroadcastResponse(payload = {}) {
+  return {
+    status: normalizeText(payload.status, null),
+    worldId: normalizeText(payload.worldId, null),
+    senderAgentId: normalizeText(payload.senderAgentId, null),
+    senderRole: normalizeWorldRole(payload.senderRole, null),
+    audience: normalizeBroadcastAudience(payload.audience, 'members'),
+    excludeSelf: normalizeOptionalBoolean(payload.excludeSelf, null),
+    eligibility: normalizeText(payload.eligibility, null),
+    broadcastId: normalizeText(payload.broadcastId, null),
+    totalTargets: normalizeOptionalInteger(payload.totalTargets, null),
+    createdCount: normalizeOptionalInteger(payload.createdCount, null),
+    failedCount: normalizeOptionalInteger(payload.failedCount, null),
+    pendingCount: normalizeOptionalInteger(payload.pendingCount, null),
+    autoAcceptedCount: normalizeOptionalInteger(payload.autoAcceptedCount, null),
+    rejectedCount: normalizeOptionalInteger(payload.rejectedCount, null),
+    nextAction: normalizeText(payload.nextAction, null),
+    requests: Array.isArray(payload.requests)
+      ? payload.requests.map((item) => normalizeWorldBroadcastRequestItem(item))
+      : [],
+    failures: Array.isArray(payload.failures)
+      ? payload.failures.map((item) => normalizeWorldBroadcastFailureItem(item))
+      : [],
+  };
+}
+
 async function fetchJson(fetchImpl, url, init = {}) {
   let response;
   try {
@@ -366,3 +442,67 @@ export async function manageModeratedWorld({
 
   return normalizeManagedWorld(result.body);
 }
+
+export async function broadcastModeratedWorld({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  worldId = null,
+  announcementText = null,
+  audience = null,
+  excludeSelf = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world broadcast helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world broadcast helper requires agentId');
+  }
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld world broadcast helper requires worldId');
+  }
+  const resolvedAnnouncementText = normalizeText(announcementText, null);
+  if (!resolvedAnnouncementText) {
+    throw new Error('claworld world broadcast helper requires announcementText');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/broadcast`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      payload: {
+        text: resolvedAnnouncementText,
+      },
+      ...(normalizeText(audience, null) ? { audience: normalizeText(audience, null) } : {}),
+      ...(typeof excludeSelf === 'boolean' ? { excludeSelf } : {}),
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:moderation] world broadcast failed', {
+      status: result.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createModerationHttpError('broadcast', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeWorldBroadcastResponse(result.body);
+}