@keemakr/event-sdk 0.2.0-dev-20261012160211

package/dist/apps/index.d.ts

@@ -0,0 +1,16 @@
+import type { EventContract } from '../index.js';
+/**
+ * The event contracts of the Apps Core maintains, by `key@version`. An App event
+ * is a fact an outside platform reported through a Core-maintained integration.
+ * Its contract ships with Core, so it lives here in code.
+ *
+ * A Pack event is the other kind: a Pack declares it in its manifest and Pack
+ * publish registers it in the database, because a Pack can arrive at any time.
+ * It is never listed here. A new Core App adds its events to this list.
+ *
+ * The four channel families (widget, whatsapp, email, sms) and the contact and
+ * conversation families are Core's own conversation contracts: a Channel
+ * Binding delivers them to the inbound handler that subscribes to them.
+ */
+export declare const APP_EVENT_CONTRACTS: ReadonlyMap<string, EventContract>;
+export { CHANNEL_MESSAGE_RECEIVED, CHANNEL_MESSAGE_SENT, contactEvents, conversationEvents, type ChannelMessageReceived, type ChannelMessageSent, type ContactVerified, type ConversationOwnerChanged, type ConversationActionRequested, } from './channels.js';

package/dist/apps/index.js

@@ -0,0 +1,27 @@
+import { contactEvents, conversationEvents, emailEvents, smsEvents, whatsappEvents, widgetEvents, } from './channels.js';
+import { smartleadEvents } from './smartlead.js';
+/**
+ * The event contracts of the Apps Core maintains, by `key@version`. An App event
+ * is a fact an outside platform reported through a Core-maintained integration.
+ * Its contract ships with Core, so it lives here in code.
+ *
+ * A Pack event is the other kind: a Pack declares it in its manifest and Pack
+ * publish registers it in the database, because a Pack can arrive at any time.
+ * It is never listed here. A new Core App adds its events to this list.
+ *
+ * The four channel families (widget, whatsapp, email, sms) and the contact and
+ * conversation families are Core's own conversation contracts: a Channel
+ * Binding delivers them to the inbound handler that subscribes to them.
+ */
+export const APP_EVENT_CONTRACTS = new Map([
+    smartleadEvents,
+    widgetEvents,
+    whatsappEvents,
+    emailEvents,
+    smsEvents,
+    contactEvents,
+    conversationEvents,
+]
+    .flatMap((events) => Object.values(events))
+    .map((contract) => [`${contract.key}@${contract.version}`, contract]));
+export { CHANNEL_MESSAGE_RECEIVED, CHANNEL_MESSAGE_SENT, contactEvents, conversationEvents, } from './channels.js';

