@tristan2828/ui-foundation 3.30.1 → 4.1.0

package/openapi/foundation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: UI Foundation — the contract every app shares
-  version: "3.0.0"
+  version: "4.1.0"
   description: >
     The part of an app's API contract that the foundation package's own code
     calls: session-cookie auth under /auth/*, and the two error envelopes the
@@ -36,8 +36,43 @@ paths:
           content:
             application/json:
               schema: { $ref: "#/components/schemas/User" }
+        "202":
+          description: >
+            The password is right and the account has a second step. No
+            session yet: sets a short-lived, single-use pending_login cookie
+            for POST /auth/login/totp.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LoginNextStep" }
         "401": { $ref: "#/components/responses/UnauthorizedError" }
         "422": { $ref: "#/components/responses/ValidationError" }
+        "429": { $ref: "#/components/responses/RateLimitedError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /auth/login/totp:
+    x-optional: true
+    post:
+      operationId: loginTotp
+      summary: The second step of a sign-in, a code from an authenticator app or a recovery code
+      description: >
+        Needs the pending_login cookie a 202 from POST /auth/login set. A
+        right code starts the session as a 200 from /auth/login does.
+      tags: [auth]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/TotpLoginRequest" }
+      responses:
+        "200":
+          description: Authenticated. Sets the session_id cookie.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "410": { $ref: "#/components/responses/SignInExpiredError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "429": { $ref: "#/components/responses/RateLimitedError" }
         "500": { $ref: "#/components/responses/ServerError" }
 
   /auth/register:
@@ -101,6 +136,31 @@ paths:
               schema: { $ref: "#/components/schemas/DataEnvironment" }
         "500": { $ref: "#/components/responses/ServerError" }
 
+  /client-errors:
+    x-optional: true
+    post:
+      operationId: reportClientError
+      summary: A failure in the browser, for the backend to forward to error reporting
+      description: >
+        Sent by the package when an app turns on FoundationProviders'
+        errorReporting. Needs a session, so the public can't post into it.
+        The backend may drop a report (a duplicate, too many) and still
+        answer 204. The user is the session's; the report never carries
+        request or response bodies, cookies, headers, form values or
+        query strings.
+      tags: [errors]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ClientErrorReport" }
+      responses:
+        "204":
+          description: Received (forwarded, or dropped as a duplicate).
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
 components:
   schemas:
     DataEnvironment:
@@ -127,7 +187,26 @@ components:
       required: [email, password]
       properties:
         email: { type: string, format: email }
-        password: { type: string, minLength: 8 }
+        password: { type: string, minLength: 8, maxLength: 1024 }
+
+    LoginNextStep:
+      type: object
+      required: [next]
+      properties:
+        next:
+          type: string
+          enum: [totp]
+          description: The step the sign-in still needs.
+
+    TotpLoginRequest:
+      type: object
+      required: [code]
+      properties:
+        code:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: The 6-digit code from the authenticator app, or a recovery code.
 
     RegisterRequest:
       type: object
@@ -137,6 +216,25 @@ components:
         name: { $ref: "#/components/schemas/User/properties/name" }
         password: { $ref: "#/components/schemas/LoginRequest/properties/password" }
 
+    ClientErrorReport:
+      type: object
+      required: [source, type, message]
+      properties:
+        source:
+          type: string
+          enum: [route, window, unhandledrejection, query, mutation]
+          description: Where the package caught it.
+        type: { type: string, minLength: 1, maxLength: 200, description: "The error's type (TypeError, ServerError)." }
+        message: { type: string, maxLength: 2000 }
+        stack: { type: string, maxLength: 16000 }
+        route:
+          type: string
+          maxLength: 300
+          description: The route pattern (/items/:id), never the URL.
+        method: { type: string, maxLength: 10, description: The HTTP method of a failed request. }
+        status: { type: integer, minimum: 100, maximum: 599, description: The HTTP status of a failed request. }
+        release: { type: string, maxLength: 100, description: The frontend build (its commit). }
+
     ValidationErrorBody:
       type: object
       description: FastAPI's default 422 shape (RequestValidationError).
@@ -178,6 +276,20 @@ components:
       content:
         application/json:
           schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    RateLimitedError:
+      description: Too many failed attempts. Try again after Retry-After seconds.
+      headers:
+        Retry-After:
+          description: Seconds until another attempt is allowed.
+          schema: { type: integer, minimum: 1 }
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    SignInExpiredError:
+      description: The pending sign-in is missing, expired or out of tries. Start again with POST /auth/login.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
     ServerError:
       description: Unhandled server error.
       content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.30.1",
+  "version": "4.1.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {