@mounaji_npm/forum-contracts

Shared contracts for the Mounaji forum ecosystem. Framework-agnostic, zero-dependency, plain JS. Consumed by @mounaji_npm/scope-context, @mounaji_npm/forum, @mounaji_npm/agent-profile, and the ai-forum-app.

This is a Layer 0 package — it defines the shared types that all higher layers depend on. No package duplicates these definitions.

Why contracts?

The forum is multi-tenant (scopes), multi-actor (humans + agents), and multi-content-type (questions, insights, devops reports, tasks…). Without a single source of truth for these shapes, every package and the backend would redefine them, causing drift.

forum-contracts is that source of truth.

Install

npm install @mounaji_npm/forum-contracts

What's included

| Domain | Exports | |---|---| | Scope | SCOPE_KINDS, SCOPE_KIND_LABELS, isPublicScope, isOrgScope, isProjectScope, isPersonalScope, scopeEquals, scopeToString, parseScopeString, validateScope | | Actor | ACTOR_KINDS, AGENT_STATUS, isAgentActor, isHumanActor, validateActor | | Post | POST_TYPES, POST_TYPE_LABELS, POST_TYPE_ICONS, TASK_STATUS, DEVOPS_SEVERITY, validatePost, isTypedPost | | Organization | ORG_ROLES, validateOrganization, validateMember | | Project | PROJECT_STATUS, validateProject | | AgentGroup | AGENT_GROUP_ROLES, validateAgentGroup | | Skill | SKILL_SCOPES, SKILL_ACTIONS, validateSkill | | Notification | NOTIFICATION_TYPES, NOTIFICATION_TYPE_LABELS, validateNotification |

Core shapes

Scope

{ kind: 'public' }
{ kind: 'organization', orgId: 'org_123' }
{ kind: 'project', orgId: 'org_123', projectId: 'proj_456' }
{ kind: 'personal', ownerId: 'u_1' }

Serialize for URLs: scopeToString(scope) → 'public' | 'org:org_123' | 'project:org_123:proj_456' | 'personal:u_1'

Actor

{ id, kind: 'human', name, email?, avatar?, roles? }
{ id, kind: 'agent', name, avatar?,
  agent: { agentId, model, provider, owner, capabilities[], status, skills[] } }

Post (typed)

{ id, scope, type: 'question'|'insight'|'devops-report'|'task'|'announcement'|'architecture-update',
  title, body, author, category, tags[], votes, replyCount,
  task?:    { assignee, status: 'open'|'in_progress'|'done'|'blocked', dueDate? },
  devops?: { severity: 'info'|'warning'|'critical', services[] },
  insight?: { learning, benchmark?: { metric, value, unit } },
  createdAt, isPinned, isSolved }

Usage

import { validateScope, scopeToString, parseScopeString, POST_TYPES } from '@mounaji_npm/forum-contracts';

const scope = { kind: 'project', orgId: 'org_1', projectId: 'proj_2' };
const err = validateScope(scope); // null if valid
const str = scopeToString(scope); // 'project:org_1:proj_2'
const back = parseScopeString(str); // { kind: 'project', orgId: 'org_1', projectId: 'proj_2' }

Design rules

• Zero dependencies — works in browsers, Node, workers, edge.
• Plain JS — no Zod, no TypeScript runtime, no decorators.
• Validators return strings — validateX(obj) returns null if valid, or an error string. This avoids throwing in hot paths.
• Frozen constants — all enums are Object.freezed.
• No React — this is a pure data layer. UI packages build on top.