@xfxstudio/claworld 0.1.0

package/src/product-shell/feedback/feedback-contract.js

@@ -0,0 +1,13 @@
+export const FEEDBACK_CATEGORY_VALUES = Object.freeze([
+  'experience_issue',
+  'usage_issue',
+  'bug_report',
+  'feature_request',
+]);
+
+export const FEEDBACK_IMPACT_VALUES = Object.freeze([
+  'low',
+  'medium',
+  'high',
+  'blocker',
+]);

package/src/product-shell/feedback/feedback-routes.js

@@ -0,0 +1,98 @@
+import { resolveAuthenticatedAgentId } from '../../lib/http-auth.js';
+
+function sendFeedbackError(res, error) {
+  const status = Number.isInteger(error?.status) ? error.status : 500;
+  if (error?.responseBody && typeof error.responseBody === 'object') {
+    return res.status(status).json(error.responseBody);
+  }
+  const code = typeof error?.code === 'string' ? error.code : 'internal_error';
+  return res.status(status).json({ error: code, message: error?.message || code });
+}
+
+export function registerFeedbackRoutes(app, { store, feedbackService }) {
+  function resolveAgentIdentity(req, res, { providedAgentId = null, fieldName = 'agentId', required = true } = {}) {
+    const result = resolveAuthenticatedAgentId({
+      store,
+      req,
+      providedAgentId,
+      fieldName,
+    });
+    if (!result.ok) {
+      res.status(result.status).json(result.body);
+      return null;
+    }
+    if (!result.agentId) {
+      if (!required) return null;
+      res.status(400).json({
+        error: 'invalid_agent',
+        field: fieldName,
+        message: `${fieldName} is required`,
+      });
+      return null;
+    }
+    return result.agentId;
+  }
+
+  app.post('/v1/feedback', async (req, res) => {
+    const reporterAgentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!reporterAgentId) return;
+
+    try {
+      const result = await feedbackService.submitFeedback({
+        reporterAgentId,
+        accountId: req.body?.accountId,
+        category: req.body?.category,
+        title: req.body?.title,
+        goal: req.body?.goal,
+        actualBehavior: req.body?.actualBehavior,
+        expectedBehavior: req.body?.expectedBehavior,
+        impact: req.body?.impact,
+        details: req.body?.details,
+        reproductionSteps: req.body?.reproductionSteps,
+        worldId: req.body?.worldId,
+        sessionId: req.body?.sessionId,
+        roundId: req.body?.roundId,
+        targetAgentId: req.body?.targetAgentId,
+        targetAgentCode: req.body?.targetAgentCode,
+        tags: req.body?.tags,
+        metadata: req.body?.metadata,
+        context: req.body?.context,
+        source: req.body?.source,
+        runtimeContext: req.body?.runtimeContext,
+      });
+      res.status(201).json(result);
+    } catch (error) {
+      sendFeedbackError(res, error);
+    }
+  });
+
+  app.get('/v1/moderation/feedback', (req, res) => {
+    try {
+      const result = feedbackService.listFeedback({
+        category: req.query.category,
+        impact: req.query.impact,
+        accountId: req.query.accountId,
+        reporterAgentId: req.query.reporterAgentId,
+        worldId: req.query.worldId,
+        sessionId: req.query.sessionId,
+        source: req.query.source,
+        page: req.query.page,
+        limit: req.query.limit,
+      });
+      res.json(result);
+    } catch (error) {
+      sendFeedbackError(res, error);
+    }
+  });
+
+  app.get('/v1/moderation/feedback/:feedbackId', (req, res) => {
+    try {
+      res.json(feedbackService.getFeedback(req.params.feedbackId));
+    } catch (error) {
+      sendFeedbackError(res, error);
+    }
+  });
+}

package/src/product-shell/feedback/feedback-service.js

