@orthacms/webhooks-server 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/webhooks-server
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/webhooks-server
+```

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@orthacms/webhooks-server` — outgoing webhooks on content changes.
+ *
+ * Subscribes to the transactional outbox, queues one delivery row per
+ * subscribed endpoint, and sends them from a worker that holds no transaction
+ * while it waits on someone else's server. Owns three tables and ships their
+ * migrations; the rules about what a delivery *means* live in
+ * `@orthacms/webhooks-domain`.
+ */
+export { WebhooksPlugin, type WebhooksServerPluginType } from './lib/utils/webhooks-plugin';
+export { WebhooksModule } from './lib/webhooks.module';
+export { WEBHOOKS_DEFAULTS, resolveWebhooksConfig, type ResolvedWebhooksConfig, type WebhooksPluginConfig } from './lib/types/webhooks-config';
+export { InjectWebhooksConfig, WEBHOOKS_CONFIG } from './lib/webhooks.tokens';
+export { WebhookEndpointsService, type WebhookEndpointWithSecret } from './lib/application/webhook-endpoints.service';
+export { WebhookDeliveryWorker } from './lib/infrastructure/webhook-delivery.worker';
+export { WebhookDeliveryNotFoundError, WebhookEndpointNotFoundError } from './lib/domain/errors';
+export type { WebhookDeliveryDetailView, WebhookDeliveryPage, WebhookDeliveryView, WebhookEndpointView, WebhookLastDeliveryView, WebhookTestResult } from './lib/domain/webhook-views';
+export { webhookDeliveries, webhookEndpointWorkspaces, webhookEndpoints } from './lib/infrastructure/schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACH,cAAc,EACd,KAAK,wBAAwB,EAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EACH,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC5B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EACH,uBAAuB,EACvB,KAAK,yBAAyB,EACjC,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AAErF,OAAO,EACH,4BAA4B,EAC5B,4BAA4B,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACR,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACH,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,EACnB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * `@orthacms/webhooks-server` — outgoing webhooks on content changes.
+ *
+ * Subscribes to the transactional outbox, queues one delivery row per
+ * subscribed endpoint, and sends them from a worker that holds no transaction
+ * while it waits on someone else's server. Owns three tables and ships their
+ * migrations; the rules about what a delivery *means* live in
+ * `@orthacms/webhooks-domain`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhookEndpoints = exports.webhookEndpointWorkspaces = exports.webhookDeliveries = exports.WebhookEndpointNotFoundError = exports.WebhookDeliveryNotFoundError = exports.WebhookDeliveryWorker = exports.WebhookEndpointsService = exports.WEBHOOKS_CONFIG = exports.InjectWebhooksConfig = exports.resolveWebhooksConfig = exports.WEBHOOKS_DEFAULTS = exports.WebhooksModule = exports.WebhooksPlugin = void 0;
+var webhooks_plugin_1 = require("./lib/utils/webhooks-plugin");
+Object.defineProperty(exports, "WebhooksPlugin", { enumerable: true, get: function () { return webhooks_plugin_1.WebhooksPlugin; } });
+var webhooks_module_1 = require("./lib/webhooks.module");
+Object.defineProperty(exports, "WebhooksModule", { enumerable: true, get: function () { return webhooks_module_1.WebhooksModule; } });
+var webhooks_config_1 = require("./lib/types/webhooks-config");
+Object.defineProperty(exports, "WEBHOOKS_DEFAULTS", { enumerable: true, get: function () { return webhooks_config_1.WEBHOOKS_DEFAULTS; } });
+Object.defineProperty(exports, "resolveWebhooksConfig", { enumerable: true, get: function () { return webhooks_config_1.resolveWebhooksConfig; } });
+var webhooks_tokens_1 = require("./lib/webhooks.tokens");
+Object.defineProperty(exports, "InjectWebhooksConfig", { enumerable: true, get: function () { return webhooks_tokens_1.InjectWebhooksConfig; } });
+Object.defineProperty(exports, "WEBHOOKS_CONFIG", { enumerable: true, get: function () { return webhooks_tokens_1.WEBHOOKS_CONFIG; } });
+var webhook_endpoints_service_1 = require("./lib/application/webhook-endpoints.service");
+Object.defineProperty(exports, "WebhookEndpointsService", { enumerable: true, get: function () { return webhook_endpoints_service_1.WebhookEndpointsService; } });
+var webhook_delivery_worker_1 = require("./lib/infrastructure/webhook-delivery.worker");
+Object.defineProperty(exports, "WebhookDeliveryWorker", { enumerable: true, get: function () { return webhook_delivery_worker_1.WebhookDeliveryWorker; } });
+var errors_1 = require("./lib/domain/errors");
+Object.defineProperty(exports, "WebhookDeliveryNotFoundError", { enumerable: true, get: function () { return errors_1.WebhookDeliveryNotFoundError; } });
+Object.defineProperty(exports, "WebhookEndpointNotFoundError", { enumerable: true, get: function () { return errors_1.WebhookEndpointNotFoundError; } });
+var schema_1 = require("./lib/infrastructure/schema");
+Object.defineProperty(exports, "webhookDeliveries", { enumerable: true, get: function () { return schema_1.webhookDeliveries; } });
+Object.defineProperty(exports, "webhookEndpointWorkspaces", { enumerable: true, get: function () { return schema_1.webhookEndpointWorkspaces; } });
+Object.defineProperty(exports, "webhookEndpoints", { enumerable: true, get: function () { return schema_1.webhookEndpoints; } });

package/dist/lib/application/dto/list-deliveries-query.dto.d.ts

@@ -0,0 +1,8 @@
+/** Filters and paging for `GET /api/webhooks/:id/deliveries`. */
+export declare class ListDeliveriesQueryDto {
+    status?: string;
+    eventKind?: string;
+    page?: number;
+    pageSize?: number;
+}
+//# sourceMappingURL=list-deliveries-query.dto.d.ts.map

package/dist/lib/application/dto/list-deliveries-query.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-deliveries-query.dto.d.ts","sourceRoot":"","sources":["../../../../src/lib/application/dto/list-deliveries-query.dto.ts"],"names":[],"mappings":"AAWA,iEAAiE;AACjE,qBAAa,sBAAsB;IAO/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,SAAS,CAAC,EAAE,MAAM,CAAC;IAYnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAcd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/lib/application/dto/list-deliveries-query.dto.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListDeliveriesQueryDto = void 0;
+const tslib_1 = require("tslib");
+const swagger_1 = require("@nestjs/swagger");
+const webhooks_domain_1 = require("@orthacms/webhooks-domain");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/** The largest page the delivery log will return. */
+const MAX_PAGE_SIZE = 100;
+/** Filters and paging for `GET /api/webhooks/:id/deliveries`. */
+class ListDeliveriesQueryDto {
+    status;
+    eventKind;
+    page;
+    pageSize;
+}
+exports.ListDeliveriesQueryDto = ListDeliveriesQueryDto;
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Only deliveries in this state.',
+        enum: webhooks_domain_1.DELIVERY_STATUSES
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(webhooks_domain_1.DELIVERY_STATUSES),
+    tslib_1.__metadata("design:type", String)
+], ListDeliveriesQueryDto.prototype, "status", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Only deliveries of this event kind.',
+        enum: webhooks_domain_1.WEBHOOK_EVENT_KINDS
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(webhooks_domain_1.WEBHOOK_EVENT_KINDS),
+    tslib_1.__metadata("design:type", String)
+], ListDeliveriesQueryDto.prototype, "eventKind", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: '1-based page number.',
+        type: 'integer',
+        minimum: 1,
+        default: 1
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    tslib_1.__metadata("design:type", Number)
+], ListDeliveriesQueryDto.prototype, "page", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Rows per page.',
+        type: 'integer',
+        minimum: 1,
+        maximum: MAX_PAGE_SIZE,
+        default: 25
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MAX_PAGE_SIZE),
+    tslib_1.__metadata("design:type", Number)
+], ListDeliveriesQueryDto.prototype, "pageSize", void 0);

