@xtandard/webhooks 0.1.0

package/dist/contract-CiPskNvS.d.cts

@@ -0,0 +1,46 @@
+import { n as Principal } from "./contract-lETlIuXo.cjs";
+
+//#region src/authorization/contract.d.ts
+/** The full set of authorizable actions. */
+type WebhooksAction = "application:read" | "application:create" | "application:update" | "application:delete" | "event-type:read" | "event-type:create" | "event-type:update" | "event-type:delete" | "endpoint:read" | "endpoint:create" | "endpoint:update" | "endpoint:delete" | "endpoint:rotate-secret" | "endpoint:read-secret" | "message:read" | "message:publish" | "delivery:read" | "delivery:retry" | "audit:read";
+/** The resource an action targets. */
+type WebhooksResource = {
+  type: "application";
+  applicationKey: string;
+} | {
+  type: "event-type";
+  name: string;
+} | {
+  type: "endpoint";
+  applicationKey: string;
+  endpointId: string;
+} | {
+  type: "message";
+  applicationKey: string;
+  messageId?: string;
+} | {
+  type: "delivery";
+  applicationKey: string;
+  deliveryId?: string;
+} | {
+  type: "audit";
+  applicationKey?: string;
+};
+/** Input passed to {@link AuthorizationProvider.authorize}. */
+interface AuthorizeInput {
+  principal: Principal | null;
+  action: WebhooksAction;
+  resource: WebhooksResource;
+  request: Request;
+}
+/** Decides whether an action is permitted. */
+interface AuthorizationProvider {
+  authorize(input: AuthorizeInput): Promise<boolean>;
+}
+/** Actions that mutate state — blocked in readonly mode. */
+declare const MUTATING_ACTIONS: ReadonlySet<WebhooksAction>;
+/** True if the action mutates state. */
+declare const isMutatingAction: (action: WebhooksAction) => boolean;
+//#endregion
+export { WebhooksResource as a, WebhooksAction as i, AuthorizeInput as n, isMutatingAction as o, MUTATING_ACTIONS as r, AuthorizationProvider as t };
+//# sourceMappingURL=contract-CiPskNvS.d.cts.map

package/dist/contract-DhQ4JjGG.d.mts

@@ -0,0 +1,71 @@
+import { o as Delivery } from "./schema-mo__wv4P.mjs";
+
+//#region src/storage/contract.d.ts
+/** The minimal key/value contract every storage backend must satisfy. */
+interface WebhooksStorage {
+  /** Read a value, or `null` if absent. */
+  getItem<T>(key: string): Promise<T | null>;
+  /** Write a value (overwriting any existing). */
+  setItem<T>(key: string, value: T): Promise<void>;
+  /** Delete a key (no-op if absent). */
+  removeItem(key: string): Promise<void>;
+  /** List all keys beginning with `prefix`. */
+  getKeys(prefix: string): Promise<string[]>;
+}
+/** A storage change event delivered to {@link WatchableWebhooksStorage.watch} callbacks. */
+interface StorageChangeEvent {
+  type: "update" | "remove";
+  key: string;
+}
+/** Storage that can push change notifications (e.g. Redis pub/sub, fs.watch). */
+interface WatchableWebhooksStorage extends WebhooksStorage {
+  /**
+   * Subscribe to changes under `prefix`. Resolves to an unsubscribe function.
+   */
+  watch(prefix: string, callback: (event: StorageChangeEvent) => void): Promise<() => void>;
+}
+/** Storage that supports atomic multi-key transactions. */
+interface TransactionalWebhooksStorage extends WebhooksStorage {
+  transaction<T>(callback: (tx: WebhooksStorage) => Promise<T>): Promise<T>;
+}
+/** Storage that supports optimistic concurrency via compare-and-swap. */
+interface CompareAndSwapWebhooksStorage extends WebhooksStorage {
+  compareAndSwap<T>(input: {
+    key: string;
+    expected: T | null;
+    next: T;
+  }): Promise<boolean>;
+}
+/**
+ * Storage that can natively claim due deliveries (sorted-set / `SKIP LOCKED`
+ * class backends). When present, the dispatcher delegates claiming entirely to
+ * the adapter instead of scanning the generic due index.
+ *
+ * The claim contract: atomically transition each returned delivery to
+ * `status: "delivering"` with `leaseUntil = now + leaseMs`, reposition its due
+ * entry at the lease expiry (so a crashed claimer's work re-surfaces), and
+ * never return the same delivery to two concurrent claimers.
+ */
+interface DeliveryQueueStorage extends WebhooksStorage {
+  claimDue(input: {
+    now: string;
+    limit: number;
+    leaseMs: number;
+  }): Promise<Delivery[]>;
+}
+/** Runtime feature-detection: does this storage implement `watch`? */
+declare function isWatchable(storage: WebhooksStorage): storage is WatchableWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `transaction`? */
+declare function isTransactional(storage: WebhooksStorage): storage is TransactionalWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `compareAndSwap`? */
+declare function isCompareAndSwap(storage: WebhooksStorage): storage is CompareAndSwapWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `claimDue`? */
+declare function hasDeliveryQueue(storage: WebhooksStorage): storage is DeliveryQueueStorage;
+/**
+ * Helper for adapters whose subpath requires an optional peer dependency. Throws
+ * a clear, actionable error when the peer is missing.
+ */
+declare function requirePeer(name: string, subpath: string): never;
+//#endregion
+export { WatchableWebhooksStorage as a, isCompareAndSwap as c, requirePeer as d, TransactionalWebhooksStorage as i, isTransactional as l, DeliveryQueueStorage as n, WebhooksStorage as o, StorageChangeEvent as r, hasDeliveryQueue as s, CompareAndSwapWebhooksStorage as t, isWatchable as u };
+//# sourceMappingURL=contract-DhQ4JjGG.d.mts.map

package/dist/contract-T1kcZNdG.d.mts

@@ -0,0 +1,177 @@
+import { a as AuditEntry, f as EventType, l as Endpoint, m as Message, n as Application, o as Delivery, p as JsonValue, s as DeliveryAttempt, t as Actor } from "./schema-mo__wv4P.mjs";
+
+//#region src/hooks/contract.d.ts
+/**
+ * Event delivered to {@link WebhooksHooks.before} — the *proposed* mutation,
+ * before it commits. Throw from the handler to deny it.
+ */
+type BeforeEvent = {
+  type: "application.create" | "application.update";
+  application: Application;
+  actor: Actor | null;
+} | {
+  type: "application.delete";
+  applicationKey: string;
+  actor: Actor | null;
+} | {
+  type: "event-type.upsert";
+  eventType: EventType;
+  actor: Actor | null;
+} | {
+  type: "event-type.delete";
+  name: string;
+  actor: Actor | null;
+} | {
+  type: "endpoint.create" | "endpoint.update";
+  applicationKey: string;
+  endpoint: Endpoint;
+  actor: Actor | null;
+} | {
+  type: "endpoint.delete" | "endpoint.rotate-secret" | "endpoint.disable" | "endpoint.enable";
+  applicationKey: string;
+  endpointId: string;
+  actor: Actor | null;
+} | {
+  /** The host's approval/quota gate for the publish hot path. */type: "message.publish";
+  applicationKey: string;
+  eventType: string;
+  payload: JsonValue;
+  idempotencyKey?: string;
+  actor: Actor | null;
+} | {
+  type: "delivery.retry";
+  applicationKey: string;
+  deliveryId: string;
+  actor: Actor | null;
+} | {
+  type: "endpoint.recover";
+  applicationKey: string;
+  endpointId: string;
+  since: string;
+  actor: Actor | null;
+};
+/**
+ * Event delivered to {@link WebhooksHooks.after} — the *committed* mutation.
+ * Carries the resulting state in full: for destructive events this is the last
+ * chance to offload the payload before it is gone from storage.
+ */
+type AfterEvent = {
+  type: "application.created" | "application.updated";
+  application: Application;
+  at: string;
+} | {
+  /** Carries the deleted application — everything under it is already gone. */type: "application.deleted";
+  applicationKey: string;
+  application: Application;
+  at: string;
+} | {
+  type: "event-type.upserted";
+  eventType: EventType;
+  at: string;
+} | {
+  type: "event-type.deleted";
+  name: string;
+  eventType: EventType;
+  at: string;
+} | {
+  type: "endpoint.created" | "endpoint.updated" | "endpoint.deleted" | "endpoint.secret-rotated" | "endpoint.disabled" | "endpoint.enabled" /** Disabled by the failure policy, not an operator (see dispatcher `autoDisable`). */ | "endpoint.auto-disabled";
+  applicationKey: string;
+  endpoint: Endpoint;
+  at: string;
+} | {
+  type: "message.published";
+  applicationKey: string;
+  message: Message;
+  deliveryIds: string[];
+  at: string;
+} | {
+  type: "delivery.succeeded";
+  applicationKey: string;
+  delivery: Delivery;
+  attempt: DeliveryAttempt;
+  at: string;
+} | {
+  /** Dead-letter offload point: the retry schedule is exhausted. */type: "delivery.exhausted";
+  applicationKey: string;
+  delivery: Delivery;
+  attempts: DeliveryAttempt[];
+  at: string;
+} | {
+  /** Messages removed by retention. Carries the **full messages** — offload now or lose them. */type: "message.pruned";
+  applicationKey: string;
+  messages: Message[];
+  at: string;
+} | {
+  /** Audit entries removed by retention (oldest-first). */type: "audit.pruned";
+  applicationKey?: string;
+  entries: AuditEntry[];
+  at: string;
+};
+/** The discriminant strings of {@link BeforeEvent} / {@link AfterEvent}. */
+type BeforeEventType = BeforeEvent["type"];
+type AfterEventType = AfterEvent["type"];
+/**
+ * Thrown from a {@link WebhooksHooks.before} handler to **deny** a mutation with
+ * a clean HTTP status (default `403`). Any thrown error denies the mutation,
+ * but a plain `Error` maps to `500` at the API layer (treated as an unexpected
+ * bug); throw this to signal a deliberate policy rejection (`403`, or a custom
+ * `status` such as `409`/`422`).
+ *
+ * @example
+ * ```ts
+ * before(event) {
+ *   if (event.type === "message.publish" && overQuota(event.applicationKey)) {
+ *     throw new HookDeniedError("Monthly webhook quota exceeded.", { status: 429 });
+ *   }
+ * }
+ * ```
+ */
+declare class HookDeniedError extends Error {
+  /** HTTP status the API layer should respond with. Default `403`. */
+  readonly status: number;
+  constructor(message: string, options?: {
+    status?: number;
+    cause?: unknown;
+  });
+}
+/**
+ * A control-plane hook. Implement `before`, `after`, or both. Pass one — or an
+ * array — to {@link ../core.createWebhooksCore} via `hooks`.
+ */
+interface WebhooksHooks {
+  /**
+   * Runs before a mutation commits. **Throw to deny** (the error propagates to
+   * the caller; its message is the reason). Return/resolve to allow. Must not
+   * mutate the event payload.
+   */
+  before?(event: BeforeEvent): void | Promise<void>;
+  /**
+   * Runs after a mutation commits. For side effects only. Errors are isolated
+   * and reported via `onHookError` — they never fail the (already committed)
+   * operation.
+   */
+  after?(event: AfterEvent): void | Promise<void>;
+}
+/** Accepts a single hook, an array, or nothing. */
+type WebhooksHooksInput = WebhooksHooks | readonly WebhooksHooks[] | undefined;
+/** Reports an error thrown by an `after` hook. */
+type HookErrorReporter = (error: unknown, event: AfterEvent) => void;
+/** Normalize the `hooks` option into a flat array (empty when unset). */
+declare function normalizeHooks(input: WebhooksHooksInput): WebhooksHooks[];
+/**
+ * Run every `before` hook sequentially, in order. The first hook to throw
+ * aborts: the error propagates to the caller (denying the mutation) and no
+ * later hook runs. A no-op when there are no `before` hooks.
+ */
+declare function runBefore(hooks: WebhooksHooks[], event: BeforeEvent): Promise<void>;
+/**
+ * Run every `after` hook, isolating failures. The mutation has already
+ * committed, so a throwing hook must not fail the operation — its error is
+ * routed to `onError` and swallowed. Remaining hooks still run.
+ */
+declare function runAfter(hooks: WebhooksHooks[], event: AfterEvent, onError: HookErrorReporter): Promise<void>;
+/** Default `after`-hook error reporter: warn, but never throw. */
+declare const defaultHookErrorReporter: HookErrorReporter;
+//#endregion
+export { HookDeniedError as a, WebhooksHooksInput as c, runAfter as d, runBefore as f, BeforeEventType as i, defaultHookErrorReporter as l, AfterEventType as n, HookErrorReporter as o, BeforeEvent as r, WebhooksHooks as s, AfterEvent as t, normalizeHooks as u };
+//# sourceMappingURL=contract-T1kcZNdG.d.mts.map

package/dist/contract-lETlIuXo.d.cts

@@ -0,0 +1,30 @@
+//#region src/auth/contract.d.ts
+/**
+ * Authentication contract. Answers: "Who is this request from?"
+ *
+ * `@xtandard/webhooks` ships `none`/`basic`/`delegated` implementations, but any
+ * object satisfying {@link AuthProvider} works — bring your own.
+ *
+ * @module
+ */
+/** An authenticated identity. */
+interface Principal {
+  id: string;
+  email?: string;
+  name?: string;
+  roles?: string[];
+  metadata?: unknown;
+}
+/** Authenticates an incoming web-standard {@link Request}. */
+interface AuthProvider {
+  /** Resolve the principal, or `null` if the request is unauthenticated. */
+  authenticate(request: Request): Promise<Principal | null>;
+  /**
+   * Optional: build a `Response` that prompts for credentials (e.g. a 401 with a
+   * `WWW-Authenticate` header). When omitted, the server returns a plain 401.
+   */
+  challenge?(request: Request): Response | undefined;
+}
+//#endregion
+export { Principal as n, AuthProvider as t };
+//# sourceMappingURL=contract-lETlIuXo.d.cts.map

package/dist/contract-lETlIuXo.d.mts

@@ -0,0 +1,30 @@
+//#region src/auth/contract.d.ts
+/**
+ * Authentication contract. Answers: "Who is this request from?"
+ *
+ * `@xtandard/webhooks` ships `none`/`basic`/`delegated` implementations, but any
+ * object satisfying {@link AuthProvider} works — bring your own.
+ *
+ * @module
+ */
+/** An authenticated identity. */
+interface Principal {
+  id: string;
+  email?: string;
+  name?: string;
+  roles?: string[];
+  metadata?: unknown;
+}
+/** Authenticates an incoming web-standard {@link Request}. */
+interface AuthProvider {
+  /** Resolve the principal, or `null` if the request is unauthenticated. */
+  authenticate(request: Request): Promise<Principal | null>;
+  /**
+   * Optional: build a `Response` that prompts for credentials (e.g. a 401 with a
+   * `WWW-Authenticate` header). When omitted, the server returns a plain 401.
+   */
+  challenge?(request: Request): Response | undefined;
+}
+//#endregion
+export { Principal as n, AuthProvider as t };
+//# sourceMappingURL=contract-lETlIuXo.d.mts.map