The best way to control Claude Code, Codex and more from any computer or phone

main
ts 151 lines 6.1 KB
Raw
1 import { sanitizeKey, type RuntimeContext } from "alchemy/RuntimeContext";
2 import * as Context from "effect/Context";
3 import type * as Effect from "effect/Effect";
4 import type * as Redacted from "effect/Redacted";
5 import type { CustomAlert } from "./CustomAlert.ts";
6 import type { AlertType, NotificationPolicy } from "./NotificationPolicy.ts";
7
8 /**
9 * Whether a notification opens or closes an incident. Alert types without
10 * incidents leave it unset.
11 */
12 export type NotificationAlertEvent =
13 | "ALERT_STATE_EVENT_START"
14 | "ALERT_STATE_EVENT_END"
15 // Keep the union open so new Cloudflare states aren't blocked by stale types.
16 | (string & {});
17
18 /**
19 * One notification Cloudflare dispatched for a policy: the generic webhook
20 * envelope, with the alert-specific payload in `data`.
21 *
22 * @see {@link https://developers.cloudflare.com/notifications/reference/webhook-payload-schema/ | Webhook payload schema}
23 */
24 export interface Notification<Data = Record<string, unknown>> {
25 /** Name of the webhook destination that received the notification. */
26 readonly name: string;
27 /** Human-readable summary of the alert. */
28 readonly text: string;
29 /** Alert-specific payload. Its shape depends on `alertType`. */
30 readonly data: Data;
31 /** When Cloudflare generated the notification, in Unix seconds (UTC). */
32 readonly ts: number;
33 /** Account the alert fired in. Not sent by every alert type. */
34 readonly accountId: string | undefined;
35 /** Id of the policy that fired. Not sent by every alert type. */
36 readonly policyId: string | undefined;
37 /** Name of the policy that fired. */
38 readonly policyName: string | undefined;
39 /** The alert type that fired, e.g. `workers_observability_real_time_issue`. */
40 readonly alertType: AlertType | undefined;
41 /** Ties together the notifications of one incident. */
42 readonly alertCorrelationId: string | undefined;
43 /** Whether this notification opens or closes an incident. */
44 readonly alertEvent: NotificationAlertEvent | undefined;
45 }
46
47 /** A policy whose notifications a runtime can consume. */
48 export type NotifyingPolicy = NotificationPolicy | CustomAlert;
49
50 export interface ConsumeNotificationsProps {
51 /**
52 * Secret Cloudflare sends in the `cf-webhook-auth` header of every
53 * notification. Requests without it are rejected. When omitted, a random
54 * secret is generated at deploy and bound onto the host.
55 */
56 secret?: Redacted.Redacted<string>;
57 /**
58 * Path on the host that Cloudflare delivers to. Defaults to a deterministic
59 * per-policy path, so deliveries don't collide with your application
60 * routes.
61 */
62 path?: string;
63 }
64
65 /**
66 * Run an Effect for every notification a policy fires.
67 *
68 * Call it in the Construction phase of any runtime that receives HTTP (a
69 * `WebhookHost`, such as a Cloudflare Worker). Cloudflare then delivers the
70 * policy's notifications to that runtime: the event source creates a webhook
71 * destination at the runtime's URL and adds it to the policy, so the policy
72 * needs no `mechanisms` of its own.
73 *
74 * **Example:** Open a GitHub issue for each new Worker issue
75 * ```typescript
76 * const policy = yield* Cloudflare.Alerting.NotificationPolicy("IssuePolicy", {
77 * alertType: "workers_observability_real_time_issue",
78 * });
79 *
80 * // `text` is Cloudflare's report: a summary line, then details and links.
81 * const createIssue = yield* GitHub.CreateIssue(yield* Repo);
82 * yield* Cloudflare.Alerting.consumeNotifications(policy, (notification) =>
83 * createIssue({
84 * title: notification.text.split("\n")[0],
85 * body: notification.text,
86 * }),
87 * );
88 * ```
89 *
90 * **Example:** Page on a SQL custom alert, with your own secret
91 * ```typescript
92 * const errors = yield* ErrorSpike; // a Cloudflare.Alerting.CustomAlert
93 *
94 * yield* Cloudflare.Alerting.consumeNotifications(
95 * errors,
96 * { secret: yield* Config.Redacted("ALERT_WEBHOOK_SECRET") },
97 * (notification) =>
98 * notification.alertEvent === "ALERT_STATE_EVENT_END"
99 * ? pager.resolve(notification.alertCorrelationId)
100 * : pager.trigger(notification.alertCorrelationId, notification.text),
101 * );
102 * ```
103 *
104 * @binding
105 * @product Alerting
106 */
107 export function consumeNotifications<Req = never>(
108 policy: NotifyingPolicy,
109 process: (notification: Notification) => Effect.Effect<void, never, Req | RuntimeContext>,
110 ): Effect.Effect<void, never, NotificationEventSource>;
111 export function consumeNotifications<Req = never>(
112 policy: NotifyingPolicy,
113 props: ConsumeNotificationsProps,
114 process: (notification: Notification) => Effect.Effect<void, never, Req | RuntimeContext>,
115 ): Effect.Effect<void, never, NotificationEventSource>;
116 export function consumeNotifications(
117 policy: NotifyingPolicy,
118 propsOrProcess:
119 | ConsumeNotificationsProps
120 | ((notification: Notification) => Effect.Effect<void, never, any>),
121 maybeProcess?: (notification: Notification) => Effect.Effect<void, never, any>,
122 ): Effect.Effect<void, never, NotificationEventSource> {
123 const [props, process] =
124 typeof propsOrProcess === "function" ? [{}, propsOrProcess] : [propsOrProcess, maybeProcess!];
125 return NotificationEventSource.use((source) => source(policy, props, process));
126 }
127
128 export type NotificationEventSourceService = <Req = never>(
129 policy: NotifyingPolicy,
130 props: ConsumeNotificationsProps,
131 process: (notification: Notification) => Effect.Effect<void, never, Req>,
132 ) => Effect.Effect<void, never, never>;
133
134 export class NotificationEventSource extends Context.Service<
135 NotificationEventSource,
136 NotificationEventSourceService
137 >()("Cloudflare.Alerting.NotificationEventSource") {}
138
139 /**
140 * Delivery path of a policy's notifications. Shared by the deploy-time half
141 * (the webhook URL) and the runtime half (the claimed route).
142 */
143 export const notificationPath = (
144 policy: Pick<NotifyingPolicy, "LogicalId">,
145 props: Pick<ConsumeNotificationsProps, "path"> = {},
146 ): string =>
147 props.path ?? `/__alchemy/cloudflare/notifications/${encodeURIComponent(policy.LogicalId)}`;
148
149 /** Env var under which the host holds a policy's webhook secret. */
150 export const notificationSecretEnvName = (policy: Pick<NotifyingPolicy, "LogicalId">): string =>
151 `ALCHEMY_CLOUDFLARE_NOTIFICATION_SECRET_${sanitizeKey(policy.LogicalId)}`;