@crowdsource.you/core 1.2.0

package/dist/testing/webhook-simulator.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * The webhook simulator — the producer side of §10.8.
+ *
+ * An integrator can point this at their own receiver and watch a real delivery
+ * arrive, signed exactly as CrowdSource signs one, without a jury having sat and
+ * without anything being enforced against a real user.
+ *
+ * It deliberately also makes it easy to send a delivery that is WRONG:
+ * `expired`, `wrongSecret`, `tampered` and a raw `signature` override are here
+ * so an integration test can assert that the receiver REFUSES those. A test
+ * suite that only ever sends valid deliveries proves the receiver can say yes.
+ * Proving it can say no is the part that matters, and it is the part nobody
+ * writes unless the tooling makes it a one-liner.
+ *
+ * Signing lives here rather than in `@crowdsource.you/core/express` because the two
+ * are opposite sides of the contract: the verifier must never import a signer
+ * that could be "corrected" until they agree with each other and both disagree
+ * with the service. What they share instead is
+ * `buildWebhookSignedPayload` from the contracts package, which is the one
+ * definition of what gets signed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSimulator = void 0;
+exports.signWebhookDelivery = signWebhookDelivery;
+const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("@crowdsource.you/contracts");
+function eventIdOf(event) {
+    if (typeof event === 'object' && event !== null && 'id' in event) {
+        const id = event.id;
+        if (typeof id === 'string')
+            return id;
+    }
+    throw new TypeError('A webhook event must carry a string `id` (§10.7).');
+}
+/** Signs one delivery. */
+function signWebhookDelivery(input) {
+    const signedBody = JSON.stringify(input.event);
+    const timestamp = String(input.timestampSeconds ?? Math.floor(Date.now() / 1000));
+    const signature = input.signature ??
+        `${contracts_1.WEBHOOK_SIGNATURE_VERSION}=${(0, node_crypto_1.createHmac)('sha256', input.secret)
+            .update((0, contracts_1.buildWebhookSignedPayload)(timestamp, signedBody), 'utf8')
+            .digest('hex')}`;
+    return {
+        headers: {
+            'content-type': 'application/json',
+            [contracts_1.WEBHOOK_EVENT_ID_HEADER]: input.eventId ?? eventIdOf(input.event),
+            [contracts_1.WEBHOOK_TIMESTAMP_HEADER]: timestamp,
+            [contracts_1.WEBHOOK_SIGNATURE_HEADER]: signature,
+        },
+        // The tampered body is sent WITHOUT re-signing, which is the whole point:
+        // the signature above covers `signedBody` and the receiver is handed
+        // something else.
+        body: input.tamperedBody ?? signedBody,
+    };
+}
+/** Comfortably outside the five-minute window, in either direction. */
+const EXPIRED_SKEW_SECONDS = 3600;
+class WebhookSimulator {
+    constructor(options) {
+        this.options = options;
+    }
+    /** Signs a delivery without sending it. */
+    sign(event, overrides = {}) {
+        return signWebhookDelivery({
+            secret: overrides.wrongSecret ?? this.options.secret,
+            event,
+            timestampSeconds: overrides.timestampSeconds ??
+                Math.floor(Date.now() / 1000) - (overrides.expired === true ? EXPIRED_SKEW_SECONDS : 0),
+            ...(overrides.tamperedBody === undefined ? {} : { tamperedBody: overrides.tamperedBody }),
+            ...(overrides.signature === undefined ? {} : { signature: overrides.signature }),
+            ...(overrides.eventId === undefined ? {} : { eventId: overrides.eventId }),
+        });
+    }
+    /** Signs and POSTs a delivery to the receiver. */
+    async deliver(event, overrides = {}) {
+        const delivery = this.sign(event, overrides);
+        const fetchImpl = this.options.fetch ?? globalThis.fetch;
+        const response = await fetchImpl(this.options.url, {
+            method: 'POST',
+            headers: delivery.headers,
+            body: delivery.body,
+        });
+        const text = await response.text();
+        let body = null;
+        if (text.length > 0) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        return { status: response.status, body };
+    }
+}
+exports.WebhookSimulator = WebhookSimulator;
+//# sourceMappingURL=webhook-simulator.js.map

