@canonmsg/backend-contracts 8.1.0 → 8.2.0

package/dist/cjs/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./diffRedaction.js"), exports);
 __exportStar(require("./environment.js"), exports);
 __exportStar(require("./media.js"), exports);
+__exportStar(require("./media-url.js"), exports);
 __exportStar(require("./message.js"), exports);
 __exportStar(require("./messageText.js"), exports);
 __exportStar(require("./runtimeCardFields.js"), exports);

package/dist/cjs/media-origins.generated.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_ORIGINS = void 0;
+// Generated by scripts/sync-runtime-endpoints.mjs from canonical endpoints and storage policies.
+exports.MEDIA_ORIGINS = {
+    "canonmail-dev.firebasestorage.app": "https://dev.api.canonmail.com",
+    "canonmail-prod.firebasestorage.app": "https://api.canonmail.com"
+};

package/dist/cjs/media-url.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFirebaseMediaUrl = buildFirebaseMediaUrl;
+exports.buildMediaDownloadUrl = buildMediaDownloadUrl;
+exports.parseMediaStoragePath = parseMediaStoragePath;
+exports.canonMediaDownloadUrl = canonMediaDownloadUrl;
+const media_js_1 = require("./media.js");
+const media_origins_generated_js_1 = require("./media-origins.generated.js");
+function buildFirebaseMediaUrl(bucket, storagePath, token) {
+    return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(storagePath)}?alt=media&token=${encodeURIComponent(token)}`;
+}
+function validMediaPath(path) {
+    const parts = path.split('/');
+    return parts.length === 4 && parts[0] === 'media'
+        && parts.every((part) => Boolean(part) && part !== '.' && part !== '..' && !/[\u0000-\u001f\u007f\\]/.test(part));
+}
+function buildMediaDownloadUrl(bucket, storagePath, token) {
+    const origin = media_origins_generated_js_1.MEDIA_ORIGINS[bucket];
+    if (!origin || !validMediaPath(storagePath))
+        return buildFirebaseMediaUrl(bucket, storagePath, token);
+    return `${origin}/files/${storagePath.split('/').slice(1).map(encodeURIComponent).join('/')}?token=${encodeURIComponent(token)}`;
+}
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+function parseMediaStoragePath(value, bucket) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        let path;
+        const prefix = `/v0/b/${bucket}/o/`;
+        if (url.origin === 'https://firebasestorage.googleapis.com' && url.pathname.startsWith(prefix)) {
+            path = decodeURIComponent(url.pathname.slice(prefix.length));
+        }
+        else if (url.origin === media_origins_generated_js_1.MEDIA_ORIGINS[bucket] && url.pathname.startsWith('/files/')) {
+            path = `media/${decodeURIComponent(url.pathname.slice('/files/'.length))}`;
+        }
+        else
+            return null;
+        return validMediaPath(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+function canonMediaDownloadUrl(value, downloadFileName) {
+    for (const bucket of Object.keys(media_origins_generated_js_1.MEDIA_ORIGINS)) {
+        const path = parseMediaStoragePath(value, bucket);
+        if (path) {
+            const token = new URL(value).searchParams.get('token');
+            if (token) {
+                const url = new URL(buildMediaDownloadUrl(bucket, path, token));
+                if (downloadFileName !== undefined)
+                    url.searchParams.set('download', (0, media_js_1.sanitizeDownloadFileName)(downloadFileName));
+                return url.href;
+            }
+        }
+    }
+    return value;
+}

package/dist/cjs/media.js

@@ -1,11 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_CACHE_CONTROL = void 0;
+exports.sanitizeDownloadFileName = sanitizeDownloadFileName;
+exports.buildMediaContentDisposition = buildMediaContentDisposition;
+exports.processedVideoFileName = processedVideoFileName;
 exports.inferMediaAttachmentKind = inferMediaAttachmentKind;
 exports.getStoredFileExtension = getStoredFileExtension;
 exports.normalizeStoredAttachments = normalizeStoredAttachments;
 exports.getMessageAttachments = getMessageAttachments;
 exports.getPrimaryAttachment = getPrimaryAttachment;
 exports.describeAttachment = describeAttachment;
+/** Allow private conditional caching, but recheck access before every reuse. */
+exports.MEDIA_CACHE_CONTROL = 'private, max-age=0, must-revalidate';
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+function sanitizeDownloadFileName(value, fallback = 'attachment') {
+    const baseName = typeof value === 'string'
+        ? value.trim().split(/[\\/]/).filter(Boolean).pop() ?? ''
+        : '';
+    let name = Array.from(baseName, (char) => /^[\ud800-\udfff]$/.test(char) ? '-' : char).join('').normalize('NFC')
+        .replace(/[\u0000-\u001f\u007f<>:"/\\|?*\u202a-\u202e\u2066-\u2069]+/g, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/^[. -]+|[. -]+$/g, '');
+    if (!name)
+        return sanitizeDownloadFileName(fallback, 'attachment');
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        name = `_${name}`;
+    const extension = name.match(/\.[a-z0-9]{1,16}$/i)?.[0] ?? '';
+    const stem = extension ? name.slice(0, -extension.length) : name;
+    // Stay below filesystem byte limits as well as the display-length limit.
+    let safeStem = '';
+    let bytes = extension.length;
+    for (const char of Array.from(stem).slice(0, 120 - extension.length)) {
+        bytes += encodeURIComponent(char).replace(/%[0-9A-F]{2}|./g, '_').length;
+        if (bytes > 240)
+            break;
+        safeStem += char;
+    }
+    return `${safeStem.replace(/[. -]+$/g, '')}${extension}`;
+}
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+function buildMediaContentDisposition(input) {
+    const fileName = sanitizeDownloadFileName(input.fileName, input.fallbackFileName);
+    const asciiName = fileName.replace(/[^\x20-\x7e]|%/g, '_');
+    const encodedName = encodeURIComponent(fileName).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${input.disposition ?? 'attachment'}; filename="${asciiName}"`
+        + (fileName === asciiName ? '' : `; filename*=UTF-8''${encodedName}`);
+}
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+function processedVideoFileName(value) {
+    const stem = typeof value === 'string' ? value.trim().replace(/\.[a-z0-9]{1,16}$/i, '') : '';
+    return sanitizeDownloadFileName(`${stem || 'video'}.mp4`, 'video.mp4');
+}
 function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';

