@marinoscar/platform-web 0.1.0-next.19 → 0.1.0-next.21

package/dist/webhooks/headless/format.d.ts

@@ -0,0 +1,84 @@
+import type { WebhookDeliveryStatus, WebhookEndpoint } from '@marinoscar/platform-contract/webhooks';
+/**
+ * The tone of a status chip, mapped by the UI onto its theme palette.
+ *
+ * @stability experimental
+ */
+export type WebhookStatusTone = 'success' | 'warning' | 'error' | 'info' | 'default';
+/**
+ * The words for each `disabledReason` the platform sets when it switches an
+ * endpoint off. A reason not listed here is shown as "Disabled".
+ *
+ * @stability experimental
+ */
+export declare const WEBHOOK_DISABLED_REASON_LABELS: Readonly<Record<string, string>>;
+/**
+ * An endpoint's status as the UI shows it.
+ *
+ * @stability experimental
+ */
+export interface WebhookEndpointStatus {
+    /** The chip text. */
+    label: string;
+    /** The chip tone. */
+    tone: WebhookStatusTone;
+    /** A sentence on what to do, when the platform disabled the endpoint. */
+    hint: string | null;
+}
+/**
+ * An endpoint's status in words: Active, Disabled (by its owner) or the reason
+ * the platform switched it off.
+ *
+ * @param endpoint - the endpoint's `enabled` and `disabledReason`.
+ * @returns the label, tone and hint.
+ *
+ * @stability experimental
+ */
+export declare function webhookEndpointStatus(endpoint: Pick<WebhookEndpoint, 'enabled' | 'disabledReason'>): WebhookEndpointStatus;
+/**
+ * A delivery's status in words: Queued, Delivering, Delivered, Retrying
+ * (`failed`: an attempt failed and another is scheduled) and Failed (`dead`).
+ *
+ * @param status - the delivery status.
+ * @returns the label.
+ *
+ * @stability experimental
+ */
+export declare function webhookDeliveryStatusLabel(status: WebhookDeliveryStatus): string;
+/**
+ * The chip tone of a delivery status.
+ *
+ * @param status - the delivery status.
+ * @returns the tone.
+ *
+ * @stability experimental
+ */
+export declare function webhookDeliveryStatusTone(status: WebhookDeliveryStatus): WebhookStatusTone;
+/**
+ * The host of an endpoint URL (what a list shows; never the path or query).
+ *
+ * @param url - the endpoint URL.
+ * @returns the host with its port, or the input when it does not parse.
+ *
+ * @stability experimental
+ */
+export declare function webhookUrlHost(url: string): string;
+/**
+ * Whether a URL uses `https:` (the UI warns otherwise; the API decides).
+ *
+ * @param url - the typed URL.
+ * @returns `true` for an https URL.
+ *
+ * @stability experimental
+ */
+export declare function isHttpsWebhookUrl(url: string): boolean;
+/**
+ * A duration in milliseconds as short text (`240 ms`, `1.2 s`).
+ *
+ * @param ms - the duration, or `null`.
+ * @returns the text, or an empty string for `null`.
+ *
+ * @stability experimental
+ */
+export declare function formatWebhookDuration(ms: number | null): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/webhooks/headless/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/webhooks/headless/format.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAErG;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAErF;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI1E,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,IAAI,EAAE,iBAAiB,CAAC;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,gBAAgB,CAAC,GAAG,qBAAqB,CAwB1H;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAahF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,qBAAqB,GAAG,iBAAiB,CAa1F;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI/D"}

package/dist/webhooks/headless/format.js

