Wilaris OSS

Repositories

1

Projects Packages Code

@wilaris/apis (0.5.0)

Published 2026-09-08 04:44:16 +00:00 by wilaris-bot in wilaris/apis

Installation

Set up this registry in your project .npmrc file:

@wilaris:registry=https://git.wilaris.dev/api/packages/wilaris/npm/

To install the package using npm, run the following command:

npm install @wilaris/apis@0.5.0

or add it to the package.json file:

"@wilaris/apis": "0.5.0"

For more information on the npm registry, see the documentation.

About this package

Canonical OpenAPI contracts and generated TypeScript & Go models for Wilaris APIs

API Contracts & Type Definitions

Canonical OpenAPI 3.0 specifications, generated Go models and TypeScript type definitions for core service APIs.

Overview

This repository acts as the single source of truth for base service contracts across backend services and client applications:

• 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

Dependencies

Development Dependencies

ID	Version
openapi-typescript	7.13.0
typescript	5.9.3

Keywords

openapi types typescript contracts wilaris api

Details

npm

wilaris/apis

2026-09-08 04:44:16 +00:00

1

Apache-2.0

latest

45 KiB

Assets (1)

apis-0.5.0.tgz 45 KiB

Versions (6) View all

0.5.0 2026-09-08

0.4.0 2026-09-06

0.3.0 2026-09-03

0.2.0 2026-09-03

0.1.2 2026-08-15

Issues