OpenAPI 3.1 Extras: Webhooks, Callbacks, and Discriminators

# A representative API contract circa "we'll figure it out later":
#
# - "We POST to your /webhooks/billing endpoint when an invoice is paid.
#    Body shape? Check our PDF docs. Versioning? We promise we won't break it.
#    Auth? You'll see an X-Signature header. Algorithm? Email support."
#
# - "The booking event has 12 'type' values. Each type has a totally different
#    payload. TypeScript? Sorry, it's all 'data: Record<string, unknown>'."
#
# - "When you create the payment, give us a callback URL. We'll POST 'something'
#    back when it's done. Generated SDK? Nope. Contract test? Nope. Vibes? Yes."
#
# Three things every grown-up API has — webhooks, callbacks, and polymorphic
# payloads — and three things the average OpenAPI spec quietly skips.
# That's the gap this post fills.

// src/index.ts — top-level webhooks describe events YOU send to consumers.
// They never become a route on your server. They show up in the OpenAPI
// document and, more importantly, in every generated client SDK.
import { App, generateOpenAPI } from "@daloyjs/core";
import { z } from "zod";

const app = new App({
  openapi: {
    info: { title: "Bookstore API", version: "1.0.0" },
    webhooks: {
      // The webhook name is what every client SDK exposes.
      "invoice.paid": {
        method: "POST",
        operationId: "invoicePaidWebhook",
        summary: "Sent when an invoice transitions to PAID.",
        tags: ["Webhooks", "Billing"],
        request: {
          headers: z.object({
            "x-signature": z.string().describe("HMAC-SHA256 of body, hex"),
            "x-event-id": z.string().uuid(),
          }),
          body: z.object({
            type: z.literal("invoice.paid"),
            data: z.object({
              invoiceId: z.string().uuid(),
              amountCents: z.number().int().positive(),
              currency: z.enum(["EUR", "NOK", "USD"]),
              paidAt: z.string().datetime(),
            }),
          }),
        },
        responses: {
          200: {
            description: "Consumer acknowledged the event.",
            body: z.object({ received: z.literal(true) }),
          },
          410: {
            description: "Consumer endpoint no longer exists — we stop retrying.",
          },
        },
      },
    },
  },
});

// On the CONSUMER's side, the generated SDK contains a typed adapter:
//
//   import { handleInvoicePaidWebhook } from "@yourapi/client";
//
//   export async function POST(req: Request) {
//     const { signature, event, error } = await handleInvoicePaidWebhook(req, {
//       secret: process.env.INVOICE_WEBHOOK_SECRET!,
//     });
//     if (error) return error.toResponse();         // ← typed problem+json
//     // event is fully typed: event.data.amountCents is `number`, not `unknown`.
//     await db.invoices.update(event.data.invoiceId, { status: "paid" });
//     return new Response(JSON.stringify({ received: true }));
//   }
//
// The webhook section appears in /openapi.json under the top-level
// "webhooks" key (OpenAPI 3.1 feature; not available in 3.0). Scalar
// renders it in your /docs UI alongside paths and components.

// src/routes/payments.ts — callbacks describe out-of-band requests YOUR
// API will make back to the consumer. The canonical example: create a
// payment, get notified later when it settles.
import { z } from "zod";
import type { CallbackMap } from "@daloyjs/core";

const PaymentCreate = z.object({
  amountCents: z.number().int().positive(),
  currency: z.enum(["EUR", "NOK", "USD"]),
  callbackUrl: z.string().url(),   // ← the URL we'll POST to later
});

const paymentCallbacks: CallbackMap = {
  // Callback name — appears in the generated client SDK.
  paymentSettled: {
    // Runtime expression — the spec value. Tells consumers WHERE we'll POST.
    "{$request.body#/callbackUrl}": {
      method: "POST",
      operationId: "paymentSettledCallback",
      summary: "We POST this when the payment leaves PENDING.",
      request: {
        headers: z.object({
          "x-signature": z.string(),
        }),
        body: z.object({
          paymentId: z.string().uuid(),
          status: z.enum(["captured", "failed"]),
          failureReason: z.string().optional(),
        }),
      },
      responses: {
        200: { description: "Consumer acknowledged." },
        4: { description: "We retry 4xx up to 5 times with backoff." },
      },
    },
  },
};

