@keemakr/event-sdk 0.2.0-poc-20260911235414

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/index.d.ts

@@ -0,0 +1,287 @@
+import { z } from 'zod';
+export type JsonSchema = Record<string, unknown>;
+export type EventSensitivity = 'none' | 'personal' | 'phi';
+export interface EventDefinitionInput {
+    owner: string;
+    key: string;
+    version: number;
+    description: string;
+    payloadSchema: JsonSchema;
+    sensitivity?: EventSensitivity;
+    subjects?: {
+        primary: readonly string[];
+    };
+}
+export interface EventContract<P = unknown> {
+    readonly owner: string;
+    readonly key: string;
+    readonly version: number;
+    readonly description: string;
+    readonly payloadSchema: Readonly<JsonSchema>;
+    readonly sensitivity: EventSensitivity;
+    readonly subjects?: {
+        readonly primary: readonly string[];
+    };
+    readonly fingerprint: string;
+    validate(value: unknown): P;
+}
+export interface EventContractArtifact {
+    owner: string;
+    event_key: string;
+    version: number;
+    description: string;
+    payload_schema: JsonSchema;
+    primary_subject_fields: string[];
+    sensitivity: EventSensitivity;
+    fingerprint: string;
+}
+/**
+ * Fetch a contract-only build artifact with a short-lived tenant access token.
+ * The exact release pin is checked before the artifact reaches build tooling.
+ */
+export declare function fetchEventContractArtifact(input: {
+    coreUrl: string;
+    accessToken: string;
+    owner: string;
+    key: string;
+    version: number;
+    fingerprint: string;
+    fetch?: typeof fetch;
+}): Promise<EventContractArtifact>;
+export declare function canonicalEventJson(value: unknown): string;
+export declare function eventPrimarySubject(payload: unknown, fields: readonly string[]): string | null;
+export declare function defineEvent<P = Record<string, unknown>>(input: EventDefinitionInput): EventContract<P>;
+export declare function eventContractFingerprint(identity: {
+    owner: string;
+    key: string;
+    version: number;
+    description: string;
+    payloadSchema: JsonSchema;
+    sensitivity: EventSensitivity;
+    subjects?: {
+        primary: readonly string[];
+    };
+}): string;
+export interface EventEnvelope<P = unknown> {
+    id: string;
+    owner: string;
+    key: string;
+    version: number;
+    fingerprint: string;
+    payloadDigest: string;
+    tenantId: string;
+    correlationId: string;
+    causation: {
+        rootEventId: string;
+        parentEventId: string | null;
+    };
+    payload: P;
+}
+export interface EventDelivery<P = unknown> {
+    deliveryId: string;
+    attemptNumber: number;
+    bindingId?: string;
+    consumer?: {
+        installId: string;
+        packVersion: number;
+        deploymentRevision: string;
+    };
+    handlerId: string;
+    event: EventEnvelope<P>;
+}
+export declare const CoreAppEventProducerSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"core_app">;
+    app: z.ZodEnum<{
+        email: "email";
+        whatsapp: "whatsapp";
+        widget: "widget";
+    }>;
+    integrationId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The exclusive channel lane. It is intentionally not an EventDelivery variant:
+ * generic Event handlers cannot accept it by widening their existing contract.
+ */
+export declare const ChannelEventDeliverySchema: z.ZodObject<{
+    deliveryId: z.ZodString;
+    eventId: z.ZodString;
+    tenantId: z.ZodString;
+    installId: z.ZodString;
+    bindingId: z.ZodString;
+    bindingRevisionId: z.ZodString;
+    conversationId: z.ZodString;
+    audience: z.ZodURL;
+    ownerEpoch: z.ZodNumber;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"agent">;
+        key: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"team">;
+        key: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    producer: z.ZodObject<{
+        kind: z.ZodLiteral<"core_app">;
+        app: z.ZodEnum<{
+            email: "email";
+            whatsapp: "whatsapp";
+            widget: "widget";
+        }>;
+        integrationId: z.ZodString;
+    }, z.core.$strip>;
+    externalPrincipal: z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type CoreAppEventProducer = z.infer<typeof CoreAppEventProducerSchema>;
+export type ChannelEventDelivery<P = Record<string, unknown>> = Omit<z.infer<typeof ChannelEventDeliverySchema>, 'payload'> & {
+    payload: P;
+};
+export interface EventDeliveryGrant {
+    tenantId: string;
+    installId: string;
+    packVersion: number;
+    deploymentRevision: string;
+    audience: string;
+    handlerId: string;
+    contract: {
+        owner: string;
+        key: string;
+        version: number;
+        fingerprint: string;
+    };
+    bindingId: string;
+    deliveryId: string;
+    attemptNumber: number;
+    eventId: string;
+    payloadDigest: string;
+    authority: Readonly<{
+        workflows?: readonly string[];
+        agents?: readonly string[];
+        teams?: readonly string[];
+        core_operations?: readonly string[];
+        publishes?: readonly {
+            key: string;
+            version: number;
+            fingerprint: string;
+        }[];
+    }>;
+}
+export declare function verifyEventDeliveryGrant(token: string, options: {
+    audience: string;
+    jwksUrl?: string;
+}): Promise<EventDeliveryGrant | null>;
+export interface EventHandlerContext {
+    deliveryId: string;
+    tenantId: string;
+    correlationId: string;
+    causation: EventEnvelope['causation'];
+    publication: EventPublishContext | null;
+    authority: EventDeliveryGrant['authority'];
+}
+export declare function eventEffectIdempotencyKey(context: Pick<EventHandlerContext, 'deliveryId'>, operation: string, discriminator?: string): string;
+/** A handler failure whose retry policy is explicit and portable across runtimes. */
+export declare class EventHandlerError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly detail?: Readonly<Record<string, unknown>>;
+    constructor(input: {
+        code: string;
+        message: string;
+        retryable: boolean;
+        detail?: Record<string, unknown>;
+    });
+}
+export declare function terminalEventError(code: string, message: string, detail?: Record<string, unknown>): EventHandlerError;
+export declare function retryableEventError(code: string, message: string, detail?: Record<string, unknown>): EventHandlerError;
+export interface EventHandler<P = any, R = unknown> {
+    readonly id: string;
+    readonly event: EventContract<P>;
+    readonly consumes: Readonly<{
+        owner: string;
+        key: string;
+        version: number;
+        fingerprint: string;
+    }>;
+    readonly run: (event: EventEnvelope<P>, context: EventHandlerContext) => Promise<R>;
+    readonly authority: Readonly<EventHandlerAuthority>;
+}
+export interface EventHandlerAuthority {
+    workflows?: readonly string[];
+    agents?: readonly string[];
+    teams?: readonly string[];
+    coreOperations?: readonly string[];
+    publishes?: readonly EventContract[];
+}
+export declare function handleEvent<P = unknown, R = unknown>(input: {
+    id: string;
+    event: EventContract<P>;
+    authority?: EventHandlerAuthority;
+    run: EventHandler<P, R>['run'];
+}): EventHandler<P, R>;
+/** Build the Event-only manifest fragment. Pack build tooling writes this output to entry.json. */
+export declare function eventManifest(input: {
+    events?: readonly EventContract[];
+    handlers?: readonly EventHandler<any, any>[];
+}): {
+    events: {
+        owner: string;
+        key: string;
+        version: number;
+        description: string;
+        payload_schema: Readonly<JsonSchema>;
+        primary_subject_fields: string[];
+        sensitivity: EventSensitivity;
+        fingerprint: string;
+    }[];
+    eventHandlers: {
+        id: string;
+        consumes: {
+            owner: string;
+            key: string;
+            version: number;
+            fingerprint: string;
+        };
+        authority: {
+            publishes?: {
+                key: string;
+                version: number;
+                fingerprint: string;
+            }[] | undefined;
+            core_operations?: string[] | undefined;
+            teams?: string[] | undefined;
+            agents?: string[] | undefined;
+            workflows?: string[] | undefined;
+        };
+    }[];
+};
+export declare function dispatchEventDelivery(delivery: EventDelivery, handlers: readonly EventHandler<any, any>[], context?: {
+    publication?: EventPublishContext | null;
+    authority?: EventDeliveryGrant['authority'];
+}): Promise<unknown>;
+export declare function handleEventDeliveryRequest(request: Request, handlers: readonly EventHandler<any, any>[], options: {
+    audience: string;
+    coreUrl?: string;
+    verifyGrant?: (token: string, options: {
+        audience: string;
+    }) => Promise<EventDeliveryGrant | null>;
+}): Promise<Response>;
+export interface EventPublishContext {
+    coreUrl: string;
+    token: string;
+    deliveryId: string;
+    eventId: string;
+    tenantId: string;
+    correlationId: string;
+    causation: EventEnvelope['causation'];
+}
+export declare function publishEvent<P>(context: EventPublishContext, contract: EventContract<P>, payload: P, options: {
+    idempotencyKey: string;
+}, dependencies?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    status: string;
+    eventId: string;
+    deliveryIds: string[];
+}>;

package/dist/index.js

@@ -0,0 +1,478 @@
+import { createHash } from 'node:crypto';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { z } from 'zod';
+/**
+ * Fetch a contract-only build artifact with a short-lived tenant access token.
+ * The exact release pin is checked before the artifact reaches build tooling.
+ */
+export async function fetchEventContractArtifact(input) {
+    const request = input.fetch ?? fetch;
+    const response = await request(`${input.coreUrl.replace(/\/$/, '')}/api/events/contracts/${encodeURIComponent(input.key)}/${input.version}`, { headers: { authorization: `Bearer ${input.accessToken}` } });
+    if (!response.ok)
+        throw new Error(`Event contract fetch failed with HTTP ${response.status}`);
+    const artifact = (await response.json());
+    if (artifact.owner !== input.owner ||
+        artifact.event_key !== input.key ||
+        artifact.version !== input.version ||
+        artifact.fingerprint !== input.fingerprint ||
+        !artifact.payload_schema ||
+        typeof artifact.payload_schema !== 'object') {
+        throw new Error('Event contract artifact does not match the pinned contract identity');
+    }
+    return artifact;
+}
+const NAMESPACE = /^[a-z][a-z0-9-]*$/;
+const EVENT_KEY = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9_-]*)+$/;
+export function canonicalEventJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalEventJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalEventJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function eventPrimarySubject(payload, fields) {
+    if (fields.length === 0 || payload === null || typeof payload !== 'object')
+        return null;
+    const record = payload;
+    const subject = {};
+    for (const field of fields) {
+        subject[field] = record[field] ?? null;
+    }
+    return canonicalEventJson(subject);
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function schemaValidator(schema) {
+    try {
+        return z.fromJSONSchema(schema);
+    }
+    catch (error) {
+        throw new Error(`payload schema is not enforceable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function defineEvent(input) {
+    if (!NAMESPACE.test(input.owner))
+        throw new Error('event owner must be a Pack namespace');
+    if (!EVENT_KEY.test(input.key))
+        throw new Error('event key must be a namespaced dotted key');
+    const namespace = input.key.split('.')[0];
+    if (namespace !== input.owner) {
+        throw new Error(`event key namespace '${namespace}' does not match owner '${input.owner}'`);
+    }
+    if (namespace === 'core' && input.owner !== 'core') {
+        throw new Error("the 'core' Event namespace is reserved");
+    }
+    if (!Number.isInteger(input.version) || input.version <= 0) {
+        throw new Error('event version must be a positive integer');
+    }
+    if (!input.description.trim())
+        throw new Error('event description is required');
+    if (!input.payloadSchema || typeof input.payloadSchema !== 'object') {
+        throw new Error('event payload schema must be an object');
+    }
+    const primary = input.subjects?.primary ?? [];
+    if (new Set(primary).size !== primary.length || primary.some((field) => !field.trim())) {
+        throw new Error('event primary subject fields must be unique non-empty names');
+    }
+    const payloadSchema = deepFreeze(cloneJson(input.payloadSchema));
+    const subjects = primary.length
+        ? deepFreeze({ primary: [...primary] })
+        : undefined;
+    const sensitivity = input.sensitivity ?? 'none';
+    const identity = {
+        owner: input.owner,
+        key: input.key,
+        version: input.version,
+        description: input.description,
+        payloadSchema,
+        sensitivity,
+        ...(subjects ? { subjects } : {}),
+    };
+    const fingerprint = eventContractFingerprint(identity);
+    const validator = schemaValidator(payloadSchema);
+    return Object.freeze({
+        ...identity,
+        fingerprint,
+        validate(value) {
+            const parsed = validator.safeParse(value);
+            if (parsed.success)
+                return parsed.data;
+            const issues = parsed.error.issues.map((issue) => issue.path.length ? `${issue.path.join('.')}: ${issue.message}` : issue.message);
+            throw new Error(`event payload is invalid: ${issues.join('; ')}`);
+        },
+    });
+}
+export function eventContractFingerprint(identity) {
+    const normalized = {
+        ...identity,
+        ...(identity.subjects?.primary.length
+            ? { subjects: identity.subjects }
+            : { subjects: undefined }),
+    };
+    return `sha256:${createHash('sha256').update(canonicalEventJson(normalized)).digest('hex')}`;
+}
+export const CoreAppEventProducerSchema = z.object({
+    kind: z.literal('core_app'),
+    app: z.enum(['email', 'whatsapp', 'widget']),
+    integrationId: z.string().min(1),
+});
+/**
+ * The exclusive channel lane. It is intentionally not an EventDelivery variant:
+ * generic Event handlers cannot accept it by widening their existing contract.
+ */
+export const ChannelEventDeliverySchema = z.object({
+    deliveryId: z.string().min(1),
+    eventId: z.string().min(1),
+    tenantId: z.string().min(1),
+    installId: z.string().min(1),
+    bindingId: z.string().min(1),
+    bindingRevisionId: z.string().min(1),
+    conversationId: z.string().min(1),
+    audience: z.url(),
+    ownerEpoch: z.number().int().nonnegative(),
+    target: z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('agent'), key: z.string().min(1) }),
+        z.object({ kind: z.literal('team'), key: z.string().min(1) }),
+    ]),
+    producer: CoreAppEventProducerSchema,
+    externalPrincipal: z.object({ kind: z.literal('external'), id: z.string().min(1) }),
+    payload: z.record(z.string(), z.unknown()),
+});
+const jwks = new Map();
+export async function verifyEventDeliveryGrant(token, options) {
+    const url = options.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
+    if (!url)
+        return null;
+    let keys = jwks.get(url);
+    if (!keys) {
+        keys = createRemoteJWKSet(new URL(url));
+        jwks.set(url, keys);
+    }
+    try {
+        const { payload } = await jwtVerify(token, keys, {
+            issuer: 'keemakr',
+            audience: options.audience,
+        });
+        const delivery = payload.event_delivery;
+        if (!delivery || typeof payload.tenant_id !== 'string')
+            return null;
+        const contract = {
+            owner: String(delivery.event_key ?? '').split('.')[0] ?? '',
+            key: String(delivery.event_key ?? ''),
+            version: Number(delivery.event_version),
+            fingerprint: String(delivery.contract_fingerprint ?? ''),
+        };
+        const grant = {
+            tenantId: payload.tenant_id,
+            installId: String(delivery.consumer_install_id ?? ''),
+            packVersion: Number(delivery.pack_version),
+            deploymentRevision: String(delivery.deployment_revision ?? ''),
+            audience: Array.isArray(payload.aud)
+                ? String(payload.aud[0] ?? '')
+                : String(payload.aud ?? ''),
+            handlerId: String(delivery.handler_id ?? ''),
+            contract,
+            bindingId: String(delivery.binding_id ?? ''),
+            deliveryId: String(delivery.delivery_id ?? ''),
+            attemptNumber: Number(delivery.attempt_number),
+            eventId: String(delivery.event_id ?? ''),
+            payloadDigest: String(delivery.payload_digest ?? ''),
+            authority: delivery.authority && typeof delivery.authority === 'object'
+                ? deepFreeze(cloneJson(delivery.authority))
+                : {},
+        };
+        const invalid = !grant.installId ||
+            !Number.isInteger(grant.packVersion) ||
+            grant.packVersion <= 0 ||
+            !grant.deploymentRevision ||
+            !grant.audience ||
+            !grant.handlerId ||
+            !grant.bindingId ||
+            !grant.deliveryId ||
+            !Number.isInteger(grant.attemptNumber) ||
+            grant.attemptNumber <= 0 ||
+            !grant.eventId ||
+            !grant.payloadDigest ||
+            !contract.owner ||
+            !contract.key ||
+            !Number.isInteger(contract.version) ||
+            !contract.fingerprint;
+        return invalid ? null : grant;
+    }
+    catch {
+        return null;
+    }
+}
+export function eventEffectIdempotencyKey(context, operation, discriminator) {
+    const suffix = discriminator ? `:${discriminator}` : '';
+    return `${context.deliveryId}:${operation}${suffix}`;
+}
+class EventDispatchError extends Error {
+    code;
+    status;
+    retryable;
+    detail;
+    constructor(code, status, retryable, message, detail) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.retryable = retryable;
+        this.detail = detail;
+    }
+}
+/** A handler failure whose retry policy is explicit and portable across runtimes. */
+export class EventHandlerError extends Error {
+    code;
+    retryable;
+    detail;
+    constructor(input) {
+        if (!/^[a-z][a-z0-9_]*$/.test(input.code)) {
+            throw new Error('Event handler failure code must be a lowercase snake-case identifier');
+        }
+        super(input.message);
+        this.name = 'EventHandlerError';
+        this.code = input.code;
+        this.retryable = input.retryable;
+        this.detail = input.detail ? deepFreeze(cloneJson(input.detail)) : undefined;
+    }
+}
+export function terminalEventError(code, message, detail) {
+    return new EventHandlerError({ code, message, retryable: false, detail });
+}
+export function retryableEventError(code, message, detail) {
+    return new EventHandlerError({ code, message, retryable: true, detail });
+}
+export function handleEvent(input) {
+    if (!/^[a-z][a-z0-9-]*$/.test(input.id)) {
+        throw new Error('event handler id must be a lowercase slug');
+    }
+    return Object.freeze({
+        id: input.id,
+        event: input.event,
+        consumes: Object.freeze({
+            owner: input.event.owner,
+            key: input.event.key,
+            version: input.event.version,
+            fingerprint: input.event.fingerprint,
+        }),
+        authority: deepFreeze({ ...(input.authority ?? {}) }),
+        run: input.run,
+    });
+}
+/** Build the Event-only manifest fragment. Pack build tooling writes this output to entry.json. */
+export function eventManifest(input) {
+    const events = input.events ?? [];
+    const handlers = input.handlers ?? [];
+    return deepFreeze({
+        events: events.map((event) => ({
+            owner: event.owner,
+            key: event.key,
+            version: event.version,
+            description: event.description,
+            payload_schema: cloneJson(event.payloadSchema),
+            primary_subject_fields: [...(event.subjects?.primary ?? [])],
+            sensitivity: event.sensitivity,
+            fingerprint: event.fingerprint,
+        })),
+        eventHandlers: handlers.map((handler) => ({
+            id: handler.id,
+            consumes: { ...handler.consumes },
+            authority: {
+                ...(handler.authority.workflows ? { workflows: [...handler.authority.workflows] } : {}),
+                ...(handler.authority.agents ? { agents: [...handler.authority.agents] } : {}),
+                ...(handler.authority.teams ? { teams: [...handler.authority.teams] } : {}),
+                ...(handler.authority.coreOperations
+                    ? { core_operations: [...handler.authority.coreOperations] }
+                    : {}),
+                ...(handler.authority.publishes
+                    ? {
+                        publishes: handler.authority.publishes.map((event) => ({
+                            key: event.key,
+                            version: event.version,
+                            fingerprint: event.fingerprint,
+                        })),
+                    }
+                    : {}),
+            },
+        })),
+    });
+}
+export async function dispatchEventDelivery(delivery, handlers, context) {
+    const matches = handlers.filter((handler) => handler.id === delivery.handlerId);
+    if (matches.length !== 1) {
+        throw new EventDispatchError('handler_not_found', 404, false, matches.length === 0
+            ? `unknown Event handler '${delivery.handlerId}'`
+            : `Event handler '${delivery.handlerId}' is registered more than once`);
+    }
+    const handler = matches[0];
+    const expected = handler.consumes;
+    const actual = delivery.event;
+    if (actual.owner !== expected.owner ||
+        actual.key !== expected.key ||
+        actual.version !== expected.version ||
+        actual.fingerprint !== expected.fingerprint) {
+        throw new EventDispatchError('contract_mismatch', 409, false, `delivery contract or fingerprint does not match handler '${handler.id}'`);
+    }
+    let payload;
+    try {
+        payload = handler.event.validate(actual.payload);
+    }
+    catch (error) {
+        throw new EventDispatchError('payload_invalid', 422, false, error instanceof Error ? error.message : String(error));
+    }
+    const event = { ...actual, payload };
+    try {
+        return await handler.run(event, {
+            deliveryId: delivery.deliveryId,
+            tenantId: actual.tenantId,
+            correlationId: actual.correlationId,
+            causation: actual.causation,
+            publication: context?.publication ?? null,
+            authority: context?.authority ?? {},
+        });
+    }
+    catch (error) {
+        if (error instanceof EventHandlerError) {
+            throw new EventDispatchError(error.code, error.retryable ? 503 : 422, error.retryable, error.message, error.detail ? { ...error.detail } : undefined);
+        }
+        throw new EventDispatchError('handler_failed', 500, true, error instanceof Error ? error.message : String(error));
+    }
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+export async function handleEventDeliveryRequest(request, handlers, options) {
+    const authorization = request.headers.get('authorization') ?? '';
+    const token = authorization.match(/^Bearer\s+([^\s]+)$/i)?.[1];
+    if (!token) {
+        return jsonResponse(401, {
+            ok: false,
+            failure: { code: 'grant_missing', message: 'a Core Event delivery grant is required' },
+        });
+    }
+    const grant = await (options.verifyGrant ?? verifyEventDeliveryGrant)(token, {
+        audience: options.audience,
+    });
+    if (!grant) {
+        return jsonResponse(401, {
+            ok: false,
+            failure: { code: 'grant_rejected', message: 'the Event delivery grant did not verify' },
+        });
+    }
+    let delivery;
+    try {
+        delivery = (await request.json());
+        if (!delivery?.deliveryId || !delivery?.event || !delivery?.consumer)
+            throw new Error();
+    }
+    catch {
+        return jsonResponse(400, {
+            ok: false,
+            failure: { code: 'bad_request', message: 'the Event delivery envelope is invalid' },
+        });
+    }
+    const contract = grant.contract;
+    const identityMatches = grant.tenantId === delivery.event.tenantId &&
+        grant.installId === delivery.consumer.installId &&
+        grant.packVersion === delivery.consumer.packVersion &&
+        grant.deploymentRevision === delivery.consumer.deploymentRevision &&
+        grant.audience === options.audience &&
+        grant.handlerId === delivery.handlerId &&
+        contract.owner === delivery.event.owner &&
+        contract.key === delivery.event.key &&
+        contract.version === delivery.event.version &&
+        contract.fingerprint === delivery.event.fingerprint &&
+        grant.eventId === delivery.event.id &&
+        grant.payloadDigest === delivery.event.payloadDigest &&
+        grant.payloadDigest ===
+            `sha256:${createHash('sha256').update(canonicalEventJson(delivery.event.payload)).digest('hex')}` &&
+        grant.bindingId === delivery.bindingId &&
+        grant.deliveryId === delivery.deliveryId &&
+        grant.attemptNumber === delivery.attemptNumber;
+    if (!identityMatches) {
+        return jsonResponse(403, {
+            ok: false,
+            failure: { code: 'grant_mismatch', message: 'the grant does not bind this Event delivery' },
+        });
+    }
+    try {
+        const result = await dispatchEventDelivery(delivery, handlers, {
+            authority: grant.authority,
+            publication: options.coreUrl
+                ? {
+                    coreUrl: options.coreUrl,
+                    token,
+                    deliveryId: delivery.deliveryId,
+                    eventId: delivery.event.id,
+                    tenantId: delivery.event.tenantId,
+                    correlationId: delivery.event.correlationId,
+                    causation: delivery.event.causation,
+                }
+                : null,
+        });
+        return jsonResponse(200, { ok: true, result: result ?? null });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const dispatchError = error instanceof EventDispatchError
+            ? error
+            : new EventDispatchError('handler_failed', 500, true, message);
+        return jsonResponse(dispatchError.status, {
+            ok: false,
+            failure: {
+                code: dispatchError.code,
+                message,
+                retryable: dispatchError.retryable,
+                ...(dispatchError.detail ? { detail: dispatchError.detail } : {}),
+            },
+        });
+    }
+}
+export async function publishEvent(context, contract, payload, options, dependencies = {}) {
+    if (!options.idempotencyKey?.trim())
+        throw new Error('publishEvent requires an idempotencyKey');
+    const validated = contract.validate(payload);
+    const response = await (dependencies.fetch ?? fetch)(`${context.coreUrl.replace(/\/$/, '')}/api/events/publish`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${context.token}`,
+            'content-type': 'application/json',
+            'idempotency-key': options.idempotencyKey,
+        },
+        body: JSON.stringify({
+            contract: {
+                owner: contract.owner,
+                key: contract.key,
+                version: contract.version,
+                fingerprint: contract.fingerprint,
+            },
+            payload: validated,
+            causation: { parentDeliveryId: context.deliveryId },
+        }),
+    });
+    const body = (await response.json());
+    if (!response.ok || !body.eventId) {
+        throw new Error(`Core rejected Event publication (${response.status})`);
+    }
+    return {
+        status: body.status ?? 'accepted',
+        eventId: body.eventId,
+        deliveryIds: body.deliveryIds ?? [],
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@keemakr/event-sdk",
+  "version": "0.2.0-poc-20260911235414",
+  "description": "Typed Event declarations, publication, and delivery dispatch for Keemakr Packs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/event-sdk"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}