apogeoapi 1.0.0

package/README.md

@@ -0,0 +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**

package/dist/clients/account.client.d.ts

@@ -0,0 +1,76 @@
+import { HttpClient } from '../utils/http-client';
+import { AccountDashboard, UpdateProfileDto, ChangePasswordDto, UsageStats, UsageQuery } from '../types';
+/**
+ * AccountClient - Handles user account operations
+ *
+ * @example
+ * ```typescript
+ * const account = new AccountClient(httpClient);
+ *
+ * // Get dashboard data
+ * const dashboard = await account.getDashboard();
+ *
+ * // Update profile
+ * await account.updateProfile({ username: 'new_username' });
+ *
+ * // Get usage statistics
+ * const usage = await account.getUsage({
+ *   startDate: new Date('2024-01-01'),
+ *   endDate: new Date('2024-01-31'),
+ *   groupBy: 'day'
+ * });
+ * ```
+ */
+export declare class AccountClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get account dashboard with all information
+     *
+     * Includes:
+     * - User profile
+     * - Subscription details
+     * - Usage statistics
+     * - Tier limits
+     * - API keys count
+     *
+     * @returns Complete dashboard data
+     */
+    getDashboard(): Promise<AccountDashboard>;
+    /**
+     * Update user profile
+     *
+     * @param data - Profile update data (username, email)
+     * @returns Success response
+     */
+    updateProfile(data: UpdateProfileDto): Promise<{
+        message: string;
+    }>;
+    /**
+     * Change password
+     *
+     * @param data - Password change data (currentPassword, newPassword)
+     * @returns Success response
+     */
+    changePassword(data: ChangePasswordDto): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get usage statistics
+     *
+     * @param query - Query parameters (startDate, endDate, groupBy)
+     * @returns Array of usage statistics
+     */
+    getUsage(query?: UsageQuery): Promise<UsageStats[]>;
+    /**
+     * Delete account permanently
+     *
+     * **Warning:** This action is irreversible
+     *
+     * @returns Success response
+     */
+    deleteAccount(): Promise<{
+        message: string;
+    }>;
+}
+//# sourceMappingURL=account.client.d.ts.map

package/dist/clients/account.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.client.d.ts","sourceRoot":"","sources":["../../src/clients/account.client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACX,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAEpC;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAI/C;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAIzE;;;;;OAKG;IACG,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3E;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMzD;;;;;;OAMG;IACG,aAAa,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAGpD"}

package/dist/clients/account.client.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountClient = void 0;
+/**
+ * AccountClient - Handles user account operations
+ *
+ * @example
+ * ```typescript
+ * const account = new AccountClient(httpClient);
+ *
+ * // Get dashboard data
+ * const dashboard = await account.getDashboard();
+ *
+ * // Update profile
+ * await account.updateProfile({ username: 'new_username' });
+ *
+ * // Get usage statistics
+ * const usage = await account.getUsage({
+ *   startDate: new Date('2024-01-01'),
+ *   endDate: new Date('2024-01-31'),
+ *   groupBy: 'day'
+ * });
+ * ```
+ */
+class AccountClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get account dashboard with all information
+     *
+     * Includes:
+     * - User profile
+     * - Subscription details
+     * - Usage statistics
+     * - Tier limits
+     * - API keys count
+     *
+     * @returns Complete dashboard data
+     */
+    async getDashboard() {
+        return this.http.get('/account/dashboard');
+    }
+    /**
+     * Update user profile
+     *
+     * @param data - Profile update data (username, email)
+     * @returns Success response
+     */
+    async updateProfile(data) {
+        return this.http.put('/account/profile', data);
+    }
+    /**
+     * Change password
+     *
+     * @param data - Password change data (currentPassword, newPassword)
+     * @returns Success response
+     */
+    async changePassword(data) {
+        return this.http.put('/account/password', data);
+    }
+    /**
+     * Get usage statistics
+     *
+     * @param query - Query parameters (startDate, endDate, groupBy)
+     * @returns Array of usage statistics
+     */
+    async getUsage(query) {
+        return this.http.get('/account/usage', {
+            params: query,
+        });
+    }
+    /**
+     * Delete account permanently
+     *
+     * **Warning:** This action is irreversible
+     *
+     * @returns Success response
+     */
+    async deleteAccount() {
+        return this.http.delete('/account');
+    }
+}
+exports.AccountClient = AccountClient;
+//# sourceMappingURL=account.client.js.map

package/dist/clients/account.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.client.js","sourceRoot":"","sources":["../../src/clients/account.client.ts"],"names":[],"mappings":";;;AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,aAAa;IACxB,YAAoB,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,YAAY;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAmB,oBAAoB,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa,CAAC,IAAsB;QACxC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAsB,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,IAAuB;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAsB,mBAAmB,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAkB;QAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAe,gBAAgB,EAAE;YACnD,MAAM,EAAE,KAAY;SACrB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,aAAa;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAsB,UAAU,CAAC,CAAC;IAC3D,CAAC;CACF;AA7DD,sCA6DC"}