io.github.shopanaio/novaposhta

Install

Config snippet generator goes here (5 client tabs)

README

<div align="center">

# @shopana/carrier-api

**Modern type-safe API clients for shipping carriers**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://www.apache.org/licenses/LICENSE-2.0)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
[![Monorepo](https://img.shields.io/badge/Monorepo-Yarn%20Workspaces-2C8EBB.svg?style=flat-square)](https://yarnpkg.com/features/workspaces)

[Features](#-features) • [Packages](#-packages) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🚀 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](./packages/novaposhta-api-client)

[![npm version](https://img.shields.io/npm/v/@shopana/novaposhta-api-client.svg?style=flat-square)](https://www.npmjs.com/package/@shopana/novaposhta-api-client)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@shopana/novaposhta-api-client?style=flat-square)](https://bundlephobia.com/package/@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

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

[📚 Documentation](./packages/novaposhta-api-client/README.md)

---

### AI Integration

#### [@shopana/novaposhta-mcp-server](./packages/novaposhta-mcp-server)

[![npm version](https://img.shields.io/npm/v/@shopana/novaposhta-mcp-server.svg?style=flat-square)](https://www.npmjs.com/package/@shopana/novaposhta-mcp-server)
[![MCP](https://img.shields.io/badge/MCP-1.22+-green.svg?style=flat-square)](https://modelcontextprotocol.io)
[![MCP Badge](https://lobehub.com/badge/mcp/shopanaio-carrier-api)](https://lobehub.com/mcp/shopanaio-carrier-api)

**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

```bash
npx @shopana/novaposhta-mcp-server
```

[📚 Documentation](./packages/novaposhta-mcp-server/README.md)

---

### Transport Implementations

#### [@shopana/novaposhta-transport-fetch](./packages/novaposhta-transport-fetch)

[![npm version](https://img.shields.io/npm/v/@shopana/novaposhta-transport-fetch.svg?style=flat-square)](https://www.npmjs.com/package/@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

```bash
npm i @shopana/novaposhta-transport-fetch
```

[📚 Documentation](./packages/novaposhta-transport-fetch/README.md)

---

## 🚀 Quick Start

### Nova Poshta API Client

```typescript
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 f