@canonmsg/backend-contracts 1.4.0 → 1.6.0

package/dist/cjs/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./media.js"), exports);
 __exportStar(require("./message.js"), exports);
+__exportStar(require("./runtimeCardFields.js"), exports);
 __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);

package/dist/cjs/media.js

@@ -59,6 +59,13 @@ function getStoredFileExtension(input) {
     }
     return 'bin';
 }
+// Numeric attachment metadata flows straight into every client's duration and
+// size formatting; NaN/Infinity/negatives are dropped rather than stored.
+function normalizeAttachmentNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
 function normalizeStoredAttachments(value) {
     if (!Array.isArray(value))
         return null;
@@ -76,15 +83,19 @@ function normalizeStoredAttachments(value) {
         if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
             return null;
         }
+        const sizeBytes = normalizeAttachmentNumber(candidate.sizeBytes);
+        const width = normalizeAttachmentNumber(candidate.width);
+        const height = normalizeAttachmentNumber(candidate.height);
+        const durationMs = normalizeAttachmentNumber(candidate.durationMs);
         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 } : {}),
+            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+            ...(width !== undefined ? { width } : {}),
+            ...(height !== undefined ? { height } : {}),
+            ...(durationMs !== undefined ? { durationMs } : {}),
         });
     }
     return attachments.length > 0 ? attachments : [];

