@canonmsg/backend-contracts 5.4.1 → 6.0.0

package/dist/apiErrors.d.ts

@@ -0,0 +1 @@
+export declare const MESSAGE_ADMISSION_REQUIRED_CODE: "MESSAGE_ADMISSION_REQUIRED";

package/dist/apiErrors.js

@@ -0,0 +1 @@
+export const MESSAGE_ADMISSION_REQUIRED_CODE = 'MESSAGE_ADMISSION_REQUIRED';

package/dist/canon-verbs.limits.json

@@ -64,7 +64,8 @@
     "runtimeOptionValue": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
     "workspaceOptionId": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
     "runtimeHandleKey": "^[A-Za-z0-9_.:-]{1,80}$",
-    "runtimeControlId": "^[A-Za-z0-9_-]{1,80}$"
+    "runtimeControlId": "^[A-Za-z0-9_-]{1,80}$",
+    "resumableUploadId": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
   },
   "byteSemantics": {
     "send_to.text": "utf8_bytes<=messageTextBytes",

package/dist/canon-verbs.schema.json

@@ -107,7 +107,12 @@
         "url": {
           "type": "string",
           "minLength": 1,
-          "description": "Must come from /media/upload (Canon storage) or the GIF picker — server allowlist, fail-closed (functions/src/utils/mediaUploadSafety.ts)."
+          "description": "Must come from a canonical Canon upload/finalization response or the GIF picker — server allowlist, fail-closed (functions/src/utils/mediaUploadSafety.ts)."
+        },
+        "uploadId": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
+          "description": "Server-issued resumable identity. Preserve it from finalization so the durable message transaction can validate and retain initially temporary media."
         },
         "mimeType": {
           "type": "string"

package/dist/cjs/apiErrors.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGE_ADMISSION_REQUIRED_CODE = void 0;
+exports.MESSAGE_ADMISSION_REQUIRED_CODE = 'MESSAGE_ADMISSION_REQUIRED';

package/dist/cjs/index.js

@@ -24,11 +24,11 @@ __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
 __exportStar(require("./agentSearch.js"), exports);
 __exportStar(require("./contactRequest.js"), exports);
-__exportStar(require("./contactSources.js"), exports);
 __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);
 __exportStar(require("./accessPolicy.js"), exports);
+__exportStar(require("./apiErrors.js"), exports);
 __exportStar(require("./firestoreValues.js"), exports);
 __exportStar(require("./moderation.js"), exports);
 __exportStar(require("./selfContext.js"), exports);

package/dist/cjs/media.js

@@ -83,6 +83,11 @@ function normalizeStoredAttachments(value) {
         if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
             return null;
         }
+        if (candidate.uploadId !== undefined
+            && (typeof candidate.uploadId !== 'string'
+                || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(candidate.uploadId))) {
+            return null;
+        }
         const sizeBytes = normalizeAttachmentNumber(candidate.sizeBytes);
         const width = normalizeAttachmentNumber(candidate.width);
         const height = normalizeAttachmentNumber(candidate.height);
