@norbix.ai/ts 1.1.1 → 1.2.0

package/dist/webhooks/index.d.cts

@@ -1,3 +1,5 @@
+import { CodeMashHub2 } from '../types/hub2.dtos.cjs';
+
 declare class NorbixWebhookError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -15,6 +17,38 @@ declare class NorbixWebhookParseError extends NorbixWebhookError {
  */
 declare const NORBIX_WEBHOOK_EVENT_NAMES: readonly ["database.record.inserted", "database.record.updated", "database.record.deleted", "database.record.replaced", "database.record.responsibilityChanged", "database.records.inserted", "database.records.updated", "database.records.deleted", "membership.user.registered", "membership.user.invited", "membership.user.verified", "membership.user.updated", "membership.user.deleted", "membership.user.blocked", "membership.user.reactivated", "files.file.uploaded", "files.file.deleted"];
 type NorbixWebhookEventName = (typeof NORBIX_WEBHOOK_EVENT_NAMES)[number];
+/**
+ * Named event constants — use these instead of raw strings so app code gets
+ * autocomplete and is typo-safe.
+ *
+ * @example
+ * receiver.on(NorbixWebhookEvents.Membership.UserRegistered, (user, event) => {});
+ */
+declare const NorbixWebhookEvents: {
+    readonly Database: {
+        readonly RecordInserted: "database.record.inserted";
+        readonly RecordUpdated: "database.record.updated";
+        readonly RecordDeleted: "database.record.deleted";
+        readonly RecordReplaced: "database.record.replaced";
+        readonly RecordResponsibilityChanged: "database.record.responsibilityChanged";
+        readonly RecordsInserted: "database.records.inserted";
+        readonly RecordsUpdated: "database.records.updated";
+        readonly RecordsDeleted: "database.records.deleted";
+    };
+    readonly Membership: {
+        readonly UserRegistered: "membership.user.registered";
+        readonly UserInvited: "membership.user.invited";
+        readonly UserVerified: "membership.user.verified";
+        readonly UserUpdated: "membership.user.updated";
+        readonly UserDeleted: "membership.user.deleted";
+        readonly UserBlocked: "membership.user.blocked";
+        readonly UserReactivated: "membership.user.reactivated";
+    };
+    readonly Files: {
+        readonly FileUploaded: "files.file.uploaded";
+        readonly FileDeleted: "files.file.deleted";
+    };
+};
 interface NorbixWebhookEventGroup {
     group: string;
     label: string;
@@ -44,6 +78,177 @@ declare const NORBIX_WEBHOOK_HEADERS: {
 };
 type NorbixWebhookHeaderName = (typeof NORBIX_WEBHOOK_HEADERS)[keyof typeof NORBIX_WEBHOOK_HEADERS];
 
+/**
+ * Webhook payload shapes, organised by the three trigger kinds:
+ *
+ * - **Entity**   — create / delete / single-property state flip. The payload
+ *   IS the entity; the event name already says what changed.
+ * - **Mutation** — an arbitrary edit you must diff. The payload is `{ from, to }`.
+ * - **Batch**    — many records at once. The payload is an array.
+ *
+ * Wrapper identifiers (record id, schema name, …) are NOT part of the payload —
+ * they are lifted onto `event.metadata` by the receiver. See `event-data.ts`.
+ */
+/** A before/after pair for a mutation event. */
+interface NorbixWebhookMutation<T> {
+    from: T;
+    to: T;
+}
+/** `membership.user.updated` payload — a user mutation. */
+type NorbixWebhookUserUpdated = NorbixWebhookMutation<CodeMashHub2.UserDto>;
+/** `database.record.updated` / `replaced` payload — a document mutation. */
+type NorbixWebhookRecordUpdated<TDocument = Record<string, unknown>> = NorbixWebhookMutation<TDocument>;
+/** `membership.user.invited` payload (no full entity yet — just an email). */
+interface NorbixWebhookUserInvited {
+    email: string;
+}
+/** `files.file.deleted` payload (no entity — just the path). */
+interface NorbixWebhookFileDeleted {
+    path: string;
+}
+/** Wire payload for single-record database events (insert / delete). */
+interface NorbixWebhookWireDatabaseRecord<TDocument = Record<string, unknown>> {
+    schemaName: string;
+    integrationId: string;
+    id: string;
+    document: TDocument;
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for database record updated / replaced. */
+interface NorbixWebhookWireDatabaseRecordUpdated<TDocument = Record<string, unknown>> {
+    schemaName: string;
+    integrationId: string;
+    id: string;
+    from: TDocument;
+    to: TDocument;
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for database.records.inserted (batch). */
+interface NorbixWebhookWireDatabaseRecordsInserted<TDocument = Record<string, unknown>> {
+    schemaName: string;
+    integrationId: string;
+    ids: string[];
+    documents: TDocument[];
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for database.records.updated. */
+interface NorbixWebhookWireDatabaseRecordsUpdated {
+    schemaName: string;
+    integrationId: string;
+    matchedCount: number;
+    modifiedCount: number;
+    update: Record<string, unknown>;
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for database.records.deleted. */
+interface NorbixWebhookWireDatabaseRecordsDeleted {
+    schemaName: string;
+    integrationId: string;
+    deletedCount: number;
+    filter: Record<string, unknown>;
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for database.record.responsibilityChanged. */
+interface NorbixWebhookWireDatabaseRecordResponsibilityChanged {
+    schemaName: string;
+    integrationId: string;
+    id: string;
+    fromOwnerId: string;
+    toOwnerId: string;
+    schema?: CodeMashHub2.DataSchemaDto | null;
+}
+/** Wire payload for membership.user.registered. */
+interface NorbixWebhookWireUserRegistered {
+    id: string;
+    to: CodeMashHub2.UserDto;
+}
+/** Wire payload for membership.user.verified | blocked | reactivated | updated. */
+interface NorbixWebhookWireUserTransition {
+    id: string;
+    from?: CodeMashHub2.UserDto | null;
+    to: CodeMashHub2.UserDto;
+}
+/** Wire payload for membership.user.deleted. */
+interface NorbixWebhookWireUserDeleted {
+    id: string;
+    from: CodeMashHub2.UserDto;
+}
+/** Wire payload for files.file.uploaded. */
+interface NorbixWebhookWireFileUploaded {
+    integrationId: string;
+    file: CodeMashHub2.FileResourceRefDto;
+}
+/** Wire payload for files.file.deleted. */
+interface NorbixWebhookWireFileDeleted {
+    integrationId: string;
+    path: string;
+}
+
+/**
+ * The normalised payload the receiver hands to a typed handler, per event name.
+ *
+ * - Entity events resolve to the entity itself (`UserDto`, `FileResourceRefDto`).
+ * - Mutation events resolve to `{ from, to }`.
+ * - Batch events resolve to an array.
+ *
+ * For database events the document type is unknown at the catalog level — pass
+ * it as the generic on `on<TDocument>(...)` (see `NorbixWebhookPayload`).
+ */
+interface NorbixWebhookPayloadMap<TDocument = Record<string, unknown>> {
+    'membership.user.registered': CodeMashHub2.UserDto;
+    'membership.user.verified': CodeMashHub2.UserDto;
+    'membership.user.blocked': CodeMashHub2.UserDto;
+    'membership.user.reactivated': CodeMashHub2.UserDto;
+    'membership.user.deleted': CodeMashHub2.UserDto;
+    'membership.user.invited': NorbixWebhookUserInvited;
+    'membership.user.updated': NorbixWebhookMutation<CodeMashHub2.UserDto>;
+    'database.record.inserted': TDocument;
+    'database.record.deleted': TDocument;
+    'database.record.updated': NorbixWebhookMutation<TDocument>;
+    'database.record.replaced': NorbixWebhookMutation<TDocument>;
+    'database.records.inserted': TDocument[];
+    'database.records.updated': {
+        matchedCount: number;
+        modifiedCount: number;
+    };
+    'database.records.deleted': {
+        deletedCount: number;
+    };
+    'database.record.responsibilityChanged': {
+        fromOwnerId: string;
+        toOwnerId: string;
+    };
+    'files.file.uploaded': CodeMashHub2.FileResourceRefDto;
+    'files.file.deleted': NorbixWebhookFileDeleted;
+}
+/** Resolve the typed payload for a known event (with optional document type). */
+type NorbixWebhookPayload<E extends NorbixWebhookEventName, TDocument = Record<string, unknown>> = NorbixWebhookPayloadMap<TDocument>[E];
+/**
+ * Identifiers lifted off the wire payload onto `event.metadata`.
+ * Fields are present only for events that carry them.
+ */
+interface NorbixWebhookEventMetadata {
+    /** The mutated / created entity id (membership events). */
+    user?: {
+        id: string;
+    };
+    /** Schema info for database.* events. `id` is null until the gateway sends it. */
+    schema?: {
+        id: string | null;
+        name: string;
+    };
+    /** Single record id for single-record database events. */
+    record?: {
+        id: string;
+    };
+    /** Record ids for batch database events. */
+    records?: {
+        ids: string[];
+    };
+    /** Integration id for files.* events (and database events that carry it). */
+    integrationId?: string;
+}
+
 /** JSON envelope POSTed to every webhook destination. */
 interface NorbixWebhookEnvelope<TData = unknown> {
     /** Stable delivery id — dedupe retries on this (also X-Norbix-Delivery). */
@@ -88,6 +293,32 @@ interface NorbixWebhookHandleInput {
     verify?: boolean;
 }
 type NorbixWebhookHeaderBag = Record<string, string | string[] | undefined> | Headers;
+/**
+ * Metadata object passed as the 2nd arg to a typed handler. Carries the
+ * delivery facts at the top level and payload identifiers under `metadata`.
+ */
+interface NorbixWebhookEvent {
+    /** Logical event name, e.g. "membership.user.registered". */
+    name: string;
+    /** Stable delivery id — dedupe retries on this. */
+    deliveryId: string;
+    /** ISO-8601 UTC emit time. */
+    createdOn: string;
+    triggerId: string | null;
+    /** Present once the gateway sends a correlation header/field; else null. */
+    correlationId: string | null;
+    accountId: string;
+    projectId: string;
+    integrationId: string | null;
+    destinationId: string | null;
+    /** true when signature verified; null when verification was skipped. */
+    verified: boolean | null;
+    /** Identifiers lifted off the wire payload (entity id, schema, record ids). */
+    metadata: NorbixWebhookEventMetadata;
+    /** Escape hatch: the raw envelope, if a handler needs an unmapped field. */
+    raw: NorbixWebhookEnvelope;
+}
+/** Context passed to raw (`onRaw`) handlers alongside the envelope. */
 interface NorbixWebhookContext {
     path?: string;
     headers: NorbixWebhookDeliveryHeaders;
@@ -103,15 +334,52 @@ interface NorbixWebhookHandleResult {
     handled: boolean;
     triggerId?: string | null;
 }
-type NorbixWebhookHandler<TData = unknown> = (envelope: NorbixWebhookEnvelope<TData>, ctx: NorbixWebhookContext) => void | Promise<void>;
-type NorbixWebhookHandlerMap = Partial<Record<NorbixWebhookEventName | string, NorbixWebhookHandler>>;
+/** Typed handler — first arg is the normalised payload, second is metadata. */
+type NorbixWebhookHandler<TPayload = unknown> = (payload: TPayload, event: NorbixWebhookEvent) => void | Promise<void>;
+/** Raw handler — first arg is the envelope, second is the delivery context. */
+type NorbixWebhookRawHandler<TData = unknown> = (envelope: NorbixWebhookEnvelope<TData>, ctx: NorbixWebhookContext) => void | Promise<void>;
 interface NorbixWebhookReceiverOptions {
-    /** When set, verification runs on every delivery. Omit to skip verify. */
+    /**
+     * Signing secret. When set, verification runs on every delivery.
+     * Defaults to `process.env.NORBIX_WEBHOOK_SIGNING_SECRET`. Omit to skip verify.
+     */
     secret?: string;
-    /** Reject timestamps outside this window (seconds). Default 300. */
+    /**
+     * Reject timestamps outside this window (seconds).
+     * Defaults to `process.env.NORBIX_WEBHOOK_TOLERANCE_SECONDS`, else 300.
+     */
     toleranceSeconds?: number;
+    /**
+     * Optional guard — when set, deliveries whose envelope projectId does not
+     * match are rejected. Defaults to `process.env.NORBIX_PROJECT_ID`.
+     */
+    projectId?: string;
+    /**
+     * Optional guard — when set, deliveries whose envelope accountId does not
+     * match are rejected. Defaults to `process.env.NORBIX_ACCOUNT_ID`.
+     */
+    accountId?: string;
 }
 
+/** Result of normalising a wire envelope for a typed handler. */
+interface NorbixWebhookNormalized {
+    /** The payload-first value handed to a typed handler. */
+    payload: unknown;
+    /** Identifiers lifted off the wire payload. */
+    metadata: NorbixWebhookEventMetadata;
+}
+/**
+ * Turn a raw wire envelope into `{ payload, metadata }`.
+ *
+ * - Entity events  → `payload` is the entity (user / document / file).
+ * - Mutation events → `payload` is `{ from, to }`.
+ * - Batch events   → `payload` is the array.
+ *
+ * Wrapper ids (record id, schema, user id, …) are moved onto `metadata`.
+ * Unknown events fall back to `payload = envelope.data`, `metadata = {}`.
+ */
+declare function normalizeNorbixWebhook(envelope: NorbixWebhookEnvelope): NorbixWebhookNormalized;
+
 /** Read Norbix delivery headers from an incoming HTTP request. */
 declare function parseNorbixWebhookHeaders(headers: NorbixWebhookHeaderBag): NorbixWebhookDeliveryHeaders;
 /** Parse the JSON envelope from the raw POST body. */
@@ -135,41 +403,73 @@ declare function computeNorbixWebhookSignature(secret: string, timestamp: string
 /**
  * Register handlers for inbound Norbix webhook deliveries (trigger → destination POST).
  *
- * Triggers with a `WebhookCall` action publish events to configured destinations.
- * This receiver verifies the HMAC signature, parses the envelope, and dispatches
- * to per-event handlers (similar to Stripe's webhook pattern).
+ * Verifies the HMAC signature, parses the envelope, normalises the payload, and
+ * dispatches to per-event handlers.
  *
  * @example
  * ```ts
- * const receiver = new NorbixWebhookReceiver({
- *   secret: process.env.NORBIX_WEBHOOK_SECRET,
- * });
+ * import { NorbixWebhookReceiver, NorbixWebhookEvents } from '@norbix.ai/ts/webhooks';
+ * import type { CodeMashHub2 } from '@norbix.ai/ts/types/hub';
  *
- * receiver.on('database.record.inserted', async (event) => {
- *   console.log('inserted', event.data);
- * });
+ * const receiver = new NorbixWebhookReceiver(); // reads env
  *
- * receiver.onDefault(async (event) => {
- *   console.log('unhandled', event.event);
+ * // Typed: first arg IS the payload, second is metadata.
+ * receiver.on<CodeMashHub2.UserDto>(
+ *   NorbixWebhookEvents.Membership.UserRegistered,
+ *   (user, event) => {
+ *     user.email ?? user.userName;
+ *     event.metadata.user?.id;
+ *   },
+ * );
+ *
+ * // Mutation: payload is { from, to }.
+ * receiver.on(NorbixWebhookEvents.Membership.UserUpdated, (user, event) => {
+ *   if (user.from.email !== user.to.email) { ... }
  * });
  *
+ * // Raw escape hatch: (envelope, ctx).
+ * receiver.onRaw(NorbixWebhookEvents.Files.FileUploaded, (envelope, ctx) => {});
+ *
  * await receiver.handle({ rawBody, headers: req.headers });
  * ```
  */
 declare class NorbixWebhookReceiver {
-    private readonly options;
     private readonly handlers;
     private defaultHandler?;
+    private readonly config;
     constructor(options?: NorbixWebhookReceiverOptions);
-    /** Handle a specific event name (e.g. membership.user.registered). */
+    /**
+     * Membership user entity events (create / delete / state flip) — `payload`
+     * is the user directly. Pass the entity type as the generic, e.g.
+     * `on<CodeMashHub2.UserDto>(NorbixWebhookEvents.Membership.UserRegistered, ...)`.
+     */
+    on<TUser = CodeMashHub2.UserDto>(event: 'membership.user.registered' | 'membership.user.verified' | 'membership.user.blocked' | 'membership.user.reactivated' | 'membership.user.deleted', handler: NorbixWebhookHandler<TUser>): this;
+    /** Membership user-updated mutation — `payload` is `{ from, to }`. */
+    on<TUser = CodeMashHub2.UserDto>(event: 'membership.user.updated', handler: NorbixWebhookHandler<NorbixWebhookMutation<TUser>>): this;
+    /** Database record mutation — pass the document type; `payload` is `{ from, to }`. */
+    on<TDocument>(event: 'database.record.updated' | 'database.record.replaced', handler: NorbixWebhookHandler<NorbixWebhookMutation<TDocument>>): this;
+    /** Database single-record entity — pass the document type; `payload` is the document. */
+    on<TDocument>(event: 'database.record.inserted' | 'database.record.deleted', handler: NorbixWebhookHandler<TDocument>): this;
+    /** Database batch insert — pass the document type; `payload` is the array. */
+    on<TDocument>(event: 'database.records.inserted', handler: NorbixWebhookHandler<TDocument[]>): this;
+    /** Any known catalog event — `payload` typed from the payload map. */
+    on<E extends NorbixWebhookEventName>(event: E, handler: NorbixWebhookHandler<NorbixWebhookPayload<E>>): this;
+    /** Any event name — untyped payload. */
     on(event: string, handler: NorbixWebhookHandler): this;
-    /** Fallback when no event-specific handler is registered. */
-    onDefault(handler: NorbixWebhookHandler): this;
+    /** Register the typed handler for many events at once (skips already-registered). */
+    onEach(events: readonly string[], handler: NorbixWebhookHandler): this;
+    /** Raw handler for one event — receives the envelope and delivery context. */
+    onRaw<TData = unknown>(event: string, handler: NorbixWebhookRawHandler<TData>): this;
+    /** Register a raw handler for many events at once (skips already-registered). */
+    onEachRaw(events: readonly string[], handler: NorbixWebhookRawHandler): this;
+    /** Fallback (raw) when no event-specific handler is registered. */
+    onDefault(handler: NorbixWebhookRawHandler): this;
     /**
-     * Verify (when secret configured), parse, and dispatch the delivery.
-     * Returns 200-worthy result — throw NorbixWebhookSignatureError for 401.
+     * Verify (when secret configured), parse, normalise, and dispatch the delivery.
+     * Throws NorbixWebhookSignatureError (401-worthy) on bad signature or guard
+     * mismatch; otherwise returns a 200-worthy result.
      */
     handle(input: NorbixWebhookHandleInput): Promise<NorbixWebhookHandleResult>;
 }
 
-export { NORBIX_WEBHOOK_EVENT_GROUPS, NORBIX_WEBHOOK_EVENT_NAMES, NORBIX_WEBHOOK_HEADERS, type NorbixWebhookContext, type NorbixWebhookDeliveryHeaders, type NorbixWebhookEnvelope, NorbixWebhookError, type NorbixWebhookEventGroup, type NorbixWebhookEventName, type NorbixWebhookHandleInput, type NorbixWebhookHandleResult, type NorbixWebhookHandler, type NorbixWebhookHandlerMap, type NorbixWebhookHeaderBag, type NorbixWebhookHeaderName, NorbixWebhookParseError, NorbixWebhookReceiver, type NorbixWebhookReceiverOptions, NorbixWebhookSignatureError, type NorbixWebhookSignatureVerification, type NorbixWebhookVerifyOptions, computeNorbixWebhookSignature, parseNorbixWebhookEnvelope, parseNorbixWebhookHeaders, verifyNorbixWebhookSignature };
+export { NORBIX_WEBHOOK_EVENT_GROUPS, NORBIX_WEBHOOK_EVENT_NAMES, NORBIX_WEBHOOK_HEADERS, type NorbixWebhookContext, type NorbixWebhookDeliveryHeaders, type NorbixWebhookEnvelope, NorbixWebhookError, type NorbixWebhookEvent, type NorbixWebhookEventGroup, type NorbixWebhookEventMetadata, type NorbixWebhookEventName, NorbixWebhookEvents, type NorbixWebhookFileDeleted, type NorbixWebhookHandleInput, type NorbixWebhookHandleResult, type NorbixWebhookHandler, type NorbixWebhookHeaderBag, type NorbixWebhookHeaderName, type NorbixWebhookMutation, type NorbixWebhookNormalized, NorbixWebhookParseError, type NorbixWebhookPayload, type NorbixWebhookPayloadMap, type NorbixWebhookRawHandler, NorbixWebhookReceiver, type NorbixWebhookReceiverOptions, type NorbixWebhookRecordUpdated, NorbixWebhookSignatureError, type NorbixWebhookSignatureVerification, type NorbixWebhookUserInvited, type NorbixWebhookUserUpdated, type NorbixWebhookVerifyOptions, type NorbixWebhookWireDatabaseRecord, type NorbixWebhookWireDatabaseRecordResponsibilityChanged, type NorbixWebhookWireDatabaseRecordUpdated, type NorbixWebhookWireDatabaseRecordsDeleted, type NorbixWebhookWireDatabaseRecordsInserted, type NorbixWebhookWireDatabaseRecordsUpdated, type NorbixWebhookWireFileDeleted, type NorbixWebhookWireFileUploaded, type NorbixWebhookWireUserDeleted, type NorbixWebhookWireUserRegistered, type NorbixWebhookWireUserTransition, computeNorbixWebhookSignature, normalizeNorbixWebhook, parseNorbixWebhookEnvelope, parseNorbixWebhookHeaders, verifyNorbixWebhookSignature };