package/dist/testing/webhook-simulator.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The HTTP transport: one authenticated call, and what happens when it fails.
+ *
+ * Two things here are worth reading before changing anything.
+ *
+ * **Retries do not replace the integrator's outbox.** §7.1 is explicit that the
+ * durable retry path belongs to the application: it stores the report and an
+ * outbox row in one operation, and a worker re-delivers until CrowdSource
+ * accepts. The retries below only smooth over a blip inside a single delivery
+ * attempt — they are bounded, they only fire for the statuses §10.5 marks as
+ * "come back later", and when they give up the error they throw still says
+ * `retryable: true` so the outbox keeps its job.
+ *
+ * **A retry is only safe because the write is idempotent.** Every write this
+ * client makes carries an `Idempotency-Key` (Appendix D), so a request that was
+ * received but whose response was lost returns the same `reportId` on the next
+ * attempt rather than creating a second report. A write without one must not be
+ * retried, and `request` refuses to retry a mutation that has no key rather than
+ * trusting the caller to have thought about it.
+ */
+export type FetchLike = typeof globalThis.fetch;
+/** How long a single attempt may take before it is abandoned. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Attempts per call, including the first. */
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+export interface TransportConfig {
+    readonly baseUrl: string;
+    /**
+     * What goes in `Authorization`, resolved per attempt.
+     *
+     * A function and not a string because a first-party service authenticates with
+     * an Oxy service token that EXPIRES (oxy ADR 0026) — a value captured once at
+     * construction would work for an hour and then fail forever. A CrowdSource
+     * service key never changes, so its provider simply returns the same string.
+     */
+    readonly bearerToken: () => string | Promise<string>;
+    readonly timeoutMs: number;
+    readonly maxAttempts: number;
+    readonly fetch: FetchLike;
+}
+export interface TransportRequest {
+    readonly method: 'GET' | 'POST';
+    /** Absolute path from the service root, e.g. `/v1/reports`. */
+    readonly path: string;
+    readonly body?: unknown;
+    /** Appendix D. Required for every mutation; a mutation without one is a defect. */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export declare class Transport {
+    private readonly config;
+    constructor(config: TransportConfig);
+    request<T>(request: TransportRequest): Promise<T>;
+    private attempt;
+    /** The caller's cancellation and this attempt's timeout, as one signal. */
+    private attemptSignal;
+    private readJson;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAEhD,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAQtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAgED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,eAAe;IAI7B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;YA4BzC,OAAO;IAkErB,2EAA2E;IAC3E,OAAO,CAAC,aAAa;YAKP,QAAQ;CAYvB"}

package/dist/transport.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * The HTTP transport: one authenticated call, and what happens when it fails.
+ *
+ * Two things here are worth reading before changing anything.
+ *
+ * **Retries do not replace the integrator's outbox.** §7.1 is explicit that the
+ * durable retry path belongs to the application: it stores the report and an
+ * outbox row in one operation, and a worker re-delivers until CrowdSource
+ * accepts. The retries below only smooth over a blip inside a single delivery
+ * attempt — they are bounded, they only fire for the statuses §10.5 marks as
+ * "come back later", and when they give up the error they throw still says
+ * `retryable: true` so the outbox keeps its job.
+ *
+ * **A retry is only safe because the write is idempotent.** Every write this
+ * client makes carries an `Idempotency-Key` (Appendix D), so a request that was
+ * received but whose response was lost returns the same `reportId` on the next
+ * attempt rather than creating a second report. A write without one must not be
+ * retried, and `request` refuses to retry a mutation that has no key rather than
+ * trusting the caller to have thought about it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_TIMEOUT_MS = void 0;
+const errors_js_1 = require("./errors.js");
+/** How long a single attempt may take before it is abandoned. */
+exports.DEFAULT_TIMEOUT_MS = 10000;
+/** Attempts per call, including the first. */
+exports.DEFAULT_MAX_ATTEMPTS = 3;
+/** The base of the exponential backoff between attempts. */
+const RETRY_BASE_DELAY_MS = 250;
+/** A cap so a `Retry-After` of an hour cannot hang a delivery worker. */
+const RETRY_DELAY_CEILING_MS = 5000;
+function parsedErrorBody(payload) {
+    if (typeof payload !== 'object' || payload === null || !('error' in payload))
+        return null;
+    const error = payload.error;
+    if (typeof error !== 'object' || error === null)
+        return null;
+    const record = { ...error };
+    if (typeof record.code !== 'string' || typeof record.message !== 'string')
+        return null;
+    const details = typeof record.details === 'object' && record.details !== null
+        ? record.details
+        : undefined;
+    return { code: record.code, message: record.message, details };
+}
+/** `Retry-After` in either of its two legal forms, in milliseconds. */
+function retryAfterMs(header) {
+    if (header === null)
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (Number.isNaN(date))
+        return null;
+    return Math.max(0, date - Date.now());
+}
+/**
+ * Full jitter over an exponential base. Without jitter, every worker that hit
+ * the same 503 comes back at the same millisecond and reproduces it.
+ */
+function backoffMs(attempt) {
+    const ceiling = Math.min(RETRY_BASE_DELAY_MS * 2 ** (attempt - 1), RETRY_DELAY_CEILING_MS);
+    return Math.random() * ceiling;
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new errors_js_1.CrowdSourceTransportError('The request was aborted.', { retryable: false }));
+        };
+        if (signal?.aborted === true) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+class Transport {
+    constructor(config) {
+        this.config = config;
+    }
+    async request(request) {
+        if (request.method !== 'GET' && request.idempotencyKey === undefined) {
+            throw new Error(`A ${request.method} to ${request.path} was made without an idempotency key. Appendix D requires one on every write.`);
+        }
+        let lastError = null;
+        for (let attempt = 1; attempt <= this.config.maxAttempts; attempt += 1) {
+            const outcome = await this.attempt(request);
+            if (outcome.ok)
+                return outcome.value;
+            lastError = outcome.error;
+            if (!outcome.error.retryable || attempt === this.config.maxAttempts)
+                break;
+            await delay(outcome.retryAfterMs ?? backoffMs(attempt), request.signal);
+        }
+        // Unreachable with `maxAttempts >= 1`; the loop either returns or assigns.
+        if (lastError === null) {
+            throw new errors_js_1.CrowdSourceTransportError('The request was never attempted.', {
+                retryable: false,
+            });
+        }
+        throw lastError;
+    }
+    async attempt(request) {
+        const headers = {
+            accept: 'application/json',
+            // Resolved per ATTEMPT, not per call: a retry that outlives a short-lived
+            // token must carry the new one, and this is the only place that knows an
+            // attempt is starting.
+            authorization: `Bearer ${await this.config.bearerToken()}`,
+        };
+        if (request.body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (request.idempotencyKey !== undefined) {
+            headers['idempotency-key'] = request.idempotencyKey;
+        }
+        let response;
+        try {
+            response = await this.config.fetch(`${this.config.baseUrl}${request.path}`, {
+                method: request.method,
+                headers,
+                body: request.body === undefined ? undefined : JSON.stringify(request.body),
+                signal: this.attemptSignal(request.signal),
+            });
+        }
+        catch (cause) {
+            const callerAborted = request.signal?.aborted === true;
+            return {
+                ok: false,
+                error: new errors_js_1.CrowdSourceTransportError(callerAborted
+                    ? 'The request was aborted by the caller.'
+                    : `The request to ${request.path} did not complete.`, { cause, retryable: !callerAborted }),
+            };
+        }
+        if (response.ok) {
+            return { ok: true, value: (await this.readJson(response)) };
+        }
+        const payload = await this.readJson(response).catch(() => null);
+        const body = parsedErrorBody(payload);
+        const code = body !== null && (0, errors_js_1.isCrowdSourceApiErrorCode)(body.code)
+            ? body.code
+            : (0, errors_js_1.apiErrorCodeForStatus)(response.status);
+        return {
+            ok: false,
+            error: new errors_js_1.CrowdSourceApiError({
+                status: response.status,
+                code,
+                message: body?.message ?? `CrowdSource answered ${response.status} for ${request.path}.`,
+                details: body?.details,
+            }),
+            retryAfterMs: retryAfterMs(response.headers.get('retry-after')) ?? undefined,
+        };
+    }
+    /** The caller's cancellation and this attempt's timeout, as one signal. */
+    attemptSignal(callerSignal) {
+        const timeout = AbortSignal.timeout(this.config.timeoutMs);
+        return callerSignal === undefined ? timeout : AbortSignal.any([callerSignal, timeout]);
+    }
+    async readJson(response) {
+        const text = await response.text();
+        if (text.length === 0)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new errors_js_1.CrowdSourceTransportError('CrowdSource answered with a body that is not JSON.', {
+                cause,
+                retryable: false,
+            });
+        }
+    }
+}
+exports.Transport = Transport;
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/webhookEndpoints.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Telling CrowdSource where to deliver decisions, and holding the secret it
+ * mints once.
+ *
+ * This is the half of the webhook integration that used to have no client at
+ * all: `@crowdsource.you/core/express` verifies deliveries against
+ * `CROWDSOURCE_WEBHOOK_SECRET`, and there was no supported way to obtain that
+ * value except hand-rolling an HTTP call with the bearer half of the service
+ * key. "Near-zero configuration" cannot mean an integrator writes their own
+ * fetch for a mandatory step, so §10.2's two management routes are here.
+ *
+ * Two properties of the secret shape everything below, and both are the server's
+ * design rather than this client's choice:
+ *
+ *   * **It is returned once and never again.** A webhook secret is decryptable
+ *     by CrowdSource because deliveries have to be signed with it, but re-serving
+ *     it would turn any credential holding `webhooks:manage` into a way to read
+ *     the signing key of an endpoint somebody else configured. So `secret` on a
+ *     registration is the only time that value exists outside the service.
+ *   * **Re-registering an existing URL mints nothing.** That is what makes a
+ *     deploy script safe to run on every boot — it will not invalidate the
+ *     secret the running process is verifying with. The corollary is that
+ *     re-registering cannot RECOVER a secret you failed to store; that is what
+ *     `rotateSecret` is for.
+ *
+ * Which is why `secret` is optional on the result. Its presence is not a detail:
+ * it means a value has just come into existence that nothing can produce again,
+ * and the integration is responsible for persisting it before the process exits.
+ */
+import type { Transport } from './transport.js';
+/**
+ * A signing secret, at the one moment it is visible.
+ *
+ * `signingStartsAt` is what makes a rotation overlap followable rather than
+ * guesswork: deliveries begin carrying this signature at that instant, so
+ * "install both, retire the old one after this time" is a procedure instead of
+ * an estimate.
+ */
+export interface WebhookSecret {
+    readonly version: number;
+    /** The value to configure as `CROWDSOURCE_WEBHOOK_SECRET`. Shown once. */
+    readonly value: string;
+    /** ISO-8601 UTC. When deliveries start being signed with this version. */
+    readonly signingStartsAt: string;
+}
+/** A registered endpoint, and the secret if this call is what created it. */
+export interface WebhookEndpoint {
+    readonly webhookEndpointId: string;
+    readonly url: string;
+    readonly eventTypes: readonly string[];
+    /**
+     * Kept open deliberately. §10.11 requires a newer server not to break an older
+     * client, and a status added later is exactly that case.
+     */
+    readonly status: string;
+    readonly disabledReason: string | null;
+    /** ISO-8601 UTC, as the API sends it. */
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /**
+     * Present ONLY when this call minted one — a newly created endpoint, or one
+     * whose subscription revived it. Absent when an existing URL was updated,
+     * because an update deliberately leaves the running secret alone.
+     *
+     * When it is present, store it before doing anything else. Nothing can return
+     * it again and `rotateSecret` is the only way to get a working secret back.
+     */
+    readonly secret?: WebhookSecret;
+}
+/** The outcome of a rotation: the new secret, and when the old one dies. */
+export interface RotatedWebhookSecret {
+    readonly webhookEndpointId: string;
+    readonly secret: WebhookSecret;
+    /**
+     * The secret being retired, and the instant it stops being accepted — set it
+     * as `CROWDSOURCE_WEBHOOK_SECRET_PREVIOUS` until then and a rotation drops no
+     * delivery. `null` when the cutover was immediate, which is what a leaked
+     * secret needs.
+     */
+    readonly previousSecret: {
+        readonly version: number;
+        readonly expiresAt: string;
+    } | null;
+}
+export interface RegisterWebhookEndpointInput {
+    /** Where CrowdSource should POST. HTTPS in production. */
+    readonly url: string;
+    /**
+     * The event types to subscribe to. Import `WEBHOOK_EVENT_TYPES` from
+     * `@crowdsource.you/contracts` for the current set; unknown types are
+     * accepted so a newer contract does not need a new client.
+     */
+    readonly eventTypes: readonly string[];
+}
+export interface RotateSecretOptions {
+    /**
+     * How long the outgoing secret keeps being accepted. `0` is an immediate
+     * cutover — the right choice for a leaked secret and the wrong one for routine
+     * hygiene, because in-flight deliveries signed with the old secret are refused.
+     * Omitted, the server applies its own default overlap.
+     */
+    readonly overlapSeconds?: number;
+    /**
+     * Appendix D. Defaults to a key derived from the endpoint id, which makes a
+     * RETRY of one rotation safe. Two deliberate rotations are two different
+     * operations, so pass a distinct key for the second one.
+     */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface WebhookEndpointRequestOptions {
+    /** Appendix D. Defaults to a key derived from the URL being registered. */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * §10.2's two webhook-management routes.
+ *
+ * There is no list, no read-back and no delete, because the API serves none —
+ * §10.2 defines exactly two routes. An integrator therefore cannot enumerate
+ * what it has registered, which is a real gap in the service rather than
+ * something this client can paper over; re-registering a URL is the documented
+ * way to change a subscription or revive a disabled endpoint.
+ *
+ * Both routes need a credential with the `crowdsource:webhooks:manage` scope,
+ * and both derive the application from that credential. There is no
+ * `applicationId` in any request or response here.
+ */
+export declare class WebhookEndpoints {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Registers, or updates, the endpoint CrowdSource delivers to.
+     *
+     * Safe to call on every deploy: an existing URL is updated and no new secret
+     * is minted, so the secret the running process verifies with keeps working.
+     */
+    register(input: RegisterWebhookEndpointInput, options?: WebhookEndpointRequestOptions): Promise<WebhookEndpoint>;
+    /**
+     * Mints a new signing secret, retiring the current one after an overlap.
+     *
+     * The only way to recover from a secret that was never stored, and the correct
+     * response to one that leaked.
+     */
+    rotateSecret(webhookEndpointId: string, options?: RotateSecretOptions): Promise<RotatedWebhookSecret>;
+}
+//# sourceMappingURL=webhookEndpoints.d.ts.map

package/dist/webhookEndpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookEndpoints.d.ts","sourceRoot":"","sources":["../src/webhookEndpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAmBD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,6BAA6B;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AA2BD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,SAAS,EAAE,SAAS;IAIhC;;;;;OAKG;IACG,QAAQ,CACZ,KAAK,EAAE,4BAA4B,EACnC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,eAAe,CAAC;IAyB3B;;;;;OAKG;IACG,YAAY,CAChB,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,oBAAoB,CAAC;CA0BjC"}

package/dist/webhookEndpoints.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Telling CrowdSource where to deliver decisions, and holding the secret it
+ * mints once.
+ *
+ * This is the half of the webhook integration that used to have no client at
+ * all: `@crowdsource.you/core/express` verifies deliveries against
+ * `CROWDSOURCE_WEBHOOK_SECRET`, and there was no supported way to obtain that
+ * value except hand-rolling an HTTP call with the bearer half of the service
+ * key. "Near-zero configuration" cannot mean an integrator writes their own
+ * fetch for a mandatory step, so §10.2's two management routes are here.
+ *
+ * Two properties of the secret shape everything below, and both are the server's
+ * design rather than this client's choice:
+ *
+ *   * **It is returned once and never again.** A webhook secret is decryptable
+ *     by CrowdSource because deliveries have to be signed with it, but re-serving
+ *     it would turn any credential holding `webhooks:manage` into a way to read
+ *     the signing key of an endpoint somebody else configured. So `secret` on a
+ *     registration is the only time that value exists outside the service.
+ *   * **Re-registering an existing URL mints nothing.** That is what makes a
+ *     deploy script safe to run on every boot — it will not invalidate the
+ *     secret the running process is verifying with. The corollary is that
+ *     re-registering cannot RECOVER a secret you failed to store; that is what
+ *     `rotateSecret` is for.
+ *
+ * Which is why `secret` is optional on the result. Its presence is not a detail:
+ * it means a value has just come into existence that nothing can produce again,
+ * and the integration is responsible for persisting it before the process exits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEndpoints = void 0;
+const zod_1 = require("zod");
+const digest_js_1 = require("./digest.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Appendix D's key for a registration.
+ *
+ * Derived from the URL because the URL is the endpoint's identity as far as the
+ * server is concerned — the same URL registered twice is one logical operation,
+ * which is exactly what makes a deploy-time `register` safe to retry. Hashed
+ * rather than interpolated because a URL carries `:` and `/`, and a composite
+ * value with separators in it is how an id grammar gets ambiguous.
+ *
+ * Note that the two webhook routes do NOT currently read `Idempotency-Key`
+ * server-side; only `POST /v1/reports` does. This satisfies the transport's
+ * Appendix D requirement and is inert at the service until that changes.
+ */
+function registrationIdempotencyKey(url) {
+    return `webhook-endpoint.${(0, digest_js_1.sha256Digest)(url).replace('sha256:', '')}`;
+}
+const WebhookSecretSchema = zod_1.z.looseObject({
+    version: zod_1.z.number(),
+    value: zod_1.z.string(),
+    signingStartsAt: zod_1.z.string(),
+});
+const WebhookEndpointSchema = zod_1.z.looseObject({
+    webhookEndpointId: zod_1.z.string(),
+    url: zod_1.z.string(),
+    eventTypes: zod_1.z.array(zod_1.z.string()),
+    status: zod_1.z.string(),
+    disabledReason: zod_1.z.string().nullish(),
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+    secret: WebhookSecretSchema.optional(),
+});
+const RotatedWebhookSecretSchema = zod_1.z.looseObject({
+    webhookEndpointId: zod_1.z.string(),
+    secret: WebhookSecretSchema,
+    previousSecret: zod_1.z
+        .looseObject({ version: zod_1.z.number(), expiresAt: zod_1.z.string() })
+        .nullish(),
+});
+/**
+ * §10.2's two webhook-management routes.
+ *
+ * There is no list, no read-back and no delete, because the API serves none —
+ * §10.2 defines exactly two routes. An integrator therefore cannot enumerate
+ * what it has registered, which is a real gap in the service rather than
+ * something this client can paper over; re-registering a URL is the documented
+ * way to change a subscription or revive a disabled endpoint.
+ *
+ * Both routes need a credential with the `crowdsource:webhooks:manage` scope,
+ * and both derive the application from that credential. There is no
+ * `applicationId` in any request or response here.
+ */
+class WebhookEndpoints {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Registers, or updates, the endpoint CrowdSource delivers to.
+     *
+     * Safe to call on every deploy: an existing URL is updated and no new secret
+     * is minted, so the secret the running process verifies with keeps working.
+     */
+    async register(input, options = {}) {
+        const response = await this.transport.request({
+            method: 'POST',
+            path: '/v1/webhook-endpoints',
+            body: { url: input.url, eventTypes: [...input.eventTypes] },
+            idempotencyKey: options.idempotencyKey ?? registrationIdempotencyKey(input.url),
+            signal: options.signal,
+        });
+        const parsed = WebhookEndpointSchema.safeParse(response);
+        if (!parsed.success) {
+            throw new errors_js_1.CrowdSourceTransportError('CrowdSource registered the webhook endpoint but answered with a body this client does not recognise.', { retryable: false, cause: parsed.error });
+        }
+        const { disabledReason, secret, ...rest } = parsed.data;
+        return {
+            ...rest,
+            disabledReason: disabledReason ?? null,
+            ...(secret === undefined ? {} : { secret }),
+        };
+    }
+    /**
+     * Mints a new signing secret, retiring the current one after an overlap.
+     *
+     * The only way to recover from a secret that was never stored, and the correct
+     * response to one that leaked.
+     */
+    async rotateSecret(webhookEndpointId, options = {}) {
+        const response = await this.transport.request({
+            method: 'POST',
+            path: `/v1/webhook-endpoints/${encodeURIComponent(webhookEndpointId)}/rotate-secret`,
+            body: options.overlapSeconds === undefined ? {} : { overlapSeconds: options.overlapSeconds },
+            idempotencyKey: options.idempotencyKey ??
+                `webhook-endpoint.${(0, digest_js_1.sha256Digest)(webhookEndpointId).replace('sha256:', '')}.rotate`,
+            signal: options.signal,
+        });
+        const parsed = RotatedWebhookSecretSchema.safeParse(response);
+        if (!parsed.success) {
+            throw new errors_js_1.CrowdSourceTransportError('CrowdSource rotated the webhook secret but answered with a body this client does not recognise.', { retryable: false, cause: parsed.error });
+        }
+        return {
+            webhookEndpointId: parsed.data.webhookEndpointId,
+            secret: parsed.data.secret,
+            previousSecret: parsed.data.previousSecret ?? null,
+        };
+    }
+}
+exports.WebhookEndpoints = WebhookEndpoints;
+//# sourceMappingURL=webhookEndpoints.js.map