{"id":48997357,"url":"https://github.com/0-sayed/wallet","last_synced_at":"2026-04-18T17:14:26.440Z","repository":{"id":341214598,"uuid":"1168976263","full_name":"0-sayed/wallet","owner":"0-sayed","description":"Wallet and royalty API focused on idempotency, pessimistic locking, and atomic transactions.","archived":false,"fork":false,"pushed_at":"2026-04-12T07:08:39.000Z","size":393,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T08:22:47.437Z","etag":null,"topics":["bullmq","concurrency","drizzle-orm","idempotency","ledger","nestjs","payments","postgresql","redis","royalties","typescript","wallet"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0-sayed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T02:34:29.000Z","updated_at":"2026-04-12T07:08:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0-sayed/wallet","commit_stats":null,"previous_names":["0-sayed/wallet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/0-sayed/wallet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0-sayed%2Fwallet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0-sayed%2Fwallet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0-sayed%2Fwallet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0-sayed%2Fwallet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0-sayed","download_url":"https://codeload.github.com/0-sayed/wallet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0-sayed%2Fwallet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31976899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T16:27:12.723Z","status":"ssl_error","status_checked_at":"2026-04-18T16:27:11.140Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bullmq","concurrency","drizzle-orm","idempotency","ledger","nestjs","payments","postgresql","redis","royalties","typescript","wallet"],"created_at":"2026-04-18T17:14:26.269Z","updated_at":"2026-04-18T17:14:26.429Z","avatar_url":"https://github.com/0-sayed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wallet and Royalty API\n\n[![CI](https://github.com/0-sayed/wallet/actions/workflows/ci.yml/badge.svg)](https://github.com/0-sayed/wallet/actions/workflows/ci.yml)\n![Node 22](https://img.shields.io/badge/node-22-green)\n![TypeScript](https://img.shields.io/badge/typescript-strict-blue)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)\n\nA production-minded backend for wallet balances, royalty splits, and async financial reporting, designed around correctness under concurrency.\n\n## About\n\nThis project is a mini financial system API built to prioritise transactional integrity over raw HTTP throughput.\n\n- Uses PostgreSQL transactions and `SELECT FOR UPDATE` locking to prevent double-spending.\n- Enforces idempotency with a client-owned `Idempotency-Key` and database uniqueness constraints.\n- Stores all money as integer cents to avoid floating point errors.\n- Uses deterministic royalty math: author gets floor(70%), platform gets the remainder.\n- Uses BullMQ + Redis for non-blocking report generation.\n\n## Tech Stack\n\n- NestJS + TypeScript (strict)\n- PostgreSQL + Drizzle ORM\n- BullMQ + Redis\n- Jest + Supertest\n- Docker Compose + pnpm\n\n## API Surface\n\nAll endpoints except `/health` require an `X-User-Id` header (UUID).\n\n| Method | Path                         | Description                               | Extra Headers            |\n| ------ | ---------------------------- | ----------------------------------------- | ------------------------ |\n| `GET`  | `/health`                    | Health check                              | —                        |\n| `POST` | `/wallets/:walletId/deposit` | Deposit funds into a wallet               | —                        |\n| `POST` | `/purchases`                 | Purchase an item (3-wallet royalty split) | `Idempotency-Key` (UUID) |\n| `POST` | `/reports/financial`         | Request an async financial report         | —                        |\n| `GET`  | `/reports/financial/:jobId`  | Poll report status and result             | —                        |\n\nSwagger UI is available at `/api` when `SWAGGER_ENABLED=true`.\n\n## Run Locally\n\nPrerequisites: Node.js 22+, pnpm 9+, Docker + Docker Compose.\n\n1. Install dependencies.\n\n```bash\npnpm install\n```\n\n2. Create local environment file.\n\n```bash\ncp .env.example .env\n```\n\n3. Start PostgreSQL and Redis.\n\n```bash\ndocker compose up -d\n```\n\n4. Apply database migrations.\n\n```bash\npnpm db:migrate\n```\n\n5. Seed the platform account.\n\n```bash\npnpm db:seed\n```\n\n6. Start the API.\n\n```bash\npnpm start:dev\n```\n\n7. Verify health endpoint.\n\n```bash\ncurl -s http://localhost:3000/health\n# → { \"status\": \"ok\" }\n```\n\n## Commands\n\n| Command            | Description                                                      |\n| ------------------ | ---------------------------------------------------------------- |\n| `pnpm lint`        | ESLint with auto-fix                                             |\n| `pnpm format`      | Prettier write                                                   |\n| `pnpm typecheck`   | TypeScript type check                                            |\n| `pnpm test`        | Unit tests                                                       |\n| `pnpm test:e2e`    | E2e tests                                                        |\n| `pnpm test:cov`    | Unit tests with coverage                                         |\n| `pnpm knip`        | Dead code / unused deps check                                    |\n| `pnpm validate`    | Full local quality gate (lint + typecheck + test + knip + build) |\n| `pnpm db:generate` | Generate Drizzle migration from schema changes                   |\n| `pnpm db:migrate`  | Apply pending migrations                                         |\n| `pnpm db:seed`     | Seed platform user and wallet                                    |\n| `pnpm db:studio`   | Drizzle Studio GUI                                               |\n\n## Architecture\n\nFor system context diagrams, module structure, data model, concurrency details, and the full request lifecycle, see [docs/architecture.md](docs/architecture.md).\n\n## Design Decisions\n\nKey decisions are captured in ADRs:\n\n- [ADR-001: NestJS over Fastify](docs/adr/ADR-001-nestjs-over-fastify.md)\n- [ADR-002: PostgreSQL + Drizzle ORM](docs/adr/ADR-002-postgresql-drizzle.md)\n- [ADR-003: Integer Cents over NUMERIC](docs/adr/ADR-003-integer-cents.md)\n- [ADR-004: Pessimistic Locking over Optimistic](docs/adr/ADR-004-pessimistic-locking.md)\n- [ADR-005: Platform Receives Royalty Remainder](docs/adr/ADR-005-platform-royalty-remainder.md)\n- [ADR-006: BullMQ for Async Report Generation](docs/adr/ADR-006-bullmq-async-reports.md)\n- [ADR-007: Idempotency Key Owned by Client](docs/adr/ADR-007-client-owned-idempotency-key.md)\n\n## Project Docs\n\n- [Architecture](docs/architecture.md)\n- [Architecture decisions (ADR)](docs/adr/)\n- [Security policy](SECURITY.md)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0-sayed%2Fwallet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0-sayed%2Fwallet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0-sayed%2Fwallet/lists"}