npm package: @jars-lt/sdk
Description: Official Node.js SDK for JARS.LT API - Lithuanian and Estonian Company Registry
Author: UAB Sistemium
Latest version: 1.1.2

# @jars-lt/sdk

Official Node.js SDK for [JARS.LT](https://jars.lt) - Baltic Company Registry API (Lithuania, Estonia, Latvia)

## Installation

```bash
npm install @jars-lt/sdk
# or
yarn add @jars-lt/sdk
# or
pnpm add @jars-lt/sdk
```

## Quick Start

```typescript
import { JarsClient } from '@jars-lt/sdk';

// Initialize the client
const client = new JarsClient({
  apiKey: 'your_api_key_here'
});

// Search for companies
const companies = await client.searchCompanies({
  q: 'UAB Maxima',
  limit: 10
});

console.log(companies.results);
```

## API Key

Get your API key at [jars.lt](https://jars.lt). Available plans:
- **Free**: 300 requests/month
- **Starter**: 5,000 requests/month
- **Professional**: 50,000 requests/month
- **Enterprise**: 1,000,000 requests/month

## Usage

### Initialize Client

```typescript
import { JarsClient } from '@jars-lt/sdk';

const client = new JarsClient({
  apiKey: 'your_api_key_here',
  // Optional: custom base URL
  baseURL: 'https://api.jars.lt/api/v1',
  // Optional: request timeout in ms
  timeout: 30000
});
```

### Search Companies

Search for companies by name or code. Use the `country` option for Estonian (`ee`) or Latvian (`lv`) companies:

```typescript
// Lithuanian companies (default)
const results = await client.searchCompanies({
  q: 'Maxima',
  limit: 10,
  offset: 0
});

// Estonian companies
const eeResults = await client.searchCompanies({
  q: 'Bolt',
  country: 'ee'
});

// Latvian companies
const lvResults = await client.searchCompanies({
  q: 'ELKO',
  country: 'lv'
});

console.log(`Found ${results.total} companies`);
results.results.forEach(company => {
  console.log(`${company.name} (${company.code})`);
});
```

### Get Company by Code

Retrieve detailed information about a specific company:

```typescript
// Lithuanian company
const company = await client.getCompany('111111111');

// Estonian company
const eeCompany = await client.getCompany('14532901', { country: 'ee' });

// Latvian company
const lvCompany = await client.getCompany('40003129564', { country: 'lv' });

console.log(company.name);
console.log(company.address);
console.log(company.status);
console.log(company.registrationDate);
```

### Search Addresses

Search for streets, settlements, and municipalities. Supports multi-word search:

```typescript
const results = await client.searchAddresses({
  q: 'kaunas basanavi',
  limit: 5
});

// Streets
results.streets.forEach(street => {
  console.log(`${street.name} ${street.typeAbbr}`);
  if (street.settlement) {
    console.log(`  ${street.settlement.name}`);
  }
});

// Settlements
results.settlements.forEach(settlement => {
  console.log(`${settlement.name} ${settlement.typeAbbr}`);
});

// Municipalities
results.municipalities.forEach(municipality => {
  console.log(municipality.name);
});
```

### Get Location by Postal Code

Get county, municipality, settlement, and streets for a postal code:

```typescript
const location = await client.getByPostalCode('54306');
// or with LT- prefix
const location = await client.getByPostalCode('LT-54306');

console.log('County:', location.county.name);
console.log('Municipality:', location.municipality.name);
console.log('Settlement:', location.settlement.name);

// All streets with this postal code
location.streets?.forEach(street => {
  console.log(`${street.name} ${street.typeAbbr}`);
});
```

### Get Usage Statistics

Check your current API usage and limits:

```typescript
const usage = await client.getUsage();

console.log('Plan:', usage.plan);
console.log('Requests used:', usage.requestCount);
console.log('Requests remaining:', usage.remaining);
console.log('Monthly limit:', usage.limit);
console.log('Resets on:', usage.resetDate);
console.log('Rate limit:', usage.rateLimit, 'requests/minute');
```

## Error Handling

The SDK throws `JarsAPIError` for API errors:

```typescript
import { JarsClient, JarsAPIError } from '@jars-lt/sdk';

try {
  const company = await client.getCompany('invalid');
} catch (error) {
  if (error instanceof JarsAPIError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    console.error('Network Error:', error);
  }
}
```

Common error codes:
- `400` - Invalid parameters
- `401` - Invalid API key
- `404` - Resource not found
- `429` - Rate limit exceeded
- `500` - Server error

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

```typescript
import { JarsClient, Company, SubscriptionPlan } from '@jars-lt/sdk';

const client = new JarsClient({ apiKey: 'key' });

// Fully typed responses
const company: Company = await client.getCompany('111111111');
const usage = await client.getUsage();
const plan: SubscriptionPlan = usage.plan; // 'FREE' | 'STARTER' | 'PROFESSIONAL' | 'ENTERPRISE'
```

## Advanced Usage

### Country-Specific Base URLs

You can use country-specific API domains that default to the corresponding country:

```typescript
// api.jars.lt — Lithuanian data (default)
const ltClient = new JarsClient({ apiKey: 'key', baseURL: 'https://api.jars.lt/api/v1' });

// api.jars.ee — Estonian data by default
const eeClient = new JarsClient({ apiKey: 'key', baseURL: 'https://api.jars.ee/api/v1' });

// api.jars.lv — Latvian data by default
const lvClient = new JarsClient({ apiKey: 'key', baseURL: 'https://api.jars.lv/api/v1' });
```

### Custom Axios Configuration

The SDK uses axios internally. You can access the underlying axios instance if needed:

```typescript
import { JarsClient } from '@jars-lt/sdk';

const client = new JarsClient({
  apiKey: 'key',
  timeout: 60000, // 60 seconds
  baseURL: 'https://custom-api.example.com/api/v1'
});
```

### Pagination

Handle large result sets with pagination:

```typescript
async function getAllCompanies(query: string) {
  const pageSize = 100; // Max allowed
  let offset = 0;
  let allCompanies = [];

  while (true) {
    const results = await client.searchCompanies({
      q: query,
      limit: pageSize,
      offset
    });

    allCompanies.push(...results.results);

    if (results.results.length < pageSize) {
      break; // Last page
    }

    offset += pageSize;
  }

  return allCompanies;
}
```

## Examples

### Find Company and Its Address

```typescript
const companies = await client.searchCompanies({ q: 'Maxima' });
if (companies.results.length > 0) {
  const company = await client.getCompany(companies.results[0].code);
  console.log(`${company.name} is located at ${company.address}`);
}
```

### Search Streets in Kaunas

```typescript
const results = await client.searchAddresses({ q: 'kaunas' });
console.log(`Found ${results.streets.length} streets in Kaunas`);
```

### Check if API Key is Valid

```typescript
try {
  const usage = await client.getUsage();
  console.log('API key is valid. Plan:', usage.plan);
} catch (error) {
  console.error('Invalid API key');
}
```

## Rate Limits

Respect rate limits based on your plan:
- **Free**: 30 requests/minute
- **Starter**: 60 requests/minute
- **Professional**: 300 requests/minute
- **Enterprise**: 1000 requests/minute

The API returns `429 Too Many Requests` when rate limit is exceeded.

## Support

- Documentation: [jars.lt/docs](https://jars.lt/docs)
- Contact: [jars.lt/contact](https://jars.lt/contact)

## License

MIT © UAB Sistemium