@marinoscar/platform-api 0.1.0-next.18 → 0.1.0-next.20

package/dist/webhooks/webhook-endpoints.service.d.ts

@@ -0,0 +1,142 @@
+import { type CreateWebhookEndpoint, type RotateWebhookSecretResponse, type UpdateWebhookEndpoint, type WebhookDeliveryDetail, type WebhookDeliveryList, type WebhookDeliveryListQuery, type WebhookEndpoint, type WebhookEndpointCreated, type WebhookEventCatalogEntry, type WebhookScope, type WebhookTestResponse } from '@marinoscar/platform-contract/webhooks';
+import { type AuditSink } from '../core/index';
+import { type HostResolver } from './egress/egress-guard';
+import { WebhookSecrets } from './webhook-secrets.service';
+import { type ResolvedWebhooksModuleOptions } from './webhooks.options';
+import { WebhooksRepository } from './webhooks.repository';
+/**
+ * Who is acting, in which scope.
+ *
+ * @stability experimental
+ */
+export interface WebhookScopeContext {
+    /** `user` (own endpoints), `org` (the organization's) or `system` (the deployment's). */
+    readonly scope: WebhookScope;
+    /** The acting user. */
+    readonly userId: string;
+    /** The active organization; `null` only for system scope. */
+    readonly orgId: string | null;
+    /** The caller's effective permissions, for the per-event permission gate. */
+    readonly permissions: readonly string[];
+}
+/**
+ * See the file header.
+ *
+ * @stability experimental
+ */
+export declare class WebhookEndpointsService {
+    private readonly repository;
+    private readonly secrets;
+    private readonly options;
+    private readonly resolver;
+    private readonly audit;
+    private readonly logger;
+    /** Overridable clock, for tests. */
+    now: () => Date;
+    constructor(repository: WebhooksRepository, secrets: WebhookSecrets, options: ResolvedWebhooksModuleOptions, resolver: HostResolver, audit: AuditSink);
+    /**
+     * The endpoints in the caller's scope, newest first.
+     *
+     * @param ctx - who is acting.
+     * @returns the endpoints (no secret).
+     */
+    list(ctx: WebhookScopeContext): Promise<WebhookEndpoint[]>;
+    /**
+     * One endpoint.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the endpoint.
+     * @throws WebhookNotFoundError when it does not exist or is not in the caller's scope.
+     */
+    get(ctx: WebhookScopeContext, id: string): Promise<WebhookEndpoint>;
+    /**
+     * Creates an endpoint and returns its signing secret, once.
+     *
+     * @param ctx - who is acting.
+     * @param input - the validated body.
+     * @returns the endpoint and the secret.
+     * @throws WebhookRequestError for a forbidden URL, an unknown or not-permitted event, or the endpoint limit.
+     */
+    create(ctx: WebhookScopeContext, input: CreateWebhookEndpoint): Promise<WebhookEndpointCreated>;
+    /**
+     * Changes an endpoint. Enabling a disabled endpoint clears its failure count
+     * and its disabled reason.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @param input - the validated patch.
+     * @returns the endpoint.
+     */
+    update(ctx: WebhookScopeContext, id: string, input: UpdateWebhookEndpoint): Promise<WebhookEndpoint>;
+    /**
+     * Deletes an endpoint, its deliveries and its stored secrets.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     */
+    remove(ctx: WebhookScopeContext, id: string): Promise<void>;
+    /**
+     * Rotates the signing secret. The previous secret keeps signing for the
+     * overlap window (two signatures per delivery), so the receiver can switch
+     * without dropping an event.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the new secret, once.
+     */
+    rotateSecret(ctx: WebhookScopeContext, id: string): Promise<RotateWebhookSecretResponse>;
+    /**
+     * Queues a `webhooks.ping` delivery to the endpoint.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the delivery id.
+     */
+    test(ctx: WebhookScopeContext, id: string): Promise<WebhookTestResponse>;
+    /**
+     * A page of an endpoint's deliveries.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @param query - page, size and filters.
+     * @returns the page.
+     */
+    listDeliveries(ctx: WebhookScopeContext, id: string, query: WebhookDeliveryListQuery): Promise<WebhookDeliveryList>;
+    /**
+     * One delivery with its payload.
+     *
+     * @param ctx - who is acting.
+     * @param deliveryId - the delivery id.
+     * @returns the detail.
+     */
+    getDelivery(ctx: WebhookScopeContext, deliveryId: string): Promise<WebhookDeliveryDetail>;
+    /**
+     * Sends a delivery again: the same row goes back to `pending` with a fresh
+     * attempt count and a new job. The event id (`webhook-id`) is unchanged, so a
+     * receiver that deduplicates sees the same event.
+     *
+     * @param ctx - who is acting.
+     * @param deliveryId - the delivery id.
+     * @returns the delivery.
+     * @throws WebhookDisabledError when the endpoint is switched off.
+     */
+    redeliver(ctx: WebhookScopeContext, deliveryId: string): Promise<WebhookDeliveryDetail>;
+    /**
+     * The events the caller may subscribe to at this scope.
+     *
+     * @param ctx - who is acting.
+     * @returns the catalog entries the caller's permissions allow.
+     */
+    catalog(ctx: WebhookScopeContext): WebhookEventCatalogEntry[];
+    private orgOf;
+    private filterOf;
+    private require;
+    private policy;
+    /** Syntax and, best effort, DNS: a name that does not resolve yet is accepted (it may be set up later); one that resolves to a private address is not. */
+    private assertUrlAllowed;
+    private holds;
+    private assertEventKeys;
+    private record;
+}
+//# sourceMappingURL=webhook-endpoints.service.d.ts.map

