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.1 KiB

Raw Blame History

Veza API Contract (Finalized)

1. Overview

This document defines the finalized API contract for the Veza backend. All endpoints adhere to strict JSON standards, snake_case naming conventions, and a unified response envelope.

2. Global Standards

Protocol: HTTP/1.1
Content-Type: application/json
Charset: utf-8
Date Format: ISO 8601 (YYYY-MM-DDThh:mm:ssZ)
Naming Convention: snake_case for all JSON keys.

3. Response Envelope

Every API response (Success or Error) is wrapped in a unified envelope.

3.1. Success Response

HTTP Status: 200 OK, 201 Created

{
  "success": true,
  "data": {
    // Resource or Object
    "id": "123",
    "name": "example"
  },
  "error": null
}

3.2. Error Response

HTTP Status: 4xx, 5xx

{
  "success": false,
  "data": null,
  "error": {
    "code": 400,
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_123xyz"
  }
}

4. Error Handling

Frontend clients should check the success boolean.

If success is false, read the error object.
error.code maps to standard HTTP status codes but provides application-level context.
error.details is an optional array of field-specific errors (useful for form validation).

5. Authentication

Header: Authorization: Bearer <token>
Token Type: JWT (Access Token)
Refresh: Use /api/v1/auth/refresh to rotate tokens.

6. Pagination

Endpoints returning lists support cursor-based or offset-based pagination. Helper structure in data:

{
  "list": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "has_next": true
  }
}

7. Versioning

Current Version: v1
Base Path: /api/v1

8. Key Changes (Remediation Phase)

Unified Handlers: All handlers now use RespondSuccess and RespondWithAppError.
Snake Case: All DTOs enforce snake_case.
Validation: Strict validation on all request bodies using go-playground/validator.

2.1 KiB Raw Blame History