@@ -0,0 +1,254 @@
+import {
+  FEEDBACK_CATEGORY_VALUES,
+  FEEDBACK_IMPACT_VALUES,
+} from './feedback-contract.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizePlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value;
+}
+
+function normalizeStringList(value = []) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((entry) => normalizeText(entry, null)).filter(Boolean))];
+}
+
+function normalizePaginationInteger(value, fallback) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.max(1, Math.floor(normalized));
+}
+
+function createConfigurationError() {
+  const error = new Error('feedback_store_unavailable');
+  error.code = 'feedback_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createFeedbackRequestError(fieldId, message) {
+  const error = new Error(`invalid_feedback_request:${fieldId}`);
+  error.code = 'invalid_feedback_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'feedback request is invalid',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createReporterNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  error.responseBody = {
+    error: error.code,
+    message: 'reporter agent was not found',
+    agentId,
+  };
+  return error;
+}
+
+function normalizeCategory(category) {
+  const normalized = normalizeText(category, null);
+  if (!normalized) {
+    throw createFeedbackRequestError('category', 'category is required');
+  }
+  if (!FEEDBACK_CATEGORY_VALUES.includes(normalized)) {
+    throw createFeedbackRequestError(
+      'category',
+      `category must be one of: ${FEEDBACK_CATEGORY_VALUES.join(', ')}`,
+    );
+  }
+  return normalized;
+}
+
+function normalizeImpact(impact) {
+  const normalized = normalizeText(impact, 'medium');
+  if (!FEEDBACK_IMPACT_VALUES.includes(normalized)) {
+    throw createFeedbackRequestError(
+      'impact',
+      `impact must be one of: ${FEEDBACK_IMPACT_VALUES.join(', ')}`,
+    );
+  }
+  return normalized;
+}
+
+function requireTextField(fieldId, value, message = `${fieldId} is required`) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) {
+    throw createFeedbackRequestError(fieldId, message);
+  }
+  return normalized;
+}
+
+function projectFeedback(feedback = {}) {
+  return {
+    feedbackId: feedback.feedbackId,
+    category: feedback.category,
+    title: feedback.title,
+    goal: feedback.goal,
+    actualBehavior: feedback.actualBehavior,
+    expectedBehavior: feedback.expectedBehavior,
+    impact: feedback.impact,
+    details: feedback.details || null,
+    reproductionSteps: Array.isArray(feedback.reproductionSteps) ? feedback.reproductionSteps : [],
+    source: feedback.source || 'openclaw_tool',
+    status: feedback.status || 'open',
+    accountId: feedback.accountId || null,
+    reporter: feedback.reporter && typeof feedback.reporter === 'object'
+      ? {
+          agentId: feedback.reporter.agentId || null,
+          agentCode: feedback.reporter.agentCode || null,
+          address: feedback.reporter.address || null,
+        }
+      : {
+          agentId: null,
+          agentCode: null,
+          address: null,
+        },
+    context: feedback.context && typeof feedback.context === 'object'
+      ? {
+          worldId: feedback.context.worldId || null,
+          sessionId: feedback.context.sessionId || null,
+          roundId: feedback.context.roundId || null,
+          targetAgentId: feedback.context.targetAgentId || null,
+          targetAgentCode: feedback.context.targetAgentCode || null,
+          tags: Array.isArray(feedback.context.tags) ? feedback.context.tags : [],
+          metadata: feedback.context.metadata && typeof feedback.context.metadata === 'object'
+            ? feedback.context.metadata
+            : {},
+        }
+      : {
+          worldId: null,
+          sessionId: null,
+          roundId: null,
+          targetAgentId: null,
+          targetAgentCode: null,
+          tags: [],
+          metadata: {},
+        },
+    runtimeContext: feedback.runtimeContext && typeof feedback.runtimeContext === 'object'
+      ? feedback.runtimeContext
+      : {},
+    createdAt: feedback.createdAt || null,
+    updatedAt: feedback.updatedAt || feedback.createdAt || null,
+  };
+}
+
+export function createFeedbackService({ store } = {}) {
+  if (!store || typeof store.createFeedbackReport !== 'function' || typeof store.listFeedbackReports !== 'function') {
+    throw createConfigurationError();
+  }
+
+  return {
+    async submitFeedback(input = {}) {
+      const reporterAgentId = requireTextField('agentId', input.reporterAgentId || input.agentId);
+      const reporter = store.getAgent?.(reporterAgentId);
+      if (!reporter) {
+        throw createReporterNotFoundError(reporterAgentId);
+      }
+
+      const context = normalizePlainObject(input.context);
+      const runtimeContext = normalizePlainObject(input.runtimeContext);
+      const feedback = await store.createFeedbackReport({
+        category: normalizeCategory(input.category),
+        title: requireTextField('title', input.title),
+        goal: requireTextField('goal', input.goal),
+        actualBehavior: requireTextField('actualBehavior', input.actualBehavior),
+        expectedBehavior: requireTextField('expectedBehavior', input.expectedBehavior),
+        impact: normalizeImpact(input.impact),
+        details: normalizeText(input.details, null),
+        reproductionSteps: normalizeStringList(input.reproductionSteps),
+        source: normalizeText(input.source, 'openclaw_tool'),
+        accountId: normalizeText(input.accountId, null),
+        reporter: {
+          agentId: reporter.agentId,
+          agentCode: reporter.agentCode,
+          address: reporter.address,
+        },
+        context: {
+          worldId: normalizeText(input.worldId, normalizeText(context.worldId, null)),
+          sessionId: normalizeText(input.sessionId, normalizeText(context.sessionId, null)),
+          roundId: normalizeText(input.roundId, normalizeText(context.roundId, null)),
+          targetAgentId: normalizeText(input.targetAgentId, normalizeText(context.targetAgentId, null)),
+          targetAgentCode: normalizeText(input.targetAgentCode, normalizeText(context.targetAgentCode, null)),
+          tags: normalizeStringList(input.tags || context.tags),
+          metadata: normalizePlainObject(input.metadata && Object.keys(input.metadata || {}).length > 0 ? input.metadata : context.metadata),
+        },
+        runtimeContext,
+      });
+
+      return {
+        status: 'recorded',
+        feedback: projectFeedback(feedback),
+      };
+    },
+
+    getFeedback(feedbackId) {
+      const feedback = store.getFeedbackReport(feedbackId);
+      if (!feedback) {
+        const error = new Error(`feedback_not_found:${feedbackId}`);
+        error.code = 'feedback_not_found';
+        error.status = 404;
+        error.responseBody = {
+          error: error.code,
+          message: 'feedback report was not found',
+          feedbackId,
+        };
+        throw error;
+      }
+
+      return projectFeedback(feedback);
+    },
+
+    listFeedback(filters = {}) {
+      const page = normalizePaginationInteger(filters.page, 1);
+      const limit = Math.min(normalizePaginationInteger(filters.limit, 50), 200);
+      const result = store.listFeedbackReports({
+        category: normalizeText(filters.category, null),
+        impact: normalizeText(filters.impact, null),
+        accountId: normalizeText(filters.accountId, null),
+        reporterAgentId: normalizeText(filters.reporterAgentId, null),
+        worldId: normalizeText(filters.worldId, null),
+        sessionId: normalizeText(filters.sessionId, null),
+        source: normalizeText(filters.source, null),
+        page,
+        limit,
+      });
+
+      return {
+        items: Array.isArray(result.items) ? result.items.map((item) => projectFeedback(item)) : [],
+        pagination: result.pagination && typeof result.pagination === 'object'
+          ? result.pagination
+          : {
+              page,
+              totalPages: 0,
+              totalCount: 0,
+              limit,
+            },
+        filters: {
+          category: normalizeText(filters.category, null),
+          impact: normalizeText(filters.impact, null),
+          accountId: normalizeText(filters.accountId, null),
+          reporterAgentId: normalizeText(filters.reporterAgentId, null),
+          worldId: normalizeText(filters.worldId, null),
+          sessionId: normalizeText(filters.sessionId, null),
+          source: normalizeText(filters.source, null),
+        },
+      };
+    },
+  };
+}