app.route({
  method: "POST",
  path: "/payments",
  operationId: "createPayment",
  request: { body: PaymentCreate },
  responses: {
    202: {
      description: "Accepted — payment is pending. Watch for the callback.",
      body: z.object({ paymentId: z.string().uuid() }),
    },
  },
  callbacks: paymentCallbacks,     // ← attaches to THIS operation only
  handler: createPaymentHandler,
});

// Why bother spelling this out in the spec?
//
// 1. The runtime expression "{$request.body#/callbackUrl}" tells the spec
//    consumer EXACTLY which field of the request body becomes the URL.
//    Generated clients can build mock servers around it. Postman renders it.
//
// 2. The request/response bodies attached to the callback are validated
//    types in the generated SDK. The consumer's endpoint receives
//    "PaymentSettledCallbackBody" — never "unknown" — and gets to use the
//    framework's response helpers for the 200 ack.
//
// 3. Contract tests on the consumer side can pin the EXACT shape they'll
//    accept: `expectContract<PaymentSettledCallbackBody>(req.body)`. If you
//    bump the API minor version and forget to update the callback, CI fails.
//
// 4. Documentation. Your Scalar UI shows the callback as a sub-operation of
//    POST /payments, with its own example payload and response. Onboarding
//    docs basically write themselves.

// src/schemas/animal.ts — the bare discriminator() helper.
// Use when you already have a hand-rolled JSON schema and want to attach
// the OpenAPI discriminator object cleanly:
import { discriminator } from "@daloyjs/core";

export const Animal = {
  oneOf: [
    { $ref: "#/components/schemas/Cat" },
    { $ref: "#/components/schemas/Dog" },
    { $ref: "#/components/schemas/Owl" },
  ],
  discriminator: discriminator("kind", {
    cat: "#/components/schemas/Cat",
    dog: "#/components/schemas/Dog",
    owl: "#/components/schemas/Owl",
  }),
};

// src/schemas/booking-event.ts — the everyday case: runtime validator +
// OpenAPI emitter in one. Drop-in for any route's request or response body.
import { z } from "zod";
import { discriminatedUnion } from "@daloyjs/core";

const BookingCreated = z.object({
  type: z.literal("booking.created"),
  bookingId: z.string().uuid(),
  customerId: z.string().uuid(),
  totalCents: z.number().int().positive(),
});

const BookingCancelled = z.object({
  type: z.literal("booking.cancelled"),
  bookingId: z.string().uuid(),
  reason: z.enum(["user_requested", "payment_failed", "fraud"]),
  refundCents: z.number().int().nonnegative(),
});

const BookingShipped = z.object({
  type: z.literal("booking.shipped"),
  bookingId: z.string().uuid(),
  carrier: z.enum(["posten", "bring", "dhl"]),
  trackingNumber: z.string(),
});

// One union. Three variants. Runtime validation + JSON Schema in one call:
export const BookingEvent = discriminatedUnion("type", {
  "booking.created":   BookingCreated,
  "booking.cancelled": BookingCancelled,
  "booking.shipped":   BookingShipped,
});

// Use it like any other schema:
app.route({
  method: "POST",
  path: "/events/booking",
  operationId: "ingestBookingEvent",
  request: { body: BookingEvent },
  responses: { 202: { description: "Accepted" } },
  handler: async ({ body }) => {
    // `body` is a discriminated union. TypeScript narrows on `body.type`.
    switch (body.type) {
      case "booking.created":   return create(body);    // ← totalCents is in scope
      case "booking.cancelled": return cancel(body);    // ← refundCents in scope
      case "booking.shipped":   return ship(body);      // ← trackingNumber in scope
    }
  },
});

// What `BookingEvent` emits into your OpenAPI spec — the part the generated
// client SDK reads to produce a real TypeScript tagged union:
{
  "oneOf": [
    { "$ref": "#/components/schemas/BookingCreated" },
    { "$ref": "#/components/schemas/BookingCancelled" },
    { "$ref": "#/components/schemas/BookingShipped" }
  ],
  "discriminator": {
    "propertyName": "type",
    "mapping": {
      "booking.created":   "#/components/schemas/BookingCreated",
      "booking.cancelled": "#/components/schemas/BookingCancelled",
      "booking.shipped":   "#/components/schemas/BookingShipped"
    }
  }
}

