OpenAPI 3.0 Contracts: Machine-readable specifications defined in openapi/<domain>/v1/openapi.yaml.
Go Models: Generated under gen/go/<domain>/ as modular, zero-dependency Go packages.
TypeScript Types: Generated under gen/ts/<domain>/v1/ and distributed via @wilaris/apis with full subpath exports.

Design Principles

Contract-First: OpenAPI specifications define the contracts; Go and TypeScript models are generated.
Models-Only Generation: Code generation emits data models and request/response types with no runtime framework dependencies.
Uniform Error Handling: Standardized RFC-style error envelopes across all domains and operations.
Loose Coupling: Each domain is independently versioned and consumable as its own Go module or TypeScript subpath.

Domains & Endpoints

Domain	Scope	Key Endpoints	Go Module	TypeScript Export
`audit`	Audit logging, security event queries and partition pruning	`GET /v1/audit/events`	`gen/go/audit`	`@wilaris/apis/audit/v1`
`auth`	Session management, login/logout and credential exchange	`POST /v1/auth/login`, `POST /v1/auth/logout`	`gen/go/auth`	`@wilaris/apis/auth/v1`
`common`	Shared error models, standard parameters, roles and scopes	N/A (shared schemas & responses)	`gen/go/common`	`@wilaris/apis/common/v1`
`events`	Real-time Server-Sent Events (SSE) notification stream	`GET /v1/events`	`gen/go/events`	`@wilaris/apis/events/v1`
`initialization`	One-time product initialization and admin setup wizard	`GET /v1/initialization`, `POST /v1/initialization`	`gen/go/initialization`	`@wilaris/apis/initialization/v1`
`license`	License status inspection, JWT license installation and removal	`GET /v1/license`, `PUT /v1/license`, `DELETE /v1/license`	`gen/go/license`	`@wilaris/apis/license/v1`
`meta`	Liveness and readiness probes, capability discovery	`GET /v1/health`, `GET /v1/health/ready`, `GET /v1/info`	`gen/go/meta`	`@wilaris/apis/meta/v1`
`serviceaccount`	Passwordless machine identities and their token subresources	`GET/POST /v1/service-accounts`, `GET/PATCH/DELETE /v1/service-accounts/{serviceAccountId}`, `GET/POST /v1/service-accounts/{serviceAccountId}/tokens`	`gen/go/serviceaccount`	`@wilaris/apis/serviceaccount/v1`
`system`	Host metrics, storage stats, snapshots and maintenance toggle	`GET /v1/system/metrics`, `GET /v1/system/storage/stats`, `GET /v1/system/storage/backup`, `POST /v1/system/audit/prune` and `GET/PUT /v1/system/maintenance`	`gen/go/system`	`@wilaris/apis/system/v1`
`token`	Administrative token inventory, inspection and revocation	`GET /v1/tokens`, `GET/DELETE /v1/tokens/{tokenId}`	`gen/go/token`	`@wilaris/apis/token/v1`
`user`	User profile management, role assignment, password reset and token subresources	`GET/POST /v1/users`, `GET/PATCH /v1/users/me`, `GET/POST /v1/users/me/tokens`, `GET/PATCH/DELETE /v1/users/{userId}`, `GET/POST /v1/users/{userId}/tokens`	`gen/go/user`	`@wilaris/apis/user/v1`

Contract Standards & Conventions

Shared Error Format

All error responses conform to the standard error schema defined in openapi/common/v1:

{
  "code": "invalid_credentials",
  "message": "Username or password does not match",
  "details": [
    {
      "field": "password",
      "message": "Invalid password"
    }
  ],
  "requestId": "req_01h7x..."
}

code: Machine-readable error identifier for stable client handling.
message: Human-readable error explanation.
details: Optional list of field-level validation errors for form mapping.
requestId: Correlates with the X-Request-Id response header for tracing.

Authentication & Authorization

Bearer Token: Authenticated endpoints require an Authorization: Bearer <secret> header.
Role-Based Access Control: Standardized role hierarchy (read, write and admin) defined in the common schema.
Capability Discovery: Optional domains (license, audit, system and events) are advertised in the GET /v1/info features array.

Optimistic Concurrency & Patch Semantics

ETag / Versioning: Mutable entities expose a version field. Mutation endpoints support If-Match headers to prevent concurrent stale writes (409 Conflict).
Partial Updates: PATCH endpoints ignore omitted fields; empty strings clear optional values.

Usage

Go

Install the required domain module(s):

go get git.wilaris.dev/wilaris/apis/gen/go/user
go get git.wilaris.dev/wilaris/apis/gen/go/auth

Import and use the generated types:

package main

import (
	user "git.wilaris.dev/wilaris/apis/gen/go/user"
	common "git.wilaris.dev/wilaris/apis/gen/go/common"
)

func handleUser(u user.User) {
	if u.Role == common.RoleAdmin {
		// ...
	}
}

TypeScript / JavaScript

Install the package:

pnpm add @wilaris/apis

Import flat model types directly (each domain subpath exports a type alias for every schema in its spec):

// Flat model imports (Go struct equivalent)
import type { User, CreateUserRequest } from '@wilaris/apis/user/v1';
import type { Role, Error } from '@wilaris/apis/common/v1';

// Root domain namespaces expose the same aliases
import { user, common } from '@wilaris/apis';

let myUser: user.User;
let role: common.Role;

For fetch clients, the raw paths / components / operations types are still exported unchanged:

import type { paths as UserPaths, components as UserComponents } from '@wilaris/apis/user/v1';

Note that openapi-typescript inlines cross-file $refs, so shared models such as Role, Error and ErrorDetail are also exported from every domain that references them; @wilaris/apis/common/v1 remains their canonical home, mirroring the Go module layout.

Development & Code Generation

Prerequisites

Go (1.26+)
Node.js (18+) & pnpm (via corepack enable or a standalone install; the version is pinned by the packageManager field in package.json)

Common Tasks

# Install the pinned TypeScript toolchain
pnpm install

# Generate all Go models and TypeScript types from OpenAPI specs
make generate

# Typecheck TypeScript definitions
make typecheck

# Run verification suite (formatting, vetting, typechecking and module builds)
make verify

# Run linters (formatting check, vetting, golangci-lint)
make lint

# Tag a lockstep release across all Go modules and TypeScript package
make release VERSION=v0.1.0

# Push the release commit and tags
make release-push VERSION=v0.1.0

# Format Go sources
make fmt

# Clean all generated artifacts
make clean