senke/veza

senke 0e7097ed1b chore(cleanup): J1 — purge 220MB debris, archive session docs (complete)

First-attempt commit 3a5c6e184 only captured the .gitignore change; the
pre-commit hook silently dropped the 343 staged moves/deletes during
lint-staged's "no matching task" path. This commit re-applies the intended
J1 content on top of bec75f143 (which was pushed in parallel).

Uses --no-verify because:
- J1 only touches .md/.json/.log/.png/binaries — zero code that would
  benefit from lint-staged, typecheck, or vitest
- The hook demonstrated it corrupts pure-rename commits in this repo
- Explicitly authorized by user for this one commit

Changes (343 total: 169 deletions + 174 renames):

Binaries purged (~167 MB):
- veza-backend-api/{server,modern-server,encrypt_oauth_tokens,seed,seed-v2}

Generated reports purged:
- 9 apps/web/lint_report*.json (~32 MB)
- 8 apps/web/tsc_*.{log,txt} + ts_*.log (TS error snapshots)
- 3 apps/web/storybook_*.json (1375+ stored errors)
- apps/web/{build_errors*,build_output,final_errors}.txt
- 70 veza-backend-api/coverage*.out + coverage_groups/ (~4 MB)
- 3 veza-backend-api/internal/handlers/*.bak

Root cleanup:
- 54 audit-*.png (visual regression baselines, ~11 MB)
- 9 stale MVP-era scripts (Jan 27, hardcoded v0.101):
  start_{iteration,mvp,recovery}.sh,
  test_{mvp_endpoints,protected_endpoints,user_journey}.sh,
  validate_v0101.sh, verify_logs_setup.sh, gen_hash.py

Session docs archived (not deleted — preserved under docs/archive/):
- 78 apps/web/*.md     → docs/archive/frontend-sessions-2026/
- 43 veza-backend-api/*.md → docs/archive/backend-sessions-2026/
- 53 docs/{RETROSPECTIVE_V,SMOKE_TEST_V,PLAN_V0_,V0_*_RELEASE_SCOPE,
          AUDIT_,PLAN_ACTION_AUDIT,REMEDIATION_PROGRESS}*.md
                        → docs/archive/v0-history/

README.md and CONTRIBUTING.md preserved in apps/web/ and veza-backend-api/.

Note: The .gitignore rules preventing recurrence were already pushed in
3a5c6e184 and remain in place — this commit does not modify .gitignore.

Refs: AUDIT_REPORT.md §11

2026-04-14 17:12:03 +02:00

2.3 KiB

Raw Blame History

Veza API Frontend Integration Guide

1. Introduction

This guide provides instructions for consuming the Veza Backend API in frontend applications (React, Vue, etc.).

2. API Client Setup

We recommend creating a typed API client.

2.1. TypeScript Interfaces

// Base Response Envelope
export interface APIResponse<T> {
  success: boolean;
  data: T | null;
  error: APIError | null;
}

// Error Structure
export interface APIError {
  code: number;
  message: string;
  details?: ValidationErrorDetail[] | null;
  request_id?: string;
  timestamp?: string;
}

export interface ValidationErrorDetail {
  field: string;
  message: string;
  value?: string;
  tag?: string;
}

// Pagination
export interface PaginatedList<T> {
  list: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    has_next: boolean;
  };
}

3. Making Requests

3.1. Fetch Wrapper Example

async function apiRequest<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const token = localStorage.getItem('access_token');
  const headers = {
    'Content-Type': 'application/json',
    ...(token ? { 'Authorization': `Bearer ${token}` } : {}),
    ...options.headers,
  };

  const response = await fetch(\`/api/v1${endpoint}\`, { ...options, headers });
  const result: APIResponse<T> = await response.json();

  if (!result.success) {
    // Handle API Error
    console.error('API Error:', result.error);
    throw new Error(result.error?.message || 'Unknown API Error');
  }

  // Return the data payload directly
  return result.data as T;
}

4. Handling Validation Errors

When a 400 Bad Request or 422 Unprocessable Entity occurs:

try {
  await apiRequest('/auth/login', { method: 'POST', body: JSON.stringify(creds) });
} catch (error) {
  // If error has details, map them to form fields
  const apiError = error as APIError; // You might need to adjust error throwing logic
  if (apiError.details) {
    apiError.details.forEach(detail => {
      setFieldError(detail.field, detail.message);
    });
  }
}

5. Resources & Endpoints (Swagger)

For a full list of endpoints, request/response bodies, please refer to the OpenAPI Specification:

Local URL: http://localhost:8080/swagger/index.html
File: docs/swagger.json

2.3 KiB Raw Blame History