@keemakr/event-sdk 0.2.0-dev-20261012160211

package/dist/index.js

@@ -0,0 +1,576 @@
+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) {
+    // Core publishes its keys at a fixed path, so naming core is enough.
+    const coreUrl = options.coreUrl ?? process.env.KEE_CORE_URL;
+    const url = options.jwksUrl ??
+        process.env.KEE_CORE_JWKS_URL ??
+        (coreUrl ? `${coreUrl.replace(/\/$/, '')}/.well-known/jwks.json` : undefined);
+    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 ?? ''),
+            scopes: Array.isArray(payload.scopes)
+                ? Object.freeze(payload.scopes.filter((s) => typeof s === 'string'))
+                : Object.freeze([]),
+            traceId: typeof payload.trace_id === 'string' ? payload.trace_id : null,
+            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.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,
+            attemptNumber: delivery.attemptNumber,
+            tenantId: actual.tenantId,
+            correlationId: actual.correlationId,
+            causation: actual.causation,
+            publication: context?.publication ?? null,
+            authority: context?.authority ?? {},
+            grant: context?.grant ?? null,
+        });
+    }
+    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' },
+    });
+}
+/**
+ * The Pack's `/events/v1/deliver` route. Verifies core's delivery grant for
+ * this runtime, checks that it names exactly this delivery, and runs the
+ * handler. The answer is the HTTP status: any 2xx means delivered (the body is
+ * the handler's result, or empty with 204); a failure is a non-2xx with
+ * `{ code, message, retryable }`, and `retryable` tells core whether to try again.
+ * Core may post one delivery more than once (see `EventHandlerContext`).
+ */
+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, {
+            code: 'grant_missing',
+            message: 'a Core Event delivery grant is required',
+            retryable: true,
+        });
+    }
+    const grant = await (options.verifyGrant ?? verifyEventDeliveryGrant)(token, {
+        audience: options.audience,
+        coreUrl: options.coreUrl,
+    });
+    if (!grant) {
+        return jsonResponse(401, {
+            code: 'grant_rejected',
+            message: 'the Event delivery grant did not verify',
+            retryable: true,
+        });
+    }
+    let delivery;
+    try {
+        delivery = (await request.json());
+        if (!delivery?.deliveryId || !delivery?.event || !delivery?.consumer)
+            throw new Error();
+    }
+    catch {
+        return jsonResponse(400, {
+            code: 'bad_request',
+            message: 'the Event delivery envelope is invalid',
+            retryable: false,
+        });
+    }
+    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, {
+            code: 'grant_mismatch',
+            message: 'the grant does not bind this Event delivery',
+            retryable: false,
+        });
+    }
+    try {
+        const result = await dispatchEventDelivery(delivery, handlers, {
+            authority: grant.authority,
+            grant: { token, scopes: grant.scopes, traceId: grant.traceId },
+            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,
+        });
+        // A 2xx is the whole verdict: delivered. The handler's result is the body.
+        return result === undefined || result === null
+            ? new Response(null, { status: 204 })
+            : jsonResponse(200, result);
+    }
+    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, {
+            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() || options.idempotencyKey.length > 512) {
+        throw terminalEventError('publication_key_invalid', 'Publication key must contain 1–512 characters');
+    }
+    let validated;
+    try {
+        validated = contract.validate(payload);
+    }
+    catch {
+        throw terminalEventError('payload_invalid', 'Publication payload does not match its contract');
+    }
+    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 },
+        }),
+    });
+    return publicationAnswer(response);
+}
+/**
+ * Core's refusals that no retry can change. Everything else Core refuses is
+ * handed back retryable with its code, so a handler can still tell a lease
+ * that expired mid-run (try again: the next attempt has a fresh lease) from a
+ * refusal it must not repeat.
+ */
+const PERMANENT_PUBLICATION_ERRORS = new Set([
+    'publication_invalid',
+    'publication_key_invalid',
+    'parent_delivery_mismatch',
+    'parent_required',
+    'delivery_grant_required',
+    'root_publication_not_allowed',
+    'event_owner_mismatch',
+    'event_not_declared',
+    'publication_key_conflict',
+    'chain_depth_exceeded',
+    'body_too_large',
+    'payload_invalid',
+    'pack_not_installed',
+]);
+async function publicationAnswer(response) {
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok || !body.eventId) {
+        const code = typeof body.error === 'string' ? body.error : `http_${response.status}`;
+        const message = `Core rejected Event publication: ${code}`;
+        if ([400, 403, 409, 413, 422].includes(response.status) &&
+            PERMANENT_PUBLICATION_ERRORS.has(code)) {
+            throw terminalEventError(code, message);
+        }
+        throw retryableEventError(code, message, { httpStatus: response.status });
+    }
+    return {
+        status: body.status ?? 'accepted',
+        eventId: body.eventId,
+        deliveryIds: body.deliveryIds ?? [],
+    };
+}
+/**
+ * Publishes a root event: one no incoming delivery caused, from a scheduled or
+ * standalone run of the Pack. The grant must be a run grant carrying
+ * `events:publish`, which the tenant puts there by allowing it on the install;
+ * a delivery grant is refused here (`delivery_grant_required` is the other
+ * door's answer to a run grant). The same key from the same install returns
+ * the same root and never a second.
+ */
+export async function publishRootEvent(context, contract, payload, options, dependencies = {}) {
+    if (!options.idempotencyKey?.trim() || options.idempotencyKey.length > 512) {
+        throw terminalEventError('publication_key_invalid', 'Publication key must contain 1–512 characters');
+    }
+    let validated;
+    try {
+        validated = contract.validate(payload);
+    }
+    catch {
+        throw terminalEventError('payload_invalid', 'Publication payload does not match its contract');
+    }
+    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,
+        }),
+    });
+    return publicationAnswer(response);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@keemakr/event-sdk",
+  "version": "0.2.0-dev-20261012160211",
+  "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"
+    },
+    "./apps/smartlead": {
+      "types": "./dist/apps/smartlead.d.ts",
+      "import": "./dist/apps/smartlead.js",
+      "default": "./dist/apps/smartlead.js"
+    },
+    "./apps": {
+      "types": "./dist/apps/index.d.ts",
+      "import": "./dist/apps/index.js",
+      "default": "./dist/apps/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",
+    "contracts:lock": "npm run build && node scripts/contracts-lock.mjs",
+    "contracts:check": "npm run build && node scripts/contracts-lock.mjs --check"
+  },
+  "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"
+  }
+}