npm package: @mappify/sdk
Description: Official Mappify SDK for JavaScript and TypeScript
Author: Mappify
Latest version: 1.0.0

# @mappify/sdk

Official Mappify SDK for JavaScript and TypeScript.

## Installation

```bash
npm install @mappify/sdk
# or
yarn add @mappify/sdk
# or
pnpm add @mappify/sdk
```

## Requirements

- Node.js 18+
- TypeScript 4.5+ (optional but recommended)

## Quick Start

```typescript
import { MappifyClient } from '@mappify/sdk';

const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY!,
  environment: 'sandbox', // or 'production'
});

// Create a route
const route = await client.routes.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  destination: { lat: 41.4036, lng: 2.1744 },
  profile: 'driving',
  optimize_for: 'time',
});

console.log('Distance:', route.distance_meters, 'meters');
console.log('Duration:', route.duration_seconds, 'seconds');
```

## Features

### Routes API

Create routes between coordinates with various options.

```typescript
const route = await client.routes.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  destination: { lat: 41.4036, lng: 2.1744 },
  waypoints: [{ lat: 41.39, lng: 2.17 }],
  profile: 'driving_delivery',
  optimize_for: 'time',
  avoid: { tolls: true },
});
```

### Optimizations API (Beta)

Multi-stop route optimization.

```typescript
const optimization = await client.optimizations.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  stops: [
    { lat: 41.39, lng: 2.17 },
    { lat: 41.40, lng: 2.18 },
    { lat: 41.41, lng: 2.16 },
  ],
  profile: 'driving_delivery',
});

console.log('Optimized order:', optimization.optimized_order);
```

### Navigation API

Real-time navigation sessions with turn-by-turn guidance.

```typescript
// Create a session
const session = await client.navigation.createSession({
  route_id: route.route_id,
  driver_id: 'driver_123',
});

// Update with device location
const state = await client.navigation.updateSession(session.session_id, {
  position: { lat: 41.388, lng: 2.169 },
});

console.log('Next instruction:', state.current_step.instruction);
console.log('ETA:', state.eta);
```

### Signals API

Get traffic, incidents, and signals data.

```typescript
// Signals around a position
const signals = await client.signals.getSignals({
  lat: 41.3874,
  lng: 2.1686,
  radius_meters: 300,
  types: ['congestion', 'incident'],
});

// Signals along a route
const routeSignals = await client.signals.getSignalsForRoute({
  route_id: route.route_id,
});
```

### Telemetry API

Send driver and device events.

```typescript
await client.telemetry.sendEvent({
  event_type: 'navigation_started',
  session_id: session.session_id,
  driver_id: 'driver_123',
  position: { lat: 41.3874, lng: 2.1686 },
});
```

## Error Handling

```typescript
import { MappifyApiError } from '@mappify/sdk';

try {
  const route = await client.routes.create({ /* ... */ });
} catch (error) {
  if (error instanceof MappifyApiError) {
    console.error('API Error:', {
      status: error.status,
      type: error.type,
      message: error.message,
      requestId: error.requestId,
    });
  }
}
```

## Configuration

```typescript
const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY!,
  environment: 'sandbox',
  timeoutMs: 10000, // Optional: request timeout
  baseUrlOverride: 'https://custom.api.com/v1', // Optional: for enterprise
});
```

## CommonJS

```javascript
const { MappifyClient } = require('@mappify/sdk');

const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY,
  environment: 'sandbox',
});
```

## Documentation

Full documentation available at [mappify.app/docs/sdks/javascript](https://mappify.app/docs/sdks/javascript)

## License

MIT © Mappify