@canonmsg/backend-contracts 0.1.0

package/dist/message.js

@@ -0,0 +1,119 @@
+import { getMessageAttachments } from './media.js';
+const MISSING_CREATED_AT_ISO = new Date(0).toISOString();
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === 'string');
+}
+function normalizeTimestamp(value) {
+    if (value instanceof Date)
+        return value;
+    if (isRecord(value) && typeof value.toDate === 'function') {
+        const result = value.toDate();
+        if (result instanceof Date)
+            return result;
+    }
+    return null;
+}
+function normalizeCreatedAt(value, fallback) {
+    const timestamp = normalizeTimestamp(value) ?? normalizeTimestamp(fallback);
+    return timestamp ? timestamp.toISOString() : MISSING_CREATED_AT_ISO;
+}
+function normalizeSenderType(value, fallback) {
+    if (value === 'ai_agent' || fallback === 'ai_agent')
+        return 'ai_agent';
+    return 'human';
+}
+function normalizeContentType(value, attachments) {
+    if (value === 'text'
+        || value === 'image'
+        || value === 'audio'
+        || value === 'file'
+        || value === 'contact_card') {
+        return value;
+    }
+    const primary = attachments[0]?.kind;
+    if (primary === 'image' || primary === 'audio' || primary === 'file')
+        return primary;
+    return 'text';
+}
+function normalizeForwardedFrom(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value.sourceConversationId !== 'string')
+        return undefined;
+    if (typeof value.messageId !== 'string')
+        return undefined;
+    return {
+        sourceConversationId: value.sourceConversationId,
+        messageId: value.messageId,
+    };
+}
+function normalizeContactCard(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value.userId !== 'string' || value.userId.length === 0)
+        return undefined;
+    const userType = value.userType === 'ai_agent' ? 'ai_agent' : 'human';
+    const card = {
+        userId: value.userId,
+        displayName: typeof value.displayName === 'string' ? value.displayName : 'Unknown',
+        avatarUrl: typeof value.avatarUrl === 'string' ? value.avatarUrl : null,
+        userType,
+    };
+    if (typeof value.about === 'string')
+        card.about = value.about;
+    if (typeof value.isActive === 'boolean')
+        card.isActive = value.isActive;
+    if (typeof value.ownerId === 'string')
+        card.ownerId = value.ownerId;
+    if (typeof value.ownerName === 'string')
+        card.ownerName = value.ownerName;
+    if (typeof value.lifecycleState === 'string')
+        card.lifecycleState = value.lifecycleState;
+    return card;
+}
+export function serializeStoredMessage(input) {
+    const { data } = input;
+    const attachments = getMessageAttachments({
+        attachments: data.attachments,
+    });
+    const result = {
+        id: input.id,
+        senderId: typeof data.senderId === 'string' ? data.senderId : '',
+        senderType: normalizeSenderType(data.senderType, input.senderTypeFallback),
+        isOwner: input.isOwner,
+        contentType: normalizeContentType(data.contentType, attachments),
+        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),
+    };
+    const forwardedFrom = normalizeForwardedFrom(data.forwardedFrom);
+    if (data.forwarded === true || forwardedFrom) {
+        result.forwarded = true;
+    }
+    if (forwardedFrom) {
+        result.forwardedFrom = forwardedFrom;
+    }
+    if (typeof input.senderName === 'string') {
+        result.senderName = input.senderName;
+    }
+    if (data.workSession !== undefined && data.workSession !== null) {
+        result.workSession = data.workSession;
+    }
+    if (isRecord(data.metadata)) {
+        result.metadata = data.metadata;
+    }
+    const contactCard = normalizeContactCard(data.contactCard);
+    if (contactCard) {
+        result.contactCard = contactCard;
+    }
+    return result;
+}

package/dist/turnProtocol.d.ts

@@ -0,0 +1,32 @@
+export type SenderType = 'human' | 'ai_agent';
+export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
+export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
+export interface TurnMetadata {
+    turnSemantics?: TurnMessageSemantics;
+    turnComplete?: boolean;
+    replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
+}
+export interface TurnStateLike {
+    state: TurnLifecycleState;
+}
+export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
+export declare function isTurnOpen(turnState: TurnStateLike | null | undefined): boolean;
+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;
+};
+export declare function normalizeRuntimeTurnState(value: unknown): TurnStateLike | null;

package/dist/turnProtocol.js

@@ -0,0 +1,75 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function normalizeTurnMetadata(metadata) {
+    if (!isRecord(metadata))
+        return null;
+    const turnSemantics = metadata.turnSemantics === 'progress'
+        || metadata.turnSemantics === 'turn_complete'
+        || metadata.turnSemantics === 'control'
+        ? metadata.turnSemantics
+        : undefined;
+    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply'
+        || metadata.replyBehavior === 'suppress_auto_reply'
+        ? metadata.replyBehavior
+        : undefined;
+    if (!turnSemantics && typeof metadata.turnComplete !== 'boolean' && !replyBehavior) {
+        return null;
+    }
+    return {
+        ...(turnSemantics ? { turnSemantics } : {}),
+        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
+        ...(replyBehavior ? { replyBehavior } : {}),
+    };
+}
+export function isTurnOpen(turnState) {
+    if (!turnState)
+        return false;
+    return turnState.state !== 'idle'
+        && turnState.state !== 'completed'
+        && turnState.state !== 'interrupted';
+}
+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';
+}
+export function shouldPromoteConversationMessage(input) {
+    return resolveTurnMessageSemantics(input) !== 'progress';
+}
+export function shouldTriggerAgentTurn(input) {
+    const semantics = resolveTurnMessageSemantics(input);
+    const turnMetadata = normalizeTurnMetadata(input.metadata);
+    if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
+        return { allow: false, semantics };
+    }
+    if (input.senderType === 'human') {
+        return { allow: true, semantics };
+    }
+    return { allow: semantics !== 'progress', semantics };
+}
+export function normalizeRuntimeTurnState(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.state === 'idle'
+        || value.state === 'thinking'
+        || value.state === 'streaming'
+        || value.state === 'tool'
+        || value.state === 'waiting_input'
+        || value.state === 'completed'
+        || value.state === 'interrupted') {
+        return { state: value.state };
+    }
+    if (value.state === 'running') {
+        return { state: 'streaming' };
+    }
+    if (value.state === 'requires_action') {
+        return { state: 'waiting_input' };
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@canonmsg/backend-contracts",
+  "version": "0.1.0",
+  "description": "Canon backend contract helpers shared by Functions and stream-service",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true}); require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "canon",
+    "backend",
+    "contracts",
+    "wire"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HeyBobChan/canon",
+    "directory": "packages/backend-contracts"
+  },
+  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/backend-contracts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "~5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT"
+}