package/dist/webhooks/webhook-endpoints.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-endpoints.service.d.ts","sourceRoot":"","sources":["../../src/webhooks/webhook-endpoints.service.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/webhook-endpoints.service.js

@@ -0,0 +1,366 @@
+"use strict";
+// =============================================================================
+// WebhookEndpointsService: the endpoint and delivery routes' logic
+// (issue #1046)
+// =============================================================================
+//
+// One service behind the three controllers (user, organization, system). A
+// {@link WebhookScopeContext} says which scope the caller is acting in; every
+// query is pinned to it (scope, organization and, for user scope, the owner),
+// so an endpoint or delivery outside it is a 404, never a 403: an id is not an
+// oracle.
+//
+// The signing secret is generated here, stored in the credentials store, and
+// returned exactly twice in an endpoint's life: by `create` and by
+// `rotateSecret`. No other method returns it and none logs it.
+//
+// Nothing here performs outbound HTTP. `test` and `redeliver` queue a
+// `webhooks.deliver` job like every other delivery.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var WebhookEndpointsService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEndpointsService = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const webhooks_1 = require("@marinoscar/platform-contract/webhooks");
+const index_1 = require("../core/index");
+const egress_guard_1 = require("./egress/egress-guard");
+const transport_1 = require("./egress/transport");
+const webhook_envelope_1 = require("./webhook-envelope");
+const webhook_secrets_service_1 = require("./webhook-secrets.service");
+const webhook_views_1 = require("./webhook-views");
+const builtin_events_1 = require("./registry/builtin-events");
+const webhook_catalog_1 = require("./registry/webhook-catalog");
+const webhook_event_registry_1 = require("./registry/webhook-event.registry");
+const signing_1 = require("./signing");
+const webhooks_constants_1 = require("./webhooks.constants");
+const webhooks_errors_1 = require("./webhooks.errors");
+const webhooks_options_1 = require("./webhooks.options");
+const webhooks_repository_1 = require("./webhooks.repository");
+/**
+ * See the file header.
+ *
+ * @stability experimental
+ */
+let WebhookEndpointsService = WebhookEndpointsService_1 = class WebhookEndpointsService {
+    repository;
+    secrets;
+    options;
+    resolver;
+    audit;
+    logger = new common_1.Logger(WebhookEndpointsService_1.name);
+    /** Overridable clock, for tests. */
+    now = () => new Date();
+    constructor(repository, secrets, options, resolver, audit) {
+        this.repository = repository;
+        this.secrets = secrets;
+        this.options = options;
+        this.resolver = resolver;
+        this.audit = audit;
+    }
+    // ---------------------------------------------------------------------------
+    // Endpoints
+    // ---------------------------------------------------------------------------
+    /**
+     * The endpoints in the caller's scope, newest first.
+     *
+     * @param ctx - who is acting.
+     * @returns the endpoints (no secret).
+     */
+    async list(ctx) {
+        const rows = await this.repository.listEndpoints(this.orgOf(ctx), this.filterOf(ctx));
+        return rows.map(webhook_views_1.toEndpointView);
+    }
+    /**
+     * One endpoint.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the endpoint.
+     * @throws WebhookNotFoundError when it does not exist or is not in the caller's scope.
+     */
+    async get(ctx, id) {
+        return (0, webhook_views_1.toEndpointView)(await this.require(ctx, id));
+    }
+    /**
+     * Creates an endpoint and returns its signing secret, once.
+     *
+     * @param ctx - who is acting.
+     * @param input - the validated body.
+     * @returns the endpoint and the secret.
+     * @throws WebhookRequestError for a forbidden URL, an unknown or not-permitted event, or the endpoint limit.
+     */
+    async create(ctx, input) {
+        const orgId = this.orgOf(ctx);
+        const filter = this.filterOf(ctx);
+        const limit = this.options.limits[ctx.scope];
+        if ((await this.repository.countEndpoints(orgId, filter)) >= limit) {
+            throw new webhooks_errors_1.WebhookRequestError(webhooks_1.WEBHOOK_ERROR_CODES.WEBHOOK_LIMIT_REACHED, `You can have at most ${limit} webhook endpoints.`);
+        }
+        await this.assertUrlAllowed(input.url);
+        this.assertEventKeys(ctx, input.eventKeys);
+        const row = await this.repository.createEndpoint(orgId, {
+            scope: ctx.scope,
+            ownerUserId: ctx.scope === 'user' ? ctx.userId : null,
+            createdById: ctx.userId,
+            name: input.name,
+            description: input.description ?? null,
+            url: input.url,
+            eventKeys: [...new Set(input.eventKeys)],
+            enabled: input.enabled,
+        });
+        const secret = (0, signing_1.generateWebhookSecret)();
+        try {
+            await this.secrets.put(row, row.secretVersion, secret);
+        }
+        catch (error) {
+            await this.repository.deleteEndpoint(orgId, row.id).catch(() => undefined);
+            throw error;
+        }
+        await this.record(webhooks_constants_1.WEBHOOK_AUDIT_ACTIONS.CREATE, ctx, row.id);
+        return { endpoint: (0, webhook_views_1.toEndpointView)(row), secret };
+    }
+    /**
+     * Changes an endpoint. Enabling a disabled endpoint clears its failure count
+     * and its disabled reason.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @param input - the validated patch.
+     * @returns the endpoint.
+     */
+    async update(ctx, id, input) {
+        const current = await this.require(ctx, id);
+        if (input.url !== undefined && input.url !== current.url)
+            await this.assertUrlAllowed(input.url);
+        if (input.eventKeys !== undefined)
+            this.assertEventKeys(ctx, input.eventKeys);
+        const patch = {
+            ...(input.name !== undefined ? { name: input.name } : {}),
+            ...(input.description !== undefined ? { description: input.description ?? null } : {}),
+            ...(input.url !== undefined ? { url: input.url } : {}),
+            ...(input.eventKeys !== undefined ? { eventKeys: [...new Set(input.eventKeys)] } : {}),
+        };
+        if (input.enabled !== undefined) {
+            patch.enabled = input.enabled;
+            if (input.enabled && !current.enabled) {
+                patch.consecutiveFailures = 0;
+                patch.disabledReason = null;
+            }
+            if (!input.enabled && current.enabled)
+                patch.disabledReason = null;
+        }
+        const row = await this.repository.updateEndpoint(this.orgOf(ctx), id, patch);
+        await this.record(webhooks_constants_1.WEBHOOK_AUDIT_ACTIONS.UPDATE, ctx, id);
+        return (0, webhook_views_1.toEndpointView)(row);
+    }
+    /**
+     * Deletes an endpoint, its deliveries and its stored secrets.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     */
+    async remove(ctx, id) {
+        const current = await this.require(ctx, id);
+        await this.repository.deleteEndpoint(this.orgOf(ctx), id);
+        try {
+            await this.secrets.removeAll(current, current.secretVersion);
+        }
+        catch (error) {
+            this.logger.warn(`Could not remove the stored secrets of webhook endpoint ${id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await this.record(webhooks_constants_1.WEBHOOK_AUDIT_ACTIONS.DELETE, ctx, id);
+    }
+    /**
+     * Rotates the signing secret. The previous secret keeps signing for the
+     * overlap window (two signatures per delivery), so the receiver can switch
+     * without dropping an event.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the new secret, once.
+     */
+    async rotateSecret(ctx, id) {
+        const current = await this.require(ctx, id);
+        const version = current.secretVersion + 1;
+        const secret = (0, signing_1.generateWebhookSecret)();
+        await this.secrets.put(current, version, secret);
+        const until = new Date(this.now().getTime() + this.options.rotationOverlapHours * 3_600_000);
+        await this.repository.updateEndpoint(this.orgOf(ctx), id, { secretVersion: version, previousSecretUntil: until });
+        // The secret before the one that just became "previous" is no longer needed.
+        if (current.secretVersion > 1)
+            await this.secrets.remove(current, current.secretVersion - 1).catch(() => undefined);
+        await this.record(webhooks_constants_1.WEBHOOK_AUDIT_ACTIONS.ROTATE, ctx, id);
+        return { secret, secretVersion: version, previousSecretValidUntil: until.toISOString() };
+    }
+    /**
+     * Queues a `webhooks.ping` delivery to the endpoint.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @returns the delivery id.
+     */
+    async test(ctx, id) {
+        const endpoint = await this.require(ctx, id);
+        const eventId = (0, node_crypto_1.randomUUID)();
+        const envelope = (0, webhook_envelope_1.buildEnvelope)({
+            eventId,
+            eventKey: builtin_events_1.WEBHOOK_PING_EVENT_KEY,
+            orgId: endpoint.orgId,
+            data: { message: 'This is a test delivery.', endpointId: endpoint.id },
+            occurredAt: this.now(),
+        });
+        const [delivery] = await this.repository.insertDeliveries(endpoint.orgId, [
+            { endpointId: endpoint.id, eventKey: builtin_events_1.WEBHOOK_PING_EVENT_KEY, eventId, payload: envelope },
+        ]);
+        if (!delivery)
+            throw new Error('The test delivery could not be queued');
+        return { deliveryId: delivery.id };
+    }
+    // ---------------------------------------------------------------------------
+    // Deliveries
+    // ---------------------------------------------------------------------------
+    /**
+     * A page of an endpoint's deliveries.
+     *
+     * @param ctx - who is acting.
+     * @param id - the endpoint id.
+     * @param query - page, size and filters.
+     * @returns the page.
+     */
+    async listDeliveries(ctx, id, query) {
+        const endpoint = await this.require(ctx, id);
+        const { items, total } = await this.repository.listDeliveries(endpoint.orgId, endpoint.id, query);
+        return { items: items.map(webhook_views_1.toDeliveryView), total, page: query.page, pageSize: query.pageSize, totalPages: Math.ceil(total / query.pageSize) };
+    }
+    /**
+     * One delivery with its payload.
+     *
+     * @param ctx - who is acting.
+     * @param deliveryId - the delivery id.
+     * @returns the detail.
+     */
+    async getDelivery(ctx, deliveryId) {
+        const delivery = await this.repository.findDelivery(this.orgOf(ctx), deliveryId, this.filterOf(ctx));
+        if (!delivery)
+            throw new webhooks_errors_1.WebhookDeliveryNotFoundError();
+        return (0, webhook_views_1.toDeliveryDetail)(delivery, `${(0, webhooks_options_1.userAgentToken)(this.options.appName())}-Webhooks/1.0`);
+    }
+    /**
+     * Sends a delivery again: the same row goes back to `pending` with a fresh
+     * attempt count and a new job. The event id (`webhook-id`) is unchanged, so a
+     * receiver that deduplicates sees the same event.
+     *
+     * @param ctx - who is acting.
+     * @param deliveryId - the delivery id.
+     * @returns the delivery.
+     * @throws WebhookDisabledError when the endpoint is switched off.
+     */
+    async redeliver(ctx, deliveryId) {
+        const orgId = this.orgOf(ctx);
+        const delivery = await this.repository.findDelivery(orgId, deliveryId, this.filterOf(ctx));
+        if (!delivery)
+            throw new webhooks_errors_1.WebhookDeliveryNotFoundError();
+        const endpoint = await this.repository.findEndpoint(orgId, delivery.endpointId, this.filterOf(ctx));
+        if (!endpoint)
+            throw new webhooks_errors_1.WebhookDeliveryNotFoundError();
+        if (!endpoint.enabled)
+            throw new webhooks_errors_1.WebhookDisabledError();
+        const row = await this.repository.resetForRedelivery(orgId, deliveryId);
+        await this.record(webhooks_constants_1.WEBHOOK_AUDIT_ACTIONS.REDELIVER, ctx, endpoint.id, { deliveryId });
+        return (0, webhook_views_1.toDeliveryDetail)(row, `${(0, webhooks_options_1.userAgentToken)(this.options.appName())}-Webhooks/1.0`);
+    }
+    /**
+     * The events the caller may subscribe to at this scope.
+     *
+     * @param ctx - who is acting.
+     * @returns the catalog entries the caller's permissions allow.
+     */
+    catalog(ctx) {
+        const permitted = new Set((0, webhook_catalog_1.subscribableEvents)(ctx.scope).filter((event) => this.holds(ctx, event.permission)).map((event) => event.key));
+        return (0, webhook_catalog_1.catalogFor)(ctx.scope).filter((entry) => permitted.has(entry.key));
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    orgOf(ctx) {
+        if (ctx.scope === 'system')
+            return null;
+        if (!ctx.orgId)
+            throw new webhooks_errors_1.WebhookNotFoundError();
+        return ctx.orgId;
+    }
+    filterOf(ctx) {
+        return ctx.scope === 'user' ? { scope: 'user', ownerUserId: ctx.userId } : { scope: ctx.scope };
+    }
+    async require(ctx, id) {
+        const row = await this.repository.findEndpoint(this.orgOf(ctx), id, this.filterOf(ctx));
+        if (!row)
+            throw new webhooks_errors_1.WebhookNotFoundError();
+        return row;
+    }
+    policy() {
+        return {
+            allowInsecureHttp: this.options.allowInsecureHttp,
+            allowPrivateTargets: this.options.allowPrivateTargets,
+            allowedHosts: this.options.allowedHosts,
+        };
+    }
+    /** Syntax and, best effort, DNS: a name that does not resolve yet is accepted (it may be set up later); one that resolves to a private address is not. */
+    async assertUrlAllowed(url) {
+        try {
+            await (0, egress_guard_1.resolveWebhookTarget)(url, this.policy(), this.resolver);
+        }
+        catch (error) {
+            if (!(error instanceof egress_guard_1.WebhookEgressError))
+                throw error;
+            if (error.code === 'unresolvable')
+                return;
+            throw new webhooks_errors_1.WebhookRequestError(error.code === 'invalid_url' ? webhooks_1.WEBHOOK_ERROR_CODES.WEBHOOK_URL_INVALID : webhooks_1.WEBHOOK_ERROR_CODES.WEBHOOK_URL_FORBIDDEN, error.message);
+        }
+    }
+    holds(ctx, permission) {
+        return permission === undefined || ctx.permissions.includes(permission);
+    }
+    assertEventKeys(ctx, keys) {
+        for (const pattern of keys) {
+            if (!(0, webhook_catalog_1.subscriptionIsSubscribable)(pattern, ctx.scope)) {
+                throw new webhooks_errors_1.WebhookRequestError(webhooks_1.WEBHOOK_ERROR_CODES.WEBHOOK_EVENT_UNKNOWN, `"${pattern}" names no event this kind of endpoint can receive.`);
+            }
+            const matching = (0, webhook_catalog_1.subscribableEvents)(ctx.scope).filter((event) => (0, webhook_event_registry_1.subscriptionMatches)(pattern, event.key));
+            if (!matching.some((event) => this.holds(ctx, event.permission))) {
+                throw new webhooks_errors_1.WebhookRequestError(webhooks_1.WEBHOOK_ERROR_CODES.WEBHOOK_EVENT_NOT_PERMITTED, `You may not subscribe to "${pattern}".`);
+            }
+        }
+    }
+    async record(action, ctx, targetId, extra = {}) {
+        try {
+            await this.audit.record({ action, actorUserId: ctx.userId, targetType: webhooks_constants_1.WEBHOOK_AUDIT_TARGET, targetId, meta: { scope: ctx.scope, ...extra } });
+        }
+        catch (error) {
+            this.logger.warn(`Could not record the audit event ${action}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+};
+exports.WebhookEndpointsService = WebhookEndpointsService;
+exports.WebhookEndpointsService = WebhookEndpointsService = WebhookEndpointsService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Inject)(webhooks_options_1.WEBHOOKS_OPTIONS)),
+    __param(3, (0, common_1.Inject)(transport_1.WEBHOOKS_RESOLVER)),
+    __param(4, (0, common_1.Inject)(index_1.AUDIT_SINK)),
+    __metadata("design:paramtypes", [webhooks_repository_1.WebhooksRepository,
+        webhook_secrets_service_1.WebhookSecrets, Object, Object, Object])
+], WebhookEndpointsService);
+//# sourceMappingURL=webhook-endpoints.service.js.map