package/dist/lib/application/dto/save-webhook-endpoint.dto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The body of a create or update.
+ *
+ * The three filter arrays are **optional, and an omitted or empty one means
+ * "everything"** — including things that do not exist yet. That is the whole
+ * subscription model, and it is why the shape is three plain lists rather than
+ * an expression.
+ *
+ * The URL is only shape-checked here (`@IsString`); whether it is *reachable*
+ * under this deployment's policy is decided in the service, which owns the
+ * policy and can say why in a message worth showing.
+ */
+export declare class SaveWebhookEndpointDto {
+    name: string;
+    url: string;
+    enabled?: boolean;
+    eventKinds?: string[];
+    contentTypes?: string[];
+    allWorkspaces?: boolean;
+    workspaceIds?: string[];
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=save-webhook-endpoint.dto.d.ts.map

package/dist/lib/application/dto/save-webhook-endpoint.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-webhook-endpoint.dto.d.ts","sourceRoot":"","sources":["../../../../src/lib/application/dto/save-webhook-endpoint.dto.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAsB;IAS/B,IAAI,EAAG,MAAM,CAAC;IAWd,GAAG,EAAG,MAAM,CAAC;IAQb,OAAO,CAAC,EAAE,OAAO,CAAC;IAelB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAatB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IASxB,aAAa,CAAC,EAAE,OAAO,CAAC;IAaxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAWxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC"}

package/dist/lib/application/dto/save-webhook-endpoint.dto.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SaveWebhookEndpointDto = void 0;
+const tslib_1 = require("tslib");
+const swagger_1 = require("@nestjs/swagger");
+const webhooks_domain_1 = require("@orthacms/webhooks-domain");
+const class_validator_1 = require("class-validator");
+/** Bounds on the free-text fields, restated in the OpenAPI schema below. */
+const NAME_MAX = 120;
+const URL_MAX = 2_048;
+const LIST_MAX = 200;
+/**
+ * The body of a create or update.
+ *
+ * The three filter arrays are **optional, and an omitted or empty one means
+ * "everything"** — including things that do not exist yet. That is the whole
+ * subscription model, and it is why the shape is three plain lists rather than
+ * an expression.
+ *
+ * The URL is only shape-checked here (`@IsString`); whether it is *reachable*
+ * under this deployment's policy is decided in the service, which owns the
+ * policy and can say why in a message worth showing.
+ */
+class SaveWebhookEndpointDto {
+    name;
+    url;
+    enabled;
+    eventKinds;
+    contentTypes;
+    allWorkspaces;
+    workspaceIds;
+    headers;
+}
+exports.SaveWebhookEndpointDto = SaveWebhookEndpointDto;
+tslib_1.__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Human-readable name shown in the webhooks list.',
+        maxLength: NAME_MAX,
+        example: 'Rebuild the storefront'
+    }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MinLength)(1),
+    (0, class_validator_1.MaxLength)(NAME_MAX),
+    tslib_1.__metadata("design:type", String)
+], SaveWebhookEndpointDto.prototype, "name", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Where deliveries are POSTed. Must be https:// and resolve to a public address unless the deployment allows otherwise.',
+        maxLength: URL_MAX,
+        example: 'https://example.com/hooks/ortha'
+    }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MinLength)(1),
+    (0, class_validator_1.MaxLength)(URL_MAX),
+    tslib_1.__metadata("design:type", String)
+], SaveWebhookEndpointDto.prototype, "url", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Whether the endpoint receives deliveries.',
+        default: true
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    tslib_1.__metadata("design:type", Boolean)
+], SaveWebhookEndpointDto.prototype, "enabled", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Event kinds to subscribe to. Omit or leave empty to receive every kind, including ones added later.',
+        type: [String],
+        enum: webhooks_domain_1.WEBHOOK_EVENT_KINDS,
+        maxItems: LIST_MAX
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(LIST_MAX)
+    // Derived from the catalogue, so a new kind is subscribable the moment it
+    // is added there and a removed one stops validating.
+    ,
+    (0, class_validator_1.IsIn)(webhooks_domain_1.WEBHOOK_EVENT_KINDS, { each: true }),
+    tslib_1.__metadata("design:type", Array)
+], SaveWebhookEndpointDto.prototype, "eventKinds", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Content types to subscribe to. Omit or leave empty to receive every type.',
+        type: [String],
+        maxItems: LIST_MAX
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(LIST_MAX),
+    (0, class_validator_1.IsString)({ each: true }),
+    (0, class_validator_1.MaxLength)(200, { each: true }),
+    tslib_1.__metadata("design:type", Array)
+], SaveWebhookEndpointDto.prototype, "contentTypes", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Receive events from every workspace, including workspaces created later. When true, workspaceIds is ignored.',
+        default: false
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    tslib_1.__metadata("design:type", Boolean)
+], SaveWebhookEndpointDto.prototype, "allWorkspaces", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Workspaces to receive events from. Ignored when allWorkspaces is true; an empty list with allWorkspaces false receives nothing.',
+        type: [String],
+        format: 'uuid',
+        maxItems: LIST_MAX
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(LIST_MAX),
+    (0, class_validator_1.IsUUID)('4', { each: true }),
+    tslib_1.__metadata("design:type", Array)
+], SaveWebhookEndpointDto.prototype, "workspaceIds", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Extra static headers sent with every delivery. Delivery metadata headers (X-Ortha-*) and transport headers cannot be set.',
+        type: 'object',
+        additionalProperties: { type: 'string' },
+        example: { Authorization: 'Bearer …' }
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsObject)(),
+    tslib_1.__metadata("design:type", Object)
+], SaveWebhookEndpointDto.prototype, "headers", void 0);

