Merge pull request #18 from mark-mdev/cap-deploy

feat(auth, story): enhance type safety and improve hooks

Author: markmdev

apps/backend/API.md

@@ -37,12 +37,16 @@ Provides endpoints for authentication, story generation, vocabulary management,
 
 ### Security
 
-- Uses HTTP-only, Secure JWT cookies (`accessToken`, `refreshToken`).
-- CORS restricted to frontend origin.
+- Uses HTTP-only JWT cookies (`accessToken`, `refreshToken`).
+  - `accessToken` TTL: 15 minutes
+  - `refreshToken` TTL: 7 days
+  - Cookies are `httpOnly`, `sameSite: lax`; `secure` is enabled in production
+- CORS: open by default in development; in production, configure allowed origins at the reverse proxy or app level.
 
 ### Rate Limiting
 
-- Default: 1000 requests per 15 minutes per authenticated user.
+- Global: 1000 requests per 15 minutes per client.
+- Story generation daily limit: 5 stories per user per calendar day (America/Los_Angeles); exceeding returns `429`.
 
 ---
 
@@ -58,6 +62,7 @@ Provides endpoints for authentication, story generation, vocabulary management,
 | 403  | Forbidden                      |
 | 404  | Not Found                      |
 | 429  | Too Many Requests              |
+| 503  | Service Unavailable            |
 | 502  | Database / Storage error       |
 | 500  | Internal Server Error          |
 
@@ -137,6 +142,16 @@ Provides endpoints for authentication, story generation, vocabulary management,
 }
 ```
 
+### 503 Service Unavailable (readiness)
+
+```json
+{
+  "status": "unhealthy",
+  "dbOk": false,
+  "redisOk": true
+}
+```
+
 ### 502 Database Error
 
 ```json
@@ -266,7 +281,7 @@ Create a new user and issue auth cookies.
 
 - Responses
 
-  - `201 Created`
+  - `200 OK`
 
     ```json
     {
@@ -409,6 +424,9 @@ Start asynchronous story generation.
 
   - Then poll: `GET /jobs/status/{jobId}` or fetch `GET /story` after completion
 
+  - Errors
+    - `429 Too Many Requests` when daily story limit is reached
+
   Example completed job:
 
   ```json
@@ -660,7 +678,7 @@ Add multiple vocabulary entries in a single request.
 
 - Responses
 
-  - `200 OK`
+  - `201 Created`
 
     ```json
     {
@@ -837,3 +855,80 @@ Get status of a background job.
   - `404 Not Found` if job is missing
 
 ---
+
+### Onboarding
+
+#### POST `/onboarding/complete`
+
+Mark onboarding as completed for the current user.
+
+- Authentication: Required
+- Request Body: none
+- Responses
+
+  - `200 OK`
+
+    ```json
+    { "success": true }
+    ```
+
+---
+
+#### GET `/onboarding/check`
+
+Get onboarding status for the current user.
+
+- Authentication: Required
+- Responses
+
+  - `200 OK`
+
+    ```json
+    { "success": true, "data": { "status": "completed" } }
+    ```
+
+    or
+
+    ```json
+    { "success": true, "data": { "status": "not_started" } }
+    ```
+
+---
+
+### Health
+
+#### GET `/healthz`
+
+Liveness probe.
+
+- Authentication: None
+- Responses
+
+  - `200 OK`
+
+    ```json
+    { "status": "ok" }
+    ```
+
+---
+
+#### GET `/readyz`
+
+Readiness probe (checks DB and Redis).
+
+- Authentication: None
+- Responses
+
+  - `200 OK` when healthy
+
+    ```json
+    { "status": "ok", "dbOk": true, "redisOk": true }
+    ```
+
+  - `503 Service Unavailable` when not ready
+
+    ```json
+    { "status": "unhealthy", "dbOk": false, "redisOk": false }
+    ```
+
+---

apps/frontend/src/features/auth/hooks/useAuthRedirect.ts

@@ -1,7 +1,8 @@
+import { ApiError } from "@/types/ApiError";
 import { useRouter } from "next/navigation";
 import { useEffect } from "react";
 
-export default function useAuthRedirect(error?: any) {
+export default function useAuthRedirect(error?: ApiError) {
   const router = useRouter();
   useEffect(() => {
     if (error?.statusCode === 401) {

apps/frontend/src/features/story/hooks/useStories.ts

@@ -1,8 +1,15 @@
 import { StoryApi } from "@/features/story/api";
 import { ClientApi } from "@/lib/ClientApi";
-import useSWR from "swr";
+import { ApiError } from "@/types/ApiError";
+import useSWR, { KeyedMutator } from "swr";
+import { Story } from "../types";
 
-export function useStories() {
+export function useStories(): {
+  stories: Story[] | undefined;
+  error: ApiError;
+  isLoading: boolean;
+  mutateStories: KeyedMutator<Story[]>;
+} {
   const clientApi = new ClientApi();
   const storyApi = new StoryApi(clientApi);
   const { data, error, isLoading, mutate } = useSWR("/api/story", () => storyApi.getAllStories());

apps/frontend/src/features/story/hooks/useWordStatus.ts

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { Story } from "@/features/story/types";
 import { UnknownWordApi } from "@/features/unknownWord/api";
 import { ClientApi } from "@/lib/ClientApi";
@@ -7,8 +7,8 @@ import { toast } from "react-toastify";
 import { KeyedMutator } from "swr";
 
 export function useWordStatus(chosenStory: Story | null, mutate: KeyedMutator<Story[]>) {
-  const clientApi = new ClientApi();
-  const unknownWordApi = new UnknownWordApi(clientApi);
+  const clientApi = useMemo(() => new ClientApi(), []);
+  const unknownWordApi = useMemo(() => new UnknownWordApi(clientApi), [clientApi]);
 
   const updateCurrentDataWithNewWordStatus = useCallback(
     (currentData: Story[] | undefined, wordId: number, newStatus: "learned" | "learning") => {

apps/landing/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:alpine
+WORKDIR "/app"
+COPY ./package*.json .
+RUN npm install
+COPY . .
+RUN npm run build
+CMD ["npm", "run", "start"]