{"_id":"@callmidavid/apidiff","name":"@callmidavid/apidiff","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@callmidavid/apidiff","version":"1.0.0","description":"Real-time API contract drift detector & sniffing proxy for JavaScript/TypeScript and Node.js applications","main":"index.js","bin":{"apidiff":"bin/apidiff.js"},"scripts":{"start":"node ./bin/apidiff.js","test":"echo \"APIDiff Go tests pass via 'go test ./...'\" && exit 0"},"repository":{"type":"git","url":"git+https://github.com/callmidavid/apidiff.git"},"bugs":{"url":"https://github.com/callmidavid/apidiff/issues"},"homepage":"https://github.com/callmidavid/apidiff#readme","keywords":["apidiff","api-contract","proxy","typescript","javascript","devtools","contract-testing","express-middleware","network-sniffer"],"author":{"name":"CallmiDavid"},"license":"MIT","engines":{"node":">=16.0.0"},"_id":"@callmidavid/apidiff@1.0.0","gitHead":"178be7a8b3d9a937df7da15f833d56e8a825adb7","types":"./index.d.ts","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-YaIgUF67zheDLPjqGlYVXzBrHnvBmwqHYPcsfttBcvc9QHc9cg0MT/2j5tTY3+xCXXtxoWhdGmch2r/INt9i9A==","shasum":"1b1fe0d5936c78444211d73ce40bbf14c741c03e","tarball":"https://registry.npmjs.org/@callmidavid/apidiff/-/apidiff-1.0.0.tgz","fileCount":22,"unpackedSize":83837,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHmTAnYSrLMddt/CjKvwCR28F0/wlPfEW2rTOvP/an7zAiAoFaj6Ono/nujoLcnqlbmaeLGoovOc6VlIEDwJzue9hQ=="}]},"_npmUser":{"name":"callmidavid","email":"mickyyoung660@gmail.com"},"directories":{},"maintainers":[{"name":"callmidavid","email":"mickyyoung660@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/apidiff_1.0.0_1786474178899_0.748523272243641"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-11T18:49:38.718Z","1.0.0":"2026-08-11T18:49:39.037Z","modified":"2026-08-11T18:49:39.263Z"},"maintainers":[{"name":"callmidavid","email":"mickyyoung660@gmail.com"}],"description":"Real-time API contract drift detector & sniffing proxy for JavaScript/TypeScript and Node.js applications","homepage":"https://github.com/callmidavid/apidiff#readme","keywords":["apidiff","api-contract","proxy","typescript","javascript","devtools","contract-testing","express-middleware","network-sniffer"],"repository":{"type":"git","url":"git+https://github.com/callmidavid/apidiff.git"},"author":{"name":"CallmiDavid"},"bugs":{"url":"https://github.com/callmidavid/apidiff/issues"},"license":"MIT","readme":"# ⚡ APIDiff\n\n> **Real-time API contract drift detector & lightweight sniffing proxy.**\n> Protect your frontend from silent backend database type changes, breaking schema shifts, and field removals the millisecond they happen.\n\n---\n\n## The Pain\n\nThe backend team changes a database column type or schema payload without notifying anyone. Your frontend state management or UI components silently break, and you waste hours debugging local state before realizing the raw network payload structure mutated.\n\n## The Solution\n\n**APIDiff** is a lightweight reverse proxy and local dashboard that sniffs local network traffic, infers JSON schema structures, locks baseline data contracts, and alerts you with visual structural diffs the instant an API contract breaks.\n\n---\n\n## Features\n\n- **Real-Time Traffic Sniffer**: Intercepts HTTP/JSON requests and responses without modifying payload data.\n- **Automatic Schema Extraction**: Infers full JSON schemas (primitives, nested objects, array element types, required keys).\n- **Millisecond Breaking Change Alerts**:\n  - **Type Mutations**: Detects `integer` ➔ `string` (`99812` ➔ `\"99812\"`).\n  - **Field Removals**: Flags missing required keys in response bodies.\n  - **Nullability Violations**: Detects when non-null properties suddenly return `null`.\n  - **Additive Changes**: Tracks newly introduced non-breaking properties.\n- **TypeScript Type Exporter**: Generates `.d.ts` interface definitions directly from locked baseline schemas.\n- **JavaScript & Node.js Native Support**: Installable via `npx` / `npm` and importable into Express/Fastify/Next.js applications.\n- **Embedded Web Dashboard**: Native single-binary web interface accessible at `http://localhost:8787` with real-time SSE updates.\n- **Built-in Contract Simulator**: 1-click test triggers (`Type Mismatch`, `Removed Field`, `Nullability Violation`) to test contract alerts instantly.\n- **Persistent Contract Storage**: Saved baseline contracts persist across restarts in `~/.apidiff/baselines.json`.\n\n---\n\n## Quick Start\n\n### 1. For Go Engineers\n\n```bash\ngit clone https://github.com/callmidavid/apidiff.git\ncd apidiff\ngo build -o apidiff cmd/apidiff/main.go\n./apidiff --port 8787 --target http://localhost:3000\n```\n\n### 2. For JavaScript & TypeScript Engineers\n\n#### Run directly via `npx`:\n\n```bash\nnpx @callmidavid/apidiff --port 8787 --target http://localhost:3000\n```\n\n### Global Installation via NPM\n```bash\nnpm install -g @callmidavid/apidiff\napidiff --port 8787 --target http://localhost:3000\n```\n\n### Programmable Integration in Node.js / Express\n```ts\nimport APIDiff from \"@callmidavid/apidiff\";\n\nconst apidiff = new APIDiff({\n  port: 8787,\n  target: \"http://localhost:3000\",\n});\n\nawait apidiff.start();\n```\n\n---\n\n## TypeScript Interface Generation\n\nAPIDiff automatically converts locked baseline API payload contracts into TypeScript type definitions:\n\n- **Dashboard UI**: Click **`Export TypeScript Types (.d.ts)`** on [http://localhost:8787](http://localhost:8787).\n- **HTTP Endpoint**: Download directly via `GET http://localhost:8787/_apidiff/api/export/typescript`.\n\nExample output:\n\n```typescript\n// Auto-generated by APIDiff\nexport interface GetUsersResponse {\n  email: string;\n  id: number;\n  is_active: boolean;\n  roles: string[];\n  score: number;\n  username: string;\n}\n```\n\n---\n\n### Production-Grade Capabilities\n\n1. **Low Overhead**: Built with Go standard library `httputil.NewSingleHostReverseProxy` for ultra-low latency transparent proxying.\n2. **Memory Safety**: Uses thread-safe mutex locking (`sync.RWMutex`) and a bounded ring buffer (500 requests max) to prevent memory leaks under high traffic load.\n3. **Resilient SSE Streaming**: Non-blocking Server-Sent Events hub with drop safety ensures slow dashboard clients don't block API proxy throughput.\n4. **Single Binary Deployment**: Zero runtime dependencies—the full Web Dashboard is compiled into the binary using `go:embed`.\n\n---\n\n## Project Directory Structure\n\n```\n.\n├── bin/                 # Node.js CLI executable wrapper (npx support)\n├── cmd/\n│   └── apidiff/         # Main Go application entry point\n├── docs/                # Architectural & schema diff specification docs\n├── internal/\n│   ├── capture/         # Network traffic payload & header sanitization\n│   ├── config/          # Configuration loader\n│   ├── contract/        # TypeScript interface generator & contract exports\n│   ├── diff/            # Real-time JSON schema diffing engine & tests\n│   ├── events/          # Server-Sent Events (SSE) broadcasting hub\n│   ├── mock/            # Built-in interactive contract drift simulator\n│   ├── proxy/           # HTTP reverse proxy & traffic sniffing interceptor\n│   ├── schema/          # Recursive JSON schema inference engine\n│   ├── server/          # HTTP server router & REST API controllers\n│   └── storage/         # Thread-safe in-memory store & disk persistence\n├── pkg/\n│   └── types/           # Core domain models (SchemaNode, ContractDiff, etc.)\n├── tests/               # End-to-end proxy integration tests\n├── web/                 # Web Dashboard single-page app (embedded via go:embed)\n├── index.js             # JavaScript/Node.js module export\n├── index.d.ts           # TypeScript module declarations\n├── package.json         # NPM package metadata\n├── CONTRIBUTING.md      # Developer contribution guide\n└── LICENSE              # MIT License\n```\n\n---\n\n## Architecture\n\n```\n[ Frontend App ]\n       │\n       ▼\n┌────────────────────────────────────────────────────────┐\n│ APIDiff Proxy Server (Port 8787)                       │\n│                                                        │\n│  ├─ Proxy Interceptor  ──>  [ Target API Server ]      │\n│  ├─ Schema Engine      ──>  Infer JSON Schema          │\n│  ├─ Contract Diff      ──>  Compare vs Baseline        │\n│  └─ Storage & SSE Hub  ──>  Broadcast Alerts           │\n└────────────────────────────────────────────────────────┘\n       │\n       ▼\n[ Web Dashboard & Diff Viewer ] (http://localhost:8787)\n```\n\n---\n\n## Testing\n\nRun the full test suite (including unit tests and end-to-end proxy tests):\n\n```bash\ngo test -v ./...\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and development workflow.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md","_rev":"1-bf0a43a9a925a75db2d407f1f3b9fbfc"}