@canonmsg/backend-contracts 1.7.1 → 1.8.1

package/dist/restEndpoints.js

@@ -0,0 +1,234 @@
+// Wire contract v1 — request/response schemas for the agent-facing "Canon op"
+// REST surface the bridge proxies (bridge-local-api.md §B).
+//
+// Grounded in the Functions handlers (functions/src/api/*) and the canonical
+// consumer (@canonmsg/core CanonClient) — request bodies mirror what clients
+// send today, response schemas mirror what the handlers emit. This is a
+// re-expression of current behavior, not a redesign.
+import { z } from 'zod';
+import { MediaAttachmentSchema } from './media.js';
+import { SerializedContentTypeSchema, SerializedMessageSchema, SerializedReactionsSchema, } from './message.js';
+import { InboundDispositionSchema } from './turnProtocol.js';
+// ── Shared fragments ───────────────────────────────────────────────────
+export const RestOkResponseSchema = z.looseObject({
+    success: z.boolean().optional(),
+});
+/** GET …/messages items — the serialized message plus the soft-delete flag. */
+export const RestMessageSchema = SerializedMessageSchema.extend({
+    deleted: z.boolean().optional(),
+});
+/**
+ * STRICT WRITES, TOLERANT READS: this is a READ schema over live production
+ * data, so it must describe what Firestore actually holds — not what today's
+ * writers produce. The GET /conversations serializer
+ * (functions/src/api/getConversations.ts) passes `lastMessage` fields through
+ * from the conversation doc, and legacy rows (pre-refactor writes,
+ * deleted-message repair) hold explicit nulls:
+ * - `text` is serialized `?? null` and `timestamp` as
+ *   `?.toDate?.()?.toISOString() ?? null` — both emit null by construction.
+ * - `senderId` / `senderType` / `contentType` are raw pass-throughs; live
+ *   rows exist with all three null (the getConversations "ghost fix" comment
+ *   acknowledges null senderId).
+ * - conversation `createdAt` is also serialized `?? null`.
+ * Writers (onMessageCreated / deletedMessageRepair) stay strict — they always
+ * produce the full shape; only the read contract admits the legacy nulls.
+ */
+export const RestConversationLastMessageSchema = z.looseObject({
+    text: z.string().nullable(),
+    messageId: z.string().optional(),
+    senderId: z.string().nullable().optional(),
+    senderType: z.enum(['human', 'ai_agent']).nullable().optional(),
+    contentType: SerializedContentTypeSchema.nullable().optional(),
+    timestamp: z.string().nullable(),
+});
+export const RestConversationSchema = z.looseObject({
+    id: z.string(),
+    type: z.enum(['direct', 'group']),
+    name: z.string().nullable().optional(),
+    topic: z.string().nullable().optional(),
+    memberIds: z.array(z.string()),
+    isAgentChat: z.boolean().optional(),
+    /** Resolved agent behavior policy — opaque pass-through. */
+    behavior: z.record(z.string(), z.unknown()).optional(),
+    hasUnread: z.boolean().optional(),
+    lastMessage: RestConversationLastMessageSchema.nullable(),
+    createdAt: z.string().nullable().optional(),
+});
+export const RestContactSchema = z.object({
+    id: z.string(),
+    source: z.string(),
+    addedAt: z.string().nullable(),
+    displayNameOverride: z.string().nullable(),
+});
+export const RestSessionSelectionSchema = z.union([
+    z.object({ mode: z.enum(['new', 'continue_latest', 'continue_or_create']) }),
+    z.object({ mode: z.literal('specific'), conversationId: z.string() }),
+]);
+// ── POST /messages/send ────────────────────────────────────────────────
+export const SendMessageRequestSchema = z.object({
+    conversationId: z.string(),
+    text: z.string().optional(),
+    /** Client-supplied idempotency id. */
+    messageId: z.string().optional(),
+    contentType: SerializedContentTypeSchema.optional(),
+    replyTo: z.string().optional(),
+    replyToPosition: z.number().optional(),
+    attachments: z.array(MediaAttachmentSchema).optional(),
+    contactCardUserId: z.string().optional(),
+    mentions: z.array(z.string()).optional(),
+    selfContextId: z.string().nullable().optional(),
+    /** Structured metadata (turn protocol, approval cards, …). */
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const SendMessageResponseSchema = z.object({
+    messageId: z.string(),
+});
+// ── POST /messages/react ───────────────────────────────────────────────
+export const ReactRequestSchema = z.object({
+    conversationId: z.string(),
+    messageId: z.string(),
+    emoji: z.string(),
+});
+export const ReactResponseSchema = z.object({
+    success: z.boolean(),
+    action: z.enum(['added', 'removed']),
+    reactions: SerializedReactionsSchema,
+});
+// ── POST /messages/forward ─────────────────────────────────────────────
+export const ForwardMessageRequestSchema = z.object({
+    sourceConversationId: z.string(),
+    targetConversationId: z.string(),
+    messageId: z.string(),
+    text: z.string().optional(),
+});
+export const ForwardMessageResponseSchema = z.object({
+    messageId: z.string(),
+    targetConversationId: z.string(),
+    forwardedFrom: z.object({
+        sourceConversationId: z.string(),
+        messageId: z.string(),
+    }),
+});
+// ── DELETE /conversations/:id/messages/:id, POST …/read, PATCH …/disposition ──
+export const DeleteMessageResponseSchema = RestOkResponseSchema;
+export const MarkReadResponseSchema = RestOkResponseSchema;
+export const UpdateDispositionRequestSchema = z.object({
+    inboundDisposition: InboundDispositionSchema,
+});
+// ── GET /conversations + GET …/messages ────────────────────────────────
+export const ConversationsResponseSchema = z.object({
+    conversations: z.array(RestConversationSchema),
+});
+/** Query params: limit, before, includeBehavior. */
+export const GetMessagesQuerySchema = z.object({
+    limit: z.string().optional(),
+    before: z.string().optional(),
+    includeBehavior: z.string().optional(),
+});
+export const MessagesPageResponseSchema = z.looseObject({
+    messages: z.array(RestMessageSchema),
+    /** Present with includeBehavior=1. */
+    behavior: z.record(z.string(), z.unknown()).optional(),
+    activeSelfContextIdByMessageId: z.record(z.string(), z.string()).optional(),
+    selfContexts: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+// ── POST /conversations/create ─────────────────────────────────────────
+export const CreateConversationRequestSchema = z.object({
+    type: z.enum(['direct', 'group']),
+    targetUserId: z.string().optional(),
+    memberIds: z.array(z.string()).optional(),
+    name: z.string().optional(),
+    /** Initial session config for first-party coding agents — opaque pass-through. */
+    sessionConfig: z.record(z.string(), z.unknown()).nullable().optional(),
+    sessionSelection: RestSessionSelectionSchema.optional(),
+});
+export const CreateConversationResponseSchema = z.object({
+    conversationId: z.string(),
+    created: z.boolean().optional(),
+    reused: z.boolean().optional(),
+    sessionSelection: z.enum(['new', 'continue_latest', 'continue_or_create', 'specific']).optional(),
+});
+// ── Contacts / admission ───────────────────────────────────────────────
+export const CreateContactRequestRequestSchema = z.object({
+    targetId: z.string(),
+    message: z.string().optional(),
+});
+export const CreateContactRequestResponseSchema = z.union([
+    z.looseObject({ status: z.literal('open') }),
+    z.looseObject({ status: z.enum(['created', 'duplicate']), requestId: z.string() }),
+    /** Legacy "already a contact" body. */
+    z.looseObject({ message: z.string() }),
+]);
+export const ContactsResponseSchema = z.object({
+    contacts: z.array(RestContactSchema),
+});
+export const ResolveAdmissionRequestSchema = z.union([
+    z.object({ targetUserId: z.string() }),
+    z.object({ canonContactId: z.string() }),
+]);
+export const ResolveAdmissionResponseSchema = z.looseObject({
+    resolvedTargetUserId: z.string().nullable().optional(),
+    target: z.looseObject({
+        id: z.string(),
+        canonContactId: z.string().optional(),
+        displayName: z.string().optional(),
+        avatarUrl: z.string().nullable().optional(),
+        about: z.string().optional(),
+        userType: z.enum(['human', 'ai_agent']).optional(),
+        discoverable: z.boolean().optional(),
+        inboundPolicy: z.enum(['open', 'approval-required', 'owner-only']).optional(),
+        groupJoinPolicy: z.enum(['open', 'approval-required', 'owner-only']).optional(),
+    }).nullable(),
+    admission: z.looseObject({
+        state: z.enum([
+            'self',
+            'not-found',
+            'allowed',
+            'request-required',
+            'pending-outbound',
+            'blocked',
+            'inactive',
+            'owner-only',
+        ]),
+        canMessage: z.boolean(),
+        canRequestContact: z.boolean(),
+        isContact: z.boolean(),
+        pendingRequestId: z.string().optional(),
+        blockedByViewer: z.boolean().optional(),
+        blockedByTarget: z.boolean().optional(),
+    }),
+});
+// ── Typing / streaming ─────────────────────────────────────────────────
+export const SetTypingRequestSchema = z.object({
+    conversationId: z.string(),
+    typing: z.boolean(),
+    status: z.enum(['thinking', 'typing']).optional(),
+});
+/** POST /streaming — the legacy REST facade over the RTDB streaming bubble. */
+export const SetStreamingRequestSchema = z.union([
+    z.object({
+        conversationId: z.string(),
+        text: z.string(),
+        status: z.string(),
+        messageId: z.string(),
+        turnId: z.string().nullable().optional(),
+        /** TurnOutputBlock[] — opaque pass-through. */
+        blocks: z.array(z.record(z.string(), z.unknown())).optional(),
+    }),
+    z.object({
+        conversationId: z.string(),
+        streaming: z.literal(false),
+    }),
+]);
+// ── Media upload ───────────────────────────────────────────────────────
+export const UploadMediaRequestSchema = z.object({
+    conversationId: z.string(),
+    mimeType: z.string(),
+    /** Base64-encoded file content. */
+    data: z.string(),
+    fileName: z.string().optional(),
+});
+export const UploadMediaResponseSchema = z.object({
+    url: z.string(),
+    attachment: MediaAttachmentSchema,
+});

package/dist/runtimeCardFields.d.ts

@@ -1,4 +1,17 @@
-export type RuntimeCardFieldType = 'text' | 'textarea' | 'select' | 'multiSelect' | 'boolean' | 'date' | 'number' | 'currency' | 'searchSelect' | 'lineItems';
+import { z } from 'zod';
+export declare const RuntimeCardFieldTypeSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    date: "date";
+    text: "text";
+    textarea: "textarea";
+    select: "select";
+    multiSelect: "multiSelect";
+    currency: "currency";
+    searchSelect: "searchSelect";
+    lineItems: "lineItems";
+}>;
+export type RuntimeCardFieldType = z.infer<typeof RuntimeCardFieldTypeSchema>;
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -9,44 +22,104 @@ export declare const RUNTIME_CARD_LIMITS: {
     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 const RuntimeCardFieldChoiceSchema: z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RuntimeCardFieldChoice = z.infer<typeof RuntimeCardFieldChoiceSchema>;
+export declare const RuntimeCardLineItemColumnTypeSchema: z.ZodEnum<{
+    number: "number";
+    date: "date";
+    text: "text";
+    select: "select";
+    currency: "currency";
+}>;
+export type RuntimeCardLineItemColumnType = z.infer<typeof RuntimeCardLineItemColumnTypeSchema>;
+export declare const RuntimeCardLineItemColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        date: "date";
+        text: "text";
+        select: "select";
+        currency: "currency";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        preview: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+    precision: z.ZodOptional<z.ZodNumber>;
+    currencyCode: z.ZodOptional<z.ZodString>;
+    allowOther: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RuntimeCardLineItemColumn = z.infer<typeof RuntimeCardLineItemColumnSchema>;
+export declare const RuntimeCardFieldSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+        text: "text";
+        textarea: "textarea";
+        select: "select";
+        multiSelect: "multiSelect";
+        currency: "currency";
+        searchSelect: "searchSelect";
+        lineItems: "lineItems";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        preview: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    allowOther: z.ZodOptional<z.ZodBoolean>;
+    sensitive: z.ZodOptional<z.ZodBoolean>;
+    min: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    max: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    step: z.ZodOptional<z.ZodNumber>;
+    precision: z.ZodOptional<z.ZodNumber>;
+    currencyCode: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            date: "date";
+            text: "text";
+            select: "select";
+            currency: "currency";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            preview: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodNumber>;
+        precision: z.ZodOptional<z.ZodNumber>;
+        currencyCode: z.ZodOptional<z.ZodString>;
+        allowOther: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    minRows: z.ZodOptional<z.ZodNumber>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RuntimeCardField = z.infer<typeof RuntimeCardFieldSchema>;
 export declare function validateRuntimeCardFieldValues(input: {
     actionId: string | undefined;
     actionFields: ReadonlyArray<RuntimeCardField> | undefined;

package/dist/runtimeCardFields.js

@@ -1,3 +1,16 @@
+import { z } from 'zod';
+export const RuntimeCardFieldTypeSchema = z.enum([
+    '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.
@@ -8,6 +21,50 @@ export const RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+export const RuntimeCardFieldChoiceSchema = z.object({
+    label: z.string(),
+    value: z.string().optional(),
+    description: z.string().optional(),
+    preview: z.string().optional(),
+});
+export const RuntimeCardLineItemColumnTypeSchema = z.enum([
+    'text',
+    'number',
+    'currency',
+    'date',
+    'select',
+]);
+export const RuntimeCardLineItemColumnSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    type: RuntimeCardLineItemColumnTypeSchema,
+    required: z.boolean().optional(),
+    choices: z.array(RuntimeCardFieldChoiceSchema).optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    step: z.number().optional(),
+    precision: z.number().optional(),
+    currencyCode: z.string().optional(),
+    allowOther: z.boolean().optional(),
+});
+export const RuntimeCardFieldSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    type: RuntimeCardFieldTypeSchema,
+    required: z.boolean().optional(),
+    placeholder: z.string().optional(),
+    choices: z.array(RuntimeCardFieldChoiceSchema).optional(),
+    allowOther: z.boolean().optional(),
+    sensitive: z.boolean().optional(),
+    min: z.union([z.number(), z.string()]).optional(),
+    max: z.union([z.number(), z.string()]).optional(),
+    step: z.number().optional(),
+    precision: z.number().optional(),
+    currencyCode: z.string().optional(),
+    columns: z.array(RuntimeCardLineItemColumnSchema).optional(),
+    minRows: z.number().optional(),
+    maxRows: z.number().optional(),
+});
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/schemas/agent-behavior-settings-record.schema.json

@@ -0,0 +1,48 @@
+{
+  "$id": "canon:AgentBehaviorSettingsRecordSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "participationStyle": {
+      "type": "string",
+      "enum": [
+        "natural",
+        "collaborative",
+        "mention-first",
+        "approval-gated",
+        "handoff-only",
+        "observer"
+      ]
+    },
+    "allowAgentToAgent": {
+      "type": "boolean"
+    },
+    "allowLongRunningCollaboration": {
+      "type": "boolean"
+    },
+    "requireMentionForGroupReplies": {
+      "type": "boolean"
+    },
+    "maxConsecutiveAgentTurns": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "instructions": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/bridge-connection-state-notification.schema.json

@@ -0,0 +1,19 @@
+{
+  "$id": "canon:BridgeConnectionStateNotificationSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "upstream": {
+      "type": "string",
+      "enum": [
+        "connected",
+        "reconnecting",
+        "down"
+      ]
+    }
+  },
+  "required": [
+    "upstream"
+  ],
+  "additionalProperties": false
+}

package/dist/schemas/bridge-get-attachment-params.schema.json

@@ -0,0 +1,24 @@
+{
+  "$id": "canon:BridgeGetAttachmentParamsSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "url": {
+      "type": "string"
+    },
+    "attachmentId": {
+      "type": "string"
+    },
+    "as": {
+      "type": "string",
+      "enum": [
+        "path",
+        "bytes"
+      ]
+    }
+  },
+  "required": [
+    "as"
+  ],
+  "additionalProperties": false
+}

package/dist/schemas/bridge-get-attachment-result.schema.json

@@ -0,0 +1,20 @@
+{
+  "$id": "canon:BridgeGetAttachmentResultSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string"
+    },
+    "bytes": {
+      "type": "string"
+    },
+    "mime": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "mime"
+  ],
+  "additionalProperties": false
+}

package/dist/schemas/bridge-hello-params.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "canon:BridgeHelloParamsSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "protocolVersion": {
+      "type": "number"
+    },
+    "clientType": {
+      "type": "string"
+    },
+    "wantFamilies": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "messages",
+          "contacts",
+          "typing_presence",
+          "runtime_turn",
+          "voice"
+        ]
+      }
+    },
+    "resumeCursor": {
+      "type": "string"
+    },
+    "runtimeDescriptor": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    }
+  },
+  "required": [
+    "protocolVersion",
+    "clientType",
+    "wantFamilies"
+  ],
+  "additionalProperties": false
+}