docs: add missing OpenAPI annotations for signup/verify, billing/success, billing/webhook

dist/routes/billing.js

@@ -3,9 +3,7 @@ import rateLimit from "express-rate-limit";
 import Stripe from "stripe";
 import { createProKey, downgradeByCustomer, updateEmailByCustomer, findKeyByCustomerId } from "../services/keys.js";
 import logger from "../services/logger.js";
-function escapeHtml(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
+import { escapeHtml } from "../utils/html.js";
 let _stripe = null;
 function getStripe() {
     if (!_stripe) {
@@ -103,6 +101,36 @@ router.post("/checkout", checkoutLimiter, async (req, res) => {
         res.status(500).json({ error: "Failed to create checkout session" });
     }
 });
+/**
+ * @openapi
+ * /v1/billing/success:
+ *   get:
+ *     tags: [Billing]
+ *     summary: Checkout success page
+ *     description: |
+ *       Provisions a Pro API key after successful Stripe checkout and displays it in an HTML page.
+ *       Called by Stripe redirect after payment completion.
+ *     parameters:
+ *       - in: query
+ *         name: session_id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Stripe Checkout session ID
+ *     responses:
+ *       200:
+ *         description: HTML page displaying the new API key
+ *         content:
+ *           text/html:
+ *             schema:
+ *               type: string
+ *       400:
+ *         description: Missing session_id or no customer found
+ *       409:
+ *         description: Checkout session already used
+ *       500:
+ *         description: Failed to retrieve session
+ */
 // Success page — provision Pro API key after checkout
 router.get("/success", async (req, res) => {
     const sessionId = req.query.session_id;
@@ -161,17 +189,60 @@ a { color: #4f9; }
 <div class="card">
 <h1>🎉 Welcome to Pro!</h1>
 <p>Your API key:</p>
-<div class="key" style="position:relative" data-key="${escapeHtml(keyInfo.key)}">${escapeHtml(keyInfo.key)}<button onclick="navigator.clipboard.writeText(this.parentElement.dataset.key);this.textContent='Copied!';setTimeout(()=>this.textContent='Copy',1500)" style="position:absolute;top:8px;right:8px;background:#4f9;color:#0a0a0a;border:none;border-radius:4px;padding:4px 12px;cursor:pointer;font-size:0.8rem;font-family:system-ui">Copy</button></div>
+<div class="key" style="position:relative">${escapeHtml(keyInfo.key)}<button data-copy="${escapeHtml(keyInfo.key)}" style="position:absolute;top:8px;right:8px;background:#4f9;color:#0a0a0a;border:none;border-radius:4px;padding:4px 12px;cursor:pointer;font-size:0.8rem;font-family:system-ui">Copy</button></div>
 <p><strong>Save this key!</strong> It won't be shown again.</p>
 <p>5,000 PDFs/month • All endpoints • Priority support</p>
 <p><a href="/docs">View API docs →</a></p>
-</div></body></html>`);
+</div>
+<script src="/copy-helper.js"></script>
+</body></html>`);
     }
     catch (err) {
         logger.error({ err }, "Success page error");
         res.status(500).json({ error: "Failed to retrieve session" });
     }
 });
+/**
+ * @openapi
+ * /v1/billing/webhook:
+ *   post:
+ *     tags: [Billing]
+ *     summary: Stripe webhook endpoint
+ *     description: |
+ *       Receives Stripe webhook events for subscription lifecycle management.
+ *       Requires the raw request body and a valid Stripe-Signature header for verification.
+ *       Handles checkout.session.completed, customer.subscription.updated,
+ *       customer.subscription.deleted, and customer.updated events.
+ *     parameters:
+ *       - in: header
+ *         name: Stripe-Signature
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Stripe webhook signature for payload verification
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             description: Raw Stripe event payload
+ *     responses:
+ *       200:
+ *         description: Webhook received
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 received:
+ *                   type: boolean
+ *                   example: true
+ *       400:
+ *         description: Missing Stripe-Signature header or invalid signature
+ *       500:
+ *         description: Webhook secret not configured
+ */
 // Stripe webhook for subscription lifecycle events
 router.post("/webhook", async (req, res) => {
     const sig = req.headers["stripe-signature"];