sailfork / t3code-github / .repos/ alchemy-effect/ packages/ github/ src/ Webhook.ts

import * as Repos from "@distilled.cloud/github/repos";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
import type * as GitHub from "./Providers.ts";
import type { WebhookEventName } from "./RepositoryEventSource.ts";

export interface WebhookProps {
  /**
   * Repository owner (user or organization).
   */
  owner: string;

  /**
   * Repository name.
   */
  repository: string;

  /**
   * The URL that GitHub will `POST` events to. Accepts an `Output<string>`
   * (e.g. a Cloudflare Worker's `url`) so the webhook can target a
   * resource provisioned in the same stack.
   */
  url: Input<string>;

  /**
   * GitHub event names to subscribe to (e.g. `["push", "pull_request"]`).
   * Use `["*"]` to receive every event GitHub emits.
   * @default ["push"]
   */
  events?: WebhookEventName[];

  /**
   * Secret used to sign each delivery with `HMAC-SHA256`. The signature is
   * sent in the `X-Hub-Signature-256` header so the receiver can verify the
   * payload originated from GitHub. Wrap with `Redacted.make` to keep it out
   * of logs and state.
   */
  secret?: Redacted.Redacted<string>;

  /**
   * Payload media type.
   * @default "json"
   */
  contentType?: "json" | "form";

  /**
   * Whether deliveries are active.
   * @default true
   */
  active?: boolean;

  /**
   * Skip TLS verification of the delivery URL (`insecure_ssl`). Only use for
   * local/testing endpoints.
   * @default false
   */
  insecureSsl?: boolean;

  /**
   * Override the GitHub host or API base URL for this resource only (e.g.
   * `github.example.com` for GitHub Enterprise). Falls back to
   * `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
   * provider. Changing it replaces the resource — the same name on a
   * different GitHub instance is a different physical resource.
   */
  baseUrl?: string;
}

export interface Webhook extends Resource<
  "GitHub.Webhook",
  WebhookProps,
  {
    /**
     * Numeric ID of the webhook in GitHub.
     */
    webhookId: number;

    /**
     * The configured delivery URL.
     */
    url: string;

    /**
     * URL used by GitHub to send a `ping` event.
     */
    pingUrl: string | undefined;

    /**
     * URL used by GitHub to re-deliver the last event.
     */
    testUrl: string | undefined;

    /**
     * ISO-8601 timestamp of the last update.
     */
    updatedAt: string;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub repository webhook.
 *
 * `Webhook` manages the lifecycle of a repository webhook that `POST`s
 * events to a delivery URL. It is created on the first deploy and updated
 * in place on subsequent deploys, and is deleted when the resource is
 * destroyed.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied
 * by `GitHub.providers()` (env, stored PAT, or `gh` CLI). The token needs
 * `repo` scope (admin access to the repository) to manage webhooks.
 *
 * Most users don't construct `Webhook` directly — prefer
 * {@link import("./RepositoryEventSource.ts").events | events(repository, handler)}
 * inside a Cloudflare Worker, which provisions the webhook, wires the
 * delivery URL to the Worker, and forwards verified events to your handler.
 * ### Creating a Webhook
 * **Example:** Forward push events to a URL
 * ```typescript
 * yield* GitHub.Webhook("ci-webhook", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   url: "https://example.com/github",
 *   events: ["push", "pull_request"],
 *   secret: Redacted.make(process.env.WEBHOOK_SECRET!),
 * });
 * ```
 *
 * **Example:** Point a webhook at a Worker
 * ```typescript
 * const worker = yield* Cloudflare.Worker("Api", { ... });
 *
 * yield* GitHub.Webhook("repo-webhook", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   url: worker.url!,
 *   events: ["*"],
 * });
 * ```
 *
 * @resource
 * @product Webhook
 */
export const Webhook = Resource<Webhook>("GitHub.Webhook");

export const WebhookProvider = () =>
  Provider.succeed(Webhook, {
    stables: ["webhookId"],

    // A webhook belongs to (host, owner, repository) — its server-assigned
    // id is meaningless in any other repo, so moving it replaces the
    // resource: the engine creates the new webhook first, then `delete`
    // removes the old one from the old repo. Everything else (url, events,
    // secret, active) is mutated in place by `reconcile`. Replacement is
    // safe here — a webhook is declarative config that is fully
    // re-creatable from props.
    diff: Effect.fn(function* ({ news, olds }) {
      if (!isResolved(news)) return;
      if (olds === undefined) return;
      if (
        news.owner !== olds.owner ||
        news.repository !== olds.repository ||
        (yield* gitHubBaseUrlChanged(olds, news))
      ) {
        return { action: "replace" };
      }
    }),

    reconcile: Effect.fn(
      function* ({ news, output }) {
        const scope = { owner: news.owner, repo: news.repository };

        const config = {
          url: news.url as string,
          content_type: news.contentType ?? "json",
          // Sensitive on the wire: the SDK unwraps the Redacted when it sends.
          secret: news.secret,
          insecure_ssl: news.insecureSsl ? "1" : "0",
        };
        const events = news.events ?? ["push"];
        const active = news.active ?? true;

        // Observe — GitHub assigns the hook id server-side. Probe for live
        // state via the cached id; a 404 (deleted out-of-band, or never
        // created) collapses to "no observed webhook" so we converge by
        // creating a fresh one.
        const observed = output?.webhookId
          ? yield* Repos.getWebhook({ ...scope, hook_id: output.webhookId }).pipe(
              Effect.catchTag("NotFound", () => Effect.undefined),
            )
          : undefined;

        // Ensure — POST creates the webhook.
        if (observed === undefined) {
          return toAttrs(
            yield* Repos.createWebhook({ ...scope, name: "web", active, events, config }),
          );
        }

        // Sync — PATCH the existing webhook with the desired config. The
        // secret can never be read back, so we always send the full config
        // to converge rather than diffing.
        return toAttrs(
          yield* Repos.updateWebhook({ ...scope, hook_id: observed.id, active, events, config }),
        );
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    // GitHub has no global webhook list — hooks are repo-scoped. Enumerate every
    // repository the authenticated token can see, then list each repo's webhooks.
    list: Effect.fn(function* () {
      const repos = yield* Stream.runCollect(
        Repos.listForAuthenticatedUser.items({ per_page: 100 }),
      );
      const perRepo = yield* Effect.forEach(
        repos,
        (repo) =>
          Stream.runCollect(
            Repos.listWebhooks.items({
              owner: repo.owner.login,
              repo: repo.name,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((hooks) => hooks.map(toAttrs)),
            // Repos where the token lacks admin access reject the webhooks
            // endpoint with 403/404 — skip them per the per-item not-found
            // rule rather than failing the whole enumeration.
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(
      function* ({ olds, output }) {
        yield* Repos.deleteWebhook({
          owner: olds.owner,
          repo: olds.repository,
          hook_id: output.webhookId,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });

const toAttrs = (data: {
  id: number;
  config?: { url?: string } | null;
  ping_url?: string | null;
  test_url?: string | null;
  updated_at?: string | null;
}): Webhook["Attributes"] => ({
  webhookId: data.id,
  url: data.config?.url ?? "",
  pingUrl: data.ping_url ?? undefined,
  testUrl: data.test_url ?? undefined,
  updatedAt: data.updated_at ?? new Date().toISOString(),
});