apogeoapi 1.0.0 → 1.0.2

package/README.md

@@ -1,532 +1,532 @@
-# @geo-api/sdk
-
-Official TypeScript SDK for Geo API - Professional geographic data API with comprehensive country, state, and city information.
-
-[![npm version](https://img.shields.io/npm/v/@geo-api/sdk)](https://www.npmjs.com/package/@geo-api/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 🚀 Features
-
-- ✅ **Full TypeScript Support** - Complete type definitions with autocomplete
-- ✅ **Auto-Retry Logic** - Automatic retry with exponential backoff
-- ✅ **Error Handling** - Typed error responses
-- ✅ **Rate Limit Handling** - Respects retry-after headers
-- ✅ **Multiple Auth Methods** - API Key or JWT token
-- ✅ **Comprehensive Coverage** - All API endpoints covered
-- ✅ **Zero Config** - Works out of the box with sensible defaults
-
-## 📦 Installation
-
-```bash
-npm install @geo-api/sdk
-
-# or with yarn
-yarn add @geo-api/sdk
-
-# or with pnpm
-pnpm add @geo-api/sdk
-```
-
-## 🏃 Quick Start
-
-```typescript
-import { GeoAPI } from '@geo-api/sdk';
-
-// Initialize with API key (recommended)
-const client = new GeoAPI({
-  apiKey: 'geoapi_live_xxxxx',
-  baseURL: 'https://api.yourcompany.com/v1' // optional
-});
-
-// Get all countries
-const countries = await client.geo.getCountries();
-console.log(`Total countries: ${countries.length}`);
-
-// Search for cities
-const cities = await client.geo.searchCities('New York', 10);
-console.log(cities);
-
-// Get usage statistics
-const dashboard = await client.account.getDashboard();
-console.log(`API calls this month: ${dashboard.usage.requestsThisMonth}`);
-```
-
-## 📚 Table of Contents
-
-- [Authentication](#authentication)
-- [Geography API](#geography-api)
-- [Account Management](#account-management)
-- [API Keys Management](#api-keys-management)
-- [Billing & Subscriptions](#billing--subscriptions)
-- [Webhooks](#webhooks)
-- [Error Handling](#error-handling)
-- [Advanced Configuration](#advanced-configuration)
-
----
-
-## 🔐 Authentication
-
-### API Key (Recommended for Client-Side)
-
-```typescript
-const client = new GeoAPI({
-  apiKey: 'geoapi_live_xxxxx'
-});
-```
-
-### JWT Token (After Login)
-
-```typescript
-const client = new GeoAPI({
-  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
-});
-
-// Or set token after initialization
-client.setToken('new_token_here');
-```
-
-### Register & Login
-
-```typescript
-// Register new user
-const { user, access_token, refresh_token } = await client.auth.register({
-  email: 'user@example.com',
-  password: 'securePassword123',
-  username: 'johndoe'
-});
-
-// Login
-const tokens = await client.auth.login({
-  email: 'user@example.com',
-  password: 'securePassword123'
-});
-
-// Token is automatically set after login
-console.log('Logged in as:', tokens.user.username);
-
-// Refresh token
-const newTokens = await client.auth.refreshToken({
-  refresh_token: tokens.refresh_token
-});
-```
-
----
-
-## 🌍 Geography API
-
-### Countries
-
-```typescript
-// Get all countries
-const countries = await client.geo.getCountries();
-
-// Get country by ISO code
-const usa = await client.geo.getCountryByIso('US');
-console.log(usa.name); // "United States"
-console.log(usa.capital); // "Washington"
-console.log(usa.currency); // "USD"
-
-// Search countries
-const matching = await client.geo.searchCountries('united', 5);
-```
-
-### States/Provinces
-
-```typescript
-// Get all states of a country
-const usStates = await client.geo.getStates('US');
-console.log(`US has ${usStates.length} states`);
-
-// Get specific state
-const california = await client.geo.getStateById(1234);
-console.log(california.name); // "California"
-
-// Search states
-const texasMatch = await client.geo.searchStates('texas', 1);
-```
-
-### Cities
-
-```typescript
-// Get cities of a state
-const californiaCities = await client.geo.getCities(1234, 100, 0);
-
-// Get specific city
-const city = await client.geo.getCityById(5678);
-console.log(`${city.name}, ${city.state.name}`);
-
-// Search cities
-const newYorkCities = await client.geo.searchCities('New York', 10);
-```
-
-### Universal Search
-
-```typescript
-// Search across all types
-const results = await client.geo.search({
-  query: 'san',
-  limit: 20,
-  offset: 0,
-  type: 'city' // optional: 'country' | 'state' | 'city'
-});
-
-console.log(`Found ${results.total} results`);
-```
-
----
-
-## 👤 Account Management
-
-### Dashboard
-
-```typescript
-// Get complete dashboard
-const dashboard = await client.account.getDashboard();
-
-console.log('User:', dashboard.user.username);
-console.log('Tier:', dashboard.subscription.tier);
-console.log('Usage:', dashboard.usage.requestsThisMonth, '/', dashboard.usage.monthlyQuota);
-console.log('API Keys:', dashboard.apiKeys.active, '/', dashboard.apiKeys.max);
-```
-
-### Profile
-
-```typescript
-// Update profile
-await client.account.updateProfile({
-  username: 'new_username',
-  email: 'newemail@example.com'
-});
-
-// Change password
-await client.account.changePassword({
-  currentPassword: 'oldpass123',
-  newPassword: 'newpass456'
-});
-```
-
-### Usage Statistics
-
-```typescript
-// Get usage for date range
-const stats = await client.account.getUsage({
-  startDate: new Date('2024-01-01'),
-  endDate: new Date('2024-01-31'),
-  groupBy: 'day' // or 'month'
-});
-
-stats.forEach(stat => {
-  console.log(`${stat.date}: ${stat.requests} requests`);
-});
-```
-
----
-
-## 🔑 API Keys Management
-
-### List & Create
-
-```typescript
-// List all API keys
-const keys = await client.apiKeys.list();
-
-// Create new API key
-const newKey = await client.apiKeys.create({
-  name: 'Production Server',
-  expiresAt: new Date('2025-12-31')
-});
-
-console.log('🔑 Save this key:', newKey.key);
-// ⚠️ Key is only shown once!
-```
-
-### Update & Delete
-
-```typescript
-// Rename key
-await client.apiKeys.update(keyId, {
-  name: 'Production Server v2'
-});
-
-// Revoke key (deactivate)
-await client.apiKeys.revoke(keyId);
-
-// Reactivate key
-await client.apiKeys.activate(keyId);
-
-// Delete permanently
-await client.apiKeys.delete(keyId);
-```
-
----
-
-## 💳 Billing & Subscriptions
-
-### Upgrade Plan
-
-```typescript
-// Create checkout session
-const checkout = await client.billing.createCheckoutSession(
-  'professional', // tier
-  'https://myapp.com/success', // success URL
-  'https://myapp.com/cancel' // cancel URL
-);
-
-// Redirect user to Stripe
-window.location.href = checkout.url;
-```
-
-### Manage Subscription
-
-```typescript
-// Access billing portal
-const portal = await client.billing.createPortalSession(
-  'https://myapp.com/account' // return URL
-);
-
-// Redirect user to Stripe portal
-window.location.href = portal.url;
-```
-
-### Invoices
-
-```typescript
-// Get all invoices
-const invoices = await client.billing.getInvoices(10);
-
-invoices.forEach(invoice => {
-  console.log(`${invoice.created}: $${invoice.amount/100} - ${invoice.status}`);
-  console.log(`PDF: ${invoice.invoice_pdf}`);
-});
-
-// Get specific invoice
-const invoice = await client.billing.getInvoice('in_xxxxx');
-```
-
-### Cancel Subscription
-
-```typescript
-// Cancel at period end
-await client.billing.cancelSubscription();
-// User keeps access until period ends
-
-// Reactivate before period ends
-await client.billing.reactivateSubscription();
-```
-
----
-
-## 🪝 Webhooks
-
-### Create Webhook
-
-```typescript
-// Create webhook
-const webhook = await client.webhooks.create({
-  url: 'https://myapp.com/webhooks/geo-api',
-  events: [
-    'usage.quota_warning',
-    'usage.quota_exceeded',
-    'subscription.updated'
-  ]
-});
-
-console.log('Webhook ID:', webhook.id);
-console.log('Secret:', webhook.secret); // Use to validate payloads
-```
-
-### Manage Webhooks
-
-```typescript
-// List all webhooks
-const webhooks = await client.webhooks.list();
-
-// Update webhook
-await client.webhooks.update(webhookId, {
-  url: 'https://myapp.com/new-webhook-url',
-  events: ['subscription.created', 'subscription.canceled']
-});
-
-// Test webhook
-const result = await client.webhooks.test(webhookId);
-console.log('Test success:', result.success);
-
-// Deactivate
-await client.webhooks.deactivate(webhookId);
-
-// Delete
-await client.webhooks.delete(webhookId);
-```
-
-### Delivery Logs
-
-```typescript
-// Get webhook delivery logs
-const logs = await client.webhooks.getLogs(webhookId, 50);
-
-logs.forEach(log => {
-  console.log(`${log.createdAt}: ${log.event} - ${log.success ? '✅' : '❌'}`);
-  if (!log.success) {
-    console.log(`  Status: ${log.statusCode}`);
-  }
-});
-```
-
----
-
-## ⚠️ Error Handling
-
-```typescript
-import { GeoAPI, GeoAPIError } from '@geo-api/sdk';
-
-const client = new GeoAPI({ apiKey: 'xxx' });
-
-try {
-  const country = await client.geo.getCountryByIso('INVALID');
-} catch (error) {
-  if (error instanceof GeoAPIError) {
-    console.error('Status:', error.statusCode);
-    console.error('Message:', error.message);
-    console.error('Response:', error.response);
-
-    // Handle specific errors
-    if (error.statusCode === 404) {
-      console.log('Country not found');
-    } else if (error.statusCode === 429) {
-      console.log('Rate limit exceeded, retry after:', error.response?.retryAfter);
-    } else if (error.statusCode === 403) {
-      console.log('Quota exceeded or invalid API key');
-    }
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
----
-
-## ⚙️ Advanced Configuration
-
-### Custom Configuration
-
-```typescript
-const client = new GeoAPI({
-  apiKey: 'geoapi_live_xxxxx',
-  baseURL: 'https://api.yourcompany.com/v1',
-  timeout: 30000, // 30 seconds
-  retries: 3, // retry failed requests 3 times
-  debug: true // enable debug logging
-});
-```
-
-### Debug Mode
-
-```typescript
-const client = new GeoAPI({
-  apiKey: 'xxx',
-  debug: true
-});
-
-// Logs all requests and retries
-// [SDK] GET /geo/countries
-// [SDK] Response 200 from /geo/countries
-```
-
-### Using Different Environments
-
-```typescript
-// Development
-const devClient = new GeoAPI({
-  apiKey: process.env.DEV_API_KEY,
-  baseURL: 'http://localhost:3000/v1'
-});
-
-// Production
-const prodClient = new GeoAPI({
-  apiKey: process.env.PROD_API_KEY,
-  baseURL: 'https://api.yourcompany.com/v1'
-});
-```
-
----
-
-## 🧪 Examples
-
-### Complete Application Example
-
-```typescript
-import { GeoAPI } from '@geo-api/sdk';
-
-const client = new GeoAPI({
-  apiKey: process.env.GEO_API_KEY!
-});
-
-async function main() {
-  // 1. Get dashboard
-  const dashboard = await client.account.getDashboard();
-  console.log(`Welcome ${dashboard.user.username}!`);
-  console.log(`You're on the ${dashboard.subscription.tier} plan`);
-  console.log(`Usage: ${dashboard.usage.usagePercentage}%`);
-
-  // 2. Query geography data
-  const countries = await client.geo.getCountries();
-  console.log(`\nTotal countries: ${countries.length}`);
-
-  // 3. Search for specific location
-  const cities = await client.geo.searchCities('Paris', 5);
-  console.log(`\nCities named Paris:`);
-  cities.forEach(city => {
-    console.log(`- ${city.name}, ${city.state?.name}, ${city.country?.name}`);
-  });
-
-  // 4. Check usage
-  const usage = await client.account.getUsage({
-    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
-    endDate: new Date(),
-    groupBy: 'day'
-  });
-  console.log(`\nLast 30 days usage:`, usage.length, 'days');
-}
-
-main().catch(console.error);
-```
-
----
-
-## 📝 TypeScript Support
-
-Full TypeScript support with complete type definitions:
-
-```typescript
-import { GeoAPI, Country, City, Tier, WebhookEvent } from '@geo-api/sdk';
-
-const client = new GeoAPI({ apiKey: 'xxx' });
-
-// All responses are fully typed
-const country: Country = await client.geo.getCountryByIso('US');
-const cities: City[] = await client.geo.searchCities('London', 10);
-
-// Enums are typed
-const tier: Tier = 'professional';
-const events: WebhookEvent[] = ['usage.quota_warning', 'subscription.updated'];
-```
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## 📄 License
-
-MIT © Geo API Team
-
-## 🔗 Links
-
-- [API Documentation](https://api.yourcompany.com/docs)
-- [GitHub Repository](https://github.com/your-org/geo-api-sdk)
-- [Support](mailto:support@yourcompany.com)
-
----
-
-**Made with ❤️ by the Geo API Team**
+# apogeoapi — JavaScript/TypeScript SDK
+
+Official TypeScript SDK for ApogeoAPI — professional geographic data API with comprehensive country, state, and city information, IP geolocation, and exchange rates.
+
+[![npm version](https://img.shields.io/npm/v/apogeoapi)](https://www.npmjs.com/package/apogeoapi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Full TypeScript Support** - Complete type definitions with autocomplete
+- **Auto-Retry Logic** - Automatic retry with exponential backoff
+- **Error Handling** - Typed error responses
+- **Rate Limit Handling** - Respects retry-after headers
+- **Multiple Auth Methods** - API Key or JWT token
+- **Comprehensive Coverage** - All API endpoints covered
+- **Zero Config** - Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install apogeoapi
+
+# or with yarn
+yarn add apogeoapi
+
+# or with pnpm
+pnpm add apogeoapi
+```
+
+## Quick Start
+
+```typescript
+import { ApogeoAPI } from 'apogeoapi';
+
+// Initialize with API key (recommended)
+const client = new ApogeoAPI({
+  apiKey: 'geoapi_live_xxxxx'
+});
+
+// Get all countries
+const countries = await client.geo.getCountries();
+console.log(`Total countries: ${countries.length}`);
+
+// Search for cities
+const cities = await client.geo.searchCities('New York', 10);
+console.log(cities);
+
+// Get usage statistics
+const dashboard = await client.account.getDashboard();
+console.log(`API calls this month: ${dashboard.usage.requestsThisMonth}`);
+```
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Geography API](#geography-api)
+- [Account Management](#account-management)
+- [API Keys Management](#api-keys-management)
+- [Billing & Subscriptions](#billing--subscriptions)
+- [Webhooks](#webhooks)
+- [Error Handling](#error-handling)
+- [Advanced Configuration](#advanced-configuration)
+
+---
+
+## Authentication
+
+### API Key (Recommended for Client-Side)
+
+```typescript
+const client = new ApogeoAPI({
+  apiKey: 'geoapi_live_xxxxx'
+});
+```
+
+### JWT Token (After Login)
+
+```typescript
+const client = new ApogeoAPI({
+  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+});
+
+// Or set token after initialization
+client.setToken('new_token_here');
+```
+
+### Register & Login
+
+```typescript
+// Register new user
+const { user, access_token, refresh_token } = await client.auth.register({
+  email: 'user@example.com',
+  password: 'securePassword123',
+  username: 'johndoe'
+});
+
+// Login
+const tokens = await client.auth.login({
+  email: 'user@example.com',
+  password: 'securePassword123'
+});
+
+// Token is automatically set after login
+console.log('Logged in as:', tokens.user.username);
+
+// Refresh token
+const newTokens = await client.auth.refreshToken({
+  refresh_token: tokens.refresh_token
+});
+```
+
+---
+
+## Geography API
+
+### Countries
+
+```typescript
+// Get all countries
+const countries = await client.geo.getCountries();
+
+// Get country by ISO code
+const usa = await client.geo.getCountryByIso('US');
+console.log(usa.name); // "United States"
+console.log(usa.capital); // "Washington"
+console.log(usa.currency); // "USD"
+
+// Search countries
+const matching = await client.geo.searchCountries('united', 5);
+```
+
+### States/Provinces
+
+```typescript
+// Get all states of a country
+const usStates = await client.geo.getStates('US');
+console.log(`US has ${usStates.length} states`);
+
+// Get specific state
+const california = await client.geo.getStateById(1234);
+console.log(california.name); // "California"
+
+// Search states
+const texasMatch = await client.geo.searchStates('texas', 1);
+```
+
+### Cities
+
+```typescript
+// Get cities of a state
+const californiaCities = await client.geo.getCities(1234, 100, 0);
+
+// Get specific city
+const city = await client.geo.getCityById(5678);
+console.log(`${city.name}, ${city.state.name}`);
+
+// Search cities
+const newYorkCities = await client.geo.searchCities('New York', 10);
+```
+
+### Universal Search
+
+```typescript
+// Search across all types
+const results = await client.geo.search({
+  query: 'san',
+  limit: 20,
+  offset: 0,
+  type: 'city' // optional: 'country' | 'state' | 'city'
+});
+
+console.log(`Found ${results.total} results`);
+```
+
+---
+
+## Account Management
+
+### Dashboard
+
+```typescript
+// Get complete dashboard
+const dashboard = await client.account.getDashboard();
+
+console.log('User:', dashboard.user.username);
+console.log('Tier:', dashboard.subscription.tier);
+console.log('Usage:', dashboard.usage.requestsThisMonth, '/', dashboard.usage.monthlyQuota);
+console.log('API Keys:', dashboard.apiKeys.active, '/', dashboard.apiKeys.max);
+```
+
+### Profile
+
+```typescript
+// Update profile
+await client.account.updateProfile({
+  username: 'new_username',
+  email: 'newemail@example.com'
+});
+
+// Change password
+await client.account.changePassword({
+  currentPassword: 'oldpass123',
+  newPassword: 'newpass456'
+});
+```
+
+### Usage Statistics
+
+```typescript
+// Get usage for date range
+const stats = await client.account.getUsage({
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-01-31'),
+  groupBy: 'day' // or 'month'
+});
+
+stats.forEach(stat => {
+  console.log(`${stat.date}: ${stat.requests} requests`);
+});
+```
+
+---
+
+## API Keys Management
+
+### List & Create
+
+```typescript
+// List all API keys
+const keys = await client.apiKeys.list();
+
+// Create new API key
+const newKey = await client.apiKeys.create({
+  name: 'Production Server',
+  expiresAt: new Date('2025-12-31')
+});
+
+console.log('Save this key:', newKey.key);
+// Key is only shown once!
+```
+
+### Update & Delete
+
+```typescript
+// Rename key
+await client.apiKeys.update(keyId, {
+  name: 'Production Server v2'
+});
+
+// Revoke key (deactivate)
+await client.apiKeys.revoke(keyId);
+
+// Reactivate key
+await client.apiKeys.activate(keyId);
+
+// Delete permanently
+await client.apiKeys.delete(keyId);
+```
+
+---
+
+## Billing & Subscriptions
+
+### Upgrade Plan
+
+```typescript
+// Create checkout session
+const checkout = await client.billing.createCheckoutSession(
+  'professional', // tier
+  'https://myapp.com/success', // success URL
+  'https://myapp.com/cancel' // cancel URL
+);
+
+// Redirect user to payment page
+window.location.href = checkout.url;
+```
+
+### Manage Subscription
+
+```typescript
+// Access billing portal
+const portal = await client.billing.createPortalSession(
+  'https://myapp.com/account' // return URL
+);
+
+// Redirect user to billing portal
+window.location.href = portal.url;
+```
+
+### Invoices
+
+```typescript
+// Get all invoices
+const invoices = await client.billing.getInvoices(10);
+
+invoices.forEach(invoice => {
+  console.log(`${invoice.created}: $${invoice.amount/100} - ${invoice.status}`);
+  console.log(`PDF: ${invoice.invoice_pdf}`);
+});
+
+// Get specific invoice
+const invoice = await client.billing.getInvoice('in_xxxxx');
+```
+
+### Cancel Subscription
+
+```typescript
+// Cancel at period end
+await client.billing.cancelSubscription();
+// User keeps access until period ends
+
+// Reactivate before period ends
+await client.billing.reactivateSubscription();
+```
+
+---
+
+## Webhooks
+
+### Create Webhook
+
+```typescript
+// Create webhook
+const webhook = await client.webhooks.create({
+  url: 'https://myapp.com/webhooks/apogeoapi',
+  events: [
+    'usage.quota_warning',
+    'usage.quota_exceeded',
+    'subscription.updated'
+  ]
+});
+
+console.log('Webhook ID:', webhook.id);
+console.log('Secret:', webhook.secret); // Use to validate payloads
+```
+
+### Manage Webhooks
+
+```typescript
+// List all webhooks
+const webhooks = await client.webhooks.list();
+
+// Update webhook
+await client.webhooks.update(webhookId, {
+  url: 'https://myapp.com/new-webhook-url',
+  events: ['subscription.created', 'subscription.canceled']
+});
+
+// Test webhook
+const result = await client.webhooks.test(webhookId);
+console.log('Test success:', result.success);
+
+// Deactivate
+await client.webhooks.deactivate(webhookId);
+
+// Delete
+await client.webhooks.delete(webhookId);
+```
+
+### Delivery Logs
+
+```typescript
+// Get webhook delivery logs
+const logs = await client.webhooks.getLogs(webhookId, 50);
+
+logs.forEach(log => {
+  console.log(`${log.createdAt}: ${log.event} - ${log.success ? 'OK' : 'FAIL'}`);
+  if (!log.success) {
+    console.log(`  Status: ${log.statusCode}`);
+  }
+});
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { ApogeoAPI, ApogeoAPIError } from 'apogeoapi';
+
+const client = new ApogeoAPI({ apiKey: 'xxx' });
+
+try {
+  const country = await client.geo.getCountryByIso('INVALID');
+} catch (error) {
+  if (error instanceof ApogeoAPIError) {
+    console.error('Status:', error.statusCode);
+    console.error('Message:', error.message);
+    console.error('Response:', error.response);
+
+    // Handle specific errors
+    if (error.statusCode === 404) {
+      console.log('Country not found');
+    } else if (error.statusCode === 429) {
+      console.log('Rate limit exceeded, retry after:', error.response?.retryAfter);
+    } else if (error.statusCode === 403) {
+      console.log('Quota exceeded or invalid API key');
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+---
+
+## Advanced Configuration
+
+### Custom Configuration
+
+```typescript
+const client = new ApogeoAPI({
+  apiKey: 'geoapi_live_xxxxx',
+  baseURL: 'https://api.apogeoapi.com/v1',
+  timeout: 30000, // 30 seconds
+  retries: 3, // retry failed requests 3 times
+  debug: true // enable debug logging
+});
+```
+
+### Debug Mode
+
+```typescript
+const client = new ApogeoAPI({
+  apiKey: 'xxx',
+  debug: true
+});
+
+// Logs all requests and retries
+// [SDK] GET /geo/countries
+// [SDK] Response 200 from /geo/countries
+```
+
+### Using Different Environments
+
+```typescript
+// Development
+const devClient = new ApogeoAPI({
+  apiKey: process.env.DEV_API_KEY,
+  baseURL: 'http://localhost:3000/v1'
+});
+
+// Production
+const prodClient = new ApogeoAPI({
+  apiKey: process.env.PROD_API_KEY,
+  baseURL: 'https://api.apogeoapi.com/v1'
+});
+```
+
+---
+
+## Examples
+
+### Complete Application Example
+
+```typescript
+import { ApogeoAPI } from 'apogeoapi';
+
+const client = new ApogeoAPI({
+  apiKey: process.env.GEO_API_KEY!
+});
+
+async function main() {
+  // 1. Get dashboard
+  const dashboard = await client.account.getDashboard();
+  console.log(`Welcome ${dashboard.user.username}!`);
+  console.log(`You're on the ${dashboard.subscription.tier} plan`);
+  console.log(`Usage: ${dashboard.usage.usagePercentage}%`);
+
+  // 2. Query geography data
+  const countries = await client.geo.getCountries();
+  console.log(`\nTotal countries: ${countries.length}`);
+
+  // 3. Search for specific location
+  const cities = await client.geo.searchCities('Paris', 5);
+  console.log(`\nCities named Paris:`);
+  cities.forEach(city => {
+    console.log(`- ${city.name}, ${city.state?.name}, ${city.country?.name}`);
+  });
+
+  // 4. Check usage
+  const usage = await client.account.getUsage({
+    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+    endDate: new Date(),
+    groupBy: 'day'
+  });
+  console.log(`\nLast 30 days usage:`, usage.length, 'days');
+}
+
+main().catch(console.error);
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with complete type definitions:
+
+```typescript
+import { ApogeoAPI, Country, City, Tier, WebhookEvent } from 'apogeoapi';
+
+const client = new ApogeoAPI({ apiKey: 'xxx' });
+
+// All responses are fully typed
+const country: Country = await client.geo.getCountryByIso('US');
+const cities: City[] = await client.geo.searchCities('London', 10);
+
+// Enums are typed
+const tier: Tier = 'professional';
+const events: WebhookEvent[] = ['usage.quota_warning', 'subscription.updated'];
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+MIT © ApogeoAPI
+
+## Links
+
+- [API Documentation](https://api.apogeoapi.com/api/docs)
+- [npm Package](https://www.npmjs.com/package/apogeoapi)
+- [Website](https://apogeoapi.com)
+- [Support](mailto:support@apogeoapi.com)
+
+---
+
+**Made with care by the ApogeoAPI Team**