package/dist/webhooks/webhook-endpoints.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-endpoints.service.js","sourceRoot":"","sources":["../../src/webhooks/webhook-endpoints.service.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/webhook-envelope.d.ts

@@ -0,0 +1,36 @@
+import { type WebhookEnvelope } from '@marinoscar/platform-contract/webhooks';
+/** The `apiVersion` of every envelope. @stability experimental */
+export declare const WEBHOOK_ENVELOPE_API_VERSION_VALUE = "2026-11-01";
+/** What {@link buildEnvelope} takes. @stability experimental */
+export interface EnvelopeInput {
+    /** Event id. */
+    readonly eventId: string;
+    /** Event key. */
+    readonly eventKey: string;
+    /** Org id. */
+    readonly orgId: string | null;
+    /** Data. */
+    readonly data: unknown;
+    /** Occurred at. */
+    readonly occurredAt: Date;
+}
+/**
+ * The envelope: `{ id, type, createdAt, apiVersion, org, data }`.
+ *
+ * @param input - see {@link EnvelopeInput}.
+ * @returns the envelope, stored on the delivery row as the body sent.
+ *
+ * @stability experimental
+ */
+export declare function buildEnvelope(input: EnvelopeInput): WebhookEnvelope;
+/**
+ * The bounded `event_group` metric label of an event key: its first segment
+ * when that is a registered group (or `notification`), else `other`.
+ *
+ * @param eventKey - an event key.
+ * @returns the label.
+ *
+ * @stability experimental
+ */
+export declare function eventGroupOf(eventKey: string): string;
+//# sourceMappingURL=webhook-envelope.d.ts.map

