The best way to control Claude Code, Codex and more from any computer or phone
| 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)}`; |