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

package/dist/webhooks/registry/webhook-event.registry.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { WEBHOOK_EVENT_KEY_PATTERN, type WebhookScope } from '@marinoscar/platform-contract/webhooks';
+/**
+ * One event an endpoint can subscribe to.
+ *
+ * @stability experimental
+ */
+export interface WebhookEventDef {
+    /** `area.entity.action`, lower snake case segments, at least two (`nodes.node.offline`). PERMANENT. */
+    readonly key: string;
+    /** A short name for the event picker. */
+    readonly label: string;
+    /** One sentence: when the event fires. */
+    readonly description: string;
+    /** The picker's group heading (`Nodes`). */
+    readonly group: string;
+    /**
+     * Who may subscribe: `user` (a member's own endpoints; the event is about
+     * that member), `org` (an organization's endpoints) or `system` (the
+     * deployment's endpoints). An endpoint of a scope receives only events whose
+     * audience is that scope.
+     */
+    readonly audience: WebhookScope;
+    /**
+     * The permission the endpoint's OWNER must hold when the event fans out
+     * (re-read every time, so revoking it silences the endpoint). Absent: none.
+     */
+    readonly permission?: string;
+    /** Validates the event's `data`; exported as JSON Schema by `GET .../events`. */
+    readonly payloadSchema: z.ZodType;
+    /** A sample `data` for the catalog and the docs. */
+    readonly example?: unknown;
+    /** Who registered it (`platform` or a slice or app id). */
+    readonly source: string;
+}
+/**
+ * The registered events.
+ *
+ * @stability experimental
+ */
+export declare const webhookEventRegistry: import("../../core/index").Registry<WebhookEventDef>;
+/**
+ * Adds an event to the catalog. Registering the same definition again (the
+ * same object) is a no-op, so a module that composes twice in one process
+ * (Jest workers) does not fail.
+ *
+ * @param def - the event.
+ * @throws RegistryError when the key is malformed, the definition invalid, or another definition owns the key.
+ *
+ * @example
+ * ```ts
+ * registerWebhookEvent({
+ *   key: 'invoices.invoice.paid', label: 'Invoice paid', description: 'An invoice was paid.',
+ *   group: 'Invoices', audience: 'org', permission: 'org_webhooks:read',
+ *   payloadSchema: z.object({ invoiceId: z.string() }), source: 'invoices',
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerWebhookEvent(def: WebhookEventDef): void;
+/**
+ * The event definition for a key, or `undefined`.
+ *
+ * @param key - an exact event key.
+ * @returns the definition.
+ *
+ * @stability experimental
+ */
+export declare function findWebhookEvent(key: string): WebhookEventDef | undefined;
+/**
+ * The registered events whose audience is `scope`, in registration order.
+ *
+ * @param scope - the endpoint scope.
+ * @returns the definitions.
+ *
+ * @stability experimental
+ */
+export declare function webhookEventsForScope(scope: WebhookScope): WebhookEventDef[];
+/**
+ * Whether a subscription entry (`exact`, `group.*` or `*`) matches an event key.
+ *
+ * @param pattern - one entry of an endpoint's `eventKeys`.
+ * @param eventKey - the emitted event's key.
+ * @returns `true` when it matches.
+ *
+ * @stability experimental
+ */
+export declare function subscriptionMatches(pattern: string, eventKey: string): boolean;
+/**
+ * Whether any entry of `patterns` matches `eventKey`.
+ *
+ * @param patterns - an endpoint's `eventKeys`.
+ * @param eventKey - the emitted event's key.
+ * @returns `true` when subscribed.
+ *
+ * @stability experimental
+ */
+export declare function isSubscribed(patterns: readonly string[], eventKey: string): boolean;
+/**
+ * Whether a subscription entry could ever match a registered event of `scope`
+ * (an exact key that is registered for the scope, a wildcard that matches at
+ * least one, or `*`).
+ *
+ * @param pattern - one entry.
+ * @param scope - the endpoint scope.
+ * @returns `true` when it names something subscribable.
+ *
+ * @stability experimental
+ */
+export declare function patternHasEventsForScope(pattern: string, scope: WebhookScope): boolean;
+/** The JSON Schema of an event's `data`, or an open object when conversion is not possible. */
+export declare function jsonSchemaOf(event: WebhookEventDef): Record<string, unknown>;
+export { WEBHOOK_EVENT_KEY_PATTERN };
+//# sourceMappingURL=webhook-event.registry.d.ts.map

