Generated SDK Workflow

Goal

This frontend is contract-driven.

The generated SDK is not an optional convenience layer. It is the canonical transport contract between this repository and the paired Laravel backend.

Source of truth chain

The intended chain is:

1. backend OpenAPI document
2. generated frontend typings
3. generated frontend SDK
4. app-facing API facades in src/service/api/*
5. usage from stores, composables, and views

Canonical files:

• obsidian-admin-laravel/docs/openapi.yaml
• src/service/api/generated
• src/service/api/generated-adapter.ts
• src/service/api/generated-caller.ts

Commands

Regenerate frontend contract artifacts with:

pnpm api:types
pnpm openapi:client:official
pnpm typecheck:api

For release-grade verification:

pnpm check:ci

What is generated

This repository generates:

• backend contract typings
• backend DTO/resource typings
• official SDK client code from @hey-api/openapi-ts

Generated outputs include:

• src/typings/api/openapi-generated.d.ts
• src/typings/api/backend-generated.d.ts
• src/service/api/generated

These files are machine-owned and should not be hand-edited.

Facade rule

Business code should not import the generated SDK directly.

Instead, route usage through:

• src/service/api/*

Those facades are the stable app-facing API layer. They adapt generated operations into frontend-friendly behavior without leaking transport details into stores, composables, or views.

Architecture gate

The repository already enforces the main rule:

• business code must not import the request entrypoint directly
• business code must not import generated SDK files directly

Gate:

• scripts/api-architecture-check.mjs

When to regenerate

Regenerate whenever:

• backend OpenAPI changes
• backend DTO/resource shapes change in ways that affect generated typings
• a new backend endpoint should become part of the canonical frontend contract

Do not delay regeneration until release day. Generated drift should be fixed as part of the same change set.