package/dist/webhooks/webhook-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-envelope.d.ts","sourceRoot":"","sources":["../../src/webhooks/webhook-envelope.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAInG,kEAAkE;AAClE,eAAO,MAAM,kCAAkC,eAAsB,CAAC;AAEtE,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iBAAiB;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,cAAc;IACd,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY;IACZ,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,mBAAmB;IACnB,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CASnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD"}

package/dist/webhooks/webhook-envelope.js

@@ -0,0 +1,46 @@
+"use strict";
+// =============================================================================
+// The body a receiver gets, and the metric label of an event (issue #1046)
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_ENVELOPE_API_VERSION_VALUE = void 0;
+exports.buildEnvelope = buildEnvelope;
+exports.eventGroupOf = eventGroupOf;
+const webhooks_1 = require("@marinoscar/platform-contract/webhooks");
+const webhook_event_registry_1 = require("./registry/webhook-event.registry");
+/** The `apiVersion` of every envelope. @stability experimental */
+exports.WEBHOOK_ENVELOPE_API_VERSION_VALUE = webhooks_1.WEBHOOK_API_VERSION;
+/**
+ * The envelope: `{ id, type, createdAt, apiVersion, org, data }`.
+ *
+ * @param input - see {@link EnvelopeInput}.
+ * @returns the envelope, stored on the delivery row as the body sent.
+ *
+ * @stability experimental
+ */
+function buildEnvelope(input) {
+    return {
+        id: input.eventId,
+        type: input.eventKey,
+        createdAt: input.occurredAt.toISOString(),
+        apiVersion: exports.WEBHOOK_ENVELOPE_API_VERSION_VALUE,
+        org: input.orgId ? { id: input.orgId } : null,
+        data: input.data,
+    };
+}
+/**
+ * The bounded `event_group` metric label of an event key: its first segment
+ * when that is a registered group (or `notification`), else `other`.
+ *
+ * @param eventKey - an event key.
+ * @returns the label.
+ *
+ * @stability experimental
+ */
+function eventGroupOf(eventKey) {
+    const first = eventKey.split('.')[0] ?? '';
+    if (first === 'notification')
+        return first;
+    return webhook_event_registry_1.webhookEventRegistry.list().some((event) => event.key.split('.')[0] === first) ? first : 'other';
+}
+//# sourceMappingURL=webhook-envelope.js.map

package/dist/webhooks/webhook-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-envelope.js","sourceRoot":"","sources":["../../src/webhooks/webhook-envelope.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;;;AA+BhF,sCASC;AAWD,oCAIC;AArDD,qEAAmG;AAEnG,8EAAyE;AAEzE,kEAAkE;AACrD,QAAA,kCAAkC,GAAG,8BAAmB,CAAC;AAgBtE;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,KAAoB;IAChD,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,OAAO;QACjB,IAAI,EAAE,KAAK,CAAC,QAAQ;QACpB,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE;QACzC,UAAU,EAAE,0CAAkC;QAC9C,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI;QAC7C,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAAC,QAAgB;IAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,KAAK,KAAK,cAAc;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,6CAAoB,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;AAC1G,CAAC"}