{"_id":"@us-legal-tools/courtlistener-sdk","_rev":"3-caca0ee608d7b5cbdf33fe7498c6462a","name":"@us-legal-tools/courtlistener-sdk","dist-tags":{"latest":"1.5.2"},"versions":{"1.4.1":{"name":"@us-legal-tools/courtlistener-sdk","version":"1.4.1","keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"license":"MIT","_id":"@us-legal-tools/courtlistener-sdk@1.4.1","maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"homepage":"https://github.com/beshkenadze/us-legal-tools#readme","bugs":{"url":"https://github.com/beshkenadze/us-legal-tools/issues"},"dist":{"shasum":"af7147a74bb4dbd3ffb62ce462f94ce30450b974","tarball":"https://registry.npmjs.org/@us-legal-tools/courtlistener-sdk/-/courtlistener-sdk-1.4.1.tgz","fileCount":290,"integrity":"sha512-Oj4UFldNX5KKjWSy9KrtXfi786o7HoBqoP34qSuQyFp/SIDa30T/zAzZKDBytnCXC+DvYr0Wzd7qkRjITOpvUA==","signatures":[{"sig":"MEYCIQDcANkIEyXTaFiLXrPa6YeQoUhgkNkqdUS9OoWJMQOQogIhAOeGGtettvbQ8j18EoaNKJkrtqU8bztozUV0pGhbX2hZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":453565},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp/index.d.ts","import":"./dist/mcp/index.mjs","require":"./dist/mcp/index.js"}},"gitHead":"e1d649df011d594b9accbe61ec75a1fe9ab04ae9","scripts":{"dev":"bun run src/index.ts","lint":"biome lint --write .","test":"bun test src","build":"bun run build.ts","check":"biome check --write .","format":"biome format --write .","check:ci":"biome ci .","download":"echo 'No download script defined, use `bun run generate` to generate the SDK from the API specification.'","generate":"orval","test:all":"bun test","mcp:server":"bun run src/mcp/server.ts","test:watch":"bun test --watch src","prepublishOnly":"bun run build","test:integration":"SKIP_INTEGRATION_TESTS=false bun test src"},"_npmUser":{"name":"beshkenadze","email":"beshkenadze@gmail.com"},"repository":{"url":"git+https://github.com/beshkenadze/us-legal-tools.git","type":"git","directory":"packages/courtlistener-sdk"},"_npmVersion":"11.4.2","description":"TypeScript SDK and MCP server for CourtListener API","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.1","axios":"^1.11.0","@modelcontextprotocol/sdk":"^1.17.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"orval":"^7.10.0","@types/bun":"latest","typescript":"^5.8.3","@types/node":"^24.1.0","@biomejs/biome":"2.1.2","@us-legal-tools/tsconfig":"workspace:*"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/courtlistener-sdk_1.4.1_1753892390139_0.7465473654429295","host":"s3://npm-registry-packages-npm-production"}},"1.5.1":{"name":"@us-legal-tools/courtlistener-sdk","version":"1.5.1","keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"license":"MIT","_id":"@us-legal-tools/courtlistener-sdk@1.5.1","maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"homepage":"https://github.com/beshkenadze/us-legal-tools#readme","bugs":{"url":"https://github.com/beshkenadze/us-legal-tools/issues"},"dist":{"shasum":"0f02b9b002c0dff3d7b9e711dfc9283f777d285a","tarball":"https://registry.npmjs.org/@us-legal-tools/courtlistener-sdk/-/courtlistener-sdk-1.5.1.tgz","fileCount":148,"integrity":"sha512-zsOz+/2CiV4bD5mCyh6QYYNbXPDbzSVrK6BfhvJzWq1JiIGeNUiwGzeQ+RBlT2LLYabUGiLAYdDWrpbcnz+Iiw==","signatures":[{"sig":"MEQCIEULDWyCKCGPJwxoLyk16mz/b71YyVB8PAfgn5scEwVdAiBg9CDrwNneHs6OP6ZCQQRA5LcY0dKxusnJqV+g+isfoA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":600459},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp/index.d.ts","import":"./dist/mcp/index.mjs","require":"./dist/mcp/index.js"}},"gitHead":"ce39d47e654fc2d12897ed9f5642c8e584e73e86","scripts":{"dev":"bun run src/index.ts","lint":"biome lint --write .","test":"bun test src","build":"bun run build.ts","check":"biome check --write .","format":"biome format --write .","check:ci":"biome ci .","download":"echo 'No download script defined, use `bun run generate` to generate the SDK from the API specification.'","generate":"NODE_OPTIONS='--max-old-space-size=4096' bun run --bun $(which orval)","test:all":"bun test","mcp:server":"bun run src/mcp/server.ts","test:watch":"bun test --watch src","prepublishOnly":"bun run build","test:integration":"SKIP_INTEGRATION_TESTS=false bun test src"},"_npmUser":{"name":"beshkenadze","email":"beshkenadze@gmail.com"},"repository":{"url":"git+https://github.com/beshkenadze/us-legal-tools.git","type":"git","directory":"packages/courtlistener-sdk"},"_npmVersion":"11.4.2","description":"TypeScript SDK and MCP server for CourtListener API","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.1","axios":"^1.11.0","@modelcontextprotocol/sdk":"^1.17.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"orval":"^7.10.0","@types/bun":"latest","typescript":"^5.8.3","@types/node":"^24.1.0","@biomejs/biome":"2.1.3","typedoc-plugin-markdown":"^4.8.0","@us-legal-tools/tsconfig":"workspace:*","@us-legal-tools/orval-config":"workspace:*"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/courtlistener-sdk_1.5.1_1754054103963_0.07498369137335437","host":"s3://npm-registry-packages-npm-production"}},"1.5.2":{"name":"@us-legal-tools/courtlistener-sdk","version":"1.5.2","description":"TypeScript SDK and MCP server for CourtListener API","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","type":"module","scripts":{"dev":"bun run src/index.ts","build":"bun run build.ts","generate":"NODE_OPTIONS='--max-old-space-size=4096' bun run --bun $(which orval)","format":"biome format --write .","lint":"biome lint --write .","check":"biome check --write .","check:ci":"biome ci .","prepublishOnly":"bun run build","test":"bun test src","test:watch":"bun test --watch src","test:integration":"SKIP_INTEGRATION_TESTS=false bun test src","test:all":"bun test","mcp:server":"bun run src/mcp/server.ts","download":"echo 'No download script defined, use `bun run generate` to generate the SDK from the API specification.'"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.1","axios":"^1.11.0","zod":"^3.24.1"},"devDependencies":{"@biomejs/biome":"2.1.3","@types/bun":"latest","@types/node":"^24.2.0","@us-legal-tools/orval-config":"workspace:*","@us-legal-tools/tsconfig":"workspace:*","orval":"^7.11.2","typedoc-plugin-markdown":"^4.8.0","typescript":"^5.8.3"},"peerDependencies":{"typescript":"^5.0.0"},"keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"homepage":"https://github.com/beshkenadze/us-legal-tools#readme","repository":{"type":"git","url":"git+https://github.com/beshkenadze/us-legal-tools.git","directory":"packages/courtlistener-sdk"},"bugs":{"url":"https://github.com/beshkenadze/us-legal-tools/issues"},"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"license":"MIT","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp/index.d.ts","import":"./dist/mcp/index.mjs","require":"./dist/mcp/index.js"}},"publishConfig":{"access":"public"},"_id":"@us-legal-tools/courtlistener-sdk@1.5.2","gitHead":"a3f8c8d04bf1590f7ba5cd29c6fb14d9ec8257af","_nodeVersion":"22.14.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-6/IJqiTbTj6oTIYqAG+w2tuF2ScedUt1IP2NsfRMYmssfQpmE7zz0au6zTIHFjEJ3WZr4+etguLw9uoHdd64yg==","shasum":"cb8a404c9cff6b57e7e153ed9e247a18c085a51b","tarball":"https://registry.npmjs.org/@us-legal-tools/courtlistener-sdk/-/courtlistener-sdk-1.5.2.tgz","fileCount":148,"unpackedSize":609001,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQChT5vExrJWsD1RWmkYu5lzl/JwyGCn6tCrBgnmLJRkXgIgfhSJGq/1SlEv0ySHcJ0Lu0HDU1TBlnG1Vs1dOJnEEFI="}]},"_npmUser":{"name":"beshkenadze","email":"beshkenadze@gmail.com"},"directories":{},"maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/courtlistener-sdk_1.5.2_1754311851387_0.9810352033417384"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-30T16:19:50.040Z","modified":"2025-08-04T12:50:51.750Z","1.4.1":"2025-07-30T16:19:50.312Z","1.5.1":"2025-08-01T13:15:04.229Z","1.5.2":"2025-08-04T12:50:51.582Z"},"bugs":{"url":"https://github.com/beshkenadze/us-legal-tools/issues"},"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"license":"MIT","homepage":"https://github.com/beshkenadze/us-legal-tools#readme","keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"repository":{"type":"git","url":"git+https://github.com/beshkenadze/us-legal-tools.git","directory":"packages/courtlistener-sdk"},"description":"TypeScript SDK and MCP server for CourtListener API","maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"readme":"<div align=\"center\">\n  <h1>@us-legal-tools/courtlistener-sdk</h1>\n  <p>\n    <strong>TypeScript SDK and MCP server for CourtListener - the largest free legal database</strong>\n  </p>\n  <p>\n    <a href=\"https://www.npmjs.com/package/@us-legal-tools/courtlistener-sdk\">\n      <img alt=\"npm version\" src=\"https://img.shields.io/npm/v/@us-legal-tools/courtlistener-sdk.svg?style=for-the-badge\">\n    </a>\n    <a href=\"https://www.npmjs.com/package/@us-legal-tools/courtlistener-sdk\">\n      <img alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/@us-legal-tools/courtlistener-sdk.svg?style=for-the-badge\">\n    </a>\n    <a href=\"https://github.com/beshkenadze/us-legal-tools/blob/main/LICENSE\">\n      <img alt=\"License\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge\">\n    </a>\n    <a href=\"https://github.com/beshkenadze/us-legal-tools/actions/workflows/validate.yml\">\n      <img alt=\"CI Status\" src=\"https://img.shields.io/github/actions/workflow/status/beshkenadze/us-legal-tools/validate.yml?branch=main&style=for-the-badge\">\n    </a>\n  </p>\n  <p>\n    <a href=\"#features\">Features</a> •\n    <a href=\"#installation\">Installation</a> •\n    <a href=\"#authentication\">Authentication</a> •\n    <a href=\"#quick-start\">Quick Start</a> •\n    <a href=\"#api-reference\">API</a> •\n    <a href=\"#mcp-server\">MCP Server</a> •\n    <a href=\"https://www.courtlistener.com/help/api/\">CourtListener API Docs</a>\n  </p>\n</div>\n\n## Features\n\n- ⚖️ **Case Law** - Access millions of legal opinions from federal and state courts\n- 👨‍⚖️ **Judge Data** - Comprehensive judge profiles and biographical information\n- 🎙️ **Oral Arguments** - Audio recordings with metadata\n- 📚 **Citation Tools** - Advanced citation lookup and normalization\n- 💼 **PACER Integration** - Federal court docket access\n- 🔔 **Real-time Alerts** - Track changes to cases and dockets\n- 🤖 **MCP Server** - AI-ready server for integration with Claude and other AI assistants\n- 🔍 **Advanced Search** - Powerful search with Elasticsearch backend\n- ✨ **Type-safe** - Full TypeScript support with auto-completion\n\n## Installation\n\n```bash\n# npm\nnpm install @us-legal-tools/courtlistener-sdk\n\n# yarn\nyarn add @us-legal-tools/courtlistener-sdk\n\n# pnpm\npnpm add @us-legal-tools/courtlistener-sdk\n\n# bun\nbun add @us-legal-tools/courtlistener-sdk\n```\n\n## Authentication\n\nThe CourtListener API requires authentication for most endpoints. Get your API token from [CourtListener](https://www.courtlistener.com/help/api/rest/#authentication).\n\n```typescript\n// Set via environment variable\nprocess.env.COURTLISTENER_API_TOKEN = 'your-token';\n\n// Or configure the axios instance directly\nimport { axiosInstance } from '@us-legal-tools/courtlistener-sdk';\naxiosInstance.defaults.headers.common['Authorization'] = 'Token your-token';\n```\n\n## Quick Start\n\n### Basic Search\n\n```typescript\nimport { getSearch } from '@us-legal-tools/courtlistener-sdk';\n\n// Search for Supreme Court cases\nconst results = await getSearch({\n  type: 'o', // 'o' for opinions\n  q: 'miranda rights',\n  court: 'scotus',\n  order_by: 'score desc'\n});\n\nconsole.log(`Found ${results.count} cases`);\nresults.results.forEach(result => {\n  console.log(`- ${result.caseName} (${result.dateFiled})`);\n});\n```\n\n### Get Case Details\n\n```typescript\nimport { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';\n\n// Get a specific opinion\nconst opinion = await getOpinionsId({ id: 123456 });\n\nconsole.log(`Case: ${opinion.case_name}`);\nconsole.log(`Court: ${opinion.court}`);\nconsole.log(`Date: ${opinion.date_filed}`);\nconsole.log(`Text: ${opinion.plain_text || opinion.html}`);\n```\n\n### Search Judges\n\n```typescript\nimport { getSearch } from '@us-legal-tools/courtlistener-sdk';\n\n// Search for judges\nconst judges = await getSearch({\n  type: 'p', // 'p' for people/judges\n  q: 'Ruth Bader Ginsburg',\n  order_by: 'name_reverse asc'\n});\n\njudges.results.forEach(judge => {\n  console.log(`${judge.name_full} - ${judge.court}`);\n});\n```\n\n### Get Audio Recordings\n\n```typescript\nimport { getAudio } from '@us-legal-tools/courtlistener-sdk';\n\n// Get oral arguments\nconst audio = await getAudio({\n  docket__court: 'scotus',\n  argued_after: '2023-01-01'\n});\n\naudio.results.forEach(recording => {\n  console.log(`${recording.case_name} - ${recording.date_argued}`);\n  console.log(`Audio: ${recording.download_url}`);\n});\n```\n\n## API Reference\n\n### Search Endpoints\n\n- `getSearch` - Universal search endpoint for all content types\n- `getSearchV4OpinionsClusters` - Search opinion clusters\n- `getSearchV4People` - Search judges and people\n- `getSearchV4OralArguments` - Search oral arguments\n\n### Opinion Endpoints\n\n- `getOpinions` - List opinions\n- `getOpinionsId` - Get specific opinion\n- `getClusters` - List opinion clusters\n- `getClustersId` - Get specific cluster\n\n### Judge/Person Endpoints\n\n- `getPeople` - List judges and people\n- `getPeopleId` - Get specific person details\n- `getPersonDisclosures` - Get financial disclosures\n\n### Docket Endpoints\n\n- `getDockets` - List dockets\n- `getDocketsId` - Get specific docket\n- `getDocketEntries` - List docket entries\n- `getDocketAlerts` - Manage docket alerts\n\n### Audio Endpoints\n\n- `getAudio` - List audio recordings\n- `getAudioId` - Get specific audio recording\n\n### Citation Endpoints\n\n- `getCitations` - Citation lookup\n- `getCitationNormalize` - Normalize citations\n\n## MCP Server\n\nThe MCP server allows AI assistants to interact with the CourtListener API.\n\n### Running the Server\n\n```bash\n# Using the SDK directly (requires COURTLISTENER_API_TOKEN env var)\nCOURTLISTENER_API_TOKEN=your-token npx @us-legal-tools/courtlistener-sdk/mcp\n\n# Or if installed locally\ncd node_modules/@us-legal-tools/courtlistener-sdk\nCOURTLISTENER_API_TOKEN=your-token npm run mcp:server\n```\n\n### Integration with Claude\n\nAdd to your Claude configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"courtlistener\": {\n      \"command\": \"npx\",\n      \"args\": [\"@us-legal-tools/courtlistener-sdk/mcp\"],\n      \"env\": {\n        \"COURTLISTENER_API_TOKEN\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n## Search Types\n\nUse the following types with the search endpoint:\n\n- `o` - Opinions\n- `r` - RECAP Archive\n- `d` - Dockets\n- `p` - People/Judges\n- `oa` - Oral Arguments\n- `opinion-cluster` - Opinion Clusters\n\n## Advanced Search\n\n```typescript\nimport { getSearch } from '@us-legal-tools/courtlistener-sdk';\n\n// Complex search with filters\nconst results = await getSearch({\n  type: 'o',\n  q: 'first amendment',\n  court: 'ca9 ca10 cafc',  // Multiple courts\n  filed_after: '2020-01-01',\n  filed_before: '2023-12-31',\n  cited_gt: 50,  // Cited more than 50 times\n  order_by: 'dateFiled desc',\n  highlight: true\n});\n```\n\n## Error Handling\n\n```typescript\nimport { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';\n\ntry {\n  const opinion = await getOpinionsId({ id: 123456 });\n} catch (error) {\n  if (error.response?.status === 401) {\n    console.error('Invalid API token');\n  } else if (error.response?.status === 404) {\n    console.error('Opinion not found');\n  } else if (error.response?.status === 429) {\n    console.error('Rate limit exceeded');\n  } else {\n    console.error('API error:', error.message);\n  }\n}\n```\n\n## Rate Limiting\n\nCourtListener has rate limits based on your account type. Free accounts are limited to 5,000 requests per day.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.\n\n## Links\n\n- [npm Package](https://www.npmjs.com/package/@us-legal-tools/courtlistener-sdk)\n- [GitHub Repository](https://github.com/beshkenadze/us-legal-tools)\n- [CourtListener Website](https://www.courtlistener.com/)\n- [CourtListener API Documentation](https://www.courtlistener.com/help/api/)\n- [Report Issues](https://github.com/beshkenadze/us-legal-tools/issues/new?labels=bug&template=bug-report.md)\n- [Request Features](https://github.com/beshkenadze/us-legal-tools/issues/new?labels=enhancement&template=feature-request.md)\n\n## Support\n\nNeed help? Check out our [documentation](https://github.com/beshkenadze/us-legal-tools) or [create an issue](https://github.com/beshkenadze/us-legal-tools/issues/new/choose).\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>","readmeFilename":"README.md"}