package/dist/cjs/runtimeCardFields.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_CARD_LIMITS = void 0;
+exports.validateRuntimeCardFieldValues = validateRuntimeCardFieldValues;
+/**
+ * Caps shared across runtime-card normalizers, response validation, and
+ * authoring tools. Keep these backend-safe so Functions can import them.
+ */
+exports.RUNTIME_CARD_LIMITS = {
+    detailsRows: 32,
+    lineItemRows: 50,
+    lineItemColumns: 8,
+    searchSelectChoices: 100,
+};
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidCalendarDate(value) {
+    if (!ISO_DATE_PATTERN.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map((part) => Number.parseInt(part, 10));
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year
+        && date.getUTCMonth() === month - 1
+        && date.getUTCDate() === day;
+}
+function fieldChoiceValue(choice) {
+    return choice.value ?? choice.label;
+}
+function isMissingScalar(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+function decimalPlaces(value) {
+    if (Number.isInteger(value))
+        return 0;
+    const text = Math.abs(value).toString();
+    if (text.includes('e') || text.includes('E')) {
+        const match = /e-?(\d+)/i.exec(text);
+        return match ? Number.parseInt(match[1], 10) : 0;
+    }
+    const dot = text.indexOf('.');
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+function alignsToStep(value, step) {
+    if (!(step > 0))
+        return true;
+    const quotient = value / step;
+    return Math.abs(quotient - Math.round(quotient)) < 1e-9;
+}
+function numericBound(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function dateBound(value) {
+    return typeof value === 'string' && isValidCalendarDate(value) ? value : undefined;
+}
+function validateScalarValue(spec, value) {
+    switch (spec.type) {
+        case 'boolean': {
+            if (typeof value !== 'boolean')
+                return `${spec.label} must be true or false`;
+            return null;
+        }
+        case 'multiSelect': {
+            if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string' && entry.trim())) {
+                return `${spec.label} must be a list of choices`;
+            }
+            if (!spec.allowOther) {
+                const allowed = new Set((spec.choices ?? []).map(fieldChoiceValue));
+                for (const entry of value) {
+                    if (!allowed.has(entry))
+                        return `${spec.label} contains an invalid choice`;
+                }
+            }
+            return null;
+        }
+        case 'date': {
+            if (typeof value !== 'string' || !isValidCalendarDate(value.trim())) {
+                return `${spec.label} must be a valid date (YYYY-MM-DD)`;
+            }
+            const date = value.trim();
+            const min = dateBound(spec.min);
+            const max = dateBound(spec.max);
+            if (min && date < min)
+                return `${spec.label} must be on or after ${min}`;
+            if (max && date > max)
+                return `${spec.label} must be on or before ${max}`;
+            return null;
+        }
+        case 'number':
+        case 'currency': {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return `${spec.label} must be a number`;
+            }
+            const min = numericBound(spec.min);
+            const max = numericBound(spec.max);
+            if (min !== undefined && value < min)
+                return `${spec.label} must be at least ${min}`;
+            if (max !== undefined && value > max)
+                return `${spec.label} must be at most ${max}`;
+            const precision = spec.type === 'currency'
+                ? (spec.precision ?? 2)
+                : spec.precision;
+            if (precision !== undefined && decimalPlaces(value) > precision) {
+                return `${spec.label} must have at most ${precision} decimal place${precision === 1 ? '' : 's'}`;
+            }
+            if (spec.type === 'number' && spec.step !== undefined && !alignsToStep(value, spec.step)) {
+                return `${spec.label} must be a multiple of ${spec.step}`;
+            }
+            return null;
+        }
+        case 'select':
+        case 'searchSelect': {
+            if (typeof value !== 'string')
+                return `${spec.label} must be text`;
+            if (!spec.allowOther) {
+                const allowed = new Set((spec.choices ?? []).map(fieldChoiceValue));
+                if (!allowed.has(value))
+                    return `${spec.label} contains an invalid choice`;
+            }
+            return null;
+        }
+        case 'text':
+        case 'textarea':
+        default: {
+            if (typeof value !== 'string')
+                return `${spec.label} must be text`;
+            return null;
+        }
+    }
+}
+function validateLineItemColumnValue(column, value) {
+    return validateScalarValue({
+        type: column.type,
+        label: column.label,
+        choices: column.choices,
+        allowOther: column.allowOther,
+        min: column.min,
+        max: column.max,
+        step: column.step,
+        precision: column.precision,
+    }, value);
+}
+function validateLineItemsValue(field, raw) {
+    if (!Array.isArray(raw))
+        return `${field.label} must be a list of rows`;
+    const columns = field.columns ?? [];
+    const minRows = field.minRows;
+    const maxRows = field.maxRows !== undefined
+        ? Math.min(field.maxRows, exports.RUNTIME_CARD_LIMITS.lineItemRows)
+        : exports.RUNTIME_CARD_LIMITS.lineItemRows;
+    if (raw.length > maxRows)
+        return `${field.label} allows at most ${maxRows} rows`;
+    if (minRows !== undefined && raw.length < minRows) {
+        return `${field.label} requires at least ${minRows} row${minRows === 1 ? '' : 's'}`;
+    }
+    if (field.required && raw.length === 0)
+        return `${field.label} is required`;
+    const columnIds = new Set(columns.map((column) => column.id));
+    for (let index = 0; index < raw.length; index += 1) {
+        const row = raw[index];
+        if (!isRecord(row))
+            return `${field.label}: row ${index + 1} must be an object`;
+        for (const key of Object.keys(row)) {
+            if (!columnIds.has(key))
+                return `${field.label}: row ${index + 1} has unknown column "${key}"`;
+        }
+        for (const column of columns) {
+            const cell = row[column.id];
+            const missing = isMissingScalar(cell);
+            if (column.required && missing) {
+                return `${field.label}: ${column.label} is required in row ${index + 1}`;
+            }
+            if (missing)
+                continue;
+            const error = validateLineItemColumnValue(column, cell);
+            if (error)
+                return `${field.label}: row ${index + 1}: ${error}`;
+        }
+    }
+    return null;
+}
+function validateRuntimeCardFieldValues(input) {
+    const fields = input.actionFields;
+    if (!input.actionId || !fields || fields.length === 0)
+        return null;
+    const values = input.values ?? {};
+    const allowedIds = new Set(fields.map((field) => field.id));
+    for (const key of Object.keys(values)) {
+        if (!allowedIds.has(key))
+            return `Unknown field: ${key}`;
+    }
+    for (const field of fields) {
+        const raw = values[field.id];
+        if (field.type === 'lineItems') {
+            if (raw === undefined || raw === null) {
+                if (field.required)
+                    return `${field.label} is required`;
+                continue;
+            }
+            const error = validateLineItemsValue(field, raw);
+            if (error)
+                return error;
+            continue;
+        }
+        if (field.required && isMissingScalar(raw))
+            return `${field.label} is required`;
+        if (raw === undefined || raw === null || raw === '')
+            continue;
+        const error = validateScalarValue(field, raw);
+        if (error)
+            return error;
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './media.js';
 export * from './message.js';
+export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './media.js';
 export * from './message.js';
+export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';

package/dist/media.js

@@ -51,6 +51,13 @@ export function getStoredFileExtension(input) {
     }
     return 'bin';
 }
+// Numeric attachment metadata flows straight into every client's duration and
+// size formatting; NaN/Infinity/negatives are dropped rather than stored.
+function normalizeAttachmentNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
 export function normalizeStoredAttachments(value) {
     if (!Array.isArray(value))
         return null;
@@ -68,15 +75,19 @@ export function normalizeStoredAttachments(value) {
         if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
             return null;
         }
+        const sizeBytes = normalizeAttachmentNumber(candidate.sizeBytes);
+        const width = normalizeAttachmentNumber(candidate.width);
+        const height = normalizeAttachmentNumber(candidate.height);
+        const durationMs = normalizeAttachmentNumber(candidate.durationMs);
         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 } : {}),
+            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+            ...(width !== undefined ? { width } : {}),
+            ...(height !== undefined ? { height } : {}),
+            ...(durationMs !== undefined ? { durationMs } : {}),
         });
     }
     return attachments.length > 0 ? attachments : [];

