@canonmsg/backend-contracts 0.1.0

package/dist/cjs/media.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferMediaAttachmentKind = inferMediaAttachmentKind;
+exports.getStoredFileExtension = getStoredFileExtension;
+exports.normalizeStoredAttachments = normalizeStoredAttachments;
+exports.getMessageAttachments = getMessageAttachments;
+exports.getPrimaryAttachment = getPrimaryAttachment;
+exports.describeAttachment = describeAttachment;
+function inferMediaAttachmentKind(mimeType) {
+    if (mimeType.startsWith('image/'))
+        return 'image';
+    if (mimeType.startsWith('audio/'))
+        return 'audio';
+    return 'file';
+}
+function getStoredFileExtension(input) {
+    const mimeType = input.mimeType?.toLowerCase().trim() || '';
+    const explicitByMime = {
+        'image/jpeg': 'jpg',
+        'image/jpg': 'jpg',
+        'image/png': 'png',
+        'image/webp': 'webp',
+        'image/gif': 'gif',
+        'audio/mp4': 'm4a',
+        'audio/x-m4a': 'm4a',
+        'audio/mpeg': 'mp3',
+        'audio/webm': 'webm',
+        'audio/ogg': 'ogg',
+        'application/pdf': 'pdf',
+        'text/plain': 'txt',
+        'application/json': 'json',
+        'application/zip': 'zip',
+    };
+    if (explicitByMime[mimeType])
+        return explicitByMime[mimeType];
+    const trimmedName = input.fileName?.trim() || '';
+    const lastDot = trimmedName.lastIndexOf('.');
+    if (lastDot > 0 && lastDot < trimmedName.length - 1) {
+        const fromName = trimmedName.slice(lastDot + 1).toLowerCase();
+        if (/^[a-z0-9]{1,10}$/.test(fromName))
+            return fromName;
+    }
+    const slashIndex = mimeType.indexOf('/');
+    if (slashIndex !== -1 && slashIndex < mimeType.length - 1) {
+        const subtype = mimeType.slice(slashIndex + 1).split('+')[0].toLowerCase();
+        if (/^[a-z0-9.-]{1,20}$/.test(subtype)) {
+            if (subtype === 'plain')
+                return 'txt';
+            if (subtype === 'octet-stream')
+                return 'bin';
+            return subtype.replace(/[^a-z0-9]/g, '') || 'bin';
+        }
+    }
+    return 'bin';
+}
+function normalizeStoredAttachments(value) {
+    if (!Array.isArray(value))
+        return null;
+    const attachments = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object')
+            return null;
+        const candidate = item;
+        if (candidate.kind !== 'image'
+            && candidate.kind !== 'audio'
+            && candidate.kind !== 'file') {
+            return null;
+        }
+        if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
+            return null;
+        }
+        attachments.push({
+            kind: candidate.kind,
+            url: candidate.url,
+            ...(typeof candidate.mimeType === 'string' && candidate.mimeType ? { mimeType: candidate.mimeType } : {}),
+            ...(typeof candidate.fileName === 'string' && candidate.fileName ? { fileName: candidate.fileName } : {}),
+            ...(typeof candidate.sizeBytes === 'number' ? { sizeBytes: candidate.sizeBytes } : {}),
+            ...(typeof candidate.width === 'number' ? { width: candidate.width } : {}),
+            ...(typeof candidate.height === 'number' ? { height: candidate.height } : {}),
+            ...(typeof candidate.durationMs === 'number' ? { durationMs: candidate.durationMs } : {}),
+        });
+    }
+    return attachments.length > 0 ? attachments : [];
+}
+function getMessageAttachments(input) {
+    const normalizedAttachments = normalizeStoredAttachments(input.attachments);
+    return normalizedAttachments ?? [];
+}
+function getPrimaryAttachment(input) {
+    const attachments = getMessageAttachments(input);
+    return attachments[0] ?? null;
+}
+function describeAttachment(attachment) {
+    if (!attachment)
+        return null;
+    if (attachment.kind === 'image')
+        return '📷 Image';
+    if (attachment.kind === 'audio')
+        return '🎤 Voice message';
+    return attachment.fileName ? `📎 ${attachment.fileName}` : '📎 File';
+}

package/dist/cjs/message.js

@@ -0,0 +1,122 @@
+"use strict";
+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);
+}
+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;
+}
+function serializeStoredMessage(input) {
+    const { data } = input;
+    const attachments = (0, media_js_1.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/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/turnProtocol.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTurnMetadata = normalizeTurnMetadata;
+exports.isTurnOpen = isTurnOpen;
+exports.resolveTurnMessageSemantics = resolveTurnMessageSemantics;
+exports.shouldPromoteConversationMessage = shouldPromoteConversationMessage;
+exports.shouldTriggerAgentTurn = shouldTriggerAgentTurn;
+exports.normalizeRuntimeTurnState = normalizeRuntimeTurnState;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+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 } : {}),
+    };
+}
+function isTurnOpen(turnState) {
+    if (!turnState)
+        return false;
+    return turnState.state !== 'idle'
+        && turnState.state !== 'completed'
+        && turnState.state !== 'interrupted';
+}
+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';
+}
+function shouldPromoteConversationMessage(input) {
+    return resolveTurnMessageSemantics(input) !== 'progress';
+}
+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 };
+}
+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/dist/contactRequest.d.ts

@@ -0,0 +1,20 @@
+export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+export interface SerializedContactRequest {
+    id: string;
+    requesterId: string;
+    requesterName: string;
+    requesterAvatarUrl: string | null;
+    targetId: string;
+    approverId: string;
+    message: string | null;
+    status: SerializedContactRequestStatus;
+    kind: 'dm' | 'group_invite';
+    groupContext?: {
+        conversationId: string;
+        groupName: string | null;
+    };
+    createdAt: string | null;
+    resolvedAt?: string | null;
+    expiresAt?: string | null;
+}
+export declare function serializeContactRequest(requestId: string, data: Record<string, unknown>): SerializedContactRequest | null;

package/dist/contactRequest.js

@@ -0,0 +1,69 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeTimestamp(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (isRecord(value) && typeof value.toDate === 'function') {
+        const result = value.toDate();
+        if (result instanceof Date)
+            return result.toISOString();
+    }
+    return null;
+}
+function normalizeStatus(value) {
+    if (value === 'pending'
+        || value === 'approved'
+        || value === 'rejected'
+        || value === 'expired') {
+        return value;
+    }
+    return 'pending';
+}
+export function serializeContactRequest(requestId, data) {
+    if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
+        return null;
+    }
+    if (typeof data.requesterId !== 'string' || data.requesterId.length === 0) {
+        return null;
+    }
+    if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
+        return null;
+    }
+    const kindValue = typeof data.kind === 'string' ? data.kind : 'dm';
+    if (kindValue !== 'dm' && kindValue !== 'group_invite') {
+        return null;
+    }
+    let groupContext = null;
+    if (kindValue === 'group_invite') {
+        const ctx = isRecord(data.groupContext) ? data.groupContext : null;
+        const conversationId = typeof ctx?.conversationId === 'string'
+            ? ctx.conversationId.trim()
+            : '';
+        if (!conversationId) {
+            return null;
+        }
+        groupContext = {
+            conversationId,
+            groupName: typeof ctx?.groupName === 'string' ? ctx.groupName : null,
+        };
+    }
+    const payload = {
+        id: requestId,
+        requesterId: data.requesterId,
+        requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
+        requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
+        targetId: data.targetId,
+        approverId: data.approverId,
+        message: typeof data.message === 'string' ? data.message : null,
+        status: normalizeStatus(data.status),
+        kind: kindValue,
+        createdAt: normalizeTimestamp(data.createdAt),
+        resolvedAt: normalizeTimestamp(data.resolvedAt),
+        expiresAt: normalizeTimestamp(data.expiresAt),
+    };
+    if (groupContext) {
+        payload.groupContext = groupContext;
+    }
+    return payload;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './media.js';
+export * from './message.js';
+export * from './turnProtocol.js';
+export * from './agentBehaviorPolicy.js';
+export * from './contactRequest.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './media.js';
+export * from './message.js';
+export * from './turnProtocol.js';
+export * from './agentBehaviorPolicy.js';
+export * from './contactRequest.js';

package/dist/media.d.ts

@@ -0,0 +1,24 @@
+export type MediaAttachmentKind = 'image' | 'audio' | 'file';
+export interface MediaAttachment {
+    kind: MediaAttachmentKind;
+    url: string;
+    mimeType?: string;
+    fileName?: string;
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+}
+export declare function inferMediaAttachmentKind(mimeType: string): MediaAttachmentKind;
+export declare function getStoredFileExtension(input: {
+    mimeType?: string | null;
+    fileName?: string | null;
+}): string;
+export declare function normalizeStoredAttachments(value: unknown): MediaAttachment[] | null;
+export declare function getMessageAttachments(input: {
+    attachments?: unknown;
+}): MediaAttachment[];
+export declare function getPrimaryAttachment(input: {
+    attachments?: unknown;
+}): MediaAttachment | null;
+export declare function describeAttachment(attachment: MediaAttachment | null | undefined): string | null;

package/dist/media.js

