Generate OpenAPI 3.1 document from the zod contracts (GET /api/v1/openapi.json)

apps/web/src/app/api/v1/openapi.json/route.ts

@@ -0,0 +1,10 @@
+import { buildOpenApiDocument } from "@pointup/core/contracts";
+import { NextResponse } from "next/server";
+
+/**
+ * Public OpenAPI 3.1 document for the v1 API, generated from the zod contracts.
+ * Lets third parties integrate (or generate clients) without the TS package.
+ */
+export function GET() {
+  return NextResponse.json(buildOpenApiDocument());
+}

docs/api.md

@@ -47,6 +47,10 @@ Every surface — web app, mobile, browser extension — talks to the same versi
 
 Unauthenticated liveness check used by the ALB. Returns `{ "status": "ok" }`.
 
+### `GET /api/v1/openapi.json`
+
+Public OpenAPI 3.1 document for this API, generated from the same zod contracts the server validates against (component schemas via `z.toJSONSchema`). Point Swagger UI or a client generator at it, or fetch via `client.getOpenApiDocument()`.
+
 ### `GET /api/v1/providers`
 
 The catalog of supported loyalty programs. Public — surfaces use it to render link forms before sign-in. `kind` is one of `airline`, `hotel`, `credit_card`, `rail`, or `shopping`, covering airlines, hotels, transferable credit card currencies (Chase Ultimate Rewards, Amex Membership Rewards, Capital One, Citi ThankYou, Bilt), rail (Amtrak Guest Rewards), and shopping portals (Rakuten).

packages/api-client/src/index.ts

@@ -81,6 +81,11 @@ export class PointUpClient {
     return this.request("GET", "/api/v1/providers");
   }
 
+  /** The OpenAPI 3.1 document describing this API (public). */
+  getOpenApiDocument(): Promise<Record<string, unknown>> {
+    return this.request("GET", "/api/v1/openapi.json");
+  }
+
   listLoyaltyAccounts(): Promise<LoyaltyAccountDto[]> {
     return this.request("GET", "/api/v1/loyalty-accounts");
   }

packages/core/src/contracts/index.ts

@@ -794,3 +794,6 @@ export function toIngestDealPageResultDto(
     markdownExcerpt: result.markdownExcerpt,
   };
 }
+
+// OpenAPI 3.1 document generated from the schemas above.
+export * from "./openapi";