Skip to content

README.md

Latest commit

 

History

History
117 lines (89 loc) · 5.63 KB

README.md

File metadata and controls

117 lines (89 loc) · 5.63 KB
Raw

Budget Buddy Contracts 🚀

OpenAPI Spec Release Status GitHub Release npm Maven API Docs Quality Gate Status

📖 Interactive API reference: https://budget-buddy-org.github.io/budget-buddy-contracts/

This repository serves as the Single Source of Truth for the Budget Buddy ecosystem. We use a "Contract-First" approach, where the API is defined in OpenAPI 3.1 and then used to generate strongly-typed clients and server interfaces for all supported platforms.

🏛 Architecture

The core of this project is the OpenAPI specification located in specs/openapi.yaml. From this single file, we derive three distinct targets:

Target Technology Delivery Method Usage
Frontend TypeScript (fetch) GitHub Packages (npm) Web dashboard
Backend Java + Spring Boot GitHub Packages (Maven) API Service implementation
Mobile Swift 6 Git Repo (SPM) iOS / macOS application

Why Contract-First?

  • Type Safety: Eliminate runtime errors caused by mismatched API schemas.
  • Parallel Development: Frontend, Backend, and Mobile teams can work simultaneously against a shared interface.
  • Documentation: The spec is the documentation.
  • Consistency: Standardized error handling (RFC 9457) across all platforms.

🛠 Developer Guide

Prerequisites

  • Node.js (v24+)
  • pnpm — pinned via Corepack from the packageManager field; run corepack enable once
pnpm install   # installs Spectral and openapi-generator-cli as devDeps

Core Commands

Command Description
pnpm run lint Lints the spec with Spectral (operationId, tags, descriptions, 500 responses).
pnpm run validate Checks the structural integrity of the OpenAPI document.
pnpm run mock Runs a Prism mock server locally at http://localhost:4010.
pnpm run generate Generates all clients (TS, Java, Swift) locally.
pnpm run generate:swift Regenerates the committed Swift sources under Sources/BudgetBuddyContracts/.

📦 Usage

See the GitHub Release badge above for the latest version.

Swift (iOS/macOS)

Add this repository as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/budget-buddy-org/budget-buddy-contracts.git", from: "<latest>")
]

TypeScript (Web)

Install from GitHub Packages (requires .npmrc configuration pointing @budget-buddy-org to https://npm.pkg.github.com):

pnpm add @budget-buddy-org/budget-buddy-contracts

Java (Spring Boot)

Add to your pom.xml (requires Maven server credentials for GitHub Packages):

<dependency>
    <groupId>com.budgetbuddy</groupId>
    <artifactId>budget-buddy-contracts</artifactId>
    <version><!-- latest --></version>
</dependency>

🚦 Release Workflow

  1. Edit the spec: specs/openapi.yaml (and/or config/*.yaml).
  2. Lint and validate: pnpm run lint && pnpm run validate.
  3. Open a PR with a conventional-commit title (feat:, fix:, feat!:, …). PRs are squash-merged, so the PR title becomes the commit on main and drives semantic-release.
  4. CI does the rest — on push to main, the release pipeline:
    • calculates the next semver from commit history
    • bumps package.json and specs/openapi.yaml to that version
    • regenerates and commits the Swift sources under Sources/BudgetBuddyContracts/
    • updates CHANGELOG.md
    • creates the Git tag and GitHub Release
    • publishes the TypeScript client to GitHub Packages (npm)
    • publishes the Java Spring stubs to GitHub Packages (Maven)

Commit message enforcement

  • Local commits are checked by Husky + Commitlint.
  • PRs are re-checked in CI; invalid messages cannot be merged.
  • Release impact follows Conventional Commits:
    • fix: / perf: → patch
    • feat: → minor
    • ! suffix or BREAKING CHANGE: footer → major

📝 API Design Conventions

  • Currency: Monetary amounts are integer (int64) in minor units — e.g. 1050 = €10.50. ISO 4217 codes accompany every amount.
  • Errors: Every error response uses application/problem+json per RFC 9457. Field-level validation errors are surfaced as Problem.errors[] on 400 responses.
  • Pagination: List endpoints accept page (zero-based, default 0) and size (1–200, default 20) query parameters; the response carries a PaginationMeta with page, size, and total.
  • Auth: Every endpoint requires a Bearer JWT issued by the OIDC provider — there are no auth endpoints in this spec.