npm package: @montarist/tamamliyo-api
Description: Unofficial TypeScript SDK for Tamamliyo partner APIs.
Author: Vignetim
Latest version: 0.1.9

# Unofficial Tamamliyo API

TypeScript SDK for the Tamamliyo partner APIs. It wraps the public insurance endpoints into a typed, enum-driven client with built-in retries, request validation, and response parsing.

## Features

- Automatic token header injection and configurable base URL/environment.
- Resilient HTTP layer with retries, timeouts, and backoff.
- Zod-based request/response validation covering Incoming Insurance, Foreign Health Insurance, and Transportation Insurance flows.
- Enumerations for common query modes (`QueryType`) and reusable schemas for geography lookups.
- Vitest + MSW test suite with coverage reporting.
- Ready-to-run examples and docs-driven API design (`docs/*.md`).

## Installation

```bash
pnpm add @montarist/tamamliyo-api
# or
npm install @montarist/tamamliyo-api
```

## Quick Start

```ts
import { ApiEnvironment, Client, QueryType } from '@montarist/tamamliyo-api';

const client = new Client({
  token: process.env.TAMAMLIYO_TOKEN!,
  environment: ApiEnvironment.Test, // defaults to production base URL
});

const quote = await client.incomingInsurance.createQuote({
  sorguTipi: QueryType.Passport,
  sigortaEttiren: {
    pasaportNo: 'X1234567',
    ad: 'Ada',
    soyad: 'Yilmaz',
    cinsiyet: 'K',
    uyruk: '33',
    babaAdi: 'Mehmet',
    dogumYeri: 'Paris',
    dogumTarihi: '1998-12-31',
  },
  sigortali: [
    {
      pasaportNo: 'X1234567',
      ad: 'Ada',
      soyad: 'Yilmaz',
      cinsiyet: 'K',
      uyruk: '33',
      babaAdi: 'Mehmet',
      dogumYeri: 'Paris',
      dogumTarihi: '1998-12-31',
      relationTypeId: 'F',
    },
  ],
  baslangicTarihi: '2024-05-01',
  bitisTarihi: '2024-05-15',
  email: 'partner@example.com',
  gsmNo: '5551234567',
  urunId: 110,
});

console.log(quote.data.teklifBilgileri.teklifId);
```

## API Surface

### Incoming Insurance

- `createQuote`
- `makePayment`
- `createPolicy`
- `getQuoteDetails`
- `listCountries`
- `listProvinces`
- `listDistricts`
- `getPolicyPdf`
- `getReceiptPdf`

### Green Card Insurance

- `getPrice`
- `createQuote`
- `makePayment`
- `createPolicy`
- `getPolicyPdf`
- `getCertificatePdf`
- `getReceiptPdf`

### Foreign Health Insurance

- `getPrice`
- `createQuote`
- `makePayment`
- `createPolicy`
- `getQuoteDetails`
- `listProducts`
- Geography + PDF helpers

### Travel Health Insurance

- `listProductCodes`
- `getPrice`
- `createQuote`
- `makePayment`
- `createPolicy`
- `getQuoteDetails`
- `listCountries`
- `listProvinces`
- `listDistricts`
- `getPolicyPdf`
- `getReceiptPdf`
- Fast Track helpers (`createFastTrackQuote`, `createFastTrackSale`, `confirmFastTrackPayment`, `listFastTrackPrices`, `listFastTrackAirports`)

### Transportation Insurance

- `createRequest`

### Roadside Assistance

- `createOrder`
- `getOrder`
- `downloadCertificate`
- Reference data lookups (`listProducts`, `listVehicleBrands`, `listVehicleModels`, `listVehicleYears`, `listCities`, `listTowns`)

### DASK Insurance

- `createQuote`
- `makePayment`
- `createPolicy`
- `getPolicyPdf`
- `getReceiptPdf`
- `getQuoteDetails`
- Property reference helpers (damage type, construction year, usage type, banks, UAVT hierarchy)

### Traffic & Casco Requests

- `createRequest`

## Configuration

```ts
const client = new Client({
  token: 'partner-token',
  environment: ApiEnvironment.Production,
  timeoutMs: 20_000,
  maxRetries: 2,
  concurrency: 4,
  userAgent: 'tamamliyo-sdk/0.1.0',
});
```

`environment` chooses between `https://api.tamamliyo.com` and `https://api-test.tamamliyo.com`. You can override `baseUrl` directly for custom deployments.

## Development

```bash
pnpm install
pnpm lint
pnpm test
pnpm build
pnpm test:e2e # requires environment variables (see below)
```

- Tests run via Vitest with MSW-powered mocks (`pnpm test`).
- Coverage reports appear under `coverage/`.
- Example scripts live under `examples/`.
- End-to-end tests hit the real Tamamliyo APIs when `pnpm test:e2e` runs. Configure credentials in `.env.development` (added to `.gitignore`).

### E2E Environment Variables

Copy `.env.development.example` to `.env.development` (never commit) and fill in at least:

```
TAMAMLIYO_TOKEN=your_partner_token
# Optional overrides
TAMAMLIYO_BASE_URL=https://api-test.tamamliyo.com
TAMAMLIYO_E2E_TIMEOUT=30000
TAMAMLIYO_E2E_MAX_RETRIES=1
TAMAMLIYO_E2E_DEBUG=false

# Set to true to enable mutating tests (quote/order creation)
TAMAMLIYO_E2E_MUTATIONS=false

# Provide JSON payloads for mutating flows when enabling mutations
# Example:
# TAMAMLIYO_INCOMING_QUOTE_PAYLOAD={"sorguTipi":2,"sigortaEttiren":{...}}
# TAMAMLIYO_FOREIGN_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_FAST_TRACK_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_FAST_TRACK_CONFIRM_PAYLOAD={...}
# TAMAMLIYO_GREEN_CARD_QUOTE_PAYLOAD={...}
# TAMAMLIYO_DASK_QUOTE_PAYLOAD={...}
# TAMAMLIYO_ROADSIDE_ORDER_PAYLOAD={...}
# TAMAMLIYO_TRANSPORTATION_REQUEST_PAYLOAD={...}
# TAMAMLIYO_TRAFFIC_REQUEST_PAYLOAD={...}
# TAMAMLIYO_GREEN_CARD_PRICE_PAYLOAD={"urunId":176}
```

> **Tip:** Export JSON payloads carefully—they should mirror the official specs. The e2e suite skips mutating tests unless `TAMAMLIYO_E2E_MUTATIONS=true` **and** the corresponding payload env exists.

## Documentation Sources

Implementation follows the markdown specs under `docs/` (e.g., `docs/01-incoming-insurances.md`). Add new docs there and extend the SDK accordingly.

## License

MIT