@keemakr/event-sdk 0.2.0-dev-20261012160211

package/README.md

@@ -0,0 +1,41 @@
+# @keemakr/event-sdk
+
+Declare, publish, and consume typed Keemakr Events without accepting provider traffic directly in a
+Pack Runtime.
+
+An Event key is owned by its Pack namespace and one positive integer contract version. Core remains
+the authoritative validator and delivery ledger. Delivery is at least once, so direct external
+effects must use the stable delivery identity for idempotency.
+
+Consumer builds call `fetchEventContractArtifact` with a short-lived, tenant-scoped native access
+token in CI. Core applies Pack visibility, and the SDK rejects any artifact whose owner, key,
+version, or fingerprint differs from the build pin. Do not persist the access token in generated
+artifacts.
+
+## Runtime delivery endpoint
+
+A consuming Pack mounts one SDK-owned HTTP adapter at `/events/v1/deliver`:
+
+```ts
+import { handleEventDeliveryRequest } from '@keemakr/event-sdk';
+import { startReplenishment, retryIsolationProbe } from './consumers';
+
+export function POST(request: Request) {
+  return handleEventDeliveryRequest(request, [startReplenishment, retryIsolationProbe], {
+    audience: requireEnv('EVENT_RUNTIME_ORIGIN'),
+    coreUrl: requireEnv('KEEMAKR_CORE_URL'),
+  });
+}
+```
+
+The release manifest must set `runtime.event_url` to the full public endpoint, for example
+`https://inventory-consumer-v1.example/events/v1/deliver`. The URL is an immutable release pin and
+must be unique to that Pack release. A later release uses a different URL. The general
+`runtime.url` remains mutable and does not retarget accepted Event deliveries.
+
+`EVENT_RUNTIME_ORIGIN` is the URL origin used as the signed grant audience.
+`KEE_CORE_JWKS_URL` locates Core's JWKS for grant verification. `KEEMAKR_CORE_URL` is the Core API
+base used when a handler publishes an allowed child Event. The SDK compares tenant installation,
+Pack version, and deployment revision values from the signed grant with the delivery envelope. A
+release endpoint can therefore serve several tenant installations without tenant-specific runtime
+configuration.

package/dist/apps/channels.d.ts

@@ -0,0 +1,400 @@
+import { z } from 'zod';
+/**
+ * A customer message that reached a Pack's inbound handler through a Channel
+ * Binding. Core owns these contracts: a Pack subscribes to them and never
+ * redefines a provider's own events (PRD R9).
+ *
+ * The payload is what the handler may see, already routed and checked. The
+ * provider's raw fields are not here: tenant, Contact, handler and authority
+ * come from Core configuration, never from a provider payload (PRD R14).
+ */
+declare const message: z.ZodObject<{
+    conversation_id: z.ZodUUID;
+    owner_epoch: z.ZodNumber;
+    message: z.ZodObject<{
+        id: z.ZodUUID;
+        text: z.ZodString;
+        received_at: z.ZodISODateTime;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            byte_size: z.ZodNumber;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    identity: z.ZodEnum<{
+        anonymous: "anonymous";
+        identified: "identified";
+        verified: "verified";
+        conflict: "conflict";
+    }>;
+    contact_id: z.ZodNullable<z.ZodString>;
+    new_conversation: z.ZodBoolean;
+}, z.core.$strict>;
+export type ChannelMessageReceived = z.infer<typeof message>;
+/**
+ * An agent reply the provider accepted. Informational: the delivery that carries
+ * it permits no action, so a reply can never trigger another reply. Staff replies
+ * are not delivered, because a handler hears nothing while a person owns the
+ * conversation.
+ */
+declare const sentMessage: z.ZodObject<{
+    conversation_id: z.ZodUUID;
+    owner_epoch: z.ZodNumber;
+    message: z.ZodObject<{
+        id: z.ZodUUID;
+        text: z.ZodString;
+        sent_at: z.ZodISODateTime;
+    }, z.core.$strict>;
+    identity: z.ZodEnum<{
+        anonymous: "anonymous";
+        identified: "identified";
+        verified: "verified";
+        conflict: "conflict";
+    }>;
+    contact_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ChannelMessageSent = z.infer<typeof sentMessage>;
+export declare const widgetEvents: {
+    readonly 'message.received': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly 'message.sent': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+export declare const whatsappEvents: {
+    readonly 'message.received': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly 'message.sent': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+export declare const emailEvents: {
+    readonly 'message.received': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly 'message.sent': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+export declare const smsEvents: {
+    readonly 'message.received': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly 'message.sent': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+/** The contract a binding on each channel delivers for a customer message. */
+export declare const CHANNEL_MESSAGE_RECEIVED: {
+    readonly widget: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly whatsapp: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly email: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+    readonly sms: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            received_at: string;
+            attachments?: {
+                media_type: string;
+                byte_size: number;
+                name?: string | undefined;
+            }[] | undefined;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+        new_conversation: boolean;
+    }>;
+};
+/** The contract a binding on each channel delivers for an agent reply that went out. */
+export declare const CHANNEL_MESSAGE_SENT: {
+    readonly widget: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+    readonly whatsapp: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+    readonly email: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+    readonly sms: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        message: {
+            id: string;
+            text: string;
+            sent_at: string;
+        };
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+/**
+ * The person in a conversation proved a phone number or email address with a
+ * one-time code or link. The Contact is always included: proving the handle is
+ * what makes it visible under every identity rule.
+ */
+declare const verified: z.ZodObject<{
+    conversation_id: z.ZodUUID;
+    owner_epoch: z.ZodNumber;
+    contact_id: z.ZodString;
+    handle_kind: z.ZodEnum<{
+        email: "email";
+        phone: "phone";
+    }>;
+    method: z.ZodEnum<{
+        email_code: "email_code";
+        sms_code: "sms_code";
+        whatsapp_code: "whatsapp_code";
+        email_link: "email_link";
+        sms_link: "sms_link";
+        whatsapp_link: "whatsapp_link";
+    }>;
+    verified_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ContactVerified = z.infer<typeof verified>;
+export declare const contactEvents: {
+    readonly verified: import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        contact_id: string;
+        handle_kind: "email" | "phone";
+        method: "email_code" | "sms_code" | "whatsapp_code" | "email_link" | "sms_link" | "whatsapp_link";
+        verified_at: string;
+    }>;
+};
+/**
+ * The conversation came back to the agent: a person gave it back, or a handoff
+ * the agent asked for ran out. Changes to a person are not delivered: a handler
+ * hears nothing while a person owns the conversation.
+ */
+declare const ownerChanged: z.ZodObject<{
+    conversation_id: z.ZodUUID;
+    owner_epoch: z.ZodNumber;
+    owner: z.ZodLiteral<"agent">;
+    reason: z.ZodEnum<{
+        given_back: "given_back";
+        expired: "expired";
+    }>;
+    changed_at: z.ZodISODateTime;
+    identity: z.ZodEnum<{
+        anonymous: "anonymous";
+        identified: "identified";
+        verified: "verified";
+        conflict: "conflict";
+    }>;
+    contact_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ConversationOwnerChanged = z.infer<typeof ownerChanged>;
+/**
+ * A staff member clicked one of the Pack's declared buttons in the inbox, such
+ * as "Send booking link". The turn that carries it acts as whoever owns the
+ * conversation at the click: the agent, or that staff member, whose replies
+ * then go out under their name.
+ */
+declare const actionRequested: z.ZodObject<{
+    conversation_id: z.ZodUUID;
+    owner_epoch: z.ZodNumber;
+    action_key: z.ZodString;
+    choice: z.ZodNullable<z.ZodString>;
+    requested_by: z.ZodUUID;
+    acting_as: z.ZodEnum<{
+        agent: "agent";
+        staff: "staff";
+    }>;
+    requested_at: z.ZodISODateTime;
+    identity: z.ZodEnum<{
+        anonymous: "anonymous";
+        identified: "identified";
+        verified: "verified";
+        conflict: "conflict";
+    }>;
+    contact_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ConversationActionRequested = z.infer<typeof actionRequested>;
+export declare const conversationEvents: {
+    readonly 'owner.changed': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        owner: "agent";
+        reason: "given_back" | "expired";
+        changed_at: string;
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+    readonly 'action.requested': import("../index.js").EventContract<{
+        conversation_id: string;
+        owner_epoch: number;
+        action_key: string;
+        choice: string | null;
+        requested_by: string;
+        acting_as: "agent" | "staff";
+        requested_at: string;
+        identity: "anonymous" | "identified" | "verified" | "conflict";
+        contact_id: string | null;
+    }>;
+};
+export {};

package/dist/apps/channels.js

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { defineAppEvents } from './define.js';
+/**
+ * A customer message that reached a Pack's inbound handler through a Channel
+ * Binding. Core owns these contracts: a Pack subscribes to them and never
+ * redefines a provider's own events (PRD R9).
+ *
+ * The payload is what the handler may see, already routed and checked. The
+ * provider's raw fields are not here: tenant, Contact, handler and authority
+ * come from Core configuration, never from a provider payload (PRD R14).
+ */
+const message = z.strictObject({
+    /** The Core conversation; the Pack's Eve session address. */
+    conversation_id: z.uuid(),
+    /** The ownership version the delivery was made under. */
+    owner_epoch: z.number().int().positive(),
+    message: z.strictObject({
+        /** Core's timeline entry id for the message. */
+        id: z.uuid(),
+        text: z.string().max(20000),
+        received_at: z.iso.datetime(),
+        attachments: z
+            .array(z.strictObject({
+            media_type: z.string().min(1).max(200),
+            byte_size: z.number().int().positive(),
+            name: z.string().max(500).optional(),
+        }))
+            .max(10)
+            .optional(),
+    }),
+    /** What Core knows about who is writing; the handler applies its own rule. */
+    identity: z.enum(['anonymous', 'identified', 'verified', 'conflict']),
+    contact_id: z.string().min(1).max(200).nullable(),
+    /** True for the first message of a new conversation, including after a rollover. */
+    new_conversation: z.boolean(),
+});
+const received = (channel) => ({
+    version: 1,
+    description: `A customer message arrived on a ${channel} channel bound to this handler.`,
+    schema: message,
+    sensitivity: 'personal',
+    subject: ['conversation_id'],
+});
+/**
+ * An agent reply the provider accepted. Informational: the delivery that carries
+ * it permits no action, so a reply can never trigger another reply. Staff replies
+ * are not delivered, because a handler hears nothing while a person owns the
+ * conversation.
+ */
+const sentMessage = z.strictObject({
+    conversation_id: z.uuid(),
+    owner_epoch: z.number().int().positive(),
+    message: z.strictObject({
+        /** Core's timeline entry id for the message. */
+        id: z.uuid(),
+        text: z.string().max(20000),
+        sent_at: z.iso.datetime(),
+    }),
+    identity: z.enum(['anonymous', 'identified', 'verified', 'conflict']),
+    contact_id: z.string().min(1).max(200).nullable(),
+});
+const sent = (channel) => ({
+    version: 1,
+    description: `An agent reply went out on a ${channel} channel bound to this handler.`,
+    schema: sentMessage,
+    sensitivity: 'personal',
+    subject: ['conversation_id'],
+});
+export const widgetEvents = defineAppEvents('widget', {
+    'message.received': received('website widget'),
+    'message.sent': sent('website widget'),
+});
+export const whatsappEvents = defineAppEvents('whatsapp', {
+    'message.received': received('WhatsApp'),
+    'message.sent': sent('WhatsApp'),
+});
+export const emailEvents = defineAppEvents('email', {
+    'message.received': received('email'),
+    'message.sent': sent('email'),
+});
+export const smsEvents = defineAppEvents('sms', {
+    'message.received': received('SMS'),
+    'message.sent': sent('SMS'),
+});
+/** The contract a binding on each channel delivers for a customer message. */
+export const CHANNEL_MESSAGE_RECEIVED = {
+    widget: widgetEvents['message.received'],
+    whatsapp: whatsappEvents['message.received'],
+    email: emailEvents['message.received'],
+    sms: smsEvents['message.received'],
+};
+/** The contract a binding on each channel delivers for an agent reply that went out. */
+export const CHANNEL_MESSAGE_SENT = {
+    widget: widgetEvents['message.sent'],
+    whatsapp: whatsappEvents['message.sent'],
+    email: emailEvents['message.sent'],
+    sms: smsEvents['message.sent'],
+};
+/**
+ * The person in a conversation proved a phone number or email address with a
+ * one-time code or link. The Contact is always included: proving the handle is
+ * what makes it visible under every identity rule.
+ */
+const verified = z.strictObject({
+    conversation_id: z.uuid(),
+    owner_epoch: z.number().int().positive(),
+    contact_id: z.string().min(1).max(200),
+    handle_kind: z.enum(['email', 'phone']),
+    method: z.enum([
+        'email_code',
+        'sms_code',
+        'whatsapp_code',
+        'email_link',
+        'sms_link',
+        'whatsapp_link',
+    ]),
+    verified_at: z.iso.datetime(),
+});
+export const contactEvents = defineAppEvents('contact', {
+    verified: {
+        version: 1,
+        description: 'The person in a conversation proved a phone number or email address.',
+        schema: verified,
+        sensitivity: 'personal',
+        subject: ['conversation_id'],
+    },
+});
+/**
+ * The conversation came back to the agent: a person gave it back, or a handoff
+ * the agent asked for ran out. Changes to a person are not delivered: a handler
+ * hears nothing while a person owns the conversation.
+ */
+const ownerChanged = z.strictObject({
+    conversation_id: z.uuid(),
+    /** The new ownership version; the turn that carries this event acts under it. */
+    owner_epoch: z.number().int().positive(),
+    owner: z.literal('agent'),
+    reason: z.enum(['given_back', 'expired']),
+    changed_at: z.iso.datetime(),
+    identity: z.enum(['anonymous', 'identified', 'verified', 'conflict']),
+    contact_id: z.string().min(1).max(200).nullable(),
+});
+/**
+ * A staff member clicked one of the Pack's declared buttons in the inbox, such
+ * as "Send booking link". The turn that carries it acts as whoever owns the
+ * conversation at the click: the agent, or that staff member, whose replies
+ * then go out under their name.
+ */
+const actionRequested = z.strictObject({
+    conversation_id: z.uuid(),
+    owner_epoch: z.number().int().positive(),
+    /** The key the Pack declared for the button. */
+    action_key: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/),
+    /** The option the staff member picked, when the button declares options. */
+    choice: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]{0,39}$/)
+        .nullable(),
+    requested_by: z.uuid(),
+    acting_as: z.enum(['agent', 'staff']),
+    requested_at: z.iso.datetime(),
+    identity: z.enum(['anonymous', 'identified', 'verified', 'conflict']),
+    contact_id: z.string().min(1).max(200).nullable(),
+});
+export const conversationEvents = defineAppEvents('conversation', {
+    'owner.changed': {
+        version: 1,
+        description: 'The conversation came back to the agent.',
+        schema: ownerChanged,
+        sensitivity: 'personal',
+        subject: ['conversation_id'],
+    },
+    'action.requested': {
+        version: 1,
+        description: "A staff member clicked one of the Pack's buttons in the inbox.",
+        schema: actionRequested,
+        sensitivity: 'personal',
+        subject: ['conversation_id'],
+    },
+});

package/dist/apps/define.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { type EventContract, type EventSensitivity, type JsonSchema } from '../index.js';
+export interface AppEventInput {
+    version: number;
+    description: string;
+    schema: z.ZodType;
+    sensitivity?: EventSensitivity;
+    /** Payload fields that name what the event is about; they order its deliveries. */
+    subject?: readonly string[];
+}
+/**
+ * The JSON Schema a contract is published and fingerprinted with.
+ *
+ * Raw `z.toJSONSchema` output is not stable enough to fingerprint: it carries a
+ * `$schema` dialect line, and for a string format it adds the library's own
+ * validation pattern, both of which a zod release may change without the
+ * contract changing. They are dropped, so a fingerprint moves only when a field
+ * does. apps/contracts.lock.json turns any other drift into a failed check.
+ */
+export declare function stableJsonSchema(schema: z.ZodType): JsonSchema;
+/**
+ * Declares the normalized events of one Core App. The App name is the event
+ * family, so `defineAppEvents('smartlead', { 'email.opened': … })` declares
+ * `smartlead.email.opened`. Two events may share a schema: the name carries the
+ * meaning, the schema only the shape.
+ */
+export declare function defineAppEvents<const Events extends Record<string, AppEventInput>>(app: string, events: Events): {
+    readonly [Name in keyof Events]: EventContract<z.infer<Events[Name]['schema']>>;
+};

package/dist/apps/define.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { defineEvent, } from '../index.js';
+/**
+ * The JSON Schema a contract is published and fingerprinted with.
+ *
+ * Raw `z.toJSONSchema` output is not stable enough to fingerprint: it carries a
+ * `$schema` dialect line, and for a string format it adds the library's own
+ * validation pattern, both of which a zod release may change without the
+ * contract changing. They are dropped, so a fingerprint moves only when a field
+ * does. apps/contracts.lock.json turns any other drift into a failed check.
+ */
+export function stableJsonSchema(schema) {
+    const { $schema: _dialect, ...jsonSchema } = z.toJSONSchema(schema, {
+        override: ({ jsonSchema: node }) => {
+            if (node.format)
+                delete node.pattern;
+        },
+    });
+    return jsonSchema;
+}
+/**
+ * Declares the normalized events of one Core App. The App name is the event
+ * family, so `defineAppEvents('smartlead', { 'email.opened': … })` declares
+ * `smartlead.email.opened`. Two events may share a schema: the name carries the
+ * meaning, the schema only the shape.
+ */
+export function defineAppEvents(app, events) {
+    const contracts = Object.entries(events).map(([name, event]) => [
+        name,
+        defineEvent({
+            owner: app,
+            key: `${app}.${name}`,
+            version: event.version,
+            description: event.description,
+            payloadSchema: stableJsonSchema(event.schema),
+            ...(event.sensitivity ? { sensitivity: event.sensitivity } : {}),
+            ...(event.subject ? { subjects: { primary: event.subject } } : {}),
+        }),
+    ]);
+    return Object.freeze(Object.fromEntries(contracts));
+}