@budgetbuddyde/api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thorben Klein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# `@budgetbuddyde/api`
+
+## About
+
+![CI](https://ci.tklein.it/api/v1/teams/budgetbuddyde/pipelines/api/jobs/build-api/badge)
+![NPM Version](https://img.shields.io/npm/v/%40budgetbuddyde%2Fapi)
+![NPM License](https://img.shields.io/npm/l/%40budgetbuddyde%2Fapi)
+![NPM Last Update](https://img.shields.io/npm/last-update/%40budgetbuddyde%2Fapi)
+
+A type-safe, Zod-validated API client for BudgetBuddy backend services. This package provides a unified interface for communicating with all backend endpoints and offers runtime validation as well as full TypeScript support.
+
+The package can be installed via NPM:
+
+```bash
+npm install @budgetbuddyde/api
+```
+
+### Peer Dependencies
+
+> [!NOTE] 
+> The package uses Zod for schema validation, therefore `zod` must be installed as a peer dependency.
+> ```bash
+> npm install zod
+> ```
+
+
+## Getting Started
+
+### Basic Usage
+
+```typescript
+import { Api } from '@budgetbuddyde/api';
+
+// Initialize API client
+const api = new Api('https://backend.budgetbuddy.de');
+
+// Fetch transactions
+const [transactions, error] = await api.backend.transaction.getAll();
+
+if (error) {
+  console.error('Error loading transactions:', error);
+  return;
+}
+
+console.log('Transactions:', transactions);
+```
+
+### CRUD Operations
+
+All entity services provide standard CRUD operations:
+
+```typescript
+// Create - Create new category
+const [newCategory, createError] = await api.backend.category.create({
+  name: 'Groceries',
+  description: 'Supermarket purchases',
+});
+
+// Read - Fetch all categories
+const [categories, getAllError] = await api.backend.category.getAll();
+
+// Read - Fetch single category
+const [category, getError] = await api.backend.category.getById('category-id');
+
+// Update - Update category
+const [updated, updateError] = await api.backend.category.updateById(
+  'category-id',
+  { name: 'Groceries & Beverages' }
+);
+
+// Delete - Delete category
+const [deleted, deleteError] = await api.backend.category.deleteById('category-id');
+```
+
+### Query Parameters
+
+Many endpoints support query parameters for filtering and pagination:
+
+```typescript
+// Fetch transactions with date filter
+const [transactions, error] = await api.backend.transaction.getAll({
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-12-31'),
+  limit: 50,
+  offset: 0,
+});
+```
+
+### Error Handling
+
+The package uses a `TResult<T, E>` pattern for type-safe error handling:
+
+```typescript
+import type { TResult } from '@budgetbuddyde/api';
+
+async function loadBudgets() {
+  const [budgets, error] = await api.backend.budget.getAll();
+  
+  // Check for errors
+  if (error) {
+    // TypeScript knows that 'budgets' is null here
+    if (error instanceof BackendError) {
+      console.error('Backend error:', error.statusCode, error.message);
+    } else if (error instanceof NetworkError) {
+      console.error('Network error:', error.message);
+    }
+    return;
+  }
+  
+  // TypeScript knows that 'budgets' is not null here
+  console.log('Budgets loaded:', budgets);
+}
+```
+
+### Custom Request Configuration
+
+For advanced usage, request options can be passed:
+
+```typescript
+// With custom headers
+const [data, error] = await api.backend.transaction.getAll(
+  undefined,
+  {
+    headers: {
+      'X-Custom-Header': 'value',
+    },
+    signal: abortController.signal, // AbortController for cancellation
+  }
+);
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+Compiles TypeScript to JavaScript in the `lib/` folder.
+
+### Tests
+
+```bash
+# Run tests once
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Code Quality
+
+```bash
+# Biome Check (Linting + Formatting)
+npm run check
+
+# Auto-fix
+npm run check:write
+
+# Linting only
+npm run lint
+
+# Formatting only
+npm run format
+```
+
+## API Reference
+
+### Available Services
+
+| Service | Description | Endpoint |
+|---------|-------------|----------|
+| `api.backend.category` | Category management | `/api/category` |
+| `api.backend.paymentMethod` | Payment methods | `/api/paymentMethod` |
+| `api.backend.transaction` | Transactions | `/api/transaction` |
+| `api.backend.recurringPayment` | Recurring payments | `/api/recurringPayment` |
+| `api.backend.budget` | Budget management | `/api/budget` |
+
+### Common Methods
+
+All services inherit from `EntityService` and provide:
+
+```typescript
+// Type signature simplified
+class EntityService<CreatePayload, UpdatePayload, ...> {
+  getAll<Q>(query?: Q, config?: RequestInit): Promise<TResult<GetAllResult>>;
+  getById(id: string, config?: RequestInit): Promise<TResult<GetResult>>;
+  create(payload: CreatePayload, config?: RequestInit): Promise<TResult<CreateResult>>;
+  updateById(id: string, payload: UpdatePayload, config?: RequestInit): Promise<TResult<UpdateResult>>;
+  deleteById(id: string, config?: RequestInit): Promise<TResult<DeleteResult>>;
+}
+```
+
+## Type Safety
+
+The package leverages Zod for runtime validation combined with TypeScript for compile-time safety:
+
+```typescript
+// Schema defines both runtime and compile-time types
+const CategorySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+// TypeScript type is derived from schema
+type TCategory = z.infer<typeof CategorySchema>;
+
+// Runtime validation in services
+const parsingResult = CategorySchema.safeParse(apiResponse);
+if (!parsingResult.success) {
+  // Handle validation errors
+}
+```
+
+## Project Structure
+
+```
+packages/api/
+├── src/                            # Source code
+│   ├── api.ts                      # Main API class
+│   ├── client.ts                   # Re-export of API
+│   ├── error.ts                    # Custom error classes
+│   ├── index.ts                    # Main export
+│   │
+│   ├── services/                   # Service layer for backend communication
+│   │   ├── entity.service.ts       # Base service with CRUD operations
+│   │   └── <name>.service.ts       # Entity-specific operations
+│   │
+│   └── types/                      # TypeScript types and schemas
+│       ├── common.ts               # Common type helpers (TResult, etc.)
+│       ├── <name>.type.ts          # Entity-specific operations
+│       │
+│       ├── interfaces/             # TypeScript interfaces
+│       │   ├── query.interface.ts  # Base query interfaces
+│       │   └── <name>.interface.ts # Entity-specific interfaces
+│       │
+│       └── schemas/                # Zod validation schemas
+│           ├── common.schema.ts    # Common schemas
+│           └── <name>.schema.ts    # Entity-specific schemas
+│
+├── lib/                        # Compiled JavaScript files (generated)
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── README.md
+```
+
+### Architecture Components
+
+#### 1. **API Class** (`api.ts`)
+The central entry point that aggregates all service instances:
+
+```typescript
+const api = new Api('https://backend-url');
+// Access all services:
+// - api.backend.category
+// - api.backend.paymentMethod
+// - api.backend.transaction
+// - api.backend.recurringPayment
+// - api.backend.budget
+```
+
+#### 2. **Entity Service** (`services/entity.service.ts`)
+Abstract base class for all entity services with generic CRUD operations:
+
+- `getAll(query?, config?)` - Fetch all entities
+- `getById(id, config?)` - Fetch single entity
+- `create(payload, config?)` - Create new entity
+- `updateById(id, payload, config?)` - Update entity
+- `deleteById(id, config?)` - Delete entity
+
+**Features:**
+- Automatic Zod validation of all responses
+- Type-safe request/response handling
+- Query parameter serialization
+- Error handling and error types
+- Request config merging
+
+#### 3. **Specialized Services** (`services/*.service.ts`)
+Extend `EntityService` with domain-specific methods:
+
+```typescript
+// Example: BudgetService with additional method
+class BudgetService extends EntityService {
+  async getEstimatedBudget(): Promise<TResult<TEstimatedBudget>> {
+    // Budget-specific logic
+  }
+}
+```
+
+#### 4. **Type System** (`types/`)
+
+##### **Schemas** (`types/schemas/`)
+Zod schemas for runtime validation:
+
+```typescript
+import { z } from 'zod';
+
+export const CategorySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  createdAt: z.string().datetime(),
+});
+
+export const GetAllCategoriesResponse = z.object({
+  data: z.array(CategorySchema),
+  total: z.number(),
+});
+```
+
+##### **Types** (`types/*.type.ts`)
+TypeScript types, often derived from Zod schemas:
+
+```typescript
+import type { z } from 'zod';
+import { CategorySchema } from './schemas/category.schema';
+
+export type TCategory = z.infer<typeof CategorySchema>;
+```
+
+##### **Common Types** (`types/common.ts`)
+Shared type helpers:
+
+- `TResult<T, E>` - Result type for error handling
+- `TApiResponse<Schema>` - API response helper
+- `TypeOfSchema<Schema>` - Schema-to-type converter
+
+##### **Interfaces** (`types/interfaces/`)
+TypeScript interfaces for structure definitions:
+
+```typescript
+export interface IBaseGetAllQuery {
+  limit?: number;
+  offset?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+#### 5. **Error Handling** (`error.ts`)
+Custom error classes for various error scenarios:
+
+- `CustomError` - Base error class
+- `ApiError` - General API errors
+- `BackendError` - HTTP status errors from backend
+- `ResponseNotJsonError` - Response is not valid JSON
+
+```typescript
+try {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new BackendError(response.status, response.statusText);
+  }
+} catch (error) {
+  if (error instanceof BackendError) {
+    console.error('Backend returned:', error.statusCode);
+  }
+}
+```
+
+
+## Contributing
+
+See [the documentation for contribution guidelines](https://docs.budget-buddy.de/docs/introduction/contribution).

package/lib/api.d.ts

@@ -0,0 +1,17 @@
+/** biome-ignore-all lint/complexity/noStaticOnlyClass: This class is used as as a wrapper */
+import { BudgetService } from "./services/budget.service";
+import { CategoryService } from "./services/category.service";
+import { PaymentMethodService } from "./services/paymentMethod.service";
+import { RecurringPaymentService } from "./services/recurringPayment.service";
+import { TransactionService } from "./services/transaction.service";
+export declare class Api {
+    protected backendHost: string;
+    backend: {
+        category: CategoryService;
+        paymentMethod: PaymentMethodService;
+        transaction: TransactionService;
+        recurringPayment: RecurringPaymentService;
+        budget: BudgetService;
+    };
+    constructor(backendHost: string);
+}

package/lib/api.js

@@ -0,0 +1,22 @@
+"use strict";
+/** biome-ignore-all lint/complexity/noStaticOnlyClass: This class is used as as a wrapper */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Api = void 0;
+const budget_service_1 = require("./services/budget.service");
+const category_service_1 = require("./services/category.service");
+const paymentMethod_service_1 = require("./services/paymentMethod.service");
+const recurringPayment_service_1 = require("./services/recurringPayment.service");
+const transaction_service_1 = require("./services/transaction.service");
+class Api {
+    constructor(backendHost) {
+        this.backendHost = backendHost;
+        this.backend = {
+            category: new category_service_1.CategoryService(backendHost),
+            paymentMethod: new paymentMethod_service_1.PaymentMethodService(backendHost),
+            transaction: new transaction_service_1.TransactionService(backendHost),
+            recurringPayment: new recurringPayment_service_1.RecurringPaymentService(backendHost),
+            budget: new budget_service_1.BudgetService(backendHost),
+        };
+    }
+}
+exports.Api = Api;

package/lib/budget.d.ts

@@ -0,0 +1,3 @@
+export * from "./services/budget.service";
+export * from "./types/budget.type";
+export * from "./types/schemas/budget.schema";

package/lib/budget.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./services/budget.service"), exports);
+__exportStar(require("./types/budget.type"), exports);
+__exportStar(require("./types/schemas/budget.schema"), exports);

package/lib/category.d.ts

@@ -0,0 +1,3 @@
+export * from "./services/category.service";
+export * from "./types/category.type";
+export * from "./types/schemas/category.schema";

package/lib/category.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./services/category.service"), exports);
+__exportStar(require("./types/category.type"), exports);
+__exportStar(require("./types/schemas/category.schema"), exports);

package/lib/error.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Gerneric custom error class that extends the built-in Error class.
+ * @author developer.mozilla.org
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
+ */
+export declare class CustomError extends Error {
+    constructor(...params: any[]);
+}
+/**
+ * Error class representing an error occurring in the API layer.
+ *
+ * @example
+ * ```ts
+ * throw new ApiError("Failed to fetch data from API");
+ * ```
+ */
+export declare class ApiError extends CustomError {
+}
+/**
+ * Error class representing a response that is not in JSON format.
+ */
+export declare class ResponseNotJsonError extends ApiError {
+    constructor();
+}
+/**
+ * Error class representing an HTTP response containing an error from the backend.
+ */
+export declare class BackendError extends CustomError {
+    protected statusCode: number;
+    protected backendResponseText: string;
+    constructor(statusCode: number, backendResponseText: string);
+    getMessage(): string;
+}

package/lib/error.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendError = exports.ResponseNotJsonError = exports.ApiError = exports.CustomError = void 0;
+/**
+ * Gerneric custom error class that extends the built-in Error class.
+ * @author developer.mozilla.org
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
+ */
+class CustomError extends Error {
+    // biome-ignore lint/suspicious/noExplicitAny: Params can be any
+    constructor(...params) {
+        // Pass remaining arguments (including vendor specific ones) to parent constructor
+        super(...params);
+        // Maintains proper stack trace for where our error was thrown (non-standard)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CustomError);
+        }
+        this.name = this.constructor.name;
+    }
+}
+exports.CustomError = CustomError;
+/**
+ * Error class representing an error occurring in the API layer.
+ *
+ * @example
+ * ```ts
+ * throw new ApiError("Failed to fetch data from API");
+ * ```
+ */
+class ApiError extends CustomError {
+}
+exports.ApiError = ApiError;
+/**
+ * Error class representing a response that is not in JSON format.
+ */
+class ResponseNotJsonError extends ApiError {
+    constructor() {
+        super("Response is not JSON");
+    }
+}
+exports.ResponseNotJsonError = ResponseNotJsonError;
+/**
+ * Error class representing an HTTP response containing an error from the backend.
+ */
+class BackendError extends CustomError {
+    constructor(statusCode, backendResponseText) {
+        super(backendResponseText);
+        this.statusCode = statusCode;
+        this.backendResponseText = backendResponseText;
+    }
+    getMessage() {
+        return `Backend failed the request with status ${this.statusCode}: ${this.backendResponseText}`;
+    }
+}
+exports.BackendError = BackendError;

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./api";
+export * from "./error";
+export * from "./services/entity.service";
+export * from "./types/common";
+export * from "./types/interfaces/query.interface";
+export * from "./types/schemas/common.schema";

package/lib/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api"), exports);
+__exportStar(require("./error"), exports);
+__exportStar(require("./services/entity.service"), exports);
+__exportStar(require("./types/common"), exports);
+__exportStar(require("./types/interfaces/query.interface"), exports);
+__exportStar(require("./types/schemas/common.schema"), exports);

package/lib/paymentMethod.d.ts

@@ -0,0 +1,3 @@
+export * from "./services/paymentMethod.service";
+export * from "./types/paymentMethod.type";
+export * from "./types/schemas/paymentMethod.schema";

package/lib/paymentMethod.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./services/paymentMethod.service"), exports);
+__exportStar(require("./types/paymentMethod.type"), exports);
+__exportStar(require("./types/schemas/paymentMethod.schema"), exports);

package/lib/recurringPayment.d.ts

@@ -0,0 +1,4 @@
+export * from "./services/recurringPayment.service";
+export * from "./types/interfaces/recurringPayment.interface";
+export * from "./types/recurringPayment.type";
+export * from "./types/schemas/recurringPayment.schema";

package/lib/recurringPayment.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./services/recurringPayment.service"), exports);
+__exportStar(require("./types/interfaces/recurringPayment.interface"), exports);
+__exportStar(require("./types/recurringPayment.type"), exports);
+__exportStar(require("./types/schemas/recurringPayment.schema"), exports);

package/lib/services/budget.service.d.ts

@@ -0,0 +1,8 @@
+import type { TCreateOrUpdateBudgetPayload, TEstimatedBudget } from "../types/budget.type";
+import type { TResult } from "../types/common";
+import { CreateBudgetResponse, DeleteBudgetResponse, GetAllBudgetsResponse, GetBudgetResponse, UpdateBudgetResponse } from "../types/schemas/budget.schema";
+import { EntityService } from "./entity.service";
+export declare class BudgetService extends EntityService<TCreateOrUpdateBudgetPayload, Partial<TCreateOrUpdateBudgetPayload>, typeof GetAllBudgetsResponse, typeof GetBudgetResponse, typeof CreateBudgetResponse, typeof UpdateBudgetResponse, typeof DeleteBudgetResponse> {
+    constructor(host: string, entityPath?: string);
+    getEstimatedBudget(requestConfig?: RequestInit): Promise<TResult<TEstimatedBudget>>;
+}