package/dist/lib/application/webhook-endpoints.service.d.ts

@@ -0,0 +1,82 @@
+import type { WebhookDeliveryDetailView, WebhookDeliveryPage, WebhookDeliveryView, WebhookEndpointView, WebhookTestResult } from '../domain/webhook-views';
+import { WebhookDeliveryRepository, type DeliveryListQuery } from '../infrastructure/webhook-delivery.repository';
+import { WebhookEndpointRepository, type EndpointWriteModel } from '../infrastructure/webhook-endpoint.repository';
+import { WebhookHttpClient } from '../infrastructure/webhook-http.client';
+import type { ResolvedWebhooksConfig } from '../types/webhooks-config';
+/** An endpoint plus the secret, returned only from create and rotate. */
+export interface WebhookEndpointWithSecret {
+    endpoint: WebhookEndpointView;
+    /** The plaintext signing secret. This is the only time it is ever returned. */
+    secret: string;
+}
+/** Orchestration over the two repositories. */
+export declare class WebhookEndpointsService {
+    private readonly endpoints;
+    private readonly deliveries;
+    private readonly http;
+    private readonly config;
+    constructor(endpoints: WebhookEndpointRepository, deliveries: WebhookDeliveryRepository, http: WebhookHttpClient, config: ResolvedWebhooksConfig);
+    /** Every endpoint, newest first. */
+    list(): Promise<WebhookEndpointView[]>;
+    /** One endpoint. Throws {@link WebhookEndpointNotFoundError} when absent. */
+    get(id: string): Promise<WebhookEndpointView>;
+    /**
+     * Creates an endpoint and mints its secret.
+     *
+     * The URL is checked here as well as in the worker so a typo is refused in
+     * the dialog rather than discovered in the delivery log an hour later.
+     */
+    create(model: EndpointWriteModel, createdBy: string | null): Promise<WebhookEndpointWithSecret>;
+    /** Applies a full write model to an existing endpoint. */
+    update(id: string, model: EndpointWriteModel): Promise<WebhookEndpointView>;
+    /** Deletes the endpoint and, by cascade, its delivery log. */
+    delete(id: string): Promise<void>;
+    /**
+     * Rotates the signing secret.
+     *
+     * The new secret takes effect immediately, including for deliveries already
+     * queued — they are signed when they are sent, not when they were queued.
+     * A receiver therefore needs the new secret in place before rotating, which
+     * is what the dialog says.
+     */
+    rotateSecret(id: string): Promise<WebhookEndpointWithSecret>;
+    /**
+     * Sends a synthetic `ping` and reports the result **synchronously**.
+     *
+     * Deliberately not queued: the person pressing "Send test" is waiting for
+     * an answer, and a row in the log they would have to go and find is not
+     * one. It is also why a test never counts against the endpoint's
+     * consecutive-failure budget — it is a probe, not traffic.
+     */
+    sendTest(id: string): Promise<WebhookTestResult>;
+    /** One page of an endpoint's delivery log. */
+    listDeliveries(endpointId: string, query: DeliveryListQuery): Promise<WebhookDeliveryPage>;
+    /** One delivery with its bodies. */
+    getDelivery(endpointId: string, deliveryId: string): Promise<WebhookDeliveryDetailView>;
+    /**
+     * Queues the same event again as a fresh delivery.
+     *
+     * The body is copied rather than rebuilt, so the receiver gets exactly what
+     * it was sent before — with one substitution: `id` becomes the new delivery
+     * id, because that is also what the `X-Ortha-Delivery` header will say, and
+     * a body naming a different delivery than its own header is a bug waiting
+     * to be found by whoever writes the receiver.
+     *
+     * `eventId` is kept, so a receiver that deduplicates on it correctly
+     * ignores the repeat — which is exactly what a redelivery is *for* when the
+     * receiver, not the event, was the thing that was broken. Keeping it is
+     * only possible because `redeliveryOf` exempts the row from the partial
+     * unique index that makes fan-out idempotent.
+     */
+    redeliver(endpointId: string, deliveryId: string): Promise<WebhookDeliveryView>;
+    /**
+     * Refuses a write that the delivery path would only reject later.
+     *
+     * Both checks are also enforced downstream — the URL on every send, the
+     * headers when the request is built — because a row can predate a policy
+     * change. Doing them here is what turns a silent failure in the log into a
+     * message in the form.
+     */
+    private assertWritable;
+}
+//# sourceMappingURL=webhook-endpoints.service.d.ts.map

