@shopana/carrier-api

Modern type-safe API clients for shipping carriers

Features • Packages • Quick Start • Documentation • Contributing

🚀 Overview

A 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.

🎯 Why Carrier API?

✨ Type-Safe: Complete TypeScript coverage with strict typing
🔌 Plugin Architecture: Use only what you need, tree-shake the rest
🌐 Universal: Works in Node.js, browsers, and edge runtimes
🎨 Transport-Agnostic: Bring your own HTTP client
🤖 AI-Ready: MCP server for Claude and other AI assistants
📦 Zero Config: Sensible defaults, works out of the box

📦 Packages

Carrier API Clients

@shopana/novaposhta-api-client

Nova Poshta API client with plugin architecture and complete type safety.

Features:

🔧 Plugin-based services (Address, Reference, Tracking, Waybill, Counterparty, ContactPerson)
📛 Namespaced API: client.address.*, client.reference.*, client.tracking.*, client.waybill.*
🎯 Full TypeScript support with strict typing
🔄 Transport-agnostic design
🌳 Tree-shakeable - only bundle what you use
📖 Comprehensive documentation with examples

npm i @shopana/novaposhta-api-client @shopana/novaposhta-transport-fetch

📚 Documentation

AI Integration

@shopana/novaposhta-mcp-server

Model Context Protocol (MCP) server for integrating Nova Poshta with AI assistants like Claude.

Features:

🤖 Full MCP 1.22+ support
📍 Comprehensive tracking and address search
📝 Waybill creation and management
📚 Reference data access
🔄 Dual transport (stdio + HTTP)
🏢 Production-ready with enterprise-grade error handling

npx @shopana/novaposhta-mcp-server

📚 Documentation

Transport Implementations

@shopana/novaposhta-transport-fetch

Fetch-based HTTP transport for Nova Poshta API client.

Features:

🌐 Cross-platform (Node.js, browsers, edge runtimes)
⚙️ Configurable headers and fetch implementation
🚫 AbortSignal support for request cancellation
📦 Minimal dependencies
⚡ Lightweight and fast

npm i @shopana/novaposhta-transport-fetch

📚 Documentation

🚀 Quick Start

Nova Poshta API Client

import { createClient, AddressService, ReferenceService, TrackingService } from '@shopana/novaposhta-api-client';
import { createFetchHttpTransport } from '@shopana/novaposhta-transport-fetch';

// Create client with plugins
const client = createClient({
  transport: createFetchHttpTransport(),
  baseUrl: 'https://api.novaposhta.ua/v2.0/json/',
  apiKey: process.env.NOVA_POSHTA_API_KEY,
})
  .use(new AddressService())
  .use(new ReferenceService())
  .use(new TrackingService());

// Use the namespaced API
const cities = await client.address.searchCities({ FindByString: 'Київ', Limit: 10 });
const cargoTypes = await client.reference.getCargoTypes();
const tracking = await client.tracking.trackDocument({ Documents: ['20450123456789'] });

console.log('Found cities:', cities.data.length);
console.log('Package status:', tracking.data[0].Status);

MCP Server for AI Assistants

Add to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "novaposhta": {
      "command": "npx",
      "args": ["-y", "-p", "@shopana/novaposhta-mcp-server", "novaposhta-mcp"],
      "env": {
        "NOVA_POSHTA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Then ask Claude:

"Track Nova Poshta package 20450123456789"
"Find warehouses in Kyiv with POS terminals"
"Calculate shipping cost from Kyiv to Lviv for 5kg parcel"

🏗️ Architecture

All carrier clients in this monorepo follow a consistent, battle-tested design pattern:

┌─────────────────────────────────────────┐
│           Your Application              │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│      Plugin-based API Client            │
│  ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│  │ Address  │ │Reference │ │Tracking │ │
│  │ Service  │ │ Service  │ │ Service │ │
│  └──────────┘ └──────────┘ └─────────┘ │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│      Transport Layer (Injectable)       │
│         fetch / axios / custom          │
└─────────────────────────────────────────┘

Key Principles

🔌 Plugin-based: Connect only the services you need
🎯 Type-safe: Complete TypeScript coverage with inference
🎨 Transport-agnostic: Use fetch, axios, or custom HTTP client
🌳 Tree-shakeable: Optimal bundle size - only what you use
📛 Namespaced API: Clean, organized method calls
🧪 Testable: Mock transport layer for unit tests

📚 Documentation

Package Documentation

Additional Resources

🛠️ Development

Prerequisites

Node.js 18+ or 20+
Yarn 3+ (Yarn Workspaces)

Setup

# Clone the repository
git clone https://github.com/shopanaio/carrier-api.git
cd carrier-api

# Install dependencies
yarn install

# Build all packages
yarn build

Available Scripts

# Development
yarn dev                  # Watch mode for API client
yarn dev:mcp:stdio        # Run MCP server in stdio mode
yarn dev:mcp:http         # Run MCP server in HTTP mode

# Building
yarn build                # Build API client
yarn build:mcp            # Build MCP server

# Testing
yarn test                 # Run all tests
yarn test:watch           # Run tests in watch mode
yarn test:coverage        # Generate coverage report
yarn test:mcp             # Run MCP server tests

# Code Quality
yarn lint                 # Lint TypeScript files
yarn lint:fix             # Fix linting issues
yarn format               # Format code with Prettier
yarn format:check         # Check code formatting
yarn type-check           # Run TypeScript type checking

Project Structure

carrier-api/
├── packages/
│   ├── novaposhta-api-client/       # Core API client
│   │   ├── src/
│   │   │   ├── core/                # Client core logic
│   │   │   ├── services/            # Service plugins
│   │   │   ├── types/               # TypeScript types
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── novaposhta-mcp-server/       # MCP server for AI
│   │   ├── src/
│   │   │   ├── cli/                 # CLI entry points
│   │   │   ├── tools/               # MCP tools
│   │   │   ├── server.ts            # Server implementation
│   │   │   └── config.ts
│   │   └── package.json
│   │
│   └── novaposhta-transport-fetch/  # Fetch transport
│       ├── src/
│       └── package.json
│
├── e2e/                             # End-to-end tests
├── postman/                         # Postman collections
├── .mcp.json                        # MCP server config
└── package.json                     # Root package.json

🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or examples - all contributions are appreciated.