@@ -0,0 +1,142 @@
+// =============================================================================
+// Webhook presentation helpers (issue #1046): status in words, never a colour alone
+// =============================================================================
+/**
+ * The words for each `disabledReason` the platform sets when it switches an
+ * endpoint off. A reason not listed here is shown as "Disabled".
+ *
+ * @stability experimental
+ */
+export const WEBHOOK_DISABLED_REASON_LABELS = Object.freeze({
+    circuit_open: 'Paused after repeated failures',
+    owner_lost_access: 'Owner lost access',
+    gone: 'Endpoint gone',
+});
+/**
+ * An endpoint's status in words: Active, Disabled (by its owner) or the reason
+ * the platform switched it off.
+ *
+ * @param endpoint - the endpoint's `enabled` and `disabledReason`.
+ * @returns the label, tone and hint.
+ *
+ * @stability experimental
+ */
+export function webhookEndpointStatus(endpoint) {
+    if (endpoint.enabled)
+        return { label: 'Active', tone: 'success', hint: null };
+    switch (endpoint.disabledReason) {
+        case 'circuit_open':
+            return {
+                label: WEBHOOK_DISABLED_REASON_LABELS.circuit_open,
+                tone: 'warning',
+                hint: 'Deliveries kept failing, so they were paused. Fix the receiver, then enable the endpoint again.',
+            };
+        case 'owner_lost_access':
+            return {
+                label: WEBHOOK_DISABLED_REASON_LABELS.owner_lost_access,
+                tone: 'warning',
+                hint: 'The owner no longer holds the permission these events need. Enable it again once access is restored.',
+            };
+        case 'gone':
+            return {
+                label: WEBHOOK_DISABLED_REASON_LABELS.gone,
+                tone: 'error',
+                hint: 'The receiver answered 410 Gone. Point the endpoint at a new URL, then enable it again.',
+            };
+        default:
+            return { label: 'Disabled', tone: 'default', hint: null };
+    }
+}
+/**
+ * A delivery's status in words: Queued, Delivering, Delivered, Retrying
+ * (`failed`: an attempt failed and another is scheduled) and Failed (`dead`).
+ *
+ * @param status - the delivery status.
+ * @returns the label.
+ *
+ * @stability experimental
+ */
+export function webhookDeliveryStatusLabel(status) {
+    switch (status) {
+        case 'pending':
+            return 'Queued';
+        case 'delivering':
+            return 'Delivering';
+        case 'succeeded':
+            return 'Delivered';
+        case 'failed':
+            return 'Retrying';
+        case 'dead':
+            return 'Failed';
+    }
+}
+/**
+ * The chip tone of a delivery status.
+ *
+ * @param status - the delivery status.
+ * @returns the tone.
+ *
+ * @stability experimental
+ */
+export function webhookDeliveryStatusTone(status) {
+    switch (status) {
+        case 'succeeded':
+            return 'success';
+        case 'failed':
+            return 'warning';
+        case 'dead':
+            return 'error';
+        case 'delivering':
+            return 'info';
+        case 'pending':
+            return 'default';
+    }
+}
+/**
+ * The host of an endpoint URL (what a list shows; never the path or query).
+ *
+ * @param url - the endpoint URL.
+ * @returns the host with its port, or the input when it does not parse.
+ *
+ * @stability experimental
+ */
+export function webhookUrlHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Whether a URL uses `https:` (the UI warns otherwise; the API decides).
+ *
+ * @param url - the typed URL.
+ * @returns `true` for an https URL.
+ *
+ * @stability experimental
+ */
+export function isHttpsWebhookUrl(url) {
+    try {
+        return new URL(url).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A duration in milliseconds as short text (`240 ms`, `1.2 s`).
+ *
+ * @param ms - the duration, or `null`.
+ * @returns the text, or an empty string for `null`.
+ *
+ * @stability experimental
+ */
+export function formatWebhookDuration(ms) {
+    if (ms === null)
+        return '';
+    if (ms < 1000)
+        return `${ms} ms`;
+    return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)} s`;
+}
+//# sourceMappingURL=format.js.map

package/dist/webhooks/headless/format.js.map

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

package/dist/webhooks/headless/hooks.d.ts

@@ -0,0 +1,199 @@
+import type { CreateWebhookEndpointInput, RotateWebhookSecretResponse, UpdateWebhookEndpoint, WebhookDelivery, WebhookDeliveryDetail, WebhookEndpoint, WebhookEndpointCreated, WebhookEventCatalogEntry, WebhookScope, WebhookTestResponse } from '@marinoscar/platform-contract/webhooks';
+import { type WebhookDeliveriesQuery, type WebhooksApi } from './client.js';
+import { type WebhookEventGroup } from './event-selection.js';
+/**
+ * A webhook API failure in words: the stable error code's sentence, else the
+ * API's message, else `fallback`.
+ *
+ * @param error - what the call rejected with.
+ * @param fallback - the sentence when nothing better is known.
+ * @returns the message.
+ *
+ * @stability experimental
+ */
+export declare function webhookErrorMessage(error: unknown, fallback: string): string;
+/**
+ * The webhooks client of one scope over the host's transport, memoised.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the client.
+ *
+ * @stability experimental
+ */
+export declare function useWebhooksApi(scope: WebhookScope): WebhooksApi;
+/**
+ * What {@link useWebhookEndpoints} returns.
+ *
+ * @stability experimental
+ */
+export interface WebhookEndpointsState {
+    /** The endpoints, in the API's order. */
+    endpoints: WebhookEndpoint[];
+    /** Whether a load is in flight. */
+    isLoading: boolean;
+    /** A load failure, in words. */
+    error: string | null;
+    /** Reloads now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * The endpoints the caller may see at a scope (`GET <base>`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the endpoints and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookEndpoints(scope: WebhookScope): WebhookEndpointsState;
+/**
+ * What {@link useWebhookEndpoint} returns.
+ *
+ * @stability experimental
+ */
+export interface WebhookEndpointState {
+    /** The endpoint, once loaded. */
+    endpoint: WebhookEndpoint | null;
+    /** Whether a load is in flight. */
+    isLoading: boolean;
+    /** A load failure, in words. */
+    error: string | null;
+    /** Reloads now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * One endpoint (`GET <base>/:id`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param id - the endpoint id, or `null` for none.
+ * @returns the endpoint and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookEndpoint(scope: WebhookScope, id: string | null): WebhookEndpointState;
+/**
+ * What {@link useWebhookDeliveries} returns.
+ *
+ * @stability experimental
+ */
+export interface WebhookDeliveriesState {
+    /** The page of deliveries, newest first. */
+    deliveries: WebhookDelivery[];
+    /** Deliveries matching the filters, across every page. */
+    total: number;
+    /** Pages at the requested page size. */
+    totalPages: number;
+    /** Whether a load is in flight. */
+    isLoading: boolean;
+    /** A load failure, in words. */
+    error: string | null;
+    /** Reloads the current page now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * One page of an endpoint's deliveries
+ * (`GET <base>/:id/deliveries?page&pageSize&status&eventKey`), reloaded when
+ * the endpoint, the page or a filter changes.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param endpointId - the endpoint, or `null` for none.
+ * @param query - the one-based page, page size and filters.
+ * @returns the page and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookDeliveries(scope: WebhookScope, endpointId: string | null, query?: WebhookDeliveriesQuery): WebhookDeliveriesState;
+/**
+ * What {@link useWebhookDelivery} returns.
+ *
+ * @stability experimental
+ */
+export interface WebhookDeliveryState {
+    /** The delivery with its payload and request headers, once loaded. */
+    delivery: WebhookDeliveryDetail | null;
+    /** Whether a load is in flight. */
+    isLoading: boolean;
+    /** A load failure, in words. */
+    error: string | null;
+    /** Reloads now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * One delivery with its body and headers (`GET <base>/deliveries/:id`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param deliveryId - the delivery, or `null` for none.
+ * @returns the delivery and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookDelivery(scope: WebhookScope, deliveryId: string | null): WebhookDeliveryState;
+/**
+ * What {@link useWebhookEventCatalog} returns.
+ *
+ * @stability experimental
+ */
+export interface WebhookEventCatalogState {
+    /** The events the caller may subscribe to, in catalog order. */
+    entries: WebhookEventCatalogEntry[];
+    /** The same, grouped for the picker. */
+    groups: WebhookEventGroup[];
+    /** Whether the load is in flight. */
+    isLoading: boolean;
+    /** A load failure, in words. */
+    error: string | null;
+}
+/**
+ * The event catalog of a scope (`GET <base>/events`), already filtered by the
+ * API to what the caller may subscribe to.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param options - `enabled: false` skips the request (a read-only viewer never opens the picker).
+ * @returns the catalog and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookEventCatalog(scope: WebhookScope, options?: {
+    enabled?: boolean;
+}): WebhookEventCatalogState;
+/**
+ * What {@link useWebhookMutations} returns. Each action resolves with the
+ * API's answer, or `null` when it refused (see `error`).
+ *
+ * @stability experimental
+ */
+export interface WebhookMutations {
+    /** `POST <base>`: the endpoint and its secret, shown once. */
+    create: (input: CreateWebhookEndpointInput) => Promise<WebhookEndpointCreated | null>;
+    /** `PATCH <base>/:id`. */
+    update: (id: string, patch: UpdateWebhookEndpoint) => Promise<WebhookEndpoint | null>;
+    /** `DELETE <base>/:id`; resolves `true` on success. */
+    remove: (id: string) => Promise<boolean>;
+    /** `POST <base>/:id/rotate-secret`: the new secret, shown once. */
+    rotateSecret: (id: string) => Promise<RotateWebhookSecretResponse | null>;
+    /** `POST <base>/:id/test`: the queued ping delivery. */
+    sendTest: (id: string) => Promise<WebhookTestResponse | null>;
+    /** `POST <base>/deliveries/:id/redeliver`; resolves `true` on success. */
+    redeliver: (deliveryId: string) => Promise<boolean>;
+    /** Whether a write is in flight. */
+    pending: boolean;
+    /** The last refusal, in words. */
+    error: string | null;
+    /** Clears `error`. */
+    reset: () => void;
+}
+/**
+ * The webhook writes of one scope, with one shared pending flag and error.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the actions and their state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useWebhookMutations(scope: WebhookScope): WebhookMutations;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/webhooks/headless/hooks.d.ts.map

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

package/dist/webhooks/headless/hooks.js

@@ -0,0 +1,249 @@
+// =============================================================================
+// The webhooks hooks (issue #1046): reads with a load state, and the writes
+// =============================================================================
+//
+// Every hook takes the scope and talks to that scope's routes only. A failure
+// becomes a sentence in `error` (the API's message, or a stable code mapped to
+// words); a write resolves with `null` instead of throwing.
+// =============================================================================
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { WEBHOOK_ERROR_CODES } from '@marinoscar/platform-contract/webhooks';
+import { isPlatformApiError, usePlatformApi } from '../../core/index.js';
+import { createWebhooksApi } from './client.js';
+import { groupWebhookEventCatalog } from './event-selection.js';
+const CODE_MESSAGES = {
+    [WEBHOOK_ERROR_CODES.WEBHOOK_NOT_FOUND]: 'That webhook endpoint no longer exists.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_DELIVERY_NOT_FOUND]: 'That delivery no longer exists.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_URL_INVALID]: 'Enter a valid https:// URL.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_URL_FORBIDDEN]: 'That URL points at a private or internal address, which webhooks may not call.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_EVENT_UNKNOWN]: 'One of the selected events does not exist.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_EVENT_NOT_PERMITTED]: 'One of the selected events is not available to you.',
+    [WEBHOOK_ERROR_CODES.WEBHOOK_LIMIT_REACHED]: 'The maximum number of webhook endpoints has been reached.',
+};
+/**
+ * A webhook API failure in words: the stable error code's sentence, else the
+ * API's message, else `fallback`.
+ *
+ * @param error - what the call rejected with.
+ * @param fallback - the sentence when nothing better is known.
+ * @returns the message.
+ *
+ * @stability experimental
+ */
+export function webhookErrorMessage(error, fallback) {
+    if (isPlatformApiError(error)) {
+        if (typeof error.code === 'string' && CODE_MESSAGES[error.code])
+            return CODE_MESSAGES[error.code];
+        if (typeof error.message === 'string' && error.message !== '')
+            return error.message;
+    }
+    return fallback;
+}
+function useMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return useCallback(() => mounted.current, []);
+}
+/**
+ * Runs `load` now and on `refresh`, keeping only the newest answer.
+ */
+function useLoad(load, fallback) {
+    const mounted = useMounted();
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(load !== null);
+    const [error, setError] = useState(null);
+    const seq = useRef(0);
+    const refresh = useCallback(async () => {
+        if (!load)
+            return;
+        const ticket = ++seq.current;
+        setIsLoading(true);
+        try {
+            const next = await load();
+            if (!mounted() || ticket !== seq.current)
+                return;
+            setData(next);
+            setError(null);
+        }
+        catch (err) {
+            if (mounted() && ticket === seq.current)
+                setError(webhookErrorMessage(err, fallback));
+        }
+        finally {
+            if (mounted() && ticket === seq.current)
+                setIsLoading(false);
+        }
+    }, [load, fallback, mounted]);
+    useEffect(() => {
+        if (!load) {
+            seq.current += 1;
+            setData(null);
+            setIsLoading(false);
+            setError(null);
+            return;
+        }
+        void refresh();
+    }, [load, refresh]);
+    return { data, isLoading, error, refresh };
+}
+/**
+ * The webhooks client of one scope over the host's transport, memoised.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the client.
+ *
+ * @stability experimental
+ */
+export function useWebhooksApi(scope) {
+    const api = usePlatformApi();
+    return useMemo(() => createWebhooksApi(api, scope), [api, scope]);
+}
+/**
+ * The endpoints the caller may see at a scope (`GET <base>`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the endpoints and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookEndpoints(scope) {
+    const client = useWebhooksApi(scope);
+    const load = useCallback(() => client.list(), [client]);
+    const { data, isLoading, error, refresh } = useLoad(load, 'Could not load the webhook endpoints.');
+    return { endpoints: data?.items ?? [], isLoading, error, refresh };
+}
+/**
+ * One endpoint (`GET <base>/:id`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param id - the endpoint id, or `null` for none.
+ * @returns the endpoint and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookEndpoint(scope, id) {
+    const client = useWebhooksApi(scope);
+    const load = useMemo(() => (id ? () => client.get(id) : null), [client, id]);
+    const { data, isLoading, error, refresh } = useLoad(load, 'Could not load the webhook endpoint.');
+    return { endpoint: data, isLoading, error, refresh };
+}
+/**
+ * One page of an endpoint's deliveries
+ * (`GET <base>/:id/deliveries?page&pageSize&status&eventKey`), reloaded when
+ * the endpoint, the page or a filter changes.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param endpointId - the endpoint, or `null` for none.
+ * @param query - the one-based page, page size and filters.
+ * @returns the page and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookDeliveries(scope, endpointId, query = {}) {
+    const client = useWebhooksApi(scope);
+    const { page, pageSize, status, eventKey } = query;
+    const load = useMemo(() => endpointId
+        ? () => client.listDeliveries(endpointId, {
+            ...(page === undefined ? {} : { page }),
+            ...(pageSize === undefined ? {} : { pageSize }),
+            ...(status ? { status } : {}),
+            ...(eventKey ? { eventKey } : {}),
+        })
+        : null, [client, endpointId, page, pageSize, status, eventKey]);
+    const { data, isLoading, error, refresh } = useLoad(load, 'Could not load the deliveries.');
+    return {
+        deliveries: data?.items ?? [],
+        total: data?.total ?? 0,
+        totalPages: data?.totalPages ?? 0,
+        isLoading,
+        error,
+        refresh,
+    };
+}
+/**
+ * One delivery with its body and headers (`GET <base>/deliveries/:id`).
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param deliveryId - the delivery, or `null` for none.
+ * @returns the delivery and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookDelivery(scope, deliveryId) {
+    const client = useWebhooksApi(scope);
+    const load = useMemo(() => (deliveryId ? () => client.getDelivery(deliveryId) : null), [client, deliveryId]);
+    const { data, isLoading, error, refresh } = useLoad(load, 'Could not load the delivery.');
+    return { delivery: data, isLoading, error, refresh };
+}
+/**
+ * The event catalog of a scope (`GET <base>/events`), already filtered by the
+ * API to what the caller may subscribe to.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @param options - `enabled: false` skips the request (a read-only viewer never opens the picker).
+ * @returns the catalog and the load state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookEventCatalog(scope, options = {}) {
+    const enabled = options.enabled ?? true;
+    const client = useWebhooksApi(scope);
+    const load = useMemo(() => (enabled ? () => client.eventCatalog() : null), [client, enabled]);
+    const { data, isLoading, error } = useLoad(load, 'Could not load the available events.');
+    const entries = useMemo(() => data?.items ?? [], [data]);
+    const groups = useMemo(() => groupWebhookEventCatalog(entries), [entries]);
+    return { entries, groups, isLoading, error };
+}
+/**
+ * The webhook writes of one scope, with one shared pending flag and error.
+ *
+ * @param scope - `user`, `org` or `system`.
+ * @returns the actions and their state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useWebhookMutations(scope) {
+    const client = useWebhooksApi(scope);
+    const mounted = useMounted();
+    const [pendingCount, setPendingCount] = useState(0);
+    const [error, setError] = useState(null);
+    const run = useCallback(async (call, fallback) => {
+        setPendingCount((count) => count + 1);
+        setError(null);
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (mounted())
+                setError(webhookErrorMessage(err, fallback));
+            return null;
+        }
+        finally {
+            if (mounted())
+                setPendingCount((count) => count - 1);
+        }
+    }, [mounted]);
+    return {
+        create: useCallback((input) => run(() => client.create(input), 'The endpoint could not be created.'), [client, run]),
+        update: useCallback((id, patch) => run(() => client.update(id, patch), 'The endpoint could not be saved.'), [client, run]),
+        remove: useCallback(async (id) => (await run(async () => (await client.remove(id), true), 'The endpoint could not be deleted.')) === true, [client, run]),
+        rotateSecret: useCallback((id) => run(() => client.rotateSecret(id), 'The secret could not be rotated.'), [client, run]),
+        sendTest: useCallback((id) => run(() => client.sendTest(id), 'The test event could not be sent.'), [client, run]),
+        redeliver: useCallback(async (deliveryId) => (await run(async () => (await client.redeliver(deliveryId), true), 'The delivery could not be queued again.')) === true, [client, run]),
+        pending: pendingCount > 0,
+        error,
+        reset: useCallback(() => setError(null), []),
+    };
+}
+//# sourceMappingURL=hooks.js.map