// generated/client/types.gen.ts (output, not hand-written)
export type BookingEvent =
  | { type: "booking.created";   bookingId: string; customerId: string; totalCents: number }
  | { type: "booking.cancelled"; bookingId: string; reason: "user_requested" | "payment_failed" | "fraud"; refundCents: number }
  | { type: "booking.shipped";   bookingId: string; carrier: "posten" | "bring" | "dhl"; trackingNumber: string };

// apps/web/components/event-feed.tsx — react consumer.
function EventRow({ event }: { event: BookingEvent }) {
  switch (event.type) {
    case "booking.created":
      // event is narrowed: totalCents exists, refundCents does NOT.
      return <span>New booking {event.bookingId} · {event.totalCents / 100} EUR</span>;
    case "booking.cancelled":
      return <span>Cancelled {event.bookingId} · refund {event.refundCents / 100} EUR ({event.reason})</span>;
    case "booking.shipped":
      return <span>Shipped {event.bookingId} via {event.carrier} · {event.trackingNumber}</span>;
  }
}
// Add a new variant in the SERVER schema, run `pnpm gen` on the CLIENT side,
// and the TypeScript compiler instantly flags every `switch` that doesn't
// handle it. That's the entire point.

// The pattern: ONE webhook entry whose body is a discriminated union over
// every event type. The generated client gets one typed handler with
// exhaustive switch coverage instead of N near-identical webhook adapters.
const app = new App({
  openapi: {
    info: { title: "Bookstore API", version: "1.0.0" },
    webhooks: {
      "booking.event": {
        method: "POST",
        operationId: "bookingEventWebhook",
        summary: "Fires for every booking lifecycle transition.",
        request: {
          headers: z.object({ "x-signature": z.string() }),
          body: BookingEvent,                 // ← the discriminatedUnion above
        },
        responses: {
          200: { description: "Acknowledged" },
        },
      },
    },
  },
});

// Consumer (Next.js route handler):
export async function POST(req: Request) {
  const { event, error } = await handleBookingEventWebhook(req, {
    secret: process.env.BOOKING_WEBHOOK_SECRET!,
  });
  if (error) return error.toResponse();
  switch (event.type) {                       // ← exhaustive, type-checked
    case "booking.created":   return ingestCreated(event);
    case "booking.cancelled": return ingestCancelled(event);
    case "booking.shipped":   return ingestShipped(event);
  }
}

# The end-to-end loop you actually run:
pnpm gen:openapi            # dumps your spec to generated/openapi.json
pnpm gen                    # Hey API codegen → generated/client/

# What ends up on disk:
generated/
├─ openapi.json             # the OpenAPI 3.1 doc (with paths, webhooks, components)
└─ client/
   ├─ types.gen.ts          # tagged unions for every discriminatedUnion()
   ├─ sdk.gen.ts            # typed functions for routes + webhooks + callbacks
   └─ client.gen.ts         # the fetch wrapper

# CI gate: spec drift = test failure.
pnpm gen:openapi
git diff --exit-code generated/openapi.json
# ─→ exits 1 if the committed spec doesn't match the live route registry.

# When to reach for which feature.

webhooks (top-level)      ↳ Events YOU emit to consumers. They never become
                            a route on your server. Always pair with
                            x-signature headers and a discriminated union
                            body if you have more than one event type.

callbacks (route-level)   ↳ Out-of-band requests YOUR API will make back to
                            the consumer that triggered an operation.
                            Canonical: payments, long-running jobs, OAuth.
                            The runtime expression points at the request
                            field that supplied the URL.

discriminator()           ↳ Bare OpenAPI 3.1 spec builder. Use when you
                            already have hand-rolled JSON schemas and just
                            want the discriminator block.

discriminatedUnion()      ↳ Runtime validator + OpenAPI emitter, in one.
                            Default choice for polymorphic request/response
                            bodies. Produces exhaustive TypeScript tagged
                            unions on the client side.