Code Quality & Formatting

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• package.json
• README.md
• test/lib/logger.test.ts
• test/lib/github-errors.test.ts
• src/services/versions/v1/index.ts
• eslint.config.ts
• prettier.config.ts
• tsconfig.json

The FOSSBilling API Worker adheres to strict code quality and formatting standards to ensure a maintainable, secure, and performant codebase. The project utilizes TypeScript (ES modules) and is designed to be runtime-agnostic, separating core feature logic from platform-specific implementations.

Code quality is enforced through automated tooling, including ESLint for static analysis, Prettier for code style consistency, and Vitest for comprehensive testing. These tools ensure that all contributions meet the project's standards for type safety, readability, and security.

Sources: AGENTS.md:1-20, README.md:15-25

Standardized Development Workflow

The project defines a specific set of commands to manage code quality during the development lifecycle. This workflow ensures that code is formatted, linted, and tested before deployment.

Automated Tooling & Scripts

The following table summarizes the primary commands used to maintain the codebase:

Command	Purpose	Tools Used
npm run format	Automatically formats the entire codebase.	Prettier
npm run format:check	Verifies that files match the defined formatting.	Prettier
npm run lint	Performs static analysis to find code issues.	ESLint, @typescript-eslint
npm run typecheck	Validates TypeScript types without emitting files.	tsc
npm run test	Runs the Vitest suite in the Workers pool.	Vitest
npm run test:all	Runs both Workers and Node.js adapter tests.	Vitest

Sources: package.json:6-18, AGENTS.md:22-31

Formatting Standards

The project enforces a uniform style to minimize diff noise and improve readability:

• Indentation: 2-space indentation.
• Naming: Service folders use kebab-case (e.g., central-alerts).
• Commas: Prettier is configured with trailingComma: "none".
• Imports: Uses ES modules and TypeScript.

Sources: AGENTS.md:33-38

Secure Logging & Data Redaction

The API implements a robust logging system designed to prevent the leakage of sensitive information. The logger automatically redacts credentials and tokens before they are written to the console or storage.

Redaction Logic

The logging utility identifies and redacts sensitive keys within objects recursively, including nested structures and arrays.

The diagram shows the automated redaction flow that protects sensitive data during logging.

Sensitive Keys Targeted for Redaction:

• password
• token (and variants like api_token)
• key (and variants like secret_key)
• secret
• authorization headers containing Bearer tokens.

Sources: test/lib/logger.test.ts:47-150

Error Handling & Classification

The system employs a structured approach to error management, specifically for external integrations like the GitHub API. Errors are classified into specific types and assigned priorities to help the system determine the appropriate response, such as serving stale data from cache.

Error Priorities and Categories

Errors are managed through a GitHubError class hierarchy, which categorizes issues based on their severity.

Error Category	Priority	Typical Trigger
AuthError	CRITICAL	401 Unauthorized (Invalid GitHub Token)
RateLimitError	CRITICAL	403 Forbidden (GitHub API limits reached)
NetworkError	HIGH	Request timeouts or DNS failures
NotFoundError	MEDIUM	404 Not Found (Missing release or file)
ValidationError	LOW	422 Unprocessable Entity or malformed JSON

Sources: test/lib/github-errors.test.ts:10-60, src/services/versions/v1/index.ts:380-410

Error Classification Flow

The diagram illustrates the process of transforming raw exceptions into actionable, categorized errors.

Sources: src/services/versions/v1/index.ts:375-430, test/lib/github-errors.test.ts:71-125

Testing Infrastructure

Code quality is validated using Vitest. The test suite is organized to mirror the source layout, ensuring that logic remains runtime-agnostic and platform interfaces (Cache, Database) are properly mocked.

Integration Strategy

The project runs tests in multiple environments to ensure compatibility:

1. Workers Pool: Tests run in an environment simulating Cloudflare Workers.
2. Node.js Adapter: Tests run via vitest.node.config.ts to verify platform-agnostic behavior.
3. Integration Tests: Located in test/integration/, these test the full application flow including routing and cross-service communication.

Sources: AGENTS.md:40-45, package.json:14-16, test/integration/app.test.ts:40-60

Summary

FOSSBilling API Worker maintains high code quality through a combination of TypeScript's static typing, automated formatting with Prettier, and strict linting rules. Security is prioritized through automated log redaction and structured error classification, ensuring that sensitive information is never exposed and the system can gracefully handle failures by serving cached data. This rigorous approach to code standards supports the project's goal of being a lightweight, fast, and platform-agnostic central hub.