package/dist/webhooks/registry/webhook-event.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-event.registry.d.ts","sourceRoot":"","sources":["../../../src/webhooks/registry/webhook-event.registry.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,yBAAyB,EAEzB,KAAK,YAAY,EAClB,MAAM,wCAAwC,CAAC;AAIhD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uGAAuG;IACvG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAID;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,sDAoB/B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAG/D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,EAAE,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEtF;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM5E;AAED,OAAO,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/webhooks/registry/webhook-event.registry.js

@@ -0,0 +1,152 @@
+"use strict";
+// =============================================================================
+// The webhook event catalog (issue #1046)
+// =============================================================================
+//
+// An OPEN vocabulary: an event key is a string, registered with
+// `registerWebhookEvent` from the slice that raises it (the nodes and jobs
+// bridges below are the platform's own; the alerts slice registers its two the
+// same way). A key is permanent once an endpoint subscribes to it. Framework-
+// free, like every registry: no Nest, so the catalog loads in a seed or a script.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_EVENT_KEY_PATTERN = exports.webhookEventRegistry = void 0;
+exports.registerWebhookEvent = registerWebhookEvent;
+exports.findWebhookEvent = findWebhookEvent;
+exports.webhookEventsForScope = webhookEventsForScope;
+exports.subscriptionMatches = subscriptionMatches;
+exports.isSubscribed = isSubscribed;
+exports.patternHasEventsForScope = patternHasEventsForScope;
+exports.jsonSchemaOf = jsonSchemaOf;
+const zod_1 = require("zod");
+const webhooks_1 = require("@marinoscar/platform-contract/webhooks");
+Object.defineProperty(exports, "WEBHOOK_EVENT_KEY_PATTERN", { enumerable: true, get: function () { return webhooks_1.WEBHOOK_EVENT_KEY_PATTERN; } });
+const index_1 = require("../../core/index");
+const KEY_FULL = new RegExp(`^${webhooks_1.WEBHOOK_EVENT_KEY_REGEX_SOURCE}$`);
+/**
+ * The registered events.
+ *
+ * @stability experimental
+ */
+exports.webhookEventRegistry = (0, index_1.defineRegistry)({
+    name: 'webhook-events',
+    idOf: (event) => event.key,
+    idPattern: KEY_FULL,
+    order: 'registration',
+    validate: (event) => {
+        if (event.key.length > webhooks_1.WEBHOOK_EVENT_KEY_MAX)
+            throw new Error(`key must be at most ${webhooks_1.WEBHOOK_EVENT_KEY_MAX} characters`);
+        for (const field of ['label', 'description', 'group', 'source']) {
+            if (typeof event[field] !== 'string' || event[field].trim() === '')
+                throw new Error(`${field} must be a non-empty string`);
+        }
+        if (!['user', 'org', 'system'].includes(event.audience))
+            throw new Error(`audience must be user, org or system (got ${String(event.audience)})`);
+        if (event.permission !== undefined && (typeof event.permission !== 'string' || event.permission === '')) {
+            throw new Error('permission must be a non-empty string when present');
+        }
+        if (!event.payloadSchema || typeof event.payloadSchema.safeParse !== 'function') {
+            throw new Error('payloadSchema must be a zod schema');
+        }
+    },
+    describeDuplicate: (existing, incoming) => `Webhook event "${incoming.key}" is already registered by "${existing.source}"; "${incoming.source}" cannot claim it too. An event key is permanent once an endpoint subscribes to it.`,
+});
+/**
+ * Adds an event to the catalog. Registering the same definition again (the
+ * same object) is a no-op, so a module that composes twice in one process
+ * (Jest workers) does not fail.
+ *
+ * @param def - the event.
+ * @throws RegistryError when the key is malformed, the definition invalid, or another definition owns the key.
+ *
+ * @example
+ * ```ts
+ * registerWebhookEvent({
+ *   key: 'invoices.invoice.paid', label: 'Invoice paid', description: 'An invoice was paid.',
+ *   group: 'Invoices', audience: 'org', permission: 'org_webhooks:read',
+ *   payloadSchema: z.object({ invoiceId: z.string() }), source: 'invoices',
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerWebhookEvent(def) {
+    if (exports.webhookEventRegistry.get(def.key) === def)
+        return;
+    exports.webhookEventRegistry.register(def);
+}
+/**
+ * The event definition for a key, or `undefined`.
+ *
+ * @param key - an exact event key.
+ * @returns the definition.
+ *
+ * @stability experimental
+ */
+function findWebhookEvent(key) {
+    return exports.webhookEventRegistry.get(key);
+}
+/**
+ * The registered events whose audience is `scope`, in registration order.
+ *
+ * @param scope - the endpoint scope.
+ * @returns the definitions.
+ *
+ * @stability experimental
+ */
+function webhookEventsForScope(scope) {
+    return exports.webhookEventRegistry.list().filter((event) => event.audience === scope);
+}
+/**
+ * Whether a subscription entry (`exact`, `group.*` or `*`) matches an event key.
+ *
+ * @param pattern - one entry of an endpoint's `eventKeys`.
+ * @param eventKey - the emitted event's key.
+ * @returns `true` when it matches.
+ *
+ * @stability experimental
+ */
+function subscriptionMatches(pattern, eventKey) {
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('.*'))
+        return eventKey.startsWith(pattern.slice(0, -1));
+    return pattern === eventKey;
+}
+/**
+ * Whether any entry of `patterns` matches `eventKey`.
+ *
+ * @param patterns - an endpoint's `eventKeys`.
+ * @param eventKey - the emitted event's key.
+ * @returns `true` when subscribed.
+ *
+ * @stability experimental
+ */
+function isSubscribed(patterns, eventKey) {
+    return patterns.some((pattern) => subscriptionMatches(pattern, eventKey));
+}
+/**
+ * Whether a subscription entry could ever match a registered event of `scope`
+ * (an exact key that is registered for the scope, a wildcard that matches at
+ * least one, or `*`).
+ *
+ * @param pattern - one entry.
+ * @param scope - the endpoint scope.
+ * @returns `true` when it names something subscribable.
+ *
+ * @stability experimental
+ */
+function patternHasEventsForScope(pattern, scope) {
+    return webhookEventsForScope(scope).some((event) => subscriptionMatches(pattern, event.key));
+}
+/** The JSON Schema of an event's `data`, or an open object when conversion is not possible. */
+function jsonSchemaOf(event) {
+    try {
+        return zod_1.z.toJSONSchema(event.payloadSchema, { unrepresentable: 'any' });
+    }
+    catch {
+        return { type: 'object' };
+    }
+}
+//# sourceMappingURL=webhook-event.registry.js.map