package/src/product-shell/index.js

@@ -0,0 +1,163 @@
+import { createWorldService } from './worlds/world-service.js';
+import { registerWorldRoutes } from './worlds/world-routes.js';
+import { createWorldAdminService } from './worlds/world-admin-service.js';
+import { createWorldAuthorizationService } from './worlds/world-authorization.js';
+import { createWorldBroadcastService } from './worlds/world-broadcast-service.js';
+import { DEFAULT_WORLD_MANIFESTS } from './catalog/default-world-catalog.js';
+import { createOnboardingService } from './onboarding/onboarding-service.js';
+import { registerOnboardingRoutes } from './onboarding/onboarding-routes.js';
+import { createMembershipService } from './membership/membership-service.js';
+import { createMatchmakingService } from './matching/matchmaking-service.js';
+import { createWorldSearchService } from './search/search-service.js';
+import { createResultService } from './results/result-service.js';
+import { createSessionOrchestrator } from './orchestration/session-orchestrator.js';
+import { createSocialService } from './social/social-service.js';
+import { registerSocialRoutes } from './social/social-routes.js';
+import { createFriendService } from './social/friend-service.js';
+import { registerFriendRoutes } from './social/friend-routes.js';
+import { createChatRequestService } from './social/chat-request-service.js';
+import { registerChatRequestRoutes } from './social/chat-request-routes.js';
+import { createFeedbackService } from './feedback/feedback-service.js';
+import { registerFeedbackRoutes } from './feedback/feedback-routes.js';
+
+export function createClaworldProductShell({
+  worldCatalog = DEFAULT_WORLD_MANIFESTS,
+  relay = null,
+  store = null,
+  presence = null,
+} = {}) {
+  const worldService = createWorldService({ worldCatalog, store });
+  const onboardingService = createOnboardingService({ worldService, store });
+  const membershipService = createMembershipService({ worldService, store });
+  const worldAuthorizationService = createWorldAuthorizationService({
+    worldService,
+    membershipService,
+  });
+  const matchmakingService = createMatchmakingService({ worldService, worldAuthorizationService, store });
+  const searchService = createWorldSearchService({ worldService, worldAuthorizationService, store, presence });
+  const worldAdminService = createWorldAdminService({ worldService, worldAuthorizationService, store });
+  const chatRequestService = createChatRequestService({
+    store,
+    relay,
+    presence,
+    worldService,
+    worldAuthorizationService,
+  });
+  const worldBroadcastService = createWorldBroadcastService({
+    worldService,
+    worldAuthorizationService,
+    membershipService,
+    chatRequestService,
+    store,
+  });
+  const resultService = createResultService();
+  const friendService = createFriendService({ store, policy: relay?.policy });
+  const socialLookupService = createSocialService({ worldService, store });
+  const feedbackService = createFeedbackService({ store });
+  const socialService = {
+    ...friendService,
+    lookupAgentByCode(input) {
+      return socialLookupService.lookupAgentByCode(input);
+    },
+  };
+  const sessionOrchestrator = createSessionOrchestrator({
+    worldService,
+    resultService,
+  });
+
+  const productShell = {
+    contexts: {
+      onboarding: onboardingService,
+      worlds: worldService,
+      worldAuthorization: worldAuthorizationService,
+      membership: membershipService,
+      matchmaking: matchmakingService,
+      search: searchService,
+      broadcast: worldBroadcastService,
+      social: socialService,
+      chatRequests: chatRequestService,
+      moderation: worldAdminService,
+      feedback: feedbackService,
+      results: resultService,
+      orchestration: sessionOrchestrator,
+    },
+    registerRoutes(app) {
+      registerOnboardingRoutes(app, { onboardingService, store });
+      registerFriendRoutes(app, { friendService });
+      registerChatRequestRoutes(app, { chatRequestService, store });
+      registerWorldRoutes(app, {
+        productShell,
+        store,
+        worldService,
+        membershipService,
+        matchmakingService,
+        searchService,
+        worldBroadcastService,
+        worldAdminService,
+        sessionOrchestrator,
+      });
+      registerSocialRoutes(app, { socialService: socialLookupService });
+      registerFeedbackRoutes(app, { store, feedbackService });
+    },
+    describe() {
+      return {
+        product: 'claworld',
+        compatibleWith: ['relay_backend', 'openclaw_channel_plugin'],
+        boundedContexts: [
+          'onboarding',
+          'worlds',
+          'membership',
+          'matchmaking',
+          'search',
+          'broadcast',
+          'social',
+          'chatRequests',
+          'moderation',
+          'feedback',
+          'orchestration',
+          'results',
+        ],
+        routes: [
+          'GET /v1/meta/product-shell',
+          'GET /v1/meta/install',
+          'GET /v1/onboarding/plan',
+          'POST /v1/onboarding/activate',
+          'POST /v1/friend-requests',
+          'GET /v1/friend-requests',
+          'POST /v1/friend-requests/:friendRequestId/accept',
+          'POST /v1/friend-requests/:friendRequestId/reject',
+          'GET /v1/friends',
+          'DELETE /v1/friends/:peerAgentId',
+          'POST /v1/chat-requests',
+          'GET /v1/chat-requests',
+          'PUT /v1/chat-requests/approval-policy',
+          'POST /v1/chat-requests/:chatRequestId/accept',
+          'GET /v1/worlds',
+          'GET /v1/worlds/:worldId',
+          'POST /v1/worlds',
+          'POST /v1/worlds/:worldId/search',
+          'POST /v1/worlds/:worldId/broadcast',
+          'GET /v1/worlds/:worldId/candidates',
+          'POST /v1/worlds/:worldId/join-check',
+          'POST /v1/worlds/:worldId/join',
+          'GET /v1/worlds/:worldId/memberships',
+          'POST /v1/worlds/:worldId/memberships',
+          'POST /v1/worlds/:worldId/session-preview',
+          'GET /v1/social/agents/lookup',
+          'POST /v1/feedback',
+          'GET /v1/moderation/worlds',
+          'GET /v1/moderation/worlds/:worldId',
+          'PATCH /v1/moderation/worlds/:worldId',
+          'GET /v1/moderation/feedback',
+          'GET /v1/moderation/feedback/:feedbackId',
+        ],
+        worldCatalog: worldService.describeCatalog(),
+        status: 'scaffold_ready',
+      };
+    },
+  };
+
+  return productShell;
+}
+
+export { DEFAULT_WORLD_MANIFESTS } from './catalog/default-world-catalog.js';