Inline GDPR client server-side helper to _logger

Author: webstackdev

_TODO.md

@@ -18,6 +18,26 @@ dsarVerificationEmails.spec.ts can't run because RESEND_API_KEY isn't set. Provi
 
 5. componentDiscovery.spec.ts expects an error string but receives an object; ensure the helper throws an Error with the message the test asserts.
 
+## Typing client-side API calls and SSR API endpoints
+
+Shared Types vs Swagger / Keeping Docs in Sync
+
+1. Type-only sharing (current approach)
+
+- Pros: zero extra build tooling, server/client stay aligned as long as both import @pages/api/_contracts.
+- Cons: no generated docs/SDKs; discipline is required to keep manual docs current.
+- How to enforce: treat the contract files as the single source of truth, add lint rules banning request/response literal types outside _contracts, and add lightweight contract tests that instantiate each type against the endpoint handler (failing if fields diverge).
+
+2. Code-first OpenAPI (Zod or TS schemas → OpenAPI)
+
+- Define schemas in Zod/Valibot (or ts-rest) alongside the endpoint. Generate OpenAPI JSON plus TypeScript types from those schemas. Docs (Swagger UI/Redoc) and any client SDKs come from the generated spec, so they’re always in sync.
+- Guarantees: CI regenerates the spec and fails when the checked-in artifact is stale; endpoint handlers reuse the same schema for runtime validation, so a mismatch cannot compile.
+
+3. Spec-first OpenAPI + Swagger Codegen
+
+- Maintain an OpenAPI YAML/JSON file as the source of truth, run Swagger Codegen (or openapi-typescript) to produce both server stubs and client SDKs.
+- Guarantees: developers edit the spec, run codegen (enforced via a pre-commit/CI task), and the generated server stubs remind you to implement every path/verb. Documentation pages (Swagger UI) are rendered straight from the same spec, so they inherently match the implementation.
+
 ## Files with Skipped Tests
 
 social-shares.spec.ts - 12 @wip

src/lib/api/GDPR_CLIENT_USAGE.md

@@ -1,135 +1,74 @@
-# GDPR API Client Usage Guide
+# GDPR API Usage Guide
 
-This guide shows how to use the type-safe GDPR API client instead of raw fetch calls.
+This guide now focuses on sharing contract types between the SSR endpoints and any client or server-side callers. Implementation code should live alongside the endpoint that owns it. Shared files only export types.
 
-## 1. Import the client functions
+## 1. Import the contract types
 
 ```typescript
-import { recordConsent, submitDataRequest, recordConsentServerSide } from '@lib/api/gdpr.client'
+import type {
+  ConsentRequest,
+  ConsentResponse,
+  DSARRequestInput,
+  DSARResponse,
+  ErrorResponse
+} from '@pages/api/_contracts/gdpr.contracts'
 ```
 
-## 2. Client-side usage examples
+Using these shared types keeps both sides of the API honest without duplicating runtime logic.
 
-### Recording consent (cookies modal)
+## 2. Client-side consent submission example
 
 ```typescript
-// Before (raw fetch):
-await fetch('/api/gdpr/consent', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    DataSubjectId: consentState.DataSubjectId,
-    purposes,
-    source: 'cookies_modal',
-    userAgent: navigator.userAgent,
-    verified: false,
-  }),
-})
-
-// After (typed client):
-const result = await recordConsent({
+const payload: ConsentRequest = {
   DataSubjectId: consentState.DataSubjectId,
   purposes,
   source: 'cookies_modal',
   userAgent: navigator.userAgent,
   verified: false,
-})
-
-if (result.success) {
-  console.log('Consent recorded:', result.data.record.id)
-} else {
-  console.error('Failed:', result.error.message)
 }
-```
-
-### Submitting data requests (my-data page)
 
-```typescript
-// Before (raw fetch):
-const response = await fetch('/api/gdpr/request-data', {
+const response = await fetch('/api/gdpr/consent', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    email,
-    requestType: 'ACCESS'
-  })
+  body: JSON.stringify(payload),
 })
-const data = await response.json()
 
-// After (typed client):
-const result = await submitDataRequest({
-  email,
-  requestType: 'ACCESS'
-})
-
-if (result.success) {
-  accessMessage.textContent = result.data.message
-  accessMessage.className = 'form-message success'
-} else {
-  accessMessage.textContent = result.error.message
-  accessMessage.className = 'form-message error'
-}
+const data: ConsentResponse | ErrorResponse = await response.json()
 ```
 
-## 3. Server-side usage examples
+Because the payload is typed, any contract drift is caught at build time.
+
+## 3. Server-side helper usage
 
-### Contact form API
+Server routes can call the shared logger helper:
 
 ```typescript
-// Before (raw fetch):
-const consentResponse = await fetch(`${new URL(request.url).origin}/api/gdpr/consent`, {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    DataSubjectId: subjectId,
-    email: formData.email,
-    purposes: ['contact'],
-    source: 'contact_form',
-    userAgent,
-    verified: true,
-  }),
+import { recordConsent } from '@pages/api/_logger'
+
+await recordConsent({
+  origin: new URL(request.url).origin,
+  DataSubjectId: subjectId,
+  email: validatedEmail,
+  purposes: ['contact'],
+  source: 'contact_form',
+  userAgent,
+  verified: true,
 })
-
-// After (typed client):
-const result = await recordConsentServerSide(
-  new URL(request.url).origin,
-  {
-    DataSubjectId: subjectId,
-    email: formData.email,
-    purposes: ['contact'],
-    source: 'contact_form',
-    userAgent,
-    verified: true,
-  }
-)
-
-if (!result.success) {
-  // Handle error with proper typing
-  console.error('Consent failed:', result.error.code, result.error.message)
-}
 ```
 
-## 4. Benefits of the typed client
-
-1. **Type Safety**: Compile-time validation of request/response structures
-2. **Error Handling**: Consistent error response format across all functions
-3. **IntelliSense**: Auto-completion for all fields and response properties
-4. **Documentation**: JSDoc comments with usage examples
-5. **Centralized**: Single place to manage API call logic and error handling
-
-## 5. Migration checklist
+`recordConsent` now encapsulates the fetch logic so API routes stay minimal while still using the shared contracts.
 
-- [ ] `src/components/scripts/store/consent.ts` - Use `recordConsent()`
-- [ ] `src/pages/privacy/my-data.astro` - Use `submitDataRequest()`
-- [ ] `src/pages/api/contact/index.ts` - Use `recordConsentServerSide()`
-- [ ] `src/pages/api/newsletter/index.ts` - Use `recordConsentServerSide()`
+## 4. Recommended workflow
 
-## 6. Contract types
+1. Define every request/response shape in `@pages/api/_contracts`.
+2. Import those types in both the endpoint implementation and any caller (client or server).
+3. Keep shared files type-only to avoid duplicated runtime logic.
+4. Let each runtime (client, API route, worker) own the fetch/request mechanics that make sense for its environment.
 
-All types are re-exported from `@pages/api/_contracts/gdpr.contracts`:
+## 5. Available GDPR types
 
-- `ConsentRequest` - Consent recording payload
-- `ConsentResponse` - Consent creation response
-- `DSARRequestInput` - Data request payload
-- `DSARResponse` - Data request confirmation response
-- `ErrorResponse` - Standardized error format
+- `ConsentRequest` – Consent recording payload
+- `ConsentResponse` – Consent creation response
+- `DSARRequestInput` – Data request payload
+- `DSARResponse` – Data request confirmation response
+- `ErrorResponse` – Standardized error format

src/pages/api/_logger/__tests__/index.spec.ts

@@ -1,15 +1,17 @@
 /**
  * Tests for the shared consent logging helper
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest'
 import { ApiFunctionError } from '@pages/api/_errors/ApiFunctionError'
 import { recordConsent, type ConsentLogRequest } from '@pages/api/_logger'
 
-const recordConsentServerSideMock = vi.hoisted(() => vi.fn())
+const fetchMock = vi.hoisted(() => vi.fn())
+vi.stubGlobal('fetch', fetchMock)
 
-vi.mock('@lib/api/gdpr.client', () => ({
-  recordConsentServerSide: recordConsentServerSideMock,
-}))
+const buildFetchResponse = (ok: boolean, payload: unknown) => ({
+  ok,
+  json: vi.fn().mockResolvedValue(payload),
+}) as unknown as Response
 
 const buildRequest = (): ConsentLogRequest => ({
   origin: 'https://example.com',
@@ -24,49 +26,52 @@ const buildRequest = (): ConsentLogRequest => ({
 describe('recordConsent helper', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    recordConsentServerSideMock.mockReset()
+    fetchMock.mockReset()
+  })
+
+  afterAll(() => {
+    vi.unstubAllGlobals()
   })
 
   it('returns consent data when upstream succeeds', async () => {
     const mockConsent = { id: 'consent-1' }
-    recordConsentServerSideMock.mockResolvedValueOnce({
-      success: true,
-      data: mockConsent,
-    })
+    fetchMock.mockResolvedValueOnce(buildFetchResponse(true, mockConsent))
 
     const response = await recordConsent(buildRequest())
 
-    expect(recordConsentServerSideMock).toHaveBeenCalledWith('https://example.com', {
-      DataSubjectId: '1234',
-      email: 'user@example.com',
-      purposes: ['marketing'],
-      source: 'newsletter_form',
-      userAgent: 'pytest',
-      verified: false,
+    expect(fetchMock).toHaveBeenCalledWith('https://example.com/api/gdpr/consent', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        DataSubjectId: '1234',
+        email: 'user@example.com',
+        purposes: ['marketing'],
+        source: 'newsletter_form',
+        userAgent: 'pytest',
+        verified: false,
+      }),
     })
     expect(response).toBe(mockConsent)
   })
 
   it('propagates upstream error codes and defaults to 502', async () => {
-    recordConsentServerSideMock.mockResolvedValueOnce({
-      success: false,
+    fetchMock.mockResolvedValueOnce(buildFetchResponse(false, {
       error: {
         code: 'CONSENT_FAILED',
         message: 'nope',
       },
-    })
+    }))
 
     await expect(recordConsent(buildRequest())).rejects.toThrow(ApiFunctionError)
   })
 
   it('surfaces rate limit overruns with 429', async () => {
-    recordConsentServerSideMock.mockResolvedValueOnce({
-      success: false,
+    fetchMock.mockResolvedValueOnce(buildFetchResponse(false, {
       error: {
         code: 'RATE_LIMIT_EXCEEDED',
         message: 'too many',
       },
-    })
+    }))
 
     await expect(recordConsent(buildRequest())).rejects.toMatchObject({
       status: 429,

src/pages/api/_logger/index.ts

@@ -2,17 +2,57 @@
  * Shared consent logging helper for server-side API routes
  * Provides a thin wrapper around the GDPR consent endpoint with origin handling
  */
-import type { ConsentRequest } from '@pages/api/_contracts/gdpr.contracts'
+import type { ConsentRequest, ConsentResponse, ErrorResponse } from '@pages/api/_contracts/gdpr.contracts'
 import { ApiFunctionError } from '@pages/api/_errors/ApiFunctionError'
-import { recordConsentServerSide } from '@lib/api/gdpr.client'
 
 export type ConsentLogRequest = ConsentRequest & {
   origin: string
 }
 
+type ConsentApiResponse = {
+  success: true
+  data: ConsentResponse
+} | {
+  success: false
+  error: ErrorResponse['error']
+}
+
+const recordConsentUpstream = async (origin: string, request: ConsentRequest): Promise<ConsentApiResponse> => {
+  try {
+    const response = await fetch(`${origin}/api/gdpr/consent`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    })
+
+    const data = await response.json()
+
+    if (!response.ok) {
+      const errorResponse = data as ErrorResponse
+      return {
+        success: false,
+        error: errorResponse.error,
+      }
+    }
+
+    return {
+      success: true,
+      data: data as ConsentResponse,
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        message: error instanceof Error ? error.message : 'Network error',
+        code: 'INVALID_REQUEST',
+      },
+    }
+  }
+}
+
 export const recordConsent = async (request: ConsentLogRequest) => {
   const { origin, ...consentRequest } = request
-  const response = await recordConsentServerSide(origin, consentRequest)
+  const response = await recordConsentUpstream(origin, consentRequest)
 
   if (!response.success) {
     throw new ApiFunctionError({