@@ -0,0 +1,93 @@
+export function inferMediaAttachmentKind(mimeType) {
+    if (mimeType.startsWith('image/'))
+        return 'image';
+    if (mimeType.startsWith('audio/'))
+        return 'audio';
+    return 'file';
+}
+export function getStoredFileExtension(input) {
+    const mimeType = input.mimeType?.toLowerCase().trim() || '';
+    const explicitByMime = {
+        'image/jpeg': 'jpg',
+        'image/jpg': 'jpg',
+        'image/png': 'png',
+        'image/webp': 'webp',
+        'image/gif': 'gif',
+        'audio/mp4': 'm4a',
+        'audio/x-m4a': 'm4a',
+        'audio/mpeg': 'mp3',
+        'audio/webm': 'webm',
+        'audio/ogg': 'ogg',
+        'application/pdf': 'pdf',
+        'text/plain': 'txt',
+        'application/json': 'json',
+        'application/zip': 'zip',
+    };
+    if (explicitByMime[mimeType])
+        return explicitByMime[mimeType];
+    const trimmedName = input.fileName?.trim() || '';
+    const lastDot = trimmedName.lastIndexOf('.');
+    if (lastDot > 0 && lastDot < trimmedName.length - 1) {
+        const fromName = trimmedName.slice(lastDot + 1).toLowerCase();
+        if (/^[a-z0-9]{1,10}$/.test(fromName))
+            return fromName;
+    }
+    const slashIndex = mimeType.indexOf('/');
+    if (slashIndex !== -1 && slashIndex < mimeType.length - 1) {
+        const subtype = mimeType.slice(slashIndex + 1).split('+')[0].toLowerCase();
+        if (/^[a-z0-9.-]{1,20}$/.test(subtype)) {
+            if (subtype === 'plain')
+                return 'txt';
+            if (subtype === 'octet-stream')
+                return 'bin';
+            return subtype.replace(/[^a-z0-9]/g, '') || 'bin';
+        }
+    }
+    return 'bin';
+}
+export function normalizeStoredAttachments(value) {
+    if (!Array.isArray(value))
+        return null;
+    const attachments = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object')
+            return null;
+        const candidate = item;
+        if (candidate.kind !== 'image'
+            && candidate.kind !== 'audio'
+            && candidate.kind !== 'file') {
+            return null;
+        }
+        if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
+            return null;
+        }
+        attachments.push({
+            kind: candidate.kind,
+            url: candidate.url,
+            ...(typeof candidate.mimeType === 'string' && candidate.mimeType ? { mimeType: candidate.mimeType } : {}),
+            ...(typeof candidate.fileName === 'string' && candidate.fileName ? { fileName: candidate.fileName } : {}),
+            ...(typeof candidate.sizeBytes === 'number' ? { sizeBytes: candidate.sizeBytes } : {}),
+            ...(typeof candidate.width === 'number' ? { width: candidate.width } : {}),
+            ...(typeof candidate.height === 'number' ? { height: candidate.height } : {}),
+            ...(typeof candidate.durationMs === 'number' ? { durationMs: candidate.durationMs } : {}),
+        });
+    }
+    return attachments.length > 0 ? attachments : [];
+}
+export function getMessageAttachments(input) {
+    const normalizedAttachments = normalizeStoredAttachments(input.attachments);
+    return normalizedAttachments ?? [];
+}
+export function getPrimaryAttachment(input) {
+    const attachments = getMessageAttachments(input);
+    return attachments[0] ?? null;
+}
+export function describeAttachment(attachment) {
+    if (!attachment)
+        return null;
+    if (attachment.kind === 'image')
+        return '📷 Image';
+    if (attachment.kind === 'audio')
+        return '🎤 Voice message';
+    return attachment.fileName ? `📎 ${attachment.fileName}` : '📎 File';
+}

package/dist/message.d.ts

@@ -0,0 +1,47 @@
+import { MediaAttachment } from './media.js';
+export type SerializedSenderType = 'human' | 'ai_agent';
+export type SerializedContentType = 'text' | 'image' | 'audio' | 'file' | 'contact_card';
+export interface ForwardedFrom {
+    sourceConversationId: string;
+    messageId: string;
+}
+export interface SerializedContactCard {
+    userId: string;
+    displayName: string;
+    avatarUrl: string | null;
+    userType: SerializedSenderType;
+    about?: string;
+    isActive?: boolean;
+    ownerId?: string;
+    ownerName?: string;
+    lifecycleState?: string;
+}
+export interface SerializedMessage {
+    id: string;
+    senderId: string;
+    senderName?: string;
+    senderType: SerializedSenderType;
+    isOwner: boolean;
+    contentType: SerializedContentType;
+    text: string | null;
+    attachments: MediaAttachment[];
+    mentions: string[];
+    replyTo: string | null;
+    replyToPosition: number | null;
+    forwarded?: boolean;
+    forwardedFrom?: ForwardedFrom;
+    status: 'sent' | 'read';
+    createdAt: string;
+    workSession?: unknown;
+    metadata?: Record<string, unknown>;
+    contactCard?: SerializedContactCard;
+}
+export interface SerializeMessageInput {
+    id: string;
+    data: Record<string, unknown>;
+    createdAtFallback?: unknown;
+    senderTypeFallback?: unknown;
+    senderName?: string;
+    isOwner: boolean;
+}
+export declare function serializeStoredMessage(input: SerializeMessageInput): SerializedMessage;