package/dist/runtimeCardFields.d.ts

@@ -0,0 +1,54 @@
+export type RuntimeCardFieldType = 'text' | 'textarea' | 'select' | 'multiSelect' | 'boolean' | 'date' | 'number' | 'currency' | 'searchSelect' | 'lineItems';
+/**
+ * Caps shared across runtime-card normalizers, response validation, and
+ * authoring tools. Keep these backend-safe so Functions can import them.
+ */
+export declare const RUNTIME_CARD_LIMITS: {
+    readonly detailsRows: 32;
+    readonly lineItemRows: 50;
+    readonly lineItemColumns: 8;
+    readonly searchSelectChoices: 100;
+};
+export interface RuntimeCardFieldChoice {
+    label: string;
+    value?: string;
+    description?: string;
+    preview?: string;
+}
+export type RuntimeCardLineItemColumnType = 'text' | 'number' | 'currency' | 'date' | 'select';
+export interface RuntimeCardLineItemColumn {
+    id: string;
+    label: string;
+    type: RuntimeCardLineItemColumnType;
+    required?: boolean;
+    choices?: RuntimeCardFieldChoice[];
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    allowOther?: boolean;
+}
+export interface RuntimeCardField {
+    id: string;
+    label: string;
+    type: RuntimeCardFieldType;
+    required?: boolean;
+    placeholder?: string;
+    choices?: RuntimeCardFieldChoice[];
+    allowOther?: boolean;
+    sensitive?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    columns?: RuntimeCardLineItemColumn[];
+    minRows?: number;
+    maxRows?: number;
+}
+export declare function validateRuntimeCardFieldValues(input: {
+    actionId: string | undefined;
+    actionFields: ReadonlyArray<RuntimeCardField> | undefined;
+    values: Record<string, unknown> | undefined;
+}): string | null;

package/dist/runtimeCardFields.js

