@canonmsg/backend-contracts 1.7.1 → 1.8.1

package/dist/cjs/restEndpoints.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadMediaResponseSchema = exports.UploadMediaRequestSchema = exports.SetStreamingRequestSchema = exports.SetTypingRequestSchema = exports.ResolveAdmissionResponseSchema = exports.ResolveAdmissionRequestSchema = exports.ContactsResponseSchema = exports.CreateContactRequestResponseSchema = exports.CreateContactRequestRequestSchema = exports.CreateConversationResponseSchema = exports.CreateConversationRequestSchema = exports.MessagesPageResponseSchema = exports.GetMessagesQuerySchema = exports.ConversationsResponseSchema = exports.UpdateDispositionRequestSchema = exports.MarkReadResponseSchema = exports.DeleteMessageResponseSchema = exports.ForwardMessageResponseSchema = exports.ForwardMessageRequestSchema = exports.ReactResponseSchema = exports.ReactRequestSchema = exports.SendMessageResponseSchema = exports.SendMessageRequestSchema = exports.RestSessionSelectionSchema = exports.RestContactSchema = exports.RestConversationSchema = exports.RestConversationLastMessageSchema = exports.RestMessageSchema = exports.RestOkResponseSchema = void 0;
+// 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.
+const zod_1 = require("zod");
+const media_js_1 = require("./media.js");
+const message_js_1 = require("./message.js");
+const turnProtocol_js_1 = require("./turnProtocol.js");
+// ── Shared fragments ───────────────────────────────────────────────────
+exports.RestOkResponseSchema = zod_1.z.looseObject({
+    success: zod_1.z.boolean().optional(),
+});
+/** GET …/messages items — the serialized message plus the soft-delete flag. */
+exports.RestMessageSchema = message_js_1.SerializedMessageSchema.extend({
+    deleted: zod_1.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.
+ */
+exports.RestConversationLastMessageSchema = zod_1.z.looseObject({
+    text: zod_1.z.string().nullable(),
+    messageId: zod_1.z.string().optional(),
+    senderId: zod_1.z.string().nullable().optional(),
+    senderType: zod_1.z.enum(['human', 'ai_agent']).nullable().optional(),
+    contentType: message_js_1.SerializedContentTypeSchema.nullable().optional(),
+    timestamp: zod_1.z.string().nullable(),
+});
+exports.RestConversationSchema = zod_1.z.looseObject({
+    id: zod_1.z.string(),
+    type: zod_1.z.enum(['direct', 'group']),
+    name: zod_1.z.string().nullable().optional(),
+    topic: zod_1.z.string().nullable().optional(),
+    memberIds: zod_1.z.array(zod_1.z.string()),
+    isAgentChat: zod_1.z.boolean().optional(),
+    /** Resolved agent behavior policy — opaque pass-through. */
+    behavior: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    hasUnread: zod_1.z.boolean().optional(),
+    lastMessage: exports.RestConversationLastMessageSchema.nullable(),
+    createdAt: zod_1.z.string().nullable().optional(),
+});
+exports.RestContactSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    source: zod_1.z.string(),
+    addedAt: zod_1.z.string().nullable(),
+    displayNameOverride: zod_1.z.string().nullable(),
+});
+exports.RestSessionSelectionSchema = zod_1.z.union([
+    zod_1.z.object({ mode: zod_1.z.enum(['new', 'continue_latest', 'continue_or_create']) }),
+    zod_1.z.object({ mode: zod_1.z.literal('specific'), conversationId: zod_1.z.string() }),
+]);
+// ── POST /messages/send ────────────────────────────────────────────────
+exports.SendMessageRequestSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    text: zod_1.z.string().optional(),
+    /** Client-supplied idempotency id. */
+    messageId: zod_1.z.string().optional(),
+    contentType: message_js_1.SerializedContentTypeSchema.optional(),
+    replyTo: zod_1.z.string().optional(),
+    replyToPosition: zod_1.z.number().optional(),
+    attachments: zod_1.z.array(media_js_1.MediaAttachmentSchema).optional(),
+    contactCardUserId: zod_1.z.string().optional(),
+    mentions: zod_1.z.array(zod_1.z.string()).optional(),
+    selfContextId: zod_1.z.string().nullable().optional(),
+    /** Structured metadata (turn protocol, approval cards, …). */
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+exports.SendMessageResponseSchema = zod_1.z.object({
+    messageId: zod_1.z.string(),
+});
+// ── POST /messages/react ───────────────────────────────────────────────
+exports.ReactRequestSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+    emoji: zod_1.z.string(),
+});
+exports.ReactResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    action: zod_1.z.enum(['added', 'removed']),
+    reactions: message_js_1.SerializedReactionsSchema,
+});
+// ── POST /messages/forward ─────────────────────────────────────────────
+exports.ForwardMessageRequestSchema = zod_1.z.object({
+    sourceConversationId: zod_1.z.string(),
+    targetConversationId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+    text: zod_1.z.string().optional(),
+});
+exports.ForwardMessageResponseSchema = zod_1.z.object({
+    messageId: zod_1.z.string(),
+    targetConversationId: zod_1.z.string(),
+    forwardedFrom: zod_1.z.object({
+        sourceConversationId: zod_1.z.string(),
+        messageId: zod_1.z.string(),
+    }),
+});
+// ── DELETE /conversations/:id/messages/:id, POST …/read, PATCH …/disposition ──
+exports.DeleteMessageResponseSchema = exports.RestOkResponseSchema;
+exports.MarkReadResponseSchema = exports.RestOkResponseSchema;
+exports.UpdateDispositionRequestSchema = zod_1.z.object({
+    inboundDisposition: turnProtocol_js_1.InboundDispositionSchema,
+});
+// ── GET /conversations + GET …/messages ────────────────────────────────
+exports.ConversationsResponseSchema = zod_1.z.object({
+    conversations: zod_1.z.array(exports.RestConversationSchema),
+});
+/** Query params: limit, before, includeBehavior. */
+exports.GetMessagesQuerySchema = zod_1.z.object({
+    limit: zod_1.z.string().optional(),
+    before: zod_1.z.string().optional(),
+    includeBehavior: zod_1.z.string().optional(),
+});
+exports.MessagesPageResponseSchema = zod_1.z.looseObject({
+    messages: zod_1.z.array(exports.RestMessageSchema),
+    /** Present with includeBehavior=1. */
+    behavior: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    activeSelfContextIdByMessageId: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    selfContexts: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())).optional(),
+});
+// ── POST /conversations/create ─────────────────────────────────────────
+exports.CreateConversationRequestSchema = zod_1.z.object({
+    type: zod_1.z.enum(['direct', 'group']),
+    targetUserId: zod_1.z.string().optional(),
+    memberIds: zod_1.z.array(zod_1.z.string()).optional(),
+    name: zod_1.z.string().optional(),
+    /** Initial session config for first-party coding agents — opaque pass-through. */
+    sessionConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
+    sessionSelection: exports.RestSessionSelectionSchema.optional(),
+});
+exports.CreateConversationResponseSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    created: zod_1.z.boolean().optional(),
+    reused: zod_1.z.boolean().optional(),
+    sessionSelection: zod_1.z.enum(['new', 'continue_latest', 'continue_or_create', 'specific']).optional(),
+});
+// ── Contacts / admission ───────────────────────────────────────────────
+exports.CreateContactRequestRequestSchema = zod_1.z.object({
+    targetId: zod_1.z.string(),
+    message: zod_1.z.string().optional(),
+});
+exports.CreateContactRequestResponseSchema = zod_1.z.union([
+    zod_1.z.looseObject({ status: zod_1.z.literal('open') }),
+    zod_1.z.looseObject({ status: zod_1.z.enum(['created', 'duplicate']), requestId: zod_1.z.string() }),
+    /** Legacy "already a contact" body. */
+    zod_1.z.looseObject({ message: zod_1.z.string() }),
+]);
+exports.ContactsResponseSchema = zod_1.z.object({
+    contacts: zod_1.z.array(exports.RestContactSchema),
+});
+exports.ResolveAdmissionRequestSchema = zod_1.z.union([
+    zod_1.z.object({ targetUserId: zod_1.z.string() }),
+    zod_1.z.object({ canonContactId: zod_1.z.string() }),
+]);
+exports.ResolveAdmissionResponseSchema = zod_1.z.looseObject({
+    resolvedTargetUserId: zod_1.z.string().nullable().optional(),
+    target: zod_1.z.looseObject({
+        id: zod_1.z.string(),
+        canonContactId: zod_1.z.string().optional(),
+        displayName: zod_1.z.string().optional(),
+        avatarUrl: zod_1.z.string().nullable().optional(),
+        about: zod_1.z.string().optional(),
+        userType: zod_1.z.enum(['human', 'ai_agent']).optional(),
+        discoverable: zod_1.z.boolean().optional(),
+        inboundPolicy: zod_1.z.enum(['open', 'approval-required', 'owner-only']).optional(),
+        groupJoinPolicy: zod_1.z.enum(['open', 'approval-required', 'owner-only']).optional(),
+    }).nullable(),
+    admission: zod_1.z.looseObject({
+        state: zod_1.z.enum([
+            'self',
+            'not-found',
+            'allowed',
+            'request-required',
+            'pending-outbound',
+            'blocked',
+            'inactive',
+            'owner-only',
+        ]),
+        canMessage: zod_1.z.boolean(),
+        canRequestContact: zod_1.z.boolean(),
+        isContact: zod_1.z.boolean(),
+        pendingRequestId: zod_1.z.string().optional(),
+        blockedByViewer: zod_1.z.boolean().optional(),
+        blockedByTarget: zod_1.z.boolean().optional(),
+    }),
+});
+// ── Typing / streaming ─────────────────────────────────────────────────
+exports.SetTypingRequestSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    typing: zod_1.z.boolean(),
+    status: zod_1.z.enum(['thinking', 'typing']).optional(),
+});
+/** POST /streaming — the legacy REST facade over the RTDB streaming bubble. */
+exports.SetStreamingRequestSchema = zod_1.z.union([
+    zod_1.z.object({
+        conversationId: zod_1.z.string(),
+        text: zod_1.z.string(),
+        status: zod_1.z.string(),
+        messageId: zod_1.z.string(),
+        turnId: zod_1.z.string().nullable().optional(),
+        /** TurnOutputBlock[] — opaque pass-through. */
+        blocks: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())).optional(),
+    }),
+    zod_1.z.object({
+        conversationId: zod_1.z.string(),
+        streaming: zod_1.z.literal(false),
+    }),
+]);
+// ── Media upload ───────────────────────────────────────────────────────
+exports.UploadMediaRequestSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    mimeType: zod_1.z.string(),
+    /** Base64-encoded file content. */
+    data: zod_1.z.string(),
+    fileName: zod_1.z.string().optional(),
+});
+exports.UploadMediaResponseSchema = zod_1.z.object({
+    url: zod_1.z.string(),
+    attachment: media_js_1.MediaAttachmentSchema,
+});

package/dist/cjs/runtimeCardFields.js

@@ -1,7 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIME_CARD_LIMITS = void 0;
+exports.RuntimeCardFieldSchema = exports.RuntimeCardLineItemColumnSchema = exports.RuntimeCardLineItemColumnTypeSchema = exports.RuntimeCardFieldChoiceSchema = exports.RUNTIME_CARD_LIMITS = exports.RuntimeCardFieldTypeSchema = void 0;
 exports.validateRuntimeCardFieldValues = validateRuntimeCardFieldValues;
+const zod_1 = require("zod");
+exports.RuntimeCardFieldTypeSchema = zod_1.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.
@@ -12,6 +25,50 @@ exports.RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+exports.RuntimeCardFieldChoiceSchema = zod_1.z.object({
+    label: zod_1.z.string(),
+    value: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    preview: zod_1.z.string().optional(),
+});
+exports.RuntimeCardLineItemColumnTypeSchema = zod_1.z.enum([
+    'text',
+    'number',
+    'currency',
+    'date',
+    'select',
+]);
+exports.RuntimeCardLineItemColumnSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    label: zod_1.z.string(),
+    type: exports.RuntimeCardLineItemColumnTypeSchema,
+    required: zod_1.z.boolean().optional(),
+    choices: zod_1.z.array(exports.RuntimeCardFieldChoiceSchema).optional(),
+    min: zod_1.z.number().optional(),
+    max: zod_1.z.number().optional(),
+    step: zod_1.z.number().optional(),
+    precision: zod_1.z.number().optional(),
+    currencyCode: zod_1.z.string().optional(),
+    allowOther: zod_1.z.boolean().optional(),
+});
+exports.RuntimeCardFieldSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    label: zod_1.z.string(),
+    type: exports.RuntimeCardFieldTypeSchema,
+    required: zod_1.z.boolean().optional(),
+    placeholder: zod_1.z.string().optional(),
+    choices: zod_1.z.array(exports.RuntimeCardFieldChoiceSchema).optional(),
+    allowOther: zod_1.z.boolean().optional(),
+    sensitive: zod_1.z.boolean().optional(),
+    min: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).optional(),
+    max: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).optional(),
+    step: zod_1.z.number().optional(),
+    precision: zod_1.z.number().optional(),
+    currencyCode: zod_1.z.string().optional(),
+    columns: zod_1.z.array(exports.RuntimeCardLineItemColumnSchema).optional(),
+    minRows: zod_1.z.number().optional(),
+    maxRows: zod_1.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/cjs/sendContextual.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEND_CONTEXTUAL_HTTP_STATUS = exports.SendContextualResponseSchema = exports.SendContextualStateResponseSchema = exports.SendContextualDeferredResponseSchema = exports.SendContextualMessagedResponseSchema = exports.SendContextualRequestSchema = exports.SendContextualSelfContextSchema = void 0;
+// Wire contract v1 — POST /messages/send-contextual as a FIRST-CLASS contract
+// (bridge-execution-plan Phase 3; owner decision 2026-07-03: the re-spec rides
+// contract v1, the transport stays as-is and the Bridge proxies it unchanged
+// in Phase 4).
+//
+// Grounded in functions/src/api/sendContextualMessage.ts (the handler's actual
+// parse + emissions) and @canonmsg/core's SendContextualMessageOptions/Result.
+// This mirrors CURRENT behavior — a re-spec, not a redesign.
+const zod_1 = require("zod");
+const restEndpoints_js_1 = require("./restEndpoints.js");
+exports.SendContextualSelfContextSchema = zod_1.z.object({
+    type: zod_1.z.literal('cross_session'),
+    /** Private agent self-context; server caps at 1000 chars. */
+    context: zod_1.z.string(),
+});
+/**
+ * Request body. Exactly ONE of targetConversationId (existing conversation) or
+ * targetUserId (open/reuse a direct conversation, contact-request fallback)
+ * must be present — the refinement enforces the handler's rule.
+ */
+exports.SendContextualRequestSchema = zod_1.z.object({
+    sourceConversationId: zod_1.z.string(),
+    /** Target arm 1: send into an existing conversation. */
+    targetConversationId: zod_1.z.string().optional(),
+    /** Target arm 2: resolve/create a direct conversation with this user. */
+    targetUserId: zod_1.z.string().optional(),
+    text: zod_1.z.string().optional(),
+    selfContext: exports.SendContextualSelfContextSchema,
+    /** Initial agent session config (agent targets) — opaque pass-through. */
+    sessionConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
+    sessionSelection: restEndpoints_js_1.RestSessionSelectionSchema.optional(),
+    /** Contact-request message when admission requires approval. */
+    requestMessage: zod_1.z.string().optional(),
+    /**
+     * SendMessageOptions passthrough (attachments, replyTo, metadata, …).
+     * May NOT carry selfContextId/selfContext — the handler rejects overrides
+     * of the self-context linkage fields.
+     */
+    messageOptions: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+}).refine((body) => (body.targetConversationId ? 1 : 0) + (body.targetUserId ? 1 : 0) === 1, { message: 'Provide exactly one targetConversationId or targetUserId' }).refine((body) => !body.messageOptions
+    || (!('selfContextId' in body.messageOptions) && !('selfContext' in body.messageOptions)), { message: 'messageOptions may not override self-context linkage fields' });
+// ── Response arms (exactly what the handler emits today) ───────────────
+/** HTTP 201 — message persisted (or idempotent replay) with self-context linked. */
+exports.SendContextualMessagedResponseSchema = zod_1.z.object({
+    status: zod_1.z.literal('messaged'),
+    messageId: zod_1.z.string(),
+    conversationId: zod_1.z.string(),
+    selfContextId: zod_1.z.string(),
+    /** Present when the target conversation was opened by this call. */
+    created: zod_1.z.boolean().optional(),
+    reused: zod_1.z.boolean().optional(),
+    sessionSelection: zod_1.z.enum(['new', 'continue_latest', 'continue_or_create', 'specific']).optional(),
+});
+/**
+ * HTTP 202 — admission requires approval: a contact request was created
+ * (`requested`) or already pending (`pending`); the message is deferred as a
+ * contextual intent when a request id exists.
+ */
+exports.SendContextualDeferredResponseSchema = zod_1.z.object({
+    status: zod_1.z.enum(['requested', 'pending']),
+    requestId: zod_1.z.string().nullable(),
+    deferredIntentId: zod_1.z.string().nullable().optional(),
+});
+/**
+ * Terminal / retryable states:
+ * - setup_required (HTTP 202) — agent session setup must complete first.
+ * - blocked (HTTP 200)        — admission denied (block or policy).
+ * - unavailable (HTTP 200)    — target cannot be reached right now.
+ * - no_session (HTTP 404)     — session selection matched nothing.
+ */
+exports.SendContextualStateResponseSchema = zod_1.z.object({
+    status: zod_1.z.enum(['setup_required', 'blocked', 'unavailable', 'no_session']),
+    reason: zod_1.z.string(),
+});
+exports.SendContextualResponseSchema = zod_1.z.union([
+    exports.SendContextualMessagedResponseSchema,
+    exports.SendContextualDeferredResponseSchema,
+    exports.SendContextualStateResponseSchema,
+]);
+/** HTTP status the handler pairs with each response status. */
+exports.SEND_CONTEXTUAL_HTTP_STATUS = {
+    messaged: 201,
+    requested: 202,
+    pending: 202,
+    setup_required: 202,
+    blocked: 200,
+    unavailable: 200,
+    no_session: 404,
+};