webhookadmin 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,430 @@
+/** One page of a list. */
+interface Page<T> {
+    items: T[];
+    /** Pass as `cursor` to get the next page. `null` on the last page. */
+    next_cursor: string | null;
+}
+type MessageStatus = 'pending' | 'retrying' | 'success' | 'failed';
+/** `held` means the endpoint is paused; sent when it is set back to `active`. */
+type DeliveryStatus = 'pending' | 'held' | 'retrying' | 'success' | 'failed';
+type EndpointStatus = 'active' | 'paused' | 'disabled';
+interface ConsumerRef {
+    id: string;
+    external_id: string;
+    name: string;
+}
+/** A message in a list. */
+interface MessageSummary {
+    id: string;
+    event_type: string;
+    consumer: ConsumerRef;
+    /** Unix milliseconds. */
+    created_at: number;
+    status: MessageStatus;
+    attempts: number;
+    /** URL of the first endpoint, or `null` when the consumer had no endpoint. */
+    endpoint_url: string | null;
+}
+interface Attempt {
+    id: string;
+    /** Unix milliseconds. */
+    at: number;
+    response_status: number | null;
+    /** First 1024 bytes of the response body. */
+    response_head: string | null;
+    duration_ms: number;
+    error: string | null;
+    via: 'direct' | 'relay';
+    /** Static IP used when sent through the relay. `null` for direct sends. */
+    source_ip: string | null;
+}
+interface Delivery {
+    id: string;
+    endpoint_id: string;
+    url: string;
+    status: DeliveryStatus;
+    attempt_count: number;
+    /** Unix milliseconds, or `null` when no retry is scheduled. */
+    next_attempt_at: number | null;
+    attempts: Attempt[];
+}
+interface Message {
+    id: string;
+    event_type: string;
+    consumer: ConsumerRef;
+    created_at: number;
+    status: MessageStatus;
+    idempotency_key: string | null;
+    /** The payload as sent. `null` if it is no longer stored. */
+    payload: unknown;
+    deliveries: Delivery[];
+}
+interface SendMessageParams {
+    /** Your customer's ID (`external_id`). A consumer is created if it does not exist. */
+    consumer: string;
+    /** Event type, such as `invoice.paid`. */
+    event_type: string;
+    /** Any JSON value, up to 1 MB. Delivered as `data`. */
+    payload: unknown;
+}
+interface SendMessageResponse {
+    id: string;
+    /** Number of endpoints the message is delivered to. */
+    deliveries: number;
+}
+interface MessageListParams {
+    status?: MessageStatus;
+    event_type?: string;
+    /** Matches the message ID, event type, consumer external_id, or payload text (3+ characters). */
+    q?: string;
+    /** 1 to 100. Default 50. */
+    limit?: number;
+    cursor?: string;
+}
+interface Consumer {
+    id: string;
+    external_id: string;
+    name: string;
+    created_at: number;
+    endpoint_count: number;
+}
+interface ConsumerCreateParams {
+    external_id: string;
+    name?: string;
+}
+interface ConsumerListParams {
+    /** 1 to 100. Default 50. */
+    limit?: number;
+    cursor?: string;
+}
+interface Endpoint {
+    id: string;
+    consumer_id: string;
+    url: string;
+    description: string;
+    /** Event types sent to this endpoint. `null` means all. */
+    event_types: string[] | null;
+    /** Sent through the static-IP relay. */
+    fixed_ip: boolean;
+    status: EndpointStatus;
+    disabled_reason: string | null;
+    /** Unix milliseconds since failures started, or `null`. */
+    failing_since: number | null;
+    created_at: number;
+}
+interface EndpointWithSecret extends Endpoint {
+    /** Signing secret (`whsec_…`). Returned only when the endpoint is created. */
+    secret: string;
+}
+interface EndpointDetail extends Endpoint {
+    /** Latest attempts to this endpoint this month (up to 20). */
+    recent: Attempt[];
+    /** Deliveries waiting for a retry. */
+    retrying_count: number;
+}
+interface EndpointCreateParams {
+    consumer_id: string;
+    /** https (port 443 or 8443). */
+    url: string;
+    /** Omit or `null` to receive all event types. */
+    event_types?: string[] | null;
+    fixed_ip?: boolean;
+    description?: string;
+}
+interface EndpointUpdateParams {
+    url?: string;
+    event_types?: string[] | null;
+    /** `active` also re-enables a disabled endpoint and sends messages held while paused. */
+    status?: 'active' | 'paused';
+    description?: string;
+}
+interface EndpointListParams {
+    consumer_id?: string;
+}
+interface EndpointSendTestParams {
+    /** Default `webhook.test`. */
+    event_type?: string;
+}
+interface RotateSecretResponse {
+    /** New signing secret. The previous one keeps signing for 24 hours. */
+    secret: string;
+}
+interface SendTestResponse {
+    message_id: string;
+}
+interface PortalLinkParams {
+    /** Origin of the page that embeds the portal in an iframe, such as `https://app.example.com`. */
+    frame_origin?: string;
+    locale?: 'ja' | 'en';
+}
+interface PortalLink {
+    /** One-time URL of the consumer portal. */
+    url: string;
+    /** Unix milliseconds. The link is valid for 15 minutes. */
+    expires_at: number;
+}
+/** Per-request options. */
+interface RequestOptions {
+    /** Milliseconds. Overrides the client's `timeout`. */
+    timeout?: number;
+    /** Overrides the client's `maxRetries`. */
+    maxRetries?: number;
+    signal?: AbortSignal;
+}
+interface SendMessageOptions extends RequestOptions {
+    /**
+     * 1 to 256 characters. The same key returns the same message for 24 hours.
+     * Generated when omitted, and reused across retries.
+     */
+    idempotencyKey?: string;
+}
+
+type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+type HttpConfig = {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    fetch: Fetch;
+};
+type Query = Record<string, string | number | undefined>;
+type HttpRequest = {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Query;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /**
+     * Safe to send twice. 5xx and network errors are retried only for these.
+     * 429 is always retried: the API rejects it before doing anything.
+     */
+    idempotent: boolean;
+};
+declare class Http {
+    readonly config: HttpConfig;
+    constructor(config: HttpConfig);
+    url(path: string, query?: Query): string;
+    request<T>(req: HttpRequest, options?: RequestOptions): Promise<T>;
+    private once;
+}
+
+/**
+ * Result of a `list()` call.
+ * `await` it for the first page, or iterate with `for await` to walk every item across pages.
+ */
+declare class PagePromise<T> implements PromiseLike<Page<T>>, AsyncIterable<T> {
+    private readonly fetchPage;
+    private readonly cursor;
+    private first;
+    /** @internal */
+    constructor(fetchPage: (cursor: string | undefined) => Promise<Page<T>>, cursor: string | undefined);
+    private firstPage;
+    then<A = Page<T>, B = never>(onfulfilled?: ((value: Page<T>) => A | PromiseLike<A>) | null, onrejected?: ((reason: any) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onrejected?: ((reason: any) => B | PromiseLike<B>) | null): Promise<Page<T> | B>;
+    finally(onfinally?: (() => void) | null): Promise<Page<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+declare class Consumers {
+    private readonly http;
+    /** @internal */
+    constructor(http: Http);
+    /** Creates a consumer. A duplicate `external_id` throws `ConflictError`. Requires `consumers:write`. */
+    create(params: ConsumerCreateParams, options?: RequestOptions): Promise<Consumer>;
+    /** Lists consumers. Requires `logs:read`. */
+    list(params?: ConsumerListParams, options?: RequestOptions): PagePromise<Consumer>;
+}
+
+declare class Deliveries {
+    private readonly http;
+    /** @internal */
+    constructor(http: Http);
+    /**
+     * Sends a finished delivery again. A delivery still being sent throws `ConflictError`.
+     * Requires `messages:retry`.
+     */
+    retry(deliveryId: string, options?: RequestOptions): Promise<void>;
+}
+
+declare class Endpoints {
+    private readonly http;
+    /** @internal */
+    constructor(http: Http);
+    /** Creates an endpoint. The signing secret is returned only here. Requires `endpoints:write`. */
+    create(params: EndpointCreateParams, options?: RequestOptions): Promise<EndpointWithSecret>;
+    /** Lists endpoints, optionally for one consumer. All endpoints come in one page. Requires `logs:read`. */
+    list(params?: EndpointListParams, options?: RequestOptions): PagePromise<Endpoint>;
+    /** Gets an endpoint with its latest attempts. Requires `logs:read`. */
+    get(endpointId: string, options?: RequestOptions): Promise<EndpointDetail>;
+    /** Updates an endpoint. Set `status: 'active'` to resume a paused or disabled endpoint. Requires `endpoints:write`. */
+    update(endpointId: string, params: EndpointUpdateParams, options?: RequestOptions): Promise<Endpoint>;
+    /** Deletes an endpoint. Requires `endpoints:write`. */
+    delete(endpointId: string, options?: RequestOptions): Promise<void>;
+    /** Issues a new signing secret. The previous one keeps signing for 24 hours. Requires `endpoints:write`. */
+    rotateSecret(endpointId: string, options?: RequestOptions): Promise<RotateSecretResponse>;
+    /** Sends a test message to this endpoint only. Not counted in usage. Requires `messages:send`. */
+    sendTest(endpointId: string, params?: EndpointSendTestParams, options?: RequestOptions): Promise<SendTestResponse>;
+}
+
+declare class Messages {
+    private readonly http;
+    /** @internal */
+    constructor(http: Http);
+    /**
+     * Sends a message to every active endpoint of the consumer that accepts the event type.
+     * Requires the `messages:send` scope.
+     */
+    send(params: SendMessageParams, options?: SendMessageOptions): Promise<SendMessageResponse>;
+    /** Lists messages, newest first. Requires `logs:read`. */
+    list(params?: MessageListParams, options?: RequestOptions): PagePromise<MessageSummary>;
+    /** Gets a message with its deliveries and attempts. Requires `logs:read`. */
+    get(messageId: string, options?: RequestOptions): Promise<Message>;
+}
+
+declare class Portal {
+    private readonly http;
+    /** @internal */
+    constructor(http: Http);
+    /**
+     * Creates a 15-minute link to the consumer portal, where your customer manages their own endpoints.
+     * Starter plan or above. Requires `endpoints:write`.
+     */
+    createLink(consumerId: string, params?: PortalLinkParams, options?: RequestOptions): Promise<PortalLink>;
+}
+
+interface ClientOptions {
+    /** Default `https://api.webhookadmin.com`. */
+    baseUrl?: string;
+    /** Milliseconds per attempt. Default 30000. */
+    timeout?: number;
+    /** Retries after the first attempt. Default 2. `0` disables retries. */
+    maxRetries?: number;
+    /** Custom `fetch`. Default `globalThis.fetch`. */
+    fetch?: Fetch;
+}
+/** Client for the Webhook Admin API (`/v1`). */
+declare class WebhookAdmin {
+    readonly messages: Messages;
+    readonly consumers: Consumers;
+    readonly endpoints: Endpoints;
+    readonly deliveries: Deliveries;
+    readonly portal: Portal;
+    readonly baseUrl: string;
+    /**
+     * @param apiKey `sk_live_…` or `sk_test_…`. Defaults to the `WEBHOOK_ADMIN_API_KEY` environment variable.
+     */
+    constructor(apiKey?: string, options?: ClientOptions);
+}
+
+type ErrorOptions = {
+    status?: number;
+    code?: string;
+    fields?: Record<string, string>;
+    requestId?: string;
+    cause?: unknown;
+};
+/** Base class for every error thrown by the SDK. */
+declare class WebhookAdminError extends Error {
+    name: string;
+    /** HTTP status. Undefined when no response was received. */
+    readonly status: number | undefined;
+    /** API error code, such as `invalid` or `not_found`. */
+    readonly code: string | undefined;
+    /** Per-field messages for validation errors. */
+    readonly fields: Record<string, string> | undefined;
+    /** Request ID (`x-request-id`, or Cloudflare's `cf-ray`) to quote when contacting support. */
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** 401: the API key is missing, wrong, revoked or expired. */
+declare class AuthenticationError extends WebhookAdminError {
+    name: string;
+}
+/** 403: the API key does not have the scope for this operation. */
+declare class PermissionError extends WebhookAdminError {
+    name: string;
+}
+/** 404: the resource does not exist in the key's environment. */
+declare class NotFoundError extends WebhookAdminError {
+    name: string;
+}
+/** 400, 413 or 422: the request body or parameters are invalid. See `fields`. */
+declare class ValidationError extends WebhookAdminError {
+    name: string;
+}
+/** 402: the plan's limit was reached (monthly messages, or a feature not in the plan). */
+declare class PlanLimitError extends WebhookAdminError {
+    name: string;
+}
+/** 409: conflicts with the current state (duplicate external_id, delivery still in progress). */
+declare class ConflictError extends WebhookAdminError {
+    name: string;
+}
+/** 429: too many requests. Thrown after retries are used up. */
+declare class RateLimitError extends WebhookAdminError {
+    name: string;
+    /** Seconds to wait before retrying, from `retry-after`. */
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: ErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** Any other error response, including 5xx. */
+declare class ApiError extends WebhookAdminError {
+    name: string;
+}
+/** The request could not reach the API (DNS, TCP, TLS) or was aborted. */
+declare class ConnectionError extends WebhookAdminError {
+    name: string;
+}
+/** The request did not complete within `timeout`. */
+declare class TimeoutError extends ConnectionError {
+    name: string;
+}
+/** Signature verification of an incoming webhook failed. */
+declare class WebhookVerificationError extends WebhookAdminError {
+    name: string;
+}
+
+/** SDK version. Kept equal to package.json by a test. */
+declare const VERSION = "0.1.0";
+
+/** Headers as a `Headers` object or a plain object (Node's `req.headers`). Names are case-insensitive. */
+type WebhookHeaders = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+/** Raw request body. `Buffer` is a `Uint8Array`. */
+type WebhookPayload = string | Uint8Array | ArrayBuffer;
+/** Body of a webhook sent by Webhook Admin. */
+interface WebhookEvent<T = unknown> {
+    type: string;
+    /** ISO 8601. */
+    timestamp: string;
+    data: T;
+}
+interface WebhookOptions {
+    /** Allowed clock difference in seconds, both ways. Default 300. */
+    tolerance?: number;
+}
+/** Verifies webhooks sent by Webhook Admin (Standard Webhooks). */
+declare class Webhook {
+    private readonly key;
+    private readonly tolerance;
+    private cryptoKey;
+    /** @param secret The endpoint's signing secret (`whsec_…`). */
+    constructor(secret: string, options?: WebhookOptions);
+    private importKey;
+    /**
+     * Verifies the signature and timestamp, then returns the parsed body.
+     * Throws `WebhookVerificationError` when verification fails.
+     * @param payload The raw request body, exactly as received.
+     */
+    verify<T = WebhookEvent>(payload: WebhookPayload, headers: WebhookHeaders): Promise<T>;
+    /**
+     * Computes the `webhook-signature` value (`v1,<base64>`). Useful for tests.
+     * @param timestamp A `Date` or Unix seconds.
+     */
+    sign(msgId: string, timestamp: Date | number, payload: WebhookPayload): Promise<string>;
+}
+
+export { ApiError, type Attempt, AuthenticationError, type ClientOptions, ConflictError, ConnectionError, type Consumer, type ConsumerCreateParams, type ConsumerListParams, type ConsumerRef, Consumers, Deliveries, type Delivery, type DeliveryStatus, type Endpoint, type EndpointCreateParams, type EndpointDetail, type EndpointListParams, type EndpointSendTestParams, type EndpointStatus, type EndpointUpdateParams, type EndpointWithSecret, Endpoints, type Fetch, type Message, type MessageListParams, type MessageStatus, type MessageSummary, Messages, NotFoundError, type Page, PagePromise, PermissionError, PlanLimitError, Portal, type PortalLink, type PortalLinkParams, RateLimitError, type RequestOptions, type RotateSecretResponse, type SendMessageOptions, type SendMessageParams, type SendMessageResponse, type SendTestResponse, TimeoutError, VERSION, ValidationError, Webhook, WebhookAdmin, WebhookAdminError, type WebhookEvent, type WebhookHeaders, type WebhookOptions, type WebhookPayload, WebhookVerificationError };