package/dist/apps/smartlead.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * What Smartlead reports about one email to one lead. A reply is not here: it is
+ * a conversation message and belongs to `email.message.received`.
+ *
+ * Smartlead reports an open or a click once per email, and a mail security
+ * scanner usually takes that first click within seconds of the send. An event
+ * here is the provider's report, not proof that a person acted.
+ */
+declare const email: z.ZodObject<{
+    campaign_id: z.ZodString;
+    lead_id: z.ZodString;
+    email: z.ZodString;
+    occurred_at: z.ZodISODateTime;
+}, z.core.$strict>;
+declare const linkClicked: z.ZodObject<{
+    campaign_id: z.ZodString;
+    lead_id: z.ZodString;
+    email: z.ZodString;
+    occurred_at: z.ZodISODateTime;
+    link_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SmartleadEmailEvent = z.infer<typeof email>;
+export type SmartleadLinkClickedEvent = z.infer<typeof linkClicked>;
+export declare const smartleadEvents: {
+    readonly 'email.opened': import("../index.js").EventContract<{
+        campaign_id: string;
+        lead_id: string;
+        email: string;
+        occurred_at: string;
+    }>;
+    readonly 'email.link_clicked': import("../index.js").EventContract<{
+        campaign_id: string;
+        lead_id: string;
+        email: string;
+        occurred_at: string;
+        link_url?: string | undefined;
+    }>;
+    readonly 'email.bounced': import("../index.js").EventContract<{
+        campaign_id: string;
+        lead_id: string;
+        email: string;
+        occurred_at: string;
+    }>;
+    readonly 'lead.unsubscribed': import("../index.js").EventContract<{
+        campaign_id: string;
+        lead_id: string;
+        email: string;
+        occurred_at: string;
+    }>;
+};
+export {};

package/dist/apps/smartlead.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { defineAppEvents } from './define.js';
+/**
+ * What Smartlead reports about one email to one lead. A reply is not here: it is
+ * a conversation message and belongs to `email.message.received`.
+ *
+ * Smartlead reports an open or a click once per email, and a mail security
+ * scanner usually takes that first click within seconds of the send. An event
+ * here is the provider's report, not proof that a person acted.
+ */
+const email = z.strictObject({
+    campaign_id: z.string().min(1),
+    lead_id: z.string().min(1),
+    // A natural person's address: every event below is personal data.
+    email: z.string().min(1),
+    occurred_at: z.iso.datetime(),
+});
+const linkClicked = email.extend({ link_url: z.string().min(1).optional() });
+const common = {
+    version: 1,
+    sensitivity: 'personal',
+    subject: ['campaign_id', 'lead_id'],
+};
+export const smartleadEvents = defineAppEvents('smartlead', {
+    'email.opened': {
+        ...common,
+        description: 'Smartlead reported that a lead opened an email.',
+        schema: email,
+    },
+    'email.link_clicked': {
+        ...common,
+        description: 'Smartlead reported that a tracked link in an email was clicked.',
+        schema: linkClicked,
+    },
+    'email.bounced': {
+        ...common,
+        description: 'Smartlead reported that an email bounced.',
+        schema: email,
+    },
+    'lead.unsubscribed': {
+        ...common,
+        description: 'Smartlead reported that a lead unsubscribed.',
+        schema: email,
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,342 @@
+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>;
+}
+/** What core posts to a Pack's `/events/v1/deliver`: a delivery with its binding and consumer named. */
+export type EventDeliveryEnvelope<P = unknown> = EventDelivery<P> & {
+    bindingId: string;
+    consumer: NonNullable<EventDelivery['consumer']>;
+};
+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;
+    /** The capability scopes core minted for this delivery; what `kee` may call back with. */
+    scopes: readonly string[];
+    traceId: string | null;
+    authority: Readonly<{
+        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;
+    coreUrl?: string;
+}): Promise<EventDeliveryGrant | null>;
+/**
+ * Delivery is at least once: a lease can expire, a runtime can answer late, a
+ * sweep can die, and core sends the same delivery again. A handler's effects
+ * must be safe to repeat for one `deliveryId`; `eventEffectIdempotencyKey`
+ * gives the key. `attemptNumber` says which try this is.
+ */
+export interface EventHandlerContext {
+    deliveryId: string;
+    attemptNumber: number;
+    tenantId: string;
+    correlationId: string;
+    causation: EventEnvelope['causation'];
+    publication: EventPublishContext | null;
+    authority: EventDeliveryGrant['authority'];
+    /**
+     * The bearer core sent and the scopes it carries: what the handler hands to
+     * its Kee client to reach the tenant's Tables. Null when the handler is run
+     * without a grant (a local test).
+     */
+    grant: {
+        token: string;
+        scopes: readonly string[];
+        traceId: string | null;
+    } | null;
+}
+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 {
+    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;
+        };
+    }[];
+};
+export declare function dispatchEventDelivery(delivery: EventDelivery, handlers: readonly EventHandler<any, any>[], context?: {
+    publication?: EventPublishContext | null;
+    authority?: EventDeliveryGrant['authority'];
+    grant?: EventHandlerContext['grant'];
+}): Promise<unknown>;
+/**
+ * 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 declare function handleEventDeliveryRequest(request: Request, handlers: readonly EventHandler<any, any>[], options: {
+    audience: string;
+    coreUrl?: string;
+    verifyGrant?: (token: string, options: {
+        audience: string;
+        coreUrl?: 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[];
+}>;
+/** What a run outside any delivery needs to publish a root event: Core's URL and its own grant. */
+export interface EventRootPublishContext {
+    coreUrl: string;
+    token: string;
+}
+/**
+ * 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 declare function publishRootEvent<P>(context: EventRootPublishContext, contract: EventContract<P>, payload: P, options: {
+    idempotencyKey: string;
+}, dependencies?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    status: string;
+    eventId: string;
+    deliveryIds: string[];
+}>;