package/dist/cjs/turnProtocol.js

@@ -118,6 +118,13 @@ function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {
         return false;
     }
+    // Ordinary agent speech can update previews and notify people without
+    // opting into automatic agent-to-agent turns. Keep malformed explicit
+    // semantics on the existing conservative fallback.
+    if (input.metadata == null
+        || (isRecord(input.metadata) && input.metadata.turnSemantics === undefined)) {
+        return true;
+    }
     return resolveTurnMessageSemantics(input) !== 'progress';
 }
 function shouldTriggerAgentTurn(input) {

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './diffRedaction.js';
 export * from './environment.js';
 export * from './media.js';
+export * from './media-url.js';
 export * from './message.js';
 export * from './messageText.js';
 export * from './runtimeCardFields.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './diffRedaction.js';
 export * from './environment.js';
 export * from './media.js';
+export * from './media-url.js';
 export * from './message.js';
 export * from './messageText.js';
 export * from './runtimeCardFields.js';

package/dist/media-origins.generated.d.ts

@@ -0,0 +1 @@
+export declare const MEDIA_ORIGINS: Readonly<Record<string, string>>;

package/dist/media-origins.generated.js

@@ -0,0 +1,5 @@
+// Generated by scripts/sync-runtime-endpoints.mjs from canonical endpoints and storage policies.
+export const MEDIA_ORIGINS = {
+    "canonmail-dev.firebasestorage.app": "https://dev.api.canonmail.com",
+    "canonmail-prod.firebasestorage.app": "https://api.canonmail.com"
+};

package/dist/media-url.d.ts

@@ -0,0 +1,6 @@
+export declare function buildFirebaseMediaUrl(bucket: string, storagePath: string, token: string): string;
+export declare function buildMediaDownloadUrl(bucket: string, storagePath: string, token: string): string;
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+export declare function parseMediaStoragePath(value: unknown, bucket: string): string | null;
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+export declare function canonMediaDownloadUrl(value: string, downloadFileName?: string): string;

package/dist/media-url.js

@@ -0,0 +1,56 @@
+import { sanitizeDownloadFileName } from './media.js';
+import { MEDIA_ORIGINS } from './media-origins.generated.js';
+export function buildFirebaseMediaUrl(bucket, storagePath, token) {
+    return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(storagePath)}?alt=media&token=${encodeURIComponent(token)}`;
+}
+function validMediaPath(path) {
+    const parts = path.split('/');
+    return parts.length === 4 && parts[0] === 'media'
+        && parts.every((part) => Boolean(part) && part !== '.' && part !== '..' && !/[\u0000-\u001f\u007f\\]/.test(part));
+}
+export function buildMediaDownloadUrl(bucket, storagePath, token) {
+    const origin = MEDIA_ORIGINS[bucket];
+    if (!origin || !validMediaPath(storagePath))
+        return buildFirebaseMediaUrl(bucket, storagePath, token);
+    return `${origin}/files/${storagePath.split('/').slice(1).map(encodeURIComponent).join('/')}?token=${encodeURIComponent(token)}`;
+}
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+export function parseMediaStoragePath(value, bucket) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        let path;
+        const prefix = `/v0/b/${bucket}/o/`;
+        if (url.origin === 'https://firebasestorage.googleapis.com' && url.pathname.startsWith(prefix)) {
+            path = decodeURIComponent(url.pathname.slice(prefix.length));
+        }
+        else if (url.origin === MEDIA_ORIGINS[bucket] && url.pathname.startsWith('/files/')) {
+            path = `media/${decodeURIComponent(url.pathname.slice('/files/'.length))}`;
+        }
+        else
+            return null;
+        return validMediaPath(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+export function canonMediaDownloadUrl(value, downloadFileName) {
+    for (const bucket of Object.keys(MEDIA_ORIGINS)) {
+        const path = parseMediaStoragePath(value, bucket);
+        if (path) {
+            const token = new URL(value).searchParams.get('token');
+            if (token) {
+                const url = new URL(buildMediaDownloadUrl(bucket, path, token));
+                if (downloadFileName !== undefined)
+                    url.searchParams.set('download', sanitizeDownloadFileName(downloadFileName));
+                return url.href;
+            }
+        }
+    }
+    return value;
+}

package/dist/media.d.ts

@@ -1,4 +1,16 @@
 export type MediaAttachmentKind = 'image' | 'audio' | 'video' | 'file';
+/** Allow private conditional caching, but recheck access before every reuse. */
+export declare const MEDIA_CACHE_CONTROL = "private, max-age=0, must-revalidate";
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+export declare function sanitizeDownloadFileName(value: unknown, fallback?: string): string;
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+export declare function buildMediaContentDisposition(input: {
+    fileName?: unknown;
+    fallbackFileName: string;
+    disposition?: 'inline' | 'attachment';
+}): string;
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+export declare function processedVideoFileName(value: unknown): string;
 /** Lifecycle for newly uploaded videos that are normalized server-side. */
 export type VideoProcessingStatus = 'processing' | 'ready' | 'failed';
 /** Stable, display-safe reasons for a terminal video processing failure. */
@@ -7,9 +19,9 @@ export interface MediaAttachment {
     kind: MediaAttachmentKind;
     url: string;
     /**
-     * Server-issued identity for a finalized resumable upload. The send path
+     * Server-issued identity for a finalized upload. The send path
      * uses this to retain temporary canonical media atomically with the message.
-     * Legacy/base64 uploads intentionally omit it.
+     * Older attachments and forwarded copies may omit it.
      */
     uploadId?: string;
     mimeType?: string;

package/dist/media.js

@@ -1,3 +1,44 @@
+/** Allow private conditional caching, but recheck access before every reuse. */
+export const MEDIA_CACHE_CONTROL = 'private, max-age=0, must-revalidate';
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+export function sanitizeDownloadFileName(value, fallback = 'attachment') {
+    const baseName = typeof value === 'string'
+        ? value.trim().split(/[\\/]/).filter(Boolean).pop() ?? ''
+        : '';
+    let name = Array.from(baseName, (char) => /^[\ud800-\udfff]$/.test(char) ? '-' : char).join('').normalize('NFC')
+        .replace(/[\u0000-\u001f\u007f<>:"/\\|?*\u202a-\u202e\u2066-\u2069]+/g, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/^[. -]+|[. -]+$/g, '');
+    if (!name)
+        return sanitizeDownloadFileName(fallback, 'attachment');
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        name = `_${name}`;
+    const extension = name.match(/\.[a-z0-9]{1,16}$/i)?.[0] ?? '';
+    const stem = extension ? name.slice(0, -extension.length) : name;
+    // Stay below filesystem byte limits as well as the display-length limit.
+    let safeStem = '';
+    let bytes = extension.length;
+    for (const char of Array.from(stem).slice(0, 120 - extension.length)) {
+        bytes += encodeURIComponent(char).replace(/%[0-9A-F]{2}|./g, '_').length;
+        if (bytes > 240)
+            break;
+        safeStem += char;
+    }
+    return `${safeStem.replace(/[. -]+$/g, '')}${extension}`;
+}
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+export function buildMediaContentDisposition(input) {
+    const fileName = sanitizeDownloadFileName(input.fileName, input.fallbackFileName);
+    const asciiName = fileName.replace(/[^\x20-\x7e]|%/g, '_');
+    const encodedName = encodeURIComponent(fileName).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${input.disposition ?? 'attachment'}; filename="${asciiName}"`
+        + (fileName === asciiName ? '' : `; filename*=UTF-8''${encodedName}`);
+}
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+export function processedVideoFileName(value) {
+    const stem = typeof value === 'string' ? value.trim().replace(/\.[a-z0-9]{1,16}$/i, '') : '';
+    return sanitizeDownloadFileName(`${stem || 'video'}.mp4`, 'video.mp4');
+}
 export function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';

package/dist/turnProtocol.js

@@ -107,6 +107,13 @@ export function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {
         return false;
     }
+    // Ordinary agent speech can update previews and notify people without
+    // opting into automatic agent-to-agent turns. Keep malformed explicit
+    // semantics on the existing conservative fallback.
+    if (input.metadata == null
+        || (isRecord(input.metadata) && input.metadata.turnSemantics === undefined)) {
+        return true;
+    }
     return resolveTurnMessageSemantics(input) !== 'progress';
 }
 export function shouldTriggerAgentTurn(input) {

package/package.json

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