@@ -90,6 +95,7 @@ function normalizeStoredAttachments(value) {
         attachments.push({
             kind: candidate.kind,
             url: candidate.url,
+            ...(candidate.uploadId ? { uploadId: candidate.uploadId } : {}),
             ...(typeof candidate.mimeType === 'string' && candidate.mimeType ? { mimeType: candidate.mimeType } : {}),
             ...(typeof candidate.fileName === 'string' && candidate.fileName ? { fileName: candidate.fileName } : {}),
             ...(sizeBytes !== undefined ? { sizeBytes } : {}),

package/dist/cjs/verbContract.js

@@ -82,6 +82,8 @@ exports.VERB_ID_PATTERNS = {
     workspaceOptionId: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
     runtimeHandleKey: '^[A-Za-z0-9_.:-]{1,80}$',
     runtimeControlId: '^[A-Za-z0-9_-]{1,80}$',
+    /** UUID issued by Canon's resumable-media session endpoint. */
+    resumableUploadId: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$',
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement

package/dist/cjs/verbSchemas.js

@@ -93,9 +93,15 @@ const mediaAttachmentDef = {
         url: {
             type: 'string',
             minLength: 1,
-            description: 'Must come from /media/upload (Canon storage) or the GIF picker — server '
+            description: 'Must come from a canonical Canon upload/finalization response or the GIF picker — server '
                 + 'allowlist, fail-closed (functions/src/utils/mediaUploadSafety.ts).',
         },
+        uploadId: {
+            type: 'string',
+            pattern: verbContract_js_1.VERB_ID_PATTERNS.resumableUploadId,
+            description: 'Server-issued resumable identity. Preserve it from finalization so the durable message '
+                + 'transaction can validate and retain initially temporary media.',
+        },
         mimeType: { type: 'string' },
         fileName: { type: 'string' },
         sizeBytes: { type: 'number', minimum: 0 },

package/dist/index.d.ts

@@ -8,11 +8,11 @@ export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
 export * from './contactRequest.js';
-export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';

package/dist/index.js

@@ -8,11 +8,11 @@ export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
 export * from './contactRequest.js';
-export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';

package/dist/media.d.ts

@@ -2,6 +2,12 @@ export type MediaAttachmentKind = 'image' | 'audio' | 'video' | 'file';
 export interface MediaAttachment {
     kind: MediaAttachmentKind;
     url: string;
+    /**
+     * Server-issued identity for a finalized resumable upload. The send path
+     * uses this to retain temporary canonical media atomically with the message.
+     * Legacy/base64 uploads intentionally omit it.
+     */
+    uploadId?: string;
     mimeType?: string;
     fileName?: string;
     sizeBytes?: number;

package/dist/media.js

@@ -75,6 +75,11 @@ export function normalizeStoredAttachments(value) {
         if (typeof candidate.url !== 'string' || candidate.url.length === 0) {
             return null;
         }
+        if (candidate.uploadId !== undefined
+            && (typeof candidate.uploadId !== 'string'
+                || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(candidate.uploadId))) {
+            return null;
+        }
         const sizeBytes = normalizeAttachmentNumber(candidate.sizeBytes);
         const width = normalizeAttachmentNumber(candidate.width);
         const height = normalizeAttachmentNumber(candidate.height);
@@ -82,6 +87,7 @@ export function normalizeStoredAttachments(value) {
         attachments.push({
             kind: candidate.kind,
             url: candidate.url,
+            ...(candidate.uploadId ? { uploadId: candidate.uploadId } : {}),
             ...(typeof candidate.mimeType === 'string' && candidate.mimeType ? { mimeType: candidate.mimeType } : {}),
             ...(typeof candidate.fileName === 'string' && candidate.fileName ? { fileName: candidate.fileName } : {}),
             ...(sizeBytes !== undefined ? { sizeBytes } : {}),

package/dist/verbContract.d.ts

@@ -77,6 +77,8 @@ export declare const VERB_ID_PATTERNS: {
     readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
     readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
     readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
+    /** UUID issued by Canon's resumable-media session endpoint. */
+    readonly resumableUploadId: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$";
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement
@@ -246,8 +248,10 @@ export declare const VERB_NATIVE_METADATA_KEYS: readonly ["runtime", "method", "
 export declare function normalizeVerbNativeMetadata(value: unknown): VerbNativeMetadata | undefined;
 export interface VerbMediaAttachment {
     kind: 'image' | 'audio' | 'video' | 'file';
-    /** Must come from /media/upload (Canon storage) or the GIF picker — server allowlisted. */
+    /** Must come from a canonical Canon upload/finalization response or the GIF picker. */
     url: string;
+    /** Server-issued resumable identity; preserve it so durable sends retain temporary media. */
+    uploadId?: string;
     mimeType?: string;
     fileName?: string;
     sizeBytes?: number;
@@ -846,6 +850,8 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
         readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
         readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
         readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
+        /** UUID issued by Canon's resumable-media session endpoint. */
+        readonly resumableUploadId: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$";
     };
     readonly byteSemantics: {
         readonly 'send_to.text': "utf8_bytes<=messageTextBytes";

package/dist/verbContract.js

@@ -76,6 +76,8 @@ export const VERB_ID_PATTERNS = {
     workspaceOptionId: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
     runtimeHandleKey: '^[A-Za-z0-9_.:-]{1,80}$',
     runtimeControlId: '^[A-Za-z0-9_-]{1,80}$',
+    /** UUID issued by Canon's resumable-media session endpoint. */
+    resumableUploadId: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$',
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement

package/dist/verbSchemas.d.ts

@@ -253,6 +253,11 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                     readonly minLength: 1;
                     readonly description: string;
                 };
+                readonly uploadId: {
+                    readonly type: "string";
+                    readonly pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$";
+                    readonly description: string;
+                };
                 readonly mimeType: {
                     readonly type: "string";
                 };

package/dist/verbSchemas.js

@@ -88,9 +88,15 @@ const mediaAttachmentDef = {
         url: {
             type: 'string',
             minLength: 1,
-            description: 'Must come from /media/upload (Canon storage) or the GIF picker — server '
+            description: 'Must come from a canonical Canon upload/finalization response or the GIF picker — server '
                 + 'allowlist, fail-closed (functions/src/utils/mediaUploadSafety.ts).',
         },
+        uploadId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.resumableUploadId,
+            description: 'Server-issued resumable identity. Preserve it from finalization so the durable message '
+                + 'transaction can validate and retain initially temporary media.',
+        },
         mimeType: { type: 'string' },
         fileName: { type: 'string' },
         sizeBytes: { type: 'number', minimum: 0 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "5.4.1",
+  "version": "6.0.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.10.0",
+    "@canonmsg/rich-cards": "^0.10.2",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",

package/dist/cjs/contactSources.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADMISSION_GRANTING_SOURCES = void 0;
-exports.isAdmissionGrantingContactSource = isAdmissionGrantingContactSource;
-/**
- * Sources that represent a user-initiated relationship which grants admission
- * past `inboundPolicy: 'approval-required'` and
- * `groupJoinPolicy: 'approval-required'`.
- *
- * - `contact_request`: an explicit approval flow.
- * - `direct_add`: the user added the other side directly.
- * - `link` / `qr`: out-of-band invitations that imply consent.
- * - `group`: established by being in a shared group.
- * - `phone_book`: included intentionally — if a human has a registered Canon
- *   user in their device contacts, that is enough to start a human-human DM
- *   without a separate Canon request.
- * - `open_inbound_message`: the unified source written when a delivered direct
- *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
- *   consented to open inbound; the resulting mutual contact is real.
- *
- * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
- * regardless of source — ordering lives in `functions/src/utils/access.ts`
- * (`evaluatePolicy` / `buildPolicyContext`).
- */
-const ADMISSION_GRANTING_CONTACT_SOURCES = [
-    'contact_request',
-    'direct_add',
-    'link',
-    'qr',
-    'group',
-    'phone_book',
-    'open_inbound_message',
-];
-exports.ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
-/**
- * Returns true if a contact-doc source counts as an admission-granting
- * relationship. `null` / `undefined` (no doc, or doc with a missing source)
- * both return `false` — every contact doc must have an explicit source after
- * the cleanup.
- */
-function isAdmissionGrantingContactSource(source) {
-    if (source === null || source === undefined)
-        return false;
-    return exports.ADMISSION_GRANTING_SOURCES.has(source);
-}

package/dist/contactSources.d.ts

@@ -1,31 +0,0 @@
-/**
- * Sources that represent a user-initiated relationship which grants admission
- * past `inboundPolicy: 'approval-required'` and
- * `groupJoinPolicy: 'approval-required'`.
- *
- * - `contact_request`: an explicit approval flow.
- * - `direct_add`: the user added the other side directly.
- * - `link` / `qr`: out-of-band invitations that imply consent.
- * - `group`: established by being in a shared group.
- * - `phone_book`: included intentionally — if a human has a registered Canon
- *   user in their device contacts, that is enough to start a human-human DM
- *   without a separate Canon request.
- * - `open_inbound_message`: the unified source written when a delivered direct
- *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
- *   consented to open inbound; the resulting mutual contact is real.
- *
- * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
- * regardless of source — ordering lives in `functions/src/utils/access.ts`
- * (`evaluatePolicy` / `buildPolicyContext`).
- */
-declare const ADMISSION_GRANTING_CONTACT_SOURCES: readonly ["contact_request", "direct_add", "link", "qr", "group", "phone_book", "open_inbound_message"];
-export type AdmissionGrantingContactSource = (typeof ADMISSION_GRANTING_CONTACT_SOURCES)[number];
-export declare const ADMISSION_GRANTING_SOURCES: ReadonlySet<AdmissionGrantingContactSource>;
-/**
- * Returns true if a contact-doc source counts as an admission-granting
- * relationship. `null` / `undefined` (no doc, or doc with a missing source)
- * both return `false` — every contact doc must have an explicit source after
- * the cleanup.
- */
-export declare function isAdmissionGrantingContactSource(source: string | null | undefined): boolean;
-export {};

package/dist/contactSources.js

@@ -1,41 +0,0 @@
-/**
- * Sources that represent a user-initiated relationship which grants admission
- * past `inboundPolicy: 'approval-required'` and
- * `groupJoinPolicy: 'approval-required'`.
- *
- * - `contact_request`: an explicit approval flow.
- * - `direct_add`: the user added the other side directly.
- * - `link` / `qr`: out-of-band invitations that imply consent.
- * - `group`: established by being in a shared group.
- * - `phone_book`: included intentionally — if a human has a registered Canon
- *   user in their device contacts, that is enough to start a human-human DM
- *   without a separate Canon request.
- * - `open_inbound_message`: the unified source written when a delivered direct
- *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
- *   consented to open inbound; the resulting mutual contact is real.
- *
- * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
- * regardless of source — ordering lives in `functions/src/utils/access.ts`
- * (`evaluatePolicy` / `buildPolicyContext`).
- */
-const ADMISSION_GRANTING_CONTACT_SOURCES = [
-    'contact_request',
-    'direct_add',
-    'link',
-    'qr',
-    'group',
-    'phone_book',
-    'open_inbound_message',
-];
-export const ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
-/**
- * Returns true if a contact-doc source counts as an admission-granting
- * relationship. `null` / `undefined` (no doc, or doc with a missing source)
- * both return `false` — every contact doc must have an explicit source after
- * the cleanup.
- */
-export function isAdmissionGrantingContactSource(source) {
-    if (source === null || source === undefined)
-        return false;
-    return ADMISSION_GRANTING_SOURCES.has(source);
-}