Expert guidance for building and maintaining the unofficial Paywise API TypeScript/JavaScript SDK with proper versioning, testing, and API conventions.
Expert guidance for developing the `paywise-api` npm package - an unofficial TypeScript/JavaScript client for the Paywise API.
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
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
```
Every commit MUST use semantic prefixes to trigger correct version bumps:
| Commit Prefix | Version Bump | Use Case | Example |
|---------------|--------------|----------|---------|
| `fix:` | Patch (1.0.X) | Bug fixes, security patches | `fix: handle 429 rate limit errors` |
| `feat:` | Minor (1.X.0) | New features (backward compatible) | `feat: add batch claim creation` |
| `feat!:` or `BREAKING CHANGE:` | Major (X.0.0) | Breaking API changes | `feat!: change Amount type structure` |
| `docs:` | No release | Documentation only | `docs: update README examples` |
| `chore:` | No release | Maintenance tasks | `chore: update dependencies` |
| `test:` | No release | Test additions/fixes | `test: add mock API tests` |
**Before pushing**: Always verify the new version doesn't already exist on NPM!
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**:
```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
```
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
| 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 |
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`)
| 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 |
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).
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/paywise-api-typescript-sdk/raw