package/dist/lib/application/webhook-endpoints.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-endpoints.service.d.ts","sourceRoot":"","sources":["../../../src/lib/application/webhook-endpoints.service.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACR,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,yBAAyB,EACzB,KAAK,iBAAiB,EACzB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACH,yBAAyB,EACzB,KAAK,kBAAkB,EAC1B,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,yEAAyE;AACzE,MAAM,WAAW,yBAAyB;IACtC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,+CAA+C;AAC/C,qBACa,uBAAuB;IAE5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAJN,SAAS,EAAE,yBAAyB,EACpC,UAAU,EAAE,yBAAyB,EACrC,IAAI,EAAE,iBAAiB,EAEvB,MAAM,EAAE,sBAAsB;IAGnD,oCAAoC;IACpC,IAAI,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAItC,6EAA6E;IACvE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAMnD;;;;;OAKG;IACG,MAAM,CACR,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,yBAAyB,CAAC;IAQrC,0DAA0D;IACpD,MAAM,CACR,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,kBAAkB,GAC1B,OAAO,CAAC,mBAAmB,CAAC;IAU/B,8DAA8D;IACxD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC;;;;;;;OAOG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAUlE;;;;;;;OAOG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyCtD,8CAA8C;IACxC,cAAc,CAChB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,iBAAiB,GACzB,OAAO,CAAC,mBAAmB,CAAC;IAO/B,oCAAoC;IAC9B,WAAW,CACb,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,yBAAyB,CAAC;IASrC;;;;;;;;;;;;;;OAcG;IACG,SAAS,CACX,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,mBAAmB,CAAC;IAwB/B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CAczB"}

