Paywise API TypeScript SDK

Expert guidance for developing the `paywise-api` npm package - an unofficial TypeScript/JavaScript client for the Paywise API.

Critical Pre-Change Checklist

Before making ANY code changes:

1. **Verify current version**: Run `npm view paywise-api version` or check [NPM](https://www.npmjs.com/package/paywise-api)

2. **Quality gates**: ALL changes MUST pass:

- `npm run build` (TypeScript compilation)

- `npm run lint` (ESLint v9)

- `npm run test` (Jest with mocks)

3. **Commit format**: Use semantic commit prefixes (triggers automatic versioning)

4. **Documentation**: Update README.md if public API changes

5. **Changelog**: Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format

Architecture Overview

The SDK is organized into modular namespaces:

```

src/

├── index.ts # Main package exports

├── client.ts # PaywiseClient (main entry point)

├── http-client.ts # HTTP layer (fetch, retry, rate limiting)

├── types.ts # Shared types (PaywiseConfig, ApiResponse, ApiError)

├── case-management/ # Case Management API module

│ ├── client.ts # CaseManagementClient

│ └── types.ts # Type definitions (~850 lines)

└── partner-api/ # Partner API module

├── client.ts # PartnerApiClient (requires X-User-Id header)

└── types.ts # Partner-specific types

tests/

└── mocks/ # Mock API responses based on docs.paywise.de

```

Semantic Versioning Rules

Every commit MUST use semantic prefixes to trigger correct version bumps:

|---------------|--------------|----------|---------|

**Before pushing**: Always verify the new version doesn't already exist on NPM!

TypeScript Type Conventions

Follow Paywise API's snake_case property naming:

```typescript

// ✅ CORRECT: snake_case properties matching API, Amount type

export interface CreateClaimParams {

[key: string]: unknown; // Index signature for extra properties

debtor: string;

total_claim_amount: Amount; // { value: string; currency: 'EUR' }

due_date: string | null;

claim_type: 'INVOICE' | 'CONTRACT' | 'OTHER';

}

// Amount type for monetary values

export interface Amount {

value: string; // String to avoid floating-point issues

currency: 'EUR'; // Currently only EUR supported

}

// ❌ WRONG: camelCase won't match Paywise API responses

export interface CreateClaimParams {

debtorId: string;

totalAmount: number; // Number loses precision for currency

}

```

**Key requirements**:

Use `snake_case` for all API-facing properties

Include `[key: string]: unknown` index signature for extensibility

Use `Amount` type for all monetary values (never plain `number`)

Document optional vs required fields based on [docs.paywise.de](https://docs.paywise.de)

Critical API Edge Cases

Authentication

**Token expiration**: Implement exponential backoff retry (1s, 2s, 4s, 8s...)

**Partner API context**: Partner API endpoints REQUIRE `X-User-Id` header (company context)

Rate Limiting

**429 responses**: Implement exponential backoff: 1s → 2s → 4s → 8s

**Bulk operations**: Add client-side rate limiter for batch processing

Claim Workflow

**Document requirement**: NEVER call release claim without uploading documents first

**Debtor deduplication**: Provide `findOrCreateDebtor()` helper to avoid duplicates

**Mandate acceptance**: Requires polling; provide `waitForMandateAcceptance()` helper

File Handling

**Browser**: Use native `File` API

**Node.js**: Support both `Buffer` + metadata AND `File` (Node 20+)

**Validation**: Always validate MIME types before upload

NPM Scripts

```bash

npm run build # TypeScript compilation to dist/

npm run lint # ESLint v9 (entire workspace)

npm run lint:fix # Auto-fix linting issues

npm run test # Jest with mock API responses

npm run prepare # Setup Husky git hooks

```

Testing Strategy

All tests use **mock API responses** based on official [docs.paywise.de](https://docs.paywise.de) documentation:

```typescript

// tests/mocks/claim.mock.ts

export const mockClaimResponse: Claim = {

id: 'claim-123',

href: '/v1/claims/claim-123',

debtor: '/v1/debtors/debtor-456',

total_claim_amount: { value: '1500.00', currency: 'EUR' },

claim_date: '2024-01-15',

due_date: '2024-02-15',

claim_type: 'INVOICE',

// ... complete schema based on actual API

};

```

**Test categories**:

1. **Unit tests**: Type validation, utility functions

2. **Integration tests**: HTTP client with mocked responses

3. **Edge case tests**: Timeouts, 429 errors, network failures, token expiration

Key Files Reference

| File Path | Purpose |

|-----------|---------|

| `src/case-management/types.ts` | ~850 lines of Case Management API types |

| `src/partner-api/types.ts` | Partner API specific types |

| `scripts/update-changelog.js` | Keep a Changelog formatter |

| `eslint.config.mjs` | ESLint v9 flat config |

| `.github/workflows/release.yml` | CI/CD with NPM OIDC publishing |

| `tests/mocks/` | Mock API responses for testing |

Adding New Features

Follow this workflow:

1. **Research**: Check [docs.paywise.de](https://docs.paywise.de) for official API specification

2. **Types**: Add interfaces to `src/{module}/types.ts` (use snake_case!)

3. **Implementation**: Add method to `src/{module}/client.ts`

4. **Mocks**: Create mock response in `tests/mocks/{feature}.mock.ts`

5. **Tests**: Write unit + integration tests

6. **Exports**: Add to `src/index.ts` public API

7. **Documentation**: Update `README.md` with usage examples

8. **Validation**: Run `npm run build && npm run lint && npm run test`

9. **Commit**: Use semantic commit prefix (e.g., `feat: add debtor search`)

Common Pitfalls & Solutions

| Issue | Cause | Solution |

|-------|-------|----------|

| Type errors in params | Missing index signature | Add `[key: string]: unknown` to interface |

| Partner API 403 Forbidden | Missing company context | Include `X-User-Id` header |

| Release failed on GitHub Actions | Version already exists on NPM | Check `npm view paywise-api version` before committing |

| Claim release rejected by API | No document uploaded | Always upload document before releasing claim |

| IBAN validation errors | Client-side validation missing | Consider using `ibantools` package for validation |

| Semantic-release version not created | Git tags not pushed to remote | Run `git push --tags` after release |

| Floating-point currency issues | Using `number` for amounts | Always use `Amount` type with `string` value |

Maintenance Notes

**Maintainer**: [@mleem97](https://github.com/mleem97)

**Organizations**: Lunexor / MVNet Solutions / Meyer Media

**NPM Package**: [paywise-api](https://www.npmjs.com/package/paywise-api)

**API Documentation**: [docs.paywise.de](https://docs.paywise.de)

**Status**: Unofficial community implementation

When submitting PRs or making changes, always reference the official Paywise API documentation for correctness and ensure backward compatibility unless explicitly creating a breaking change (which requires major version bump).

Paywise API TypeScript SDK

Paywise API TypeScript SDK

Critical Pre-Change Checklist

Architecture Overview

Semantic Versioning Rules

TypeScript Type Conventions

Critical API Edge Cases

Authentication

Rate Limiting

Claim Workflow

File Handling

NPM Scripts

Testing Strategy

Key Files Reference

Adding New Features

Common Pitfalls & Solutions

Maintenance Notes

Reviews (0)