{
"markdown": "\n\n# @shopana/carrier-api\n\n**Modern type-safe API clients for shipping carriers**\n\n[](https://www.apache.org/licenses/LICENSE-2.0)\n[](https://www.typescriptlang.org/)\n[](https://yarnpkg.com/features/workspaces)\n\n[Features](#-features) β’ [Packages](#-packages) β’ [Quick Start](#-quick-start) β’ [Documentation](#-documentation) β’ [Contributing](#-contributing)\n\n
\n\n---\n\n## π Overview\n\nA production-ready monorepo containing **enterprise-grade TypeScript API clients** for shipping carriers. Built with modern architecture patterns, each client features plugin-based design, full type safety, and transport-agnostic implementation.\n\n### π― Why Carrier API?\n\n- β¨ **Type-Safe**: Complete TypeScript coverage with strict typing\n- π **Plugin Architecture**: Use only what you need, tree-shake the rest\n- π **Universal**: Works in Node.js, browsers, and edge runtimes\n- π¨ **Transport-Agnostic**: Bring your own HTTP client\n- π€ **AI-Ready**: MCP server for Claude and other AI assistants\n- π¦ **Zero Config**: Sensible defaults, works out of the box\n\n---\n\n## π¦ Packages\n\n### Carrier API Clients\n\n#### [@shopana/novaposhta-api-client](./packages/novaposhta-api-client)\n\n[](https://www.npmjs.com/package/@shopana/novaposhta-api-client)\n[](https://bundlephobia.com/package/@shopana/novaposhta-api-client)\n\n**Nova Poshta API client** with plugin architecture and complete type safety.\n\n**Features:**\n- π§ Plugin-based services (Address, Reference, Tracking, Waybill, Counterparty, ContactPerson)\n- π Namespaced API: `client.address.*`, `client.reference.*`, `client.tracking.*`, `client.waybill.*`\n- π― Full TypeScript support with strict typing\n- π Transport-agnostic design\n- π³ Tree-shakeable - only bundle what you use\n- π Comprehensive documentation with examples\n\n```bash\nnpm i @shopana/novaposhta-api-client @shopana/novaposhta-transport-fetch\n```\n\n[π Documentation](./packages/novaposhta-api-client/README.md)\n\n---\n\n### AI Integration\n\n#### [@shopana/novaposhta-mcp-server](./packages/novaposhta-mcp-server)\n\n[](https://www.npmjs.com/package/@shopana/novaposhta-mcp-server)\n[](https://modelcontextprotocol.io)\n[](https://lobehub.com/mcp/shopanaio-carrier-api)\n\n**Model Context Protocol (MCP) server** for integrating Nova Poshta with AI assistants like Claude.\n\n**Features:**\n- π€ Full MCP 1.22+ support\n- π Comprehensive tracking and address search\n- π Waybill creation and management\n- π Reference data access\n- π Dual transport (stdio + HTTP)\n- π’ Production-ready with enterprise-grade error handling\n\n```bash\nnpx @shopana/novaposhta-mcp-server\n```\n\n[π Documentation](./packages/novaposhta-mcp-server/README.md)\n\n---\n\n### Transport Implementations\n\n#### [@shopana/novaposhta-transport-fetch](./packages/novaposhta-transport-fetch)\n\n[](https://www.npmjs.com/package/@shopana/novaposhta-transport-fetch)\n\n**Fetch-based HTTP transport** for Nova Poshta API client.\n\n**Features:**\n- π Cross-platform (Node.js, browsers, edge runtimes)\n- βοΈ Configurable headers and fetch implementation\n- π« AbortSignal support for request cancellation\n- π¦ Minimal dependencies\n- β‘ Lightweight and fast\n\n```bash\nnpm i @shopana/novaposhta-transport-fetch\n```\n\n[π Documentation](./packages/novaposhta-transport-fetch/README.md)\n\n---\n\n## π Quick Start\n\n### Nova Poshta API Client\n\n```typescript\nimport { createClient, AddressService, ReferenceService, TrackingService } from '@shopana/novaposhta-api-client';\nimport { createFetchHttpTransport } from '@shopana/novaposhta-transport-fetch';\n\n// Create client with plugins\nconst client = createClient({\n transport: createFetchHttpTransport(),\n baseUrl: 'https://api.novaposhta.ua/v2.0/json/',\n apiKey: process.env.NOVA_POSHTA_API_KEY,\n})\n .use(new AddressService())\n .use(new ReferenceService())\n .use(new TrackingService());\n\n// Use the namespaced API\nconst cities = await client.address.searchCities({ FindByString: 'ΠΠΈΡΠ²', Limit: 10 });\nconst cargoTypes = await client.reference.getCargoTypes();\nconst tracking = await client.tracking.trackDocument({ Documents: ['20450123456789'] });\n\nconsole.log('Found cities:', cities.data.length);\nconsole.log('Package status:', tracking.data[0].Status);\n```\n\n### MCP Server for AI Assistants\n\nAdd to your `.mcp.json` or Claude Desktop config:\n\n```json\n{\n \"mcpServers\": {\n \"novaposhta\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"@shopana/novaposhta-mcp-server\", \"novaposhta-mcp\"],\n \"env\": {\n \"NOVA_POSHTA_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\nThen ask Claude:\n- \"Track Nova Poshta package 20450123456789\"\n- \"Find warehouses in Kyiv with POS terminals\"\n- \"Calculate shipping cost from Kyiv to Lviv for 5kg parcel\"\n\n---\n\n## ποΈ Architecture\n\nAll carrier clients in this monorepo follow a **consistent, battle-tested design pattern**:\n\n```\nβββββββββββββββββββββββββββββββββββββββββββ\nβ Your Application β\nββββββββββββββββ¬βββββββββββββββββββββββββββ\n β\n βΌ\nβββββββββββββββββββββββββββββββββββββββββββ\nβ Plugin-based API Client β\nβ ββββββββββββ ββββββββββββ βββββββββββ β\nβ β Address β βReference β βTracking β β\nβ β Service β β Service β β Service β β\nβ ββββββββββββ ββββββββββββ βββββββββββ β\nββββββββββββββββ¬βββββββββββββββββββββββββββ\n β\n βΌ\nβββββββββββββββββββββββββββββββββββββββββββ\nβ Transport Layer (Injectable) β\nβ fetch / axios / custom β\nβββββββββββββββββββββββββββββββββββββββββββ\n```\n\n### Key Principles\n\n- π **Plugin-based**: Connect only the services you need\n- π― **Type-safe**: Complete TypeScript coverage with inference\n- π¨ **Transport-agnostic**: Use fetch, axios, or custom HTTP client\n- π³ **Tree-shakeable**: Optimal bundle size - only what you use\n- π **Namespaced API**: Clean, organized method calls\n- π§ͺ **Testable**: Mock transport layer for unit tests\n\n---\n\n## π Documentation\n\n### Package Documentation\n\n- [Nova Poshta API Client](./packages/novaposhta-api-client/README.md)\n- [Nova Poshta MCP Server](./packages/novaposhta-mcp-server/README.md)\n- [Nova Poshta Transport (Fetch)](./packages/novaposhta-transport-fetch/README.md)\n\n### Additional Resources\n\n- [Nova Poshta API Official Docs](https://developers.novaposhta.ua/)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [TypeScript Documentation](https://www.typescriptlang.org/docs/)\n\n---\n\n## π οΈ Development\n\n### Prerequisites\n\n- Node.js 18+ or 20+\n- Yarn 3+ (Yarn Workspaces)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/shopanaio/carrier-api.git\ncd carrier-api\n\n# Install dependencies\nyarn install\n\n# Build all packages\nyarn build\n```\n\n### Available Scripts\n\n```bash\n# Development\nyarn dev # Watch mode for API client\nyarn dev:mcp:stdio # Run MCP server in stdio mode\nyarn dev:mcp:http # Run MCP server in HTTP mode\n\n# Building\nyarn build # Build API client\nyarn build:mcp # Build MCP server\n\n# Testing\nyarn test # Run all tests\nyarn test:watch # Run tests in watch mode\nyarn test:coverage # Generate coverage report\nyarn test:mcp # Run MCP server tests\n\n# Code Quality\nyarn lint # Lint TypeScript files\nyarn lint:fix # Fix linting issues\nyarn format # Format code with Prettier\nyarn format:check # Check code formatting\nyarn type-check # Run TypeScript type checking\n```\n\n### Project Structure\n\n```\ncarrier-api/\nβββ packages/\nβ βββ novaposhta-api-client/ # Core API client\nβ β βββ src/\nβ β β βββ core/ # Client core logic\nβ β β βββ services/ # Service plugins\nβ β β βββ types/ # TypeScript types\nβ β β βββ index.ts\nβ β βββ package.json\nβ β\nβ βββ novaposhta-mcp-server/ # MCP server for AI\nβ β βββ src/\nβ β β βββ cli/ # CLI entry points\nβ β β βββ tools/ # MCP tools\nβ β β βββ server.ts # Server implementation\nβ β β βββ config.ts\nβ β βββ package.json\nβ β\nβ βββ novaposhta-transport-fetch/ # Fetch transport\nβ βββ src/\nβ βββ package.json\nβ\nβββ e2e/ # End-to-end tests\nβββ postman/ # Postman collections\nβββ .mcp.json # MCP server config\nβββ package.json # Root package.json\n```\n\n---\n\n## π€ Contributing\n\nWe welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or examples - all contributions are appreciated.\n\n### How to Contribute\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes**: Follow our coding standards\n4. **Add tests**: Ensure your changes are tested\n5. **Run tests**: `yarn test` - make sure everything passes\n6. **Commit your changes**: `git commit -m 'feat: add amazing feature'`\n7. **Push to your fork**: `git push origin feature/amazing-feature`\n8. **Open a Pull Request**\n\n### Development Guidelines\n\n- Write clean, readable TypeScript code\n- Follow the existing code style\n- Add tests for new functionality\n- Update documentation as needed\n- Use conventional commits (feat, fix, docs, chore, etc.)\n\n### Changesets and releases\n\nPackage releases are automated with GitHub Actions and Changesets. Changes to\npackage source files, package scripts, or package manifests must include a\nuser-facing Changeset generated with:\n\n```sh\nyarn changeset\n```\n\nSelect every affected public package and use `patch` for backwards-compatible\nfixes or `minor` for backwards-compatible features. Major Changesets and\nplaceholder release notes are rejected automatically. Documentation-only,\ntest-only, and repository maintenance changes do not need a Changeset.\n\nThe `Changeset Required` workflow checks pull requests before release automation\ncan run.\n\nReleases use the `main` branch:\n\n1. Merge a source change and its `.changeset/*.md` file into `main`.\n2. The `Release` workflow opens a `chore: version packages` pull request.\n3. Review and merge that version pull request.\n4. The same workflow builds and publishes stable package versions to npm with\n the `latest` tag and creates GitHub releases.\n\nManual release packaging checks are:\n\n```sh\nyarn build\nyarn pack:dry-run\n```\n\nnpm publishing uses Trusted Publishing/OIDC. Configure every public npm package\nto trust the `shopanaio/carrier-api` repository and\n`.github/workflows/release.yml`. Packages that do not exist on npm yet require a\nrepository `NPM_TOKEN` secret for their first publication; it can be removed\nafter Trusted Publishing is configured. A `CHANGESETS_TOKEN` secret is optional\nand is only needed when the default `GITHUB_TOKEN` cannot manage release pull\nrequests.\n\n### Reporting Issues\n\nFound a bug or have a feature request? Please [open an issue](https://github.com/shopanaio/carrier-api/issues) with:\n\n- Clear description of the issue\n- Steps to reproduce (for bugs)\n- Expected vs actual behavior\n- Environment details (Node.js version, OS, etc.)\n\n---\n\n## πΊοΈ Roadmap\n\n### Planned Features\n\n- [ ] Additional carrier integrations\n- [ ] GraphQL API layer\n- [ ] React hooks package\n- [ ] CLI tool for common operations\n- [ ] Webhook handling utilities\n- [ ] Rate limiting and retry strategies\n- [ ] Caching layer with configurable adapters\n\n### Future Carriers\n\n**Eastern Europe:**\n- Ukrposhta\n- Meest\n- Justin\n- Delivery\n\n**International:**\n- DHL\n- FedEx\n- UPS\n- DPD\n\nWant to help implement these? [Contributions welcome!](#-contributing)\n\n---\n\n## π Status\n\n| Package | Version | Build | Coverage | Downloads |\n|---------|---------|-------|----------|-----------|\n| [@shopana/novaposhta-api-client](https://www.npmjs.com/package/@shopana/novaposhta-api-client) | [](https://www.npmjs.com/package/@shopana/novaposhta-api-client) |  |  |  |\n| [@shopana/novaposhta-mcp-server](https://www.npmjs.com/package/@shopana/novaposhta-mcp-server) | [](https://www.npmjs.com/package/@shopana/novaposhta-mcp-server) |  |  |  |\n| [@shopana/novaposhta-transport-fetch](https://www.npmjs.com/package/@shopana/novaposhta-transport-fetch) | [](https://www.npmjs.com/package/@shopana/novaposhta-transport-fetch) |  |  |  |\n\n---\n\n## π License\n\nApache License 2.0 - see [LICENSE](./LICENSE) for details.\n\nThis project is licensed under the Apache License 2.0, which means:\n- β
Commercial use allowed\n- β
Modification allowed\n- β
Distribution allowed\n- β
Patent use allowed\n- β
Private use allowed\n\n---\n\n## π¬ Support & Community\n\n- **Issues**: [GitHub Issues](https://github.com/shopanaio/carrier-api/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/shopanaio/carrier-api/discussions)\n- **Email**: [support@shopana.io](mailto:support@shopana.io)\n- **Website**: [shopana.io](https://shopana.io)\n\n---\n\n## π Acknowledgments\n\n- [Nova Poshta](https://novaposhta.ua) for their comprehensive API\n- [Model Context Protocol](https://modelcontextprotocol.io) team at Anthropic\n- All contributors who help improve this project\n\n---\n\n\n\n**Made with β€οΈ by [Shopana.io](https://shopana.io)**\n\n[](https://github.com/shopanaio/carrier-api)\n[](https://github.com/shopanaio/carrier-api/fork)\n[](https://github.com/shopanaio/carrier-api)\n\n[β¬ Back to Top](#shopanacarrier-api)\n\n
\n",
"bytes": 15458,
"sha": "214a41ec8f2a2d2b87d50dfbcd53d038fe442adb0d6852217582a0fcd355ba1b",
"repo_slug": "shopanaio/carrier-api",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_shopanaio_novaposhta_87a76146/readme"
}