proofio-sdk 1.0.0

package/README.md

@@ -0,0 +1,319 @@
+# Proofio SDK
+
+Official JavaScript/TypeScript SDK for the Proofio API.
+
+## Installation
+
+```bash
+npm install proofio-sdk
+# or
+yarn add proofio-sdk
+# or
+pnpm add proofio-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Proofio } from 'proofio-sdk';
+
+const proofio = new Proofio({ apiKey: 'your-api-key' });
+
+// List reviews
+const reviews = await proofio.reviews.list();
+
+// Get insights summary
+const summary = await proofio.insights.summary();
+
+// Get trends
+const trends = await proofio.insights.trends();
+
+// Get widget data
+const widget = await proofio.widget.get();
+```
+
+## Authentication
+
+The SDK uses API key authentication. Get your API key from the Proofio dashboard.
+
+```typescript
+const proofio = new Proofio({
+  apiKey: 'your-api-key-here',
+});
+```
+
+## Usage Examples
+
+### Reviews
+
+#### List Reviews
+
+```typescript
+// Get all reviews (default: 10)
+const reviews = await proofio.reviews.list();
+
+// With filters and pagination
+const filteredReviews = await proofio.reviews.list({
+  limit: 50,
+  offset: 0,
+  minRating: 4,
+  sentiment: 'positive',
+  language: 'de',
+  sourceId: 'source-id-here',
+  since: '2024-01-01T00:00:00Z',
+});
+```
+
+#### Get Single Review
+
+```typescript
+const review = await proofio.reviews.get('review-id-here');
+if (review) {
+  console.log(review.text);
+  console.log(review.rating);
+}
+```
+
+### Insights
+
+#### Get Summary
+
+```typescript
+const summary = await proofio.insights.summary();
+
+console.log(`Total Reviews: ${summary.totalReviews}`);
+console.log(`Average Rating: ${summary.averageRating}`);
+console.log(`Rating Distribution:`, summary.ratingDistribution);
+console.log(`Sentiment:`, summary.sentimentDistribution);
+
+// AI Summary (if available for paid plans)
+if (summary.aiSummary) {
+  console.log(`AI Summary: ${summary.aiSummary.summary}`);
+}
+```
+
+#### Get Trends
+
+```typescript
+const trends = await proofio.insights.trends();
+
+console.log(`Trend over time:`, trends.trendOverTime);
+console.log(`Top topics:`, trends.topTopics);
+console.log(`Key takeaways:`, trends.keyTakeaways);
+console.log(`Recent changes:`, trends.recentChanges);
+```
+
+### Widget
+
+#### Get Widget Data
+
+```typescript
+const widget = await proofio.widget.get();
+
+console.log(`Stats:`, widget.stats);
+console.log(`Settings:`, widget.settings);
+```
+
+#### Get Widget Configuration
+
+```typescript
+const config = await proofio.widget.config();
+
+console.log(`Language: ${config.language}`);
+console.log(`Theme: ${config.theme}`);
+console.log(`Show AI Badge: ${config.showAiBadge}`);
+```
+
+### Competitors
+
+#### Compare with Competitor
+
+```typescript
+const comparison = await proofio.competitors.compare('competitor-id', {
+  force: false, // Set to true to force refresh
+});
+
+console.log(`Summary: ${comparison.summary}`);
+console.log(`Strengths:`, comparison.strengths);
+console.log(`Weaknesses:`, comparison.weaknesses);
+console.log(`Recommendations:`, comparison.recommendations);
+```
+
+## Error Handling
+
+The SDK throws `ProofioError` for all API errors. Always wrap API calls in try-catch blocks.
+
+```typescript
+import { Proofio, ProofioError } from 'proofio';
+
+try {
+  const reviews = await proofio.reviews.list();
+} catch (error) {
+  if (error instanceof ProofioError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status: ${error.status}`);
+    console.error(`Code: ${error.code}`);
+    
+    // Check if retryable
+    if (error.isRetryable()) {
+      // Implement retry logic
+    }
+    
+    // Rate limit handling
+    if (error.status === 429) {
+      console.error(`Rate limit exceeded. Retry after: ${error.retryAfter} seconds`);
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Error Types
+
+- `INVALID_API_KEY`: API key is missing or invalid
+- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded (status 429)
+- `API_ERROR`: General API error
+- `NETWORK_ERROR`: Network/connection error
+- `TIMEOUT`: Request timeout
+
+## Pagination
+
+The SDK supports pagination for list endpoints:
+
+```typescript
+let offset = 0;
+const limit = 50;
+let allReviews: Review[] = [];
+
+while (true) {
+  const reviews = await proofio.reviews.list({ limit, offset });
+  
+  if (reviews.length === 0) {
+    break;
+  }
+  
+  allReviews = allReviews.concat(reviews);
+  offset += limit;
+  
+  // Prevent infinite loops
+  if (reviews.length < limit) {
+    break;
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const proofio = new Proofio({
+  apiKey: 'your-api-key',
+  baseURL: 'https://proofio.app', // Optional, default: https://proofio.app
+  timeout: 30000, // Optional, default: 30000ms (30 seconds)
+  maxRetries: 3, // Optional, default: 3
+  retryDelay: 1000, // Optional, default: 1000ms (1 second)
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import { Proofio, Review, InsightSummary } from 'proofio';
+
+const proofio = new Proofio({ apiKey: 'your-api-key' });
+
+// All types are inferred
+const reviews: Review[] = await proofio.reviews.list();
+const summary: InsightSummary = await proofio.insights.summary();
+```
+
+## API Reference
+
+### Proofio Class
+
+Main SDK client class.
+
+#### Constructor
+
+```typescript
+new Proofio(config: ProofioConfig)
+```
+
+#### Methods
+
+- `reviews`: ReviewsResource - Access to review endpoints
+- `insights`: InsightsResource - Access to insights endpoints
+- `competitors`: CompetitorsResource - Access to competitor endpoints
+- `widget`: WidgetResource - Access to widget endpoints
+
+### ReviewsResource
+
+#### `list(options?: ReviewFilterOptions): Promise<Review[]>`
+
+List reviews with optional filters.
+
+#### `get(id: string): Promise<Review | null>`
+
+Get a single review by ID.
+
+### InsightsResource
+
+#### `summary(): Promise<InsightSummary>`
+
+Get aggregated insights summary.
+
+#### `trends(): Promise<InsightTrends>`
+
+Get trend analysis data.
+
+### CompetitorsResource
+
+#### `compare(competitorId: string, options?: { force?: boolean }): Promise<CompetitorComparison>`
+
+Compare your product with a competitor.
+
+### WidgetResource
+
+#### `get(): Promise<WidgetData>`
+
+Get widget data including stats and settings.
+
+#### `config(): Promise<WidgetSettings>`
+
+Get widget configuration only.
+
+## Rate Limits
+
+The SDK automatically handles rate limits and includes retry logic. Rate limit information is available in error responses:
+
+```typescript
+try {
+  await proofio.reviews.list();
+} catch (error) {
+  if (error instanceof ProofioError && error.status === 429) {
+    console.log(`Remaining: ${error.rateLimitRemaining}`);
+    console.log(`Reset at: ${new Date(error.rateLimitReset! * 1000)}`);
+    console.log(`Retry after: ${error.retryAfter} seconds`);
+  }
+}
+```
+
+## Browser Support
+
+The SDK uses the Fetch API, which is available in:
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Node.js 18+ (with native fetch support)
+- For older Node.js versions, use a fetch polyfill like `node-fetch`
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/proofio/proofio-sdk/issues
+- Documentation: https://proofio.app/docs
+- Email: support@proofio.app

package/dist/cjs/client/api-client.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * Core API Client für Proofio SDK
+ *
+ * Handles:
+ * - API Key Authentication
+ * - Base URL Management
+ * - Request/Response Handling
+ * - Error Normalization
+ * - Rate Limit Handling
+ * - Retry Logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = void 0;
+const errors_1 = require("../utils/errors");
+class ApiClient {
+    constructor(config) {
+        if (!config.apiKey || typeof config.apiKey !== 'string' || config.apiKey.trim().length === 0) {
+            throw new errors_1.ProofioError({
+                message: 'API key is required',
+                status: 0,
+                code: 'INVALID_API_KEY',
+            });
+        }
+        // Validate API key format (basic validation)
+        if (config.apiKey.length < 10) {
+            throw new errors_1.ProofioError({
+                message: 'API key format is invalid',
+                status: 0,
+                code: 'INVALID_API_KEY',
+            });
+        }
+        this.apiKey = config.apiKey.trim();
+        this.baseURL = config.baseURL || 'https://proofio.app';
+        this.timeout = config.timeout || 30000; // 30 seconds
+        this.maxRetries = config.maxRetries ?? 3;
+        this.retryDelay = config.retryDelay ?? 1000; // 1 second
+    }
+    /**
+     * Sanitize API key for logging (never log full key)
+     */
+    sanitizeApiKey() {
+        if (this.apiKey.length <= 8) {
+            return '***';
+        }
+        return `${this.apiKey.substring(0, 4)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    /**
+     * Build headers for requests
+     */
+    buildHeaders(customHeaders) {
+        const headers = new Headers({
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            'User-Agent': 'proofio-sdk/1.0.0',
+            ...customHeaders,
+        });
+        // Make headers immutable by creating new Headers object
+        return new Headers(headers);
+    }
+    /**
+     * Build full URL
+     */
+    buildURL(path, queryParams) {
+        const url = new URL(path, this.baseURL);
+        if (queryParams) {
+            Object.entries(queryParams).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, String(value));
+                }
+            });
+        }
+        return url.toString();
+    }
+    /**
+     * Handle rate limit errors
+     */
+    async handleRateLimit(response) {
+        const retryAfter = response.headers.get('Retry-After');
+        const rateLimitRemaining = response.headers.get('X-RateLimit-Remaining');
+        const rateLimitReset = response.headers.get('X-RateLimit-Reset');
+        const errorData = {
+            message: 'Rate limit exceeded',
+            status: 429,
+            code: 'RATE_LIMIT_EXCEEDED',
+        };
+        if (retryAfter) {
+            errorData.retryAfter = parseInt(retryAfter, 10);
+        }
+        if (rateLimitRemaining !== null) {
+            errorData.rateLimitRemaining = parseInt(rateLimitRemaining, 10);
+        }
+        if (rateLimitReset) {
+            errorData.rateLimitReset = parseInt(rateLimitReset, 10);
+        }
+        throw new errors_1.ProofioError(errorData);
+    }
+    /**
+     * Parse error response
+     */
+    async parseErrorResponse(response) {
+        let errorData = {
+            message: `API request failed with status ${response.status}`,
+            status: response.status,
+            code: 'API_ERROR',
+        };
+        try {
+            const contentType = response.headers.get('content-type');
+            if (contentType && contentType.includes('application/json')) {
+                const data = await response.json();
+                errorData = {
+                    ...errorData,
+                    message: data.error || data.message || errorData.message,
+                    code: data.code || errorData.code,
+                    requestId: data.requestId,
+                };
+            }
+        }
+        catch {
+            // If JSON parsing fails, use default error
+        }
+        return new errors_1.ProofioError(errorData);
+    }
+    /**
+     * Sleep helper for retries
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryableError(status, error) {
+        // Retry on network errors, timeouts, and 5xx errors
+        if (!status)
+            return true; // Network error
+        if (status >= 500)
+            return true; // Server errors
+        if (status === 429)
+            return true; // Rate limit (with backoff)
+        if (status === 408)
+            return true; // Request timeout
+        return false;
+    }
+    /**
+     * Execute request with retry logic
+     */
+    async executeWithRetry(requestFn, retryCount = 0) {
+        try {
+            const response = await requestFn();
+            // If rate limited, throw immediately (don't retry immediately)
+            if (response.status === 429) {
+                await this.handleRateLimit(response);
+            }
+            // If error is retryable and we haven't exceeded max retries
+            if (!response.ok && this.isRetryableError(response.status) && retryCount < this.maxRetries) {
+                // Exponential backoff with jitter
+                const delay = this.retryDelay * Math.pow(2, retryCount) + Math.random() * 1000;
+                await this.sleep(delay);
+                return this.executeWithRetry(requestFn, retryCount + 1);
+            }
+            return response;
+        }
+        catch (error) {
+            // Network errors are retryable
+            if (retryCount < this.maxRetries && this.isRetryableError(0, error)) {
+                const delay = this.retryDelay * Math.pow(2, retryCount) + Math.random() * 1000;
+                await this.sleep(delay);
+                return this.executeWithRetry(requestFn, retryCount + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Make GET request
+     */
+    async get(path, options) {
+        const url = this.buildURL(path, options?.queryParams);
+        const headers = this.buildHeaders(options?.headers);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.executeWithRetry(async () => {
+                return fetch(url, {
+                    method: 'GET',
+                    headers,
+                    signal: controller.signal,
+                });
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                if (response.status === 429) {
+                    await this.handleRateLimit(response);
+                }
+                throw await this.parseErrorResponse(response);
+            }
+            const data = await response.json();
+            // Convert Headers to plain object
+            const headers = {};
+            response.headers.forEach((value, key) => {
+                headers[key] = value;
+            });
+            return {
+                data,
+                status: response.status,
+                headers,
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof errors_1.ProofioError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new errors_1.ProofioError({
+                    message: 'Request timeout',
+                    status: 408,
+                    code: 'TIMEOUT',
+                });
+            }
+            throw new errors_1.ProofioError({
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+                status: 0,
+                code: 'NETWORK_ERROR',
+            });
+        }
+    }
+    /**
+     * Make POST request
+     */
+    async post(path, body, options) {
+        const url = this.buildURL(path, options?.queryParams);
+        const headers = this.buildHeaders(options?.headers);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.executeWithRetry(async () => {
+                return fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                if (response.status === 429) {
+                    await this.handleRateLimit(response);
+                }
+                throw await this.parseErrorResponse(response);
+            }
+            const data = await response.json();
+            // Convert Headers to plain object
+            const headers = {};
+            response.headers.forEach((value, key) => {
+                headers[key] = value;
+            });
+            return {
+                data,
+                status: response.status,
+                headers,
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof errors_1.ProofioError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new errors_1.ProofioError({
+                    message: 'Request timeout',
+                    status: 408,
+                    code: 'TIMEOUT',
+                });
+            }
+            throw new errors_1.ProofioError({
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+                status: 0,
+                code: 'NETWORK_ERROR',
+            });
+        }
+    }
+}
+exports.ApiClient = ApiClient;

package/dist/cjs/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Proofio SDK
+ *
+ * Official JavaScript/TypeScript SDK for Proofio API
+ *
+ * @example
+ * ```typescript
+ * import { Proofio } from 'proofio-sdk';
+ *
+ * const proofio = new Proofio({ apiKey: 'your-api-key' });
+ *
+ * const reviews = await proofio.reviews.list();
+ * const summary = await proofio.insights.summary();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Proofio = exports.ApiClient = exports.ProofioError = void 0;
+const api_client_1 = require("./client/api-client");
+const reviews_1 = require("./resources/reviews");
+const insights_1 = require("./resources/insights");
+const competitors_1 = require("./resources/competitors");
+const widget_1 = require("./resources/widget");
+var errors_1 = require("./utils/errors");
+Object.defineProperty(exports, "ProofioError", { enumerable: true, get: function () { return errors_1.ProofioError; } });
+var api_client_2 = require("./client/api-client");
+Object.defineProperty(exports, "ApiClient", { enumerable: true, get: function () { return api_client_2.ApiClient; } });
+/**
+ * Main Proofio SDK Client
+ *
+ * Provides access to all Proofio API resources:
+ * - reviews: List and get reviews
+ * - insights: Get summaries and trends
+ * - competitors: Compare with competitors
+ * - widget: Get widget data and configuration
+ */
+class Proofio {
+    /**
+     * Create a new Proofio SDK instance
+     *
+     * @param config - SDK configuration
+     * @param config.apiKey - Your Proofio API key (required)
+     * @param config.baseURL - Base URL for API (default: https://proofio.app)
+     * @param config.timeout - Request timeout in milliseconds (default: 30000)
+     * @param config.maxRetries - Maximum number of retries (default: 3)
+     * @param config.retryDelay - Delay between retries in milliseconds (default: 1000)
+     *
+     * @example
+     * ```typescript
+     * const proofio = new Proofio({
+     *   apiKey: 'your-api-key-here',
+     *   baseURL: 'https://proofio.app', // optional
+     *   timeout: 30000, // optional
+     * });
+     * ```
+     */
+    constructor(config) {
+        this.client = new api_client_1.ApiClient(config);
+        // Initialize resources
+        this.reviews = new reviews_1.ReviewsResource(this.client);
+        this.insights = new insights_1.InsightsResource(this.client);
+        this.competitors = new competitors_1.CompetitorsResource(this.client);
+        this.widget = new widget_1.WidgetResource(this.client);
+    }
+    /**
+     * Get the underlying API client (for advanced usage)
+     */
+    getClient() {
+        return this.client;
+    }
+}
+exports.Proofio = Proofio;
+// Default export
+exports.default = Proofio;