@@ -0,0 +1,219 @@
+/**
+ * Caps shared across runtime-card normalizers, response validation, and
+ * authoring tools. Keep these backend-safe so Functions can import them.
+ */
+export const RUNTIME_CARD_LIMITS = {
+    detailsRows: 32,
+    lineItemRows: 50,
+    lineItemColumns: 8,
+    searchSelectChoices: 100,
+};
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidCalendarDate(value) {
+    if (!ISO_DATE_PATTERN.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map((part) => Number.parseInt(part, 10));
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year
+        && date.getUTCMonth() === month - 1
+        && date.getUTCDate() === day;
+}
+function fieldChoiceValue(choice) {
+    return choice.value ?? choice.label;
+}
+function isMissingScalar(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+function decimalPlaces(value) {
+    if (Number.isInteger(value))
+        return 0;
+    const text = Math.abs(value).toString();
+    if (text.includes('e') || text.includes('E')) {
+        const match = /e-?(\d+)/i.exec(text);
+        return match ? Number.parseInt(match[1], 10) : 0;
+    }
+    const dot = text.indexOf('.');
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+function alignsToStep(value, step) {
+    if (!(step > 0))
+        return true;
+    const quotient = value / step;
+    return Math.abs(quotient - Math.round(quotient)) < 1e-9;
+}
+function numericBound(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function dateBound(value) {
+    return typeof value === 'string' && isValidCalendarDate(value) ? value : undefined;
+}
+function validateScalarValue(spec, value) {
+    switch (spec.type) {
+        case 'boolean': {
+            if (typeof value !== 'boolean')
+                return `${spec.label} must be true or false`;
+            return null;
+        }
+        case 'multiSelect': {
+            if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string' && entry.trim())) {
+                return `${spec.label} must be a list of choices`;
+            }
+            if (!spec.allowOther) {
+                const allowed = new Set((spec.choices ?? []).map(fieldChoiceValue));
+                for (const entry of value) {
+                    if (!allowed.has(entry))
+                        return `${spec.label} contains an invalid choice`;
+                }
+            }
+            return null;
+        }
+        case 'date': {
+            if (typeof value !== 'string' || !isValidCalendarDate(value.trim())) {
+                return `${spec.label} must be a valid date (YYYY-MM-DD)`;
+            }
+            const date = value.trim();
+            const min = dateBound(spec.min);
+            const max = dateBound(spec.max);
+            if (min && date < min)
+                return `${spec.label} must be on or after ${min}`;
+            if (max && date > max)
+                return `${spec.label} must be on or before ${max}`;
+            return null;
+        }
+        case 'number':
+        case 'currency': {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return `${spec.label} must be a number`;
+            }
+            const min = numericBound(spec.min);
+            const max = numericBound(spec.max);
+            if (min !== undefined && value < min)
+                return `${spec.label} must be at least ${min}`;
+            if (max !== undefined && value > max)
+                return `${spec.label} must be at most ${max}`;
+            const precision = spec.type === 'currency'
+                ? (spec.precision ?? 2)
+                : spec.precision;
+            if (precision !== undefined && decimalPlaces(value) > precision) {
+                return `${spec.label} must have at most ${precision} decimal place${precision === 1 ? '' : 's'}`;
+            }
+            if (spec.type === 'number' && spec.step !== undefined && !alignsToStep(value, spec.step)) {
+                return `${spec.label} must be a multiple of ${spec.step}`;
+            }
+            return null;
+        }
+        case 'select':
+        case 'searchSelect': {
+            if (typeof value !== 'string')
+                return `${spec.label} must be text`;
+            if (!spec.allowOther) {
+                const allowed = new Set((spec.choices ?? []).map(fieldChoiceValue));
+                if (!allowed.has(value))
+                    return `${spec.label} contains an invalid choice`;
+            }
+            return null;
+        }
+        case 'text':
+        case 'textarea':
+        default: {
+            if (typeof value !== 'string')
+                return `${spec.label} must be text`;
+            return null;
+        }
+    }
+}
+function validateLineItemColumnValue(column, value) {
+    return validateScalarValue({
+        type: column.type,
+        label: column.label,
+        choices: column.choices,
+        allowOther: column.allowOther,
+        min: column.min,
+        max: column.max,
+        step: column.step,
+        precision: column.precision,
+    }, value);
+}
+function validateLineItemsValue(field, raw) {
+    if (!Array.isArray(raw))
+        return `${field.label} must be a list of rows`;
+    const columns = field.columns ?? [];
+    const minRows = field.minRows;
+    const maxRows = field.maxRows !== undefined
+        ? Math.min(field.maxRows, RUNTIME_CARD_LIMITS.lineItemRows)
+        : RUNTIME_CARD_LIMITS.lineItemRows;
+    if (raw.length > maxRows)
+        return `${field.label} allows at most ${maxRows} rows`;
+    if (minRows !== undefined && raw.length < minRows) {
+        return `${field.label} requires at least ${minRows} row${minRows === 1 ? '' : 's'}`;
+    }
+    if (field.required && raw.length === 0)
+        return `${field.label} is required`;
+    const columnIds = new Set(columns.map((column) => column.id));
+    for (let index = 0; index < raw.length; index += 1) {
+        const row = raw[index];
+        if (!isRecord(row))
+            return `${field.label}: row ${index + 1} must be an object`;
+        for (const key of Object.keys(row)) {
+            if (!columnIds.has(key))
+                return `${field.label}: row ${index + 1} has unknown column "${key}"`;
+        }
+        for (const column of columns) {
+            const cell = row[column.id];
+            const missing = isMissingScalar(cell);
+            if (column.required && missing) {
+                return `${field.label}: ${column.label} is required in row ${index + 1}`;
+            }
+            if (missing)
+                continue;
+            const error = validateLineItemColumnValue(column, cell);
+            if (error)
+                return `${field.label}: row ${index + 1}: ${error}`;
+        }
+    }
+    return null;
+}
+export function validateRuntimeCardFieldValues(input) {
+    const fields = input.actionFields;
+    if (!input.actionId || !fields || fields.length === 0)
+        return null;
+    const values = input.values ?? {};
+    const allowedIds = new Set(fields.map((field) => field.id));
+    for (const key of Object.keys(values)) {
+        if (!allowedIds.has(key))
+            return `Unknown field: ${key}`;
+    }
+    for (const field of fields) {
+        const raw = values[field.id];
+        if (field.type === 'lineItems') {
+            if (raw === undefined || raw === null) {
+                if (field.required)
+                    return `${field.label} is required`;
+                continue;
+            }
+            const error = validateLineItemsValue(field, raw);
+            if (error)
+                return error;
+            continue;
+        }
+        if (field.required && isMissingScalar(raw))
+            return `${field.label} is required`;
+        if (raw === undefined || raw === null || raw === '')
+            continue;
+        const error = validateScalarValue(field, raw);
+        if (error)
+            return error;
+    }
+    return null;
+}

package/package.json

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