@canonmsg/backend-contracts 0.2.4 → 1.1.0

package/dist/cjs/contactRequest.js

@@ -33,6 +33,19 @@ function serializeContactRequest(requestId, data) {
     if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
         return null;
     }
+    if (typeof data.targetName !== 'string' || data.targetName.trim().length === 0) {
+        return null;
+    }
+    if (data.targetAvatarUrl !== null && data.targetAvatarUrl !== undefined && typeof data.targetAvatarUrl !== 'string') {
+        return null;
+    }
+    if (data.targetUserType !== 'human' && data.targetUserType !== 'ai_agent') {
+        return null;
+    }
+    if (data.targetUserType === 'ai_agent'
+        && (typeof data.targetOwnerId !== 'string' || data.targetOwnerId.length === 0)) {
+        return null;
+    }
     const kindValue = typeof data.kind === 'string' ? data.kind : null;
     if (kindValue !== 'dm' && kindValue !== 'group_invite') {
         return null;
@@ -57,11 +70,9 @@ function serializeContactRequest(requestId, data) {
         requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
         requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
         targetId: data.targetId,
-        targetName: typeof data.targetName === 'string' ? data.targetName : null,
+        targetName: data.targetName.trim(),
         targetAvatarUrl: typeof data.targetAvatarUrl === 'string' ? data.targetAvatarUrl : null,
-        targetUserType: data.targetUserType === 'human' || data.targetUserType === 'ai_agent'
-            ? data.targetUserType
-            : null,
+        targetUserType: data.targetUserType,
         approverId: data.approverId,
         message: typeof data.message === 'string' ? data.message : null,
         status: normalizeStatus(data.status),
@@ -73,7 +84,7 @@ function serializeContactRequest(requestId, data) {
     if (groupContext) {
         payload.groupContext = groupContext;
     }
-    if (typeof data.targetOwnerId === 'string' && data.targetOwnerId.length > 0) {
+    if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }
     return payload;

package/dist/cjs/message.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serializeStoredMessage = serializeStoredMessage;
 const media_js_1 = require("./media.js");
-const MISSING_CREATED_AT_ISO = new Date(0).toISOString();
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -21,14 +20,17 @@ function normalizeTimestamp(value) {
     }
     return null;
 }
-function normalizeCreatedAt(value, fallback) {
-    const timestamp = normalizeTimestamp(value) ?? normalizeTimestamp(fallback);
-    return timestamp ? timestamp.toISOString() : MISSING_CREATED_AT_ISO;
+function requireCreatedAt(value) {
+    const timestamp = normalizeTimestamp(value);
+    if (!timestamp) {
+        throw new Error('Message is missing canonical createdAt');
+    }
+    return timestamp.toISOString();
 }
-function normalizeSenderType(value, fallback) {
-    if (value === 'ai_agent' || fallback === 'ai_agent')
-        return 'ai_agent';
-    return 'human';
+function requireSenderType(value) {
+    if (value === 'human' || value === 'ai_agent')
+        return value;
+    throw new Error('Message is missing canonical senderType');
 }
 function normalizeAgentClientType(value) {
     if (value === 'claude-code'
@@ -40,7 +42,7 @@ function normalizeAgentClientType(value) {
     }
     return undefined;
 }
-function normalizeContentType(value, attachments) {
+function normalizeContentType(value) {
     if (value === 'text'
         || value === 'image'
         || value === 'audio'
@@ -48,10 +50,7 @@ function normalizeContentType(value, attachments) {
         || value === 'contact_card') {
         return value;
     }
-    const primary = attachments[0]?.kind;
-    if (primary === 'image' || primary === 'audio' || primary === 'file')
-        return primary;
-    return 'text';
+    throw new Error('Message is missing canonical contentType');
 }
 function normalizeForwardedFrom(value) {
     if (!isRecord(value))
@@ -96,22 +95,25 @@ function normalizeContactCard(value) {
 }
 function serializeStoredMessage(input) {
     const { data } = input;
-    const attachments = (0, media_js_1.getMessageAttachments)({
-        attachments: data.attachments,
-    });
+    const attachments = data.attachments === undefined
+        ? []
+        : (0, media_js_1.normalizeStoredAttachments)(data.attachments);
+    if (!attachments) {
+        throw new Error('Message has malformed attachments');
+    }
     const result = {
         id: input.id,
         senderId: typeof data.senderId === 'string' ? data.senderId : '',
-        senderType: normalizeSenderType(data.senderType, input.senderTypeFallback),
+        senderType: requireSenderType(data.senderType),
         isOwner: input.isOwner,
-        contentType: normalizeContentType(data.contentType, attachments),
+        contentType: normalizeContentType(data.contentType),
         text: typeof data.text === 'string' ? data.text : null,
         attachments,
         mentions: normalizeStringArray(data.mentions),
         replyTo: typeof data.replyTo === 'string' ? data.replyTo : null,
         replyToPosition: typeof data.replyToPosition === 'number' ? data.replyToPosition : null,
         status: data.status === 'read' ? 'read' : 'sent',
-        createdAt: normalizeCreatedAt(data.createdAt, input.createdAtFallback),
+        createdAt: requireCreatedAt(data.createdAt),
     };
     const forwardedFrom = normalizeForwardedFrom(data.forwardedFrom);
     if (data.forwarded === true || forwardedFrom) {
@@ -130,5 +132,8 @@ function serializeStoredMessage(input) {
     if (contactCard) {
         result.contactCard = contactCard;
     }
+    if (isRecord(data.runtimeCard)) {
+        result.runtimeCard = data.runtimeCard;
+    }
     return result;
 }

package/dist/cjs/turnProtocol.js

@@ -22,7 +22,9 @@ function isHiddenRuntimeCardMetadata(metadata) {
         || metadata.type === 'question_reply'
         || metadata.type === 'plan_approval_reply'
         || metadata.type === 'runtime_input_reply'
-        || metadata.type === 'runtime_input_outcome';
+        || metadata.type === 'runtime_input_outcome'
+        || metadata.type === 'runtime_card_reply'
+        || metadata.type === 'runtime_card_outcome';
 }
 function normalizeTurnMetadata(metadata) {
     if (!isRecord(metadata))
@@ -36,12 +38,11 @@ function normalizeTurnMetadata(metadata) {
         || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && typeof metadata.turnComplete !== 'boolean' && !replyBehavior) {
+    if (!turnSemantics && !replyBehavior) {
         return null;
     }
     return {
         ...(turnSemantics ? { turnSemantics } : {}),
-        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
     };
 }
@@ -80,11 +81,9 @@ function resolveTurnMessageSemantics(input) {
     const turnMetadata = normalizeTurnMetadata(input.metadata);
     if (turnMetadata?.turnSemantics)
         return turnMetadata.turnSemantics;
-    if (turnMetadata?.turnComplete === true)
-        return 'turn_complete';
     if (input.senderType === 'human')
         return 'turn_complete';
-    return isTurnOpen(input.senderTurnState) ? 'progress' : 'turn_complete';
+    return 'progress';
 }
 function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {

package/dist/contactRequest.d.ts

@@ -5,9 +5,9 @@ export interface SerializedContactRequest {
     requesterName: string;
     requesterAvatarUrl: string | null;
     targetId: string;
-    targetName: string | null;
+    targetName: string;
     targetAvatarUrl: string | null;
-    targetUserType: 'human' | 'ai_agent' | null;
+    targetUserType: 'human' | 'ai_agent';
     targetOwnerId?: string | null;
     approverId: string;
     message: string | null;

package/dist/contactRequest.js

@@ -30,6 +30,19 @@ export function serializeContactRequest(requestId, data) {
     if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
         return null;
     }
+    if (typeof data.targetName !== 'string' || data.targetName.trim().length === 0) {
+        return null;
+    }
+    if (data.targetAvatarUrl !== null && data.targetAvatarUrl !== undefined && typeof data.targetAvatarUrl !== 'string') {
+        return null;
+    }
+    if (data.targetUserType !== 'human' && data.targetUserType !== 'ai_agent') {
+        return null;
+    }
+    if (data.targetUserType === 'ai_agent'
+        && (typeof data.targetOwnerId !== 'string' || data.targetOwnerId.length === 0)) {
+        return null;
+    }
     const kindValue = typeof data.kind === 'string' ? data.kind : null;
     if (kindValue !== 'dm' && kindValue !== 'group_invite') {
         return null;
@@ -54,11 +67,9 @@ export function serializeContactRequest(requestId, data) {
         requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
         requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
         targetId: data.targetId,
-        targetName: typeof data.targetName === 'string' ? data.targetName : null,
+        targetName: data.targetName.trim(),
         targetAvatarUrl: typeof data.targetAvatarUrl === 'string' ? data.targetAvatarUrl : null,
-        targetUserType: data.targetUserType === 'human' || data.targetUserType === 'ai_agent'
-            ? data.targetUserType
-            : null,
+        targetUserType: data.targetUserType,
         approverId: data.approverId,
         message: typeof data.message === 'string' ? data.message : null,
         status: normalizeStatus(data.status),
@@ -70,7 +81,7 @@ export function serializeContactRequest(requestId, data) {
     if (groupContext) {
         payload.groupContext = groupContext;
     }
-    if (typeof data.targetOwnerId === 'string' && data.targetOwnerId.length > 0) {
+    if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }
     return payload;

package/dist/message.d.ts

@@ -36,12 +36,12 @@ export interface SerializedMessage {
     createdAt: string;
     metadata?: Record<string, unknown>;
     contactCard?: SerializedContactCard;
+    /** Durable canon.card.v1 runtime card content, passed through opaquely. */
+    runtimeCard?: Record<string, unknown>;
 }
 export interface SerializeMessageInput {
     id: string;
     data: Record<string, unknown>;
-    createdAtFallback?: unknown;
-    senderTypeFallback?: unknown;
     senderName?: string;
     isOwner: boolean;
 }

package/dist/message.js

@@ -1,5 +1,4 @@
-import { getMessageAttachments } from './media.js';
-const MISSING_CREATED_AT_ISO = new Date(0).toISOString();
+import { normalizeStoredAttachments } from './media.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -18,14 +17,17 @@ function normalizeTimestamp(value) {
     }
     return null;
 }
-function normalizeCreatedAt(value, fallback) {
-    const timestamp = normalizeTimestamp(value) ?? normalizeTimestamp(fallback);
-    return timestamp ? timestamp.toISOString() : MISSING_CREATED_AT_ISO;
+function requireCreatedAt(value) {
+    const timestamp = normalizeTimestamp(value);
+    if (!timestamp) {
+        throw new Error('Message is missing canonical createdAt');
+    }
+    return timestamp.toISOString();
 }
-function normalizeSenderType(value, fallback) {
-    if (value === 'ai_agent' || fallback === 'ai_agent')
-        return 'ai_agent';
-    return 'human';
+function requireSenderType(value) {
+    if (value === 'human' || value === 'ai_agent')
+        return value;
+    throw new Error('Message is missing canonical senderType');
 }
 function normalizeAgentClientType(value) {
     if (value === 'claude-code'
@@ -37,7 +39,7 @@ function normalizeAgentClientType(value) {
     }
     return undefined;
 }
-function normalizeContentType(value, attachments) {
+function normalizeContentType(value) {
     if (value === 'text'
         || value === 'image'
         || value === 'audio'
@@ -45,10 +47,7 @@ function normalizeContentType(value, attachments) {
         || value === 'contact_card') {
         return value;
     }
-    const primary = attachments[0]?.kind;
-    if (primary === 'image' || primary === 'audio' || primary === 'file')
-        return primary;
-    return 'text';
+    throw new Error('Message is missing canonical contentType');
 }
 function normalizeForwardedFrom(value) {
     if (!isRecord(value))
@@ -93,22 +92,25 @@ function normalizeContactCard(value) {
 }
 export function serializeStoredMessage(input) {
     const { data } = input;
-    const attachments = getMessageAttachments({
-        attachments: data.attachments,
-    });
+    const attachments = data.attachments === undefined
+        ? []
+        : normalizeStoredAttachments(data.attachments);
+    if (!attachments) {
+        throw new Error('Message has malformed attachments');
+    }
     const result = {
         id: input.id,
         senderId: typeof data.senderId === 'string' ? data.senderId : '',
-        senderType: normalizeSenderType(data.senderType, input.senderTypeFallback),
+        senderType: requireSenderType(data.senderType),
         isOwner: input.isOwner,
-        contentType: normalizeContentType(data.contentType, attachments),
+        contentType: normalizeContentType(data.contentType),
         text: typeof data.text === 'string' ? data.text : null,
         attachments,
         mentions: normalizeStringArray(data.mentions),
         replyTo: typeof data.replyTo === 'string' ? data.replyTo : null,
         replyToPosition: typeof data.replyToPosition === 'number' ? data.replyToPosition : null,
         status: data.status === 'read' ? 'read' : 'sent',
-        createdAt: normalizeCreatedAt(data.createdAt, input.createdAtFallback),
+        createdAt: requireCreatedAt(data.createdAt),
     };
     const forwardedFrom = normalizeForwardedFrom(data.forwardedFrom);
     if (data.forwarded === true || forwardedFrom) {
@@ -127,5 +129,8 @@ export function serializeStoredMessage(input) {
     if (contactCard) {
         result.contactCard = contactCard;
     }
+    if (isRecord(data.runtimeCard)) {
+        result.runtimeCard = data.runtimeCard;
+    }
     return result;
 }

package/dist/turnProtocol.d.ts

@@ -3,7 +3,6 @@ export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'w
 export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
 export interface TurnMetadata {
     turnSemantics?: TurnMessageSemantics;
-    turnComplete?: boolean;
     replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
 }
 export interface TurnStateLike {
@@ -21,17 +20,14 @@ export declare function isTurnStateStale(turnState: TurnStateLike | null | undef
 export declare function resolveTurnMessageSemantics(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): TurnMessageSemantics;
 export declare function shouldPromoteConversationMessage(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): boolean;
 export declare function shouldTriggerAgentTurn(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): {
     allow: boolean;
     semantics: TurnMessageSemantics;

package/dist/turnProtocol.js

@@ -11,7 +11,9 @@ function isHiddenRuntimeCardMetadata(metadata) {
         || metadata.type === 'question_reply'
         || metadata.type === 'plan_approval_reply'
         || metadata.type === 'runtime_input_reply'
-        || metadata.type === 'runtime_input_outcome';
+        || metadata.type === 'runtime_input_outcome'
+        || metadata.type === 'runtime_card_reply'
+        || metadata.type === 'runtime_card_outcome';
 }
 export function normalizeTurnMetadata(metadata) {
     if (!isRecord(metadata))
@@ -25,12 +27,11 @@ export function normalizeTurnMetadata(metadata) {
         || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && typeof metadata.turnComplete !== 'boolean' && !replyBehavior) {
+    if (!turnSemantics && !replyBehavior) {
         return null;
     }
     return {
         ...(turnSemantics ? { turnSemantics } : {}),
-        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
     };
 }
@@ -69,11 +70,9 @@ export function resolveTurnMessageSemantics(input) {
     const turnMetadata = normalizeTurnMetadata(input.metadata);
     if (turnMetadata?.turnSemantics)
         return turnMetadata.turnSemantics;
-    if (turnMetadata?.turnComplete === true)
-        return 'turn_complete';
     if (input.senderType === 'human')
         return 'turn_complete';
-    return isTurnOpen(input.senderTurnState) ? 'progress' : 'turn_complete';
+    return 'progress';
 }
 export function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "0.2.4",
+  "version": "1.1.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",