fix(api): completedAt: null on non-complete states + OpenAPI timestamps & rate-limit headers (#29)

artifacts/api-server/src/routes/jobs.ts

@@ -309,6 +309,7 @@ router.get("/jobs/:id", async (req: Request, res: Response) => {
       jobId: job.id,
       state: job.state,
       createdAt: job.createdAt.toISOString(),
+      completedAt: job.state === "complete" ? job.updatedAt.toISOString() : null,
     };
 
     switch (job.state) {
@@ -356,7 +357,6 @@ router.get("/jobs/:id", async (req: Request, res: Response) => {
       case "complete":
         res.json({
           ...base,
-          completedAt: job.updatedAt.toISOString(),
           result: job.result ?? undefined,
           ...(job.actualCostUsd != null ? {
             costLedger: {

lib/api-spec/openapi.yaml

@@ -319,24 +319,68 @@ paths:
       responses:
         "200":
           description: Demo result
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+              description: Maximum requests allowed per window (always 5)
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+              description: Requests remaining in the current window
+            X-RateLimit-Reset:
+              schema:
+                type: integer
+              description: Unix epoch seconds when the rate limit window resets
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/DemoResponse"
         "400":
           description: Missing or invalid request param
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+            X-RateLimit-Reset:
+              schema:
+                type: integer
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
         "429":
           description: Rate limit exceeded
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+                description: Always 0 when rate limited
+            X-RateLimit-Reset:
+              schema:
+                type: integer
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
         "500":
           description: Server error
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+            X-RateLimit-Reset:
+              schema:
+                type: integer
           content:
             application/json:
               schema:
@@ -379,10 +423,15 @@ components:
       type: object
       required:
         - jobId
+        - createdAt
         - evalInvoice
       properties:
         jobId:
           type: string
+        createdAt:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of job creation
         evalInvoice:
           $ref: "#/components/schemas/InvoiceInfo"
     JobState:
@@ -451,11 +500,21 @@ components:
       required:
         - jobId
         - state
+        - createdAt
       properties:
         jobId:
           type: string
         state:
           $ref: "#/components/schemas/JobState"
+        createdAt:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of job creation (always present)
+        completedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: ISO 8601 timestamp of job completion; null when not yet complete
         evalInvoice:
           $ref: "#/components/schemas/InvoiceInfo"
         workInvoice: