@fabricorg/webhook-delivery 0.1.2 → 0.1.3

package/dist/node.d.cts

@@ -1,29 +1,88 @@
-import { g as WebhookClock, a6 as WebhookTransport, aw as WebhookDnsLookup } from './destination-joCBtgvY.cjs';
-import '@fabricorg/platform-host';
-
+import "@fabricorg/platform-host";
+//#region src/ports.d.ts
+/** Bounds every awaited port call. */
+interface WebhookCallOptions {
+  /** The absolute time after which the call's result is ignored. */
+  readonly deadline: Date;
+  /** Aborted when the caller stops waiting; implementations should stop work. */
+  readonly signal: AbortSignal;
+}
+/** One resolved address of a destination host. */
+interface WebhookResolvedAddress {
+  readonly address: string;
+  readonly family: 4 | 6;
+}
+/** A destination that passed the URL rules and whose every resolved answer is public. */
+interface WebhookVettedDestination {
+  readonly url: string;
+  /** Kept for SNI and certificate hostname verification. */
+  readonly hostname: string;
+  readonly port: 443;
+  /** The vetted addresses the transport posts to without re-resolving. */
+  readonly addresses: readonly WebhookResolvedAddress[];
+}
+/** One HTTP request handed to the transport. */
+interface WebhookTransportRequest {
+  readonly destination: WebhookVettedDestination;
+  readonly method: "POST";
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+/**
+ * What the transport observed. `not_sent` means the request never started
+ * (deadline already passed, or the signal aborted while queued) and the
+ * dispatcher releases the intent without spending budget. `timeout` covers a
+ * deadline or abort after the request started. Response bodies are not
+ * returned.
+ */
+type WebhookTransportResult = {
+  readonly kind: "response";
+  readonly status: number;
+  readonly retryAfter?: string | null;
+} | {
+  readonly kind: "network_error" | "timeout" | "dns_failure" | "invalid_url" | "private_address";
+} | {
+  readonly kind: "not_sent";
+  readonly reason: "deadline_expired" | "aborted";
+};
+/**
+ * Posts to the vetted address without re-resolving, verifies certificate and
+ * hostname, refuses redirects and bounds the response. It must reject a
+ * handoff whose deadline has passed and never start a request whose signal
+ * aborted while queued (R3).
+ */
+interface WebhookTransport {
+  send(request: WebhookTransportRequest, options: WebhookCallOptions): Promise<WebhookTransportResult>;
+}
+/** The injected clock. */
+interface WebhookClock {
+  now(): Date;
+}
+//#endregion
+//#region src/node/transport.d.ts
 /** The default response body cap: past it the connection is closed (the crossing chunk is already read). */
-declare const DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES = 65536;
+export declare const DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES = 65536;
 /** The default number of requests one transport runs at once; later calls wait in its queue. */
-declare const DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS = 16;
+export declare const DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS = 16;
 /** Options for {@link createNodeWebhookTransport}. */
 interface NodeWebhookTransportOptions {
-    /**
-     * Response body bytes after which the connection is closed; default
-     * {@link DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES}. The check runs per
-     * chunk, so the bytes read can exceed it by up to one chunk. The body is
-     * discarded as it arrives and never kept or returned: only the status and
-     * `Retry-After` are.
-     */
-    readonly maxResponseBytes?: number;
-    /** Requests in flight at once; default {@link DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS}. */
-    readonly maxConcurrentRequests?: number;
-    /**
-     * PEM trust anchors that replace Node's bundled roots, for a receiver
-     * behind a private CA. Certificate and hostname verification stay on.
-     */
-    readonly ca?: string | readonly string[];
-    /** The clock the call's deadline is compared with; the system clock by default. */
-    readonly clock?: WebhookClock;
+  /**
+   * Response body bytes after which the connection is closed; default
+   * {@link DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES}. The check runs per
+   * chunk, so the bytes read can exceed it by up to one chunk. The body is
+   * discarded as it arrives and never kept or returned: only the status and
+   * `Retry-After` are.
+   */
+  readonly maxResponseBytes?: number;
+  /** Requests in flight at once; default {@link DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS}. */
+  readonly maxConcurrentRequests?: number;
+  /**
+   * PEM trust anchors that replace Node's bundled roots, for a receiver
+   * behind a private CA. Certificate and hostname verification stay on.
+   */
+  readonly ca?: string | readonly string[];
+  /** The clock the call's deadline is compared with; the system clock by default. */
+  readonly clock?: WebhookClock;
 }
 /**
  * The Node `WebhookTransport` (ADR 0018 decision 6, R3, R8).
@@ -68,16 +127,27 @@ interface NodeWebhookTransportOptions {
  * @throws {WebhookDeliveryConfigError} when `maxResponseBytes` or
  * `maxConcurrentRequests` (at most 1024) is not a positive whole number.
  */
-declare function createNodeWebhookTransport(options?: NodeWebhookTransportOptions): WebhookTransport;
-
+export declare function createNodeWebhookTransport(options?: NodeWebhookTransportOptions): WebhookTransport;
+//#endregion
+//#region src/destination.d.ts
+/**
+ * Looks up a hostname's addresses. It is passed `{ deadline, signal }`; the
+ * resolver aborts `signal` when it stops waiting, and ignores any answer that
+ * arrives after that. Each answer is `{ address, family }` with a textual IPv4
+ * or IPv6 address. `createNodeWebhookDnsLookup()` at
+ * `@fabricorg/webhook-delivery/node` is one implementation.
+ */
+type WebhookDnsLookup = (hostname: string, options: WebhookCallOptions) => Promise<readonly WebhookResolvedAddress[]>;
+//#endregion
+//#region src/node/lookup.d.ts
 /** The default per-query timeout of {@link createNodeWebhookDnsLookup}. */
-declare const DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS = 5000;
+export declare const DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS = 5000;
 /** Options for {@link createNodeWebhookDnsLookup}. */
 interface NodeWebhookDnsLookupOptions {
-    /** DNS servers (`"ip"` or `"ip:port"`), as `Resolver.setServers` takes them; the system's by default. */
-    readonly servers?: readonly string[];
-    /** Timeout of each A and AAAA query; default {@link DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS}. */
-    readonly timeoutMs?: number;
+  /** DNS servers (`"ip"` or `"ip:port"`), as `Resolver.setServers` takes them; the system's by default. */
+  readonly servers?: readonly string[];
+  /** Timeout of each A and AAAA query; default {@link DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
 }
 /**
  * A {@link WebhookDnsLookup} for `createWebhookDestinationResolver()` built on
@@ -99,6 +169,6 @@ interface NodeWebhookDnsLookupOptions {
  * @throws {WebhookDeliveryConfigError} when `timeoutMs` is not a positive
  * whole number of at most `WEBHOOK_MAX_TIMER_MS`.
  */
-declare function createNodeWebhookDnsLookup(options?: NodeWebhookDnsLookupOptions): WebhookDnsLookup;
-
-export { DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS, DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS, DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES, type NodeWebhookDnsLookupOptions, type NodeWebhookTransportOptions, createNodeWebhookDnsLookup, createNodeWebhookTransport };
+export declare function createNodeWebhookDnsLookup(options?: NodeWebhookDnsLookupOptions): WebhookDnsLookup;
+//#endregion
+export type { NodeWebhookDnsLookupOptions, NodeWebhookTransportOptions };

package/dist/node.d.ts

@@ -1,29 +1,88 @@
-import { g as WebhookClock, a6 as WebhookTransport, aw as WebhookDnsLookup } from './destination-joCBtgvY.js';
-import '@fabricorg/platform-host';
-
+import "@fabricorg/platform-host";
+//#region src/ports.d.ts
+/** Bounds every awaited port call. */
+interface WebhookCallOptions {
+  /** The absolute time after which the call's result is ignored. */
+  readonly deadline: Date;
+  /** Aborted when the caller stops waiting; implementations should stop work. */
+  readonly signal: AbortSignal;
+}
+/** One resolved address of a destination host. */
+interface WebhookResolvedAddress {
+  readonly address: string;
+  readonly family: 4 | 6;
+}
+/** A destination that passed the URL rules and whose every resolved answer is public. */
+interface WebhookVettedDestination {
+  readonly url: string;
+  /** Kept for SNI and certificate hostname verification. */
+  readonly hostname: string;
+  readonly port: 443;
+  /** The vetted addresses the transport posts to without re-resolving. */
+  readonly addresses: readonly WebhookResolvedAddress[];
+}
+/** One HTTP request handed to the transport. */
+interface WebhookTransportRequest {
+  readonly destination: WebhookVettedDestination;
+  readonly method: "POST";
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+/**
+ * What the transport observed. `not_sent` means the request never started
+ * (deadline already passed, or the signal aborted while queued) and the
+ * dispatcher releases the intent without spending budget. `timeout` covers a
+ * deadline or abort after the request started. Response bodies are not
+ * returned.
+ */
+type WebhookTransportResult = {
+  readonly kind: "response";
+  readonly status: number;
+  readonly retryAfter?: string | null;
+} | {
+  readonly kind: "network_error" | "timeout" | "dns_failure" | "invalid_url" | "private_address";
+} | {
+  readonly kind: "not_sent";
+  readonly reason: "deadline_expired" | "aborted";
+};
+/**
+ * Posts to the vetted address without re-resolving, verifies certificate and
+ * hostname, refuses redirects and bounds the response. It must reject a
+ * handoff whose deadline has passed and never start a request whose signal
+ * aborted while queued (R3).
+ */
+interface WebhookTransport {
+  send(request: WebhookTransportRequest, options: WebhookCallOptions): Promise<WebhookTransportResult>;
+}
+/** The injected clock. */
+interface WebhookClock {
+  now(): Date;
+}
+//#endregion
+//#region src/node/transport.d.ts
 /** The default response body cap: past it the connection is closed (the crossing chunk is already read). */
-declare const DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES = 65536;
+export declare const DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES = 65536;
 /** The default number of requests one transport runs at once; later calls wait in its queue. */
-declare const DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS = 16;
+export declare const DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS = 16;
 /** Options for {@link createNodeWebhookTransport}. */
 interface NodeWebhookTransportOptions {
-    /**
-     * Response body bytes after which the connection is closed; default
-     * {@link DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES}. The check runs per
-     * chunk, so the bytes read can exceed it by up to one chunk. The body is
-     * discarded as it arrives and never kept or returned: only the status and
-     * `Retry-After` are.
-     */
-    readonly maxResponseBytes?: number;
-    /** Requests in flight at once; default {@link DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS}. */
-    readonly maxConcurrentRequests?: number;
-    /**
-     * PEM trust anchors that replace Node's bundled roots, for a receiver
-     * behind a private CA. Certificate and hostname verification stay on.
-     */
-    readonly ca?: string | readonly string[];
-    /** The clock the call's deadline is compared with; the system clock by default. */
-    readonly clock?: WebhookClock;
+  /**
+   * Response body bytes after which the connection is closed; default
+   * {@link DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES}. The check runs per
+   * chunk, so the bytes read can exceed it by up to one chunk. The body is
+   * discarded as it arrives and never kept or returned: only the status and
+   * `Retry-After` are.
+   */
+  readonly maxResponseBytes?: number;
+  /** Requests in flight at once; default {@link DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS}. */
+  readonly maxConcurrentRequests?: number;
+  /**
+   * PEM trust anchors that replace Node's bundled roots, for a receiver
+   * behind a private CA. Certificate and hostname verification stay on.
+   */
+  readonly ca?: string | readonly string[];
+  /** The clock the call's deadline is compared with; the system clock by default. */
+  readonly clock?: WebhookClock;
 }
 /**
  * The Node `WebhookTransport` (ADR 0018 decision 6, R3, R8).
@@ -68,16 +127,27 @@ interface NodeWebhookTransportOptions {
  * @throws {WebhookDeliveryConfigError} when `maxResponseBytes` or
  * `maxConcurrentRequests` (at most 1024) is not a positive whole number.
  */
-declare function createNodeWebhookTransport(options?: NodeWebhookTransportOptions): WebhookTransport;
-
+export declare function createNodeWebhookTransport(options?: NodeWebhookTransportOptions): WebhookTransport;
+//#endregion
+//#region src/destination.d.ts
+/**
+ * Looks up a hostname's addresses. It is passed `{ deadline, signal }`; the
+ * resolver aborts `signal` when it stops waiting, and ignores any answer that
+ * arrives after that. Each answer is `{ address, family }` with a textual IPv4
+ * or IPv6 address. `createNodeWebhookDnsLookup()` at
+ * `@fabricorg/webhook-delivery/node` is one implementation.
+ */
+type WebhookDnsLookup = (hostname: string, options: WebhookCallOptions) => Promise<readonly WebhookResolvedAddress[]>;
+//#endregion
+//#region src/node/lookup.d.ts
 /** The default per-query timeout of {@link createNodeWebhookDnsLookup}. */
-declare const DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS = 5000;
+export declare const DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS = 5000;
 /** Options for {@link createNodeWebhookDnsLookup}. */
 interface NodeWebhookDnsLookupOptions {
-    /** DNS servers (`"ip"` or `"ip:port"`), as `Resolver.setServers` takes them; the system's by default. */
-    readonly servers?: readonly string[];
-    /** Timeout of each A and AAAA query; default {@link DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS}. */
-    readonly timeoutMs?: number;
+  /** DNS servers (`"ip"` or `"ip:port"`), as `Resolver.setServers` takes them; the system's by default. */
+  readonly servers?: readonly string[];
+  /** Timeout of each A and AAAA query; default {@link DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
 }
 /**
  * A {@link WebhookDnsLookup} for `createWebhookDestinationResolver()` built on
@@ -99,6 +169,6 @@ interface NodeWebhookDnsLookupOptions {
  * @throws {WebhookDeliveryConfigError} when `timeoutMs` is not a positive
  * whole number of at most `WEBHOOK_MAX_TIMER_MS`.
  */
-declare function createNodeWebhookDnsLookup(options?: NodeWebhookDnsLookupOptions): WebhookDnsLookup;
-
-export { DEFAULT_NODE_WEBHOOK_DNS_TIMEOUT_MS, DEFAULT_NODE_WEBHOOK_MAX_CONCURRENT_REQUESTS, DEFAULT_NODE_WEBHOOK_MAX_RESPONSE_BYTES, type NodeWebhookDnsLookupOptions, type NodeWebhookTransportOptions, createNodeWebhookDnsLookup, createNodeWebhookTransport };
+export declare function createNodeWebhookDnsLookup(options?: NodeWebhookDnsLookupOptions): WebhookDnsLookup;
+//#endregion
+export type { NodeWebhookDnsLookupOptions, NodeWebhookTransportOptions };