@countrydataapi/sdk 1.0.0

package/README.md

@@ -0,0 +1,222 @@
+# Country Data API - TypeScript/JavaScript SDK
+
+Official SDK for the [Country Data API](https://countrydataapi.com), providing easy access to geographical data including countries, states, cities, and postal codes worldwide.
+
+## Installation
+
+```bash
+npm install @countrydataapi/sdk
+# or
+yarn add @countrydataapi/sdk
+# or
+pnpm add @countrydataapi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CountryDataApi } from '@countrydataapi/sdk';
+
+const api = new CountryDataApi({
+  apiKey: 'your-api-key'
+});
+
+// Get all countries
+const countries = await api.countries.getAll({ lang: 'en' });
+console.log(countries.data);
+
+// Get country by ISO code
+const spain = await api.countries.getByCode({ code: 'ES' });
+console.log(spain.data[0].country_name); // "Spain"
+
+// Get states for a country
+const states = await api.states.getByCountry({ country: 'Spain' });
+console.log(states.data);
+
+// Get cities for a state
+const cities = await api.cities.getByState({ state: 'Madrid' });
+console.log(cities.data);
+
+// Check remaining tokens
+const status = await api.getStatus();
+console.log(`Remaining tokens: ${status.remainingTokens}`);
+```
+
+## Configuration
+
+```typescript
+const api = new CountryDataApi({
+  apiKey: 'your-api-key',           // Required
+  baseUrl: 'https://api.countrydataapi.com', // Optional
+  timeout: 30000,                    // Optional (ms)
+  defaultLanguage: 'en'              // Optional
+});
+```
+
+## API Reference
+
+### Countries
+
+```typescript
+// Get all countries
+api.countries.getAll(options?)
+
+// Get country by name
+api.countries.getByName({ name: 'Spain', ...options })
+
+// Get country by ISO code (alpha-2, alpha-3, numeric, or CIOC)
+api.countries.getByCode({ code: 'ES', ...options })
+
+// Get countries by region
+api.countries.getByRegion({ region: 'Europe', ...options })
+
+// Get countries by currency
+api.countries.getByCurrency({ currency: 'EUR', ...options })
+
+// Get countries by language
+api.countries.getByLanguage({ language: 'spa', ...options })
+
+// Get countries by timezone
+api.countries.getByTimezone({ timezone: 'Europe/Madrid', ...options })
+```
+
+### States
+
+```typescript
+// Get all states
+api.states.getAll(options?)
+
+// Get states by country
+api.states.getByCountry({ country: 'Spain', ...options })
+
+// Get states by city
+api.states.getByCity({ city: 'Madrid', ...options })
+
+// Get states by zipcode
+api.states.getByZipcode({ zipcode: '28001', ...options })
+```
+
+### Cities
+
+```typescript
+// Get all cities
+api.cities.getAll(options?)
+
+// Get city by name
+api.cities.get({ city: 'Madrid', ...options })
+
+// Get cities by country
+api.cities.getByCountry({ country: 'Spain', ...options })
+
+// Get cities by state
+api.cities.getByState({ state: 'Madrid', ...options })
+```
+
+### Zipcodes
+
+```typescript
+// Get all zipcodes
+api.zipcodes.getAll(options?)
+
+// Get zipcodes by country
+api.zipcodes.getByCountry({ country: 'Spain', ...options })
+
+// Get zipcodes by state
+api.zipcodes.getByState({ state: 'Madrid', ...options })
+
+// Get zipcodes by region
+api.zipcodes.getByRegion({ region: 'Europe', ...options })
+```
+
+### Select (Optimized for Dropdowns)
+
+These endpoints cost only **1 token** regardless of the number of results, making them perfect for populating dropdowns.
+
+```typescript
+// Get countries for select
+api.select.countries({ lang: 'es' })
+
+// Get states for select
+api.select.states({ country: 'ES', lang: 'es' })
+
+// Get cities for select
+api.select.cities({ state: 'Madrid', country: 'ES', lang: 'es' })
+```
+
+## Request Options
+
+All methods accept these common options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `fields` | `string` | Comma-separated list of fields to return |
+| `lang` | `'en' \| 'es' \| 'pt' \| 'fr' \| 'de' \| 'it'` | Response language |
+| `limit` | `number` | Maximum number of items to return |
+| `limitToken` | `number` | Maximum tokens to use for this request |
+
+## Response Format
+
+All methods return an `ApiResponse<T>` object:
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean;
+  data: T[];
+  count: number;
+  tokens_used: number;
+  remaining_tokens?: number;
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  CountryDataApi,
+  AuthenticationError,
+  InsufficientTokensError
+} from '@countrydataapi/sdk';
+
+try {
+  const countries = await api.countries.getAll();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof InsufficientTokensError) {
+    console.error('No tokens remaining');
+  } else {
+    console.error('API error:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  Country,
+  State,
+  City,
+  ApiResponse,
+  Language
+} from '@countrydataapi/sdk';
+
+const response: ApiResponse<Country> = await api.countries.getByCode({
+  code: 'ES'
+});
+
+const country: Country = response.data[0];
+console.log(country.country_name);
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://countrydataapi.com/docs)
+- [API Reference](https://countrydataapi.com/docs/api-reference)
+- [Get API Key](https://countrydataapi.com/pricing)