package/dist/webhooks/registry/webhook-event.registry.js.map

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

package/dist/webhooks/signing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A fresh signing secret: `whsec_` and 32 random bytes in base64.
+ *
+ * @returns the secret. Shown once to its owner; stored only in the credentials store.
+ *
+ * @stability experimental
+ */
+export declare function generateWebhookSecret(): string;
+/** What {@link signedHeaders} takes. @stability experimental */
+export interface SignedHeadersInput {
+    /** The `webhook-id`: the event id, identical across retries. */
+    readonly id: string;
+    /** Unix seconds at signing time. */
+    readonly timestamp: number;
+    /** The exact body. */
+    readonly body: string;
+    /** The current secret first, then the previous one while the overlap lasts. */
+    readonly secrets: readonly string[];
+    /** The `User-Agent`. */
+    readonly userAgent: string;
+}
+/**
+ * The request headers of one delivery attempt, including `webhook-signature`.
+ *
+ * @param input - see {@link SignedHeadersInput}.
+ * @returns the headers.
+ *
+ * @stability experimental
+ */
+export declare function signedHeaders(input: SignedHeadersInput): Promise<Record<string, string>>;
+//# sourceMappingURL=signing.d.ts.map

package/dist/webhooks/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../src/webhooks/signing.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY9F"}

package/dist/webhooks/signing.js

@@ -0,0 +1,48 @@
+"use strict";
+// =============================================================================
+// Signing (issue #1046)
+// =============================================================================
+//
+// Standard Webhooks, scheme v1, through the contract's `signWebhookPayload`
+// (the same helper a receiver verifies with). The slice never invents a second
+// implementation: what is signed here is what `verifyWebhookSignature` checks.
+// During a rotation overlap the header carries two space-separated signatures,
+// the current secret's first.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWebhookSecret = generateWebhookSecret;
+exports.signedHeaders = signedHeaders;
+const node_crypto_1 = require("node:crypto");
+const webhooks_1 = require("@marinoscar/platform-contract/webhooks");
+/**
+ * A fresh signing secret: `whsec_` and 32 random bytes in base64.
+ *
+ * @returns the secret. Shown once to its owner; stored only in the credentials store.
+ *
+ * @stability experimental
+ */
+function generateWebhookSecret() {
+    return `${webhooks_1.WEBHOOK_SECRET_PREFIX}${(0, node_crypto_1.randomBytes)(32).toString('base64')}`;
+}
+/**
+ * The request headers of one delivery attempt, including `webhook-signature`.
+ *
+ * @param input - see {@link SignedHeadersInput}.
+ * @returns the headers.
+ *
+ * @stability experimental
+ */
+async function signedHeaders(input) {
+    const signatures = [];
+    for (const secret of input.secrets) {
+        signatures.push(await (0, webhooks_1.signWebhookPayload)({ secret, id: input.id, timestamp: input.timestamp, body: input.body }));
+    }
+    return {
+        'content-type': 'application/json',
+        'user-agent': input.userAgent,
+        [webhooks_1.WEBHOOK_HEADERS.ID]: input.id,
+        [webhooks_1.WEBHOOK_HEADERS.TIMESTAMP]: String(input.timestamp),
+        [webhooks_1.WEBHOOK_HEADERS.SIGNATURE]: signatures.join(' '),
+    };
+}
+//# sourceMappingURL=signing.js.map

package/dist/webhooks/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../src/webhooks/signing.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAC/E,8BAA8B;AAC9B,gFAAgF;;AAahF,sDAEC;AAwBD,sCAYC;AAjDD,6CAA0C;AAE1C,qEAAoH;AAEpH;;;;;;GAMG;AACH,SAAgB,qBAAqB;IACnC,OAAO,GAAG,gCAAqB,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;AACzE,CAAC;AAgBD;;;;;;;GAOG;AACI,KAAK,UAAU,aAAa,CAAC,KAAyB;IAC3D,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,UAAU,CAAC,IAAI,CAAC,MAAM,IAAA,6BAAkB,EAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpH,CAAC;IACD,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,YAAY,EAAE,KAAK,CAAC,SAAS;QAC7B,CAAC,0BAAe,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE;QAC9B,CAAC,0BAAe,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC;QACpD,CAAC,0BAAe,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/webhooks/tasks/webhook-purge.task.d.ts

@@ -0,0 +1,17 @@
+import { JobsService, type JobsPrisma } from '../../jobs/index';
+/**
+ * The daily `@Cron` that enqueues `webhooks.deliveries_purge` (enqueue only).
+ *
+ * @internal
+ *
+ * @stability experimental
+ */
+export declare class WebhookPurgeTask {
+    private readonly jobs;
+    private readonly prisma;
+    private readonly logger;
+    constructor(jobs: JobsService, prisma: JobsPrisma);
+    /** Enqueues today's purge, unless one is already pending. 04:17 UTC, off the hour. */
+    handleCron(): Promise<void>;
+}
+//# sourceMappingURL=webhook-purge.task.d.ts.map

package/dist/webhooks/tasks/webhook-purge.task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-purge.task.d.ts","sourceRoot":"","sources":["../../../src/webhooks/tasks/webhook-purge.task.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGxF;;;;;;GAMG;AACH,qBACa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACI,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJlD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;gBAGzC,IAAI,EAAE,WAAW,EACQ,MAAM,EAAE,UAAU;IAG9D,sFAAsF;IAEhF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CASlC"}

package/dist/webhooks/tasks/webhook-purge.task.js

@@ -0,0 +1,68 @@
+"use strict";
+// =============================================================================
+// WebhookPurgeTask: queues the daily delivery purge (issue #1046)
+// =============================================================================
+//
+// ⚠ THIS TASK DELETES NOTHING. A `@Cron` decides and enqueues, nothing more
+// (the `cron-enqueue-only` conformance suite). The deleting is
+// `webhooks.deliveries_purge`'s work, on a worker slot, retried by the queue.
+// =============================================================================
+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 WebhookPurgeTask_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookPurgeTask = void 0;
+const common_1 = require("@nestjs/common");
+const schedule_1 = require("@nestjs/schedule");
+const index_1 = require("../../core/index");
+const index_2 = require("../../jobs/index");
+const webhooks_constants_1 = require("../webhooks.constants");
+/**
+ * The daily `@Cron` that enqueues `webhooks.deliveries_purge` (enqueue only).
+ *
+ * @internal
+ *
+ * @stability experimental
+ */
+let WebhookPurgeTask = WebhookPurgeTask_1 = class WebhookPurgeTask {
+    jobs;
+    prisma;
+    logger = new common_1.Logger(WebhookPurgeTask_1.name);
+    constructor(jobs, prisma) {
+        this.jobs = jobs;
+        this.prisma = prisma;
+    }
+    /** Enqueues today's purge, unless one is already pending. 04:17 UTC, off the hour. */
+    async handleCron() {
+        await (0, index_2.enqueueHousekeepingJob)({
+            jobs: this.jobs,
+            prisma: this.prisma,
+            logger: this.logger,
+            type: webhooks_constants_1.WEBHOOK_PURGE_JOB_TYPE,
+            what: 'webhook delivery purge',
+        });
+    }
+};
+exports.WebhookPurgeTask = WebhookPurgeTask;
+__decorate([
+    (0, schedule_1.Cron)('17 4 * * *'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], WebhookPurgeTask.prototype, "handleCron", null);
+exports.WebhookPurgeTask = WebhookPurgeTask = WebhookPurgeTask_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [index_2.JobsService, Object])
+], WebhookPurgeTask);
+//# sourceMappingURL=webhook-purge.task.js.map

package/dist/webhooks/tasks/webhook-purge.task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-purge.task.js","sourceRoot":"","sources":["../../../src/webhooks/tasks/webhook-purge.task.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,kEAAkE;AAClE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,+DAA+D;AAC/D,8EAA8E;AAC9E,gFAAgF;;;;;;;;;;;;;;;;AAEhF,2CAA4D;AAC5D,+CAAwC;AAExC,4CAAmD;AACnD,4CAAwF;AACxF,8DAA+D;AAE/D;;;;;;GAMG;AAEI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IAIR;IACyB;IAJ3B,MAAM,GAAG,IAAI,eAAM,CAAC,kBAAgB,CAAC,IAAI,CAAC,CAAC;IAE5D,YACmB,IAAiB,EACQ,MAAkB;QAD3C,SAAI,GAAJ,IAAI,CAAa;QACQ,WAAM,GAAN,MAAM,CAAY;IAC3D,CAAC;IAEJ,sFAAsF;IAEhF,AAAN,KAAK,CAAC,UAAU;QACd,MAAM,IAAA,8BAAsB,EAAC;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,2CAAsB;YAC5B,IAAI,EAAE,wBAAwB;SAC/B,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAnBY,4CAAgB;AAUrB;IADL,IAAA,eAAI,EAAC,YAAY,CAAC;;;;kDASlB;2BAlBU,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;qCADD,mBAAW;GAJzB,gBAAgB,CAmB5B"}

package/dist/webhooks/testing/conformance.d.ts

@@ -0,0 +1,61 @@
+import type { ConformanceAppSuite, ConformanceTestApi } from '../../testing/index';
+declare module '../../testing/index' {
+    interface PlatformConformanceSuiteOptions {
+        /** The webhooks slice's suite: its options (an empty object runs it), or a skip with a reason. Registered by importing `@marinoscar/platform-api/webhooks/testing`. */
+        webhooks?: WebhooksConformanceOptions | false;
+    }
+}
+/**
+ * What the `webhooks` suite takes.
+ *
+ * @stability experimental
+ */
+export interface WebhooksConformanceOptions {
+    /** Extra addresses the egress case must also see refused (an app's own internal ranges). */
+    readonly extraBlockedAddresses?: readonly string[];
+}
+/** One route, as the suite sees it. @stability experimental */
+export interface WebhookRoute {
+    /** `Controller#handler`. */
+    readonly id: string;
+    /** The HTTP method. */
+    readonly method: string;
+    /** Whether it is `@Public()`. */
+    readonly isPublic: boolean;
+    /** Whether a guard protects it. */
+    readonly authenticated: boolean;
+    /** The permissions it requires. */
+    readonly permissions: readonly string[];
+}
+/** One route with the pair of permission strings its tier enforces. @stability experimental */
+export interface WebhookControllerRoute extends WebhookRoute {
+    /** The permission a `GET` of the tier requires. */
+    readonly read: string;
+    /** The permission every other method of the tier requires. */
+    readonly write: string;
+}
+/**
+ * The routes of the three controllers, read from their metadata.
+ *
+ * @returns every handler, with the tier it belongs to.
+ *
+ * @stability experimental
+ */
+export declare function discoverWebhookRoutes(): WebhookControllerRoute[];
+/**
+ * Registers the suite's cases with the test API.
+ *
+ * @param api - the runner's test API.
+ * @param options - the suite's options.
+ *
+ * @stability experimental
+ */
+export declare function registerWebhooksConformance(api: ConformanceTestApi, options: WebhooksConformanceOptions): void;
+/**
+ * The `webhooks` conformance suite.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const webhooksConformanceSuite: ConformanceAppSuite<WebhooksConformanceOptions>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/webhooks/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/webhooks/testing/conformance.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AASnF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,+BAA+B;QACvC,uKAAuK;QACvK,QAAQ,CAAC,EAAE,0BAA0B,GAAG,KAAK,CAAC;KAC/C;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,+FAA+F;AAC/F,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,sBAAsB,EAAE,CAsBhE;AAiCD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAiK9G;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBAAmB,CAAC,0BAA0B,CAQpF,CAAC"}