@canonmsg/backend-contracts 6.3.0 → 7.0.0

package/dist/cjs/communication.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCommunicationRule = readCommunicationRule;
+exports.parseDirectConversationSelection = parseDirectConversationSelection;
+/** Missing or invalid policy never widens access. */
+function readCommunicationRule(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'closed') {
+        return value;
+    }
+    // Existing owner-only records have the same outsider-facing meaning as
+    // closed; the agent owner bypass remains a separate server-side rule.
+    if (value === 'owner-only')
+        return 'closed';
+    return 'approval-required';
+}
+function parseDirectConversationSelection(value) {
+    if (value == null)
+        return { mode: 'latest_or_new' };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('selection must be an object');
+    }
+    const record = value;
+    if (record.mode === 'latest_or_new' || record.mode === 'new') {
+        return { mode: record.mode };
+    }
+    if (record.mode === 'specific') {
+        const conversationId = typeof record.conversationId === 'string'
+            ? record.conversationId.trim()
+            : '';
+        if (!conversationId)
+            throw new Error('selection.conversationId is required');
+        return { mode: 'specific', conversationId };
+    }
+    throw new Error('selection.mode is invalid');
+}

package/dist/cjs/index.js

@@ -29,6 +29,7 @@ __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);
 __exportStar(require("./accessPolicy.js"), exports);
+__exportStar(require("./communication.js"), exports);
 __exportStar(require("./apiErrors.js"), exports);
 __exportStar(require("./firestoreValues.js"), exports);
 __exportStar(require("./moderation.js"), exports);

package/dist/communication.d.ts

@@ -0,0 +1,91 @@
+/** The deliberately small policy vocabulary for principal communication. */
+export type CommunicationRule = 'open' | 'approval-required' | 'closed';
+/** Missing or invalid policy never widens access. */
+export declare function readCommunicationRule(value: unknown): CommunicationRule;
+/** Canon conversation selection is principal-neutral; a conversation is a runtime session boundary. */
+export type DirectConversationSelection = {
+    mode: 'latest_or_new';
+} | {
+    mode: 'new';
+} | {
+    mode: 'specific';
+    conversationId: string;
+};
+export type CommunicateInput = {
+    action: 'message_existing';
+    conversationId: string;
+    text: string;
+    messageId?: string;
+} | {
+    action: 'start_direct';
+    principalId: string;
+    text: string;
+    selection?: DirectConversationSelection;
+    messageId?: string;
+} | {
+    action: 'create_group';
+    name: string;
+    memberIds: string[];
+} | {
+    action: 'forward_message';
+    sourceConversationId: string;
+    targetConversationId: string;
+    messageId: string;
+    text?: string;
+};
+export type CommunicateResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+} | {
+    status: 'created';
+    conversationId: string;
+    added: string[];
+    pending: Array<{
+        userId: string;
+        requestId: string;
+        requirements: {
+            policyApproval: boolean;
+            ownerSessionSetup: boolean;
+        };
+    }>;
+    skipped: Array<{
+        userId: string;
+        reason: string;
+    }>;
+} | {
+    status: 'forwarded';
+    messageId: string;
+    targetConversationId: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+/** Principal-neutral app/SDK command. Humans may open a composer before sending. */
+export interface StartDirectInput {
+    targetUserId: string;
+    opener?: {
+        text: string;
+        messageId?: string;
+    } | null;
+    selection?: DirectConversationSelection;
+}
+export type StartDirectResult = {
+    status: 'opened' | 'messaged';
+    conversationId: string;
+    messageId?: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+export declare function parseDirectConversationSelection(value: unknown): DirectConversationSelection;

package/dist/communication.js

@@ -0,0 +1,31 @@
+/** Missing or invalid policy never widens access. */
+export function readCommunicationRule(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'closed') {
+        return value;
+    }
+    // Existing owner-only records have the same outsider-facing meaning as
+    // closed; the agent owner bypass remains a separate server-side rule.
+    if (value === 'owner-only')
+        return 'closed';
+    return 'approval-required';
+}
+export function parseDirectConversationSelection(value) {
+    if (value == null)
+        return { mode: 'latest_or_new' };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('selection must be an object');
+    }
+    const record = value;
+    if (record.mode === 'latest_or_new' || record.mode === 'new') {
+        return { mode: record.mode };
+    }
+    if (record.mode === 'specific') {
+        const conversationId = typeof record.conversationId === 'string'
+            ? record.conversationId.trim()
+            : '';
+        if (!conversationId)
+            throw new Error('selection.conversationId is required');
+        return { mode: 'specific', conversationId };
+    }
+    throw new Error('selection.mode is invalid');
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './communication.js';
 export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './communication.js';
 export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.10.2",
+    "@canonmsg/rich-cards": "^0.10.3",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",