package/dist/lib/application/webhook-endpoints.service.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEndpointsService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const webhooks_domain_1 = require("@orthacms/webhooks-domain");
+const errors_1 = require("../domain/errors");
+const webhook_secret_1 = require("../domain/webhook-secret");
+const webhook_delivery_repository_1 = require("../infrastructure/webhook-delivery.repository");
+const webhook_endpoint_repository_1 = require("../infrastructure/webhook-endpoint.repository");
+const webhook_http_client_1 = require("../infrastructure/webhook-http.client");
+const webhooks_tokens_1 = require("../webhooks.tokens");
+/** Orchestration over the two repositories. */
+let WebhookEndpointsService = class WebhookEndpointsService {
+    endpoints;
+    deliveries;
+    http;
+    config;
+    constructor(endpoints, deliveries, http, config) {
+        this.endpoints = endpoints;
+        this.deliveries = deliveries;
+        this.http = http;
+        this.config = config;
+    }
+    /** Every endpoint, newest first. */
+    list() {
+        return this.endpoints.list();
+    }
+    /** One endpoint. Throws {@link WebhookEndpointNotFoundError} when absent. */
+    async get(id) {
+        const endpoint = await this.endpoints.findById(id);
+        if (!endpoint)
+            throw new errors_1.WebhookEndpointNotFoundError(id);
+        return endpoint;
+    }
+    /**
+     * Creates an endpoint and mints its secret.
+     *
+     * The URL is checked here as well as in the worker so a typo is refused in
+     * the dialog rather than discovered in the delivery log an hour later.
+     */
+    async create(model, createdBy) {
+        this.assertWritable(model);
+        const { secret } = (0, webhook_secret_1.generateSecret)();
+        const id = await this.endpoints.create(model, secret, createdBy);
+        return { endpoint: await this.get(id), secret };
+    }
+    /** Applies a full write model to an existing endpoint. */
+    async update(id, model) {
+        if (!(await this.endpoints.exists(id))) {
+            throw new errors_1.WebhookEndpointNotFoundError(id);
+        }
+        this.assertWritable(model);
+        await this.endpoints.update(id, model);
+        return this.get(id);
+    }
+    /** Deletes the endpoint and, by cascade, its delivery log. */
+    async delete(id) {
+        if (!(await this.endpoints.exists(id))) {
+            throw new errors_1.WebhookEndpointNotFoundError(id);
+        }
+        await this.endpoints.delete(id);
+    }
+    /**
+     * Rotates the signing secret.
+     *
+     * The new secret takes effect immediately, including for deliveries already
+     * queued — they are signed when they are sent, not when they were queued.
+     * A receiver therefore needs the new secret in place before rotating, which
+     * is what the dialog says.
+     */
+    async rotateSecret(id) {
+        if (!(await this.endpoints.exists(id))) {
+            throw new errors_1.WebhookEndpointNotFoundError(id);
+        }
+        const { secret } = (0, webhook_secret_1.generateSecret)();
+        await this.endpoints.replaceSecret(id, secret);
+        return { endpoint: await this.get(id), secret };
+    }
+    /**
+     * Sends a synthetic `ping` and reports the result **synchronously**.
+     *
+     * Deliberately not queued: the person pressing "Send test" is waiting for
+     * an answer, and a row in the log they would have to go and find is not
+     * one. It is also why a test never counts against the endpoint's
+     * consecutive-failure budget — it is a probe, not traffic.
+     */
+    async sendTest(id) {
+        const endpoint = await this.endpoints.findForDelivery(id);
+        if (!endpoint)
+            throw new errors_1.WebhookEndpointNotFoundError(id);
+        const deliveryId = (0, node_crypto_1.randomUUID)();
+        const eventId = (0, node_crypto_1.randomUUID)();
+        const envelope = (0, webhooks_domain_1.buildEnvelope)(deliveryId, {
+            eventId,
+            kind: 'ping',
+            occurredAt: new Date(),
+            workspaceId: null,
+            aggregateType: 'webhook_endpoint',
+            aggregateId: id,
+            data: { endpointName: endpoint.name },
+            actor: null
+        });
+        const response = await this.http.send({
+            url: endpoint.url,
+            secret: endpoint.secret,
+            headers: endpoint.headers,
+            body: envelope,
+            eventKind: 'ping',
+            deliveryId,
+            eventId,
+            workspaceId: null,
+            attempt: 1
+        });
+        return {
+            ok: response.statusCode !== null &&
+                response.statusCode >= 200 &&
+                response.statusCode < 300,
+            statusCode: response.statusCode,
+            error: response.error,
+            durationMs: response.durationMs,
+            responseSnippet: response.responseSnippet
+        };
+    }
+    /** One page of an endpoint's delivery log. */
+    async listDeliveries(endpointId, query) {
+        if (!(await this.endpoints.exists(endpointId))) {
+            throw new errors_1.WebhookEndpointNotFoundError(endpointId);
+        }
+        return this.deliveries.list(endpointId, query);
+    }
+    /** One delivery with its bodies. */
+    async getDelivery(endpointId, deliveryId) {
+        const delivery = await this.deliveries.findDetail(endpointId, deliveryId);
+        if (!delivery)
+            throw new errors_1.WebhookDeliveryNotFoundError(deliveryId);
+        return delivery;
+    }
+    /**
+     * Queues the same event again as a fresh delivery.
+     *
+     * The body is copied rather than rebuilt, so the receiver gets exactly what
+     * it was sent before — with one substitution: `id` becomes the new delivery
+     * id, because that is also what the `X-Ortha-Delivery` header will say, and
+     * a body naming a different delivery than its own header is a bug waiting
+     * to be found by whoever writes the receiver.
+     *
+     * `eventId` is kept, so a receiver that deduplicates on it correctly
+     * ignores the repeat — which is exactly what a redelivery is *for* when the
+     * receiver, not the event, was the thing that was broken. Keeping it is
+     * only possible because `redeliveryOf` exempts the row from the partial
+     * unique index that makes fan-out idempotent.
+     */
+    async redeliver(endpointId, deliveryId) {
+        const original = await this.getDelivery(endpointId, deliveryId);
+        const id = (0, node_crypto_1.randomUUID)();
+        await this.deliveries.enqueueOne({
+            id,
+            endpointId,
+            eventId: original.eventId,
+            eventKind: original.eventKind,
+            workspaceId: original.workspaceId,
+            contentType: original.contentType,
+            payload: withDeliveryId(original.payload, id),
+            // Points at the delivery this repeats — both as provenance in the
+            // log and as the exemption from the fan-out unique index.
+            redeliveryOf: original.id
+        });
+        const queued = await this.deliveries.findDetail(endpointId, id);
+        // The row was just written in the same request; its absence would mean
+        // the endpoint was deleted underneath us.
+        if (!queued)
+            throw new errors_1.WebhookEndpointNotFoundError(endpointId);
+        return queued;
+    }
+    /**
+     * Refuses a write that the delivery path would only reject later.
+     *
+     * Both checks are also enforced downstream — the URL on every send, the
+     * headers when the request is built — because a row can predate a policy
+     * change. Doing them here is what turns a silent failure in the log into a
+     * message in the form.
+     */
+    assertWritable(model) {
+        (0, webhooks_domain_1.assertUrlShape)(model.url, {
+            allowInsecureUrls: this.config.allowInsecureUrls,
+            allowPrivateNetworks: this.config.allowPrivateNetworks
+        });
+        for (const name of Object.keys(model.headers)) {
+            if (!(0, webhooks_domain_1.isAllowedCustomHeader)(name)) {
+                throw new webhooks_domain_1.WebhookUrlRejectedError(`The header "${name}" cannot be set on a webhook — it is reserved for the delivery's own metadata.`);
+            }
+        }
+    }
+};
+exports.WebhookEndpointsService = WebhookEndpointsService;
+exports.WebhookEndpointsService = WebhookEndpointsService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(3, (0, webhooks_tokens_1.InjectWebhooksConfig)()),
+    tslib_1.__metadata("design:paramtypes", [webhook_endpoint_repository_1.WebhookEndpointRepository,
+        webhook_delivery_repository_1.WebhookDeliveryRepository,
+        webhook_http_client_1.WebhookHttpClient, Object])
+], WebhookEndpointsService);
+/**
+ * The stored envelope with its `id` swapped for this delivery's, leaving
+ * everything else — `eventId` above all — exactly as it was sent.
+ */
+function withDeliveryId(payload, deliveryId) {
+    if (typeof payload !== 'object' || payload === null)
+        return payload;
+    return { ...payload, id: deliveryId };
+}

package/dist/lib/docs/describe-webhooks-api.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The webhooks plugin's pass over the host's OpenAPI document.
+ *
+ * The routes here are ordinary decorated controllers, so `@nestjs/swagger`
+ * already knows their paths, parameters and request bodies. What it cannot
+ * know is what comes **back**: every response view is a TypeScript
+ * `interface`, erased before the scanner runs, which is why each operation
+ * arrives carrying a bare `200`/`201` with no content. This pass writes the
+ * response schemas onto the operations the plugin owns and nothing else.
+ *
+ * Pure: it takes the document and mutates only its own paths.
+ */
+import type { OpenApiDocument } from '@orthacms/bootstrap-server';
+/** Adds this plugin's schemas and describes its own operations' responses. */
+export declare function describeWebhooksApi(document: OpenApiDocument): void;
+//# sourceMappingURL=describe-webhooks-api.d.ts.map

package/dist/lib/docs/describe-webhooks-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-webhooks-api.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/describe-webhooks-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA4JlE,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CA4DnE"}