@encatch/api-sdk 0.0.9 → 0.0.10

package/README.md

@@ -0,0 +1,366 @@
+# @encatch/api-sdk
+
+JavaScript/TypeScript SDK for interacting with the Encatch API. This package provides a simple and type-safe way to fetch feedback configurations, submit user feedback, and utilize Encatch services.
+
+## Purpose
+
+Use this package when you need direct programmatic access to Encatch API endpoints for:
+- Fetching feedback form configurations
+- Submitting and viewing feedback
+- Refining text using Encatch AI services
+
+## Resources
+
+- **Website**: [https://encatch.com](https://encatch.com)
+- **Documentation**: [https://encatch.com/docs](https://encatch.com/docs)
+
+## Installation
+
+```bash
+npm install @encatch/api-sdk
+# or
+pnpm add @encatch/api-sdk
+# or
+yarn add @encatch/api-sdk
+```
+
+## Quick Start
+
+```typescript
+import { EncatchApiSDK } from '@encatch/api-sdk';
+
+// Initialize the SDK
+const sdk = new EncatchApiSDK({
+  apiKey: 'your-api-key',
+  appPackageName: 'com.example.app',
+  hostUrl: 'https://app.dev.encatch.com', // optional
+  enableLogging: true, // optional, defaults to false
+});
+
+// Fetch configurations
+const configs = await sdk.fetchConfiguration({
+  deviceDetails: {
+    deviceId: 'unique-device-id',
+    platform: 'web',
+  },
+  identifier: 'user-identifier',
+});
+```
+
+## Features
+
+- **TypeScript Support**: Full type safety with TypeScript definitions
+- **Automatic Case Conversion**: Handles snake_case/camelCase transformations
+- **Gzip Compression**: Automatic compression for feedback submissions
+- **Error Handling**: Built-in error handling with state management
+- **Logging**: Optional logging for debugging
+- **State Management**: Track loading and error states
+
+## Configuration
+
+### SDK Constructor Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiKey` | `string` | Yes | - | Your Encatch API key |
+| `appPackageName` | `string` | Yes | - | Your application package name (used as Referer) |
+| `hostUrl` | `string` | No | `https://app.dev.encatch.com` | Base URL for API endpoints |
+| `enableLogging` | `boolean` | No | `false` | Enable console logging for debugging |
+
+## API Methods
+
+### fetchConfiguration
+
+Fetches the list of available feedback configurations for a device.
+
+```typescript
+const response = await sdk.fetchConfiguration({
+  deviceDetails: {
+    deviceId: 'unique-device-id',
+    platform: 'web',
+    osVersion: '10.0',
+    appVersion: '1.0.0',
+  },
+  identifier: 'user@example.com',
+});
+```
+
+### fetchNewDeviceConfiguration
+
+Fetches configurations specifically for new devices.
+
+```typescript
+const response = await sdk.fetchNewDeviceConfiguration({
+  deviceDetails: {
+    deviceId: 'new-device-id',
+    platform: 'web',
+  },
+  identifier: 'user@example.com',
+});
+```
+
+### fetchConfigurationDetails
+
+Fetches detailed information about a specific feedback configuration.
+
+```typescript
+const details = await sdk.fetchConfigurationDetails({
+  formConfig: {
+    feedbackConfigurationId: 'config-uuid',
+    userAction: 'view',
+  },
+  deviceDetails: {
+    deviceId: 'unique-device-id',
+    platform: 'web',
+  },
+  identifier: 'user@example.com',
+});
+```
+
+### submitFeedback
+
+Submits user feedback data. The payload is automatically compressed using gzip.
+
+```typescript
+const result = await sdk.submitFeedback({
+  formConfig: {
+    feedbackConfigurationId: 'config-uuid',
+    userAction: 'submit',
+  },
+  deviceDetails: {
+    deviceId: 'unique-device-id',
+    platform: 'web',
+  },
+  identifier: 'user@example.com',
+  responses: [
+    {
+      questionId: 'q1',
+      answer: 'User response here',
+    },
+  ],
+});
+
+if (result.success) {
+  console.log('Feedback submitted successfully');
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### viewFeedback
+
+Tracks when a user views a feedback form. The payload is automatically compressed using gzip.
+
+```typescript
+const result = await sdk.viewFeedback({
+  formConfig: {
+    feedbackConfigurationId: 'config-uuid',
+    userAction: 'view',
+  },
+  deviceDetails: {
+    deviceId: 'unique-device-id',
+    platform: 'web',
+  },
+  identifier: 'user@example.com',
+});
+```
+
+### refineText
+
+Uses Encatch AI services to refine or improve text.
+
+```typescript
+const refinedText = await sdk.refineText({
+  text: 'Original text to refine',
+  context: 'feedback',
+  language: 'en',
+});
+
+console.log('Refined text:', refinedText.refinedText);
+```
+
+## State Management
+
+The SDK provides getters to track the current state:
+
+```typescript
+// Check if a request is in progress
+if (sdk.loading) {
+  console.log('Loading...');
+}
+
+// Check for errors
+if (sdk.error) {
+  console.error('Error occurred:', sdk.error);
+}
+```
+
+## Error Handling
+
+All methods throw errors on failure. Use try-catch blocks for error handling:
+
+```typescript
+try {
+  const configs = await sdk.fetchConfiguration(params);
+  // Handle success
+} catch (error) {
+  console.error('Failed to fetch configurations:', error);
+  // The error message is also available via sdk.error getter
+  console.log('SDK error state:', sdk.error);
+}
+```
+
+The `submitFeedback` and `viewFeedback` methods return a result object instead of throwing:
+
+```typescript
+const result = await sdk.submitFeedback(params);
+if (!result.success) {
+  console.error('Submission failed:', result.error);
+}
+```
+
+## TypeScript Support
+
+The package exports all TypeScript types from the `@encatch/schema` package:
+
+```typescript
+import type {
+  FetchConfigurationListRequest,
+  FetchConfigurationListResponse,
+  FetchFeedbackDetailsRequest,
+  FetchFeedbackDetailsResponse,
+  SubmitFeedback,
+  ViewFeedback,
+  RefineTextParams,
+  RefineTextResponse,
+} from '@encatch/api-sdk';
+```
+
+## Advanced Usage
+
+### Custom Host URL
+
+For different environments (development, staging, production):
+
+```typescript
+const sdk = new EncatchApiSDK({
+  apiKey: process.env.ENCATCH_API_KEY,
+  appPackageName: 'com.example.app',
+  hostUrl: process.env.ENCATCH_HOST_URL || 'https://app.encatch.com',
+  enableLogging: process.env.NODE_ENV === 'development',
+});
+```
+
+### Debugging with Logging
+
+Enable logging to see detailed request/response information:
+
+```typescript
+const sdk = new EncatchApiSDK({
+  apiKey: 'your-api-key',
+  appPackageName: 'com.example.app',
+  enableLogging: true,
+});
+
+// All API calls will now log to console:
+// [EncatchApiSDK] Fetching configuration from server
+// [EncatchApiSDK] Request body: {...}
+// [EncatchApiSDK] Configuration fetched successfully {...}
+```
+
+## Dependencies
+
+- `@encatch/schema` - Type definitions and utilities (workspace)
+- `pako` >= 2.1.0 - Gzip compression for feedback submissions
+- `ts-case-convert` >= 2.1.0 - Automatic case conversion
+- `zod` >= 4.1.8 - Runtime type validation
+
+## Best Practices
+
+1. **Store API keys securely**: Never commit API keys to version control. Use environment variables.
+
+2. **Reuse SDK instances**: Create a single SDK instance and reuse it throughout your application.
+
+3. **Error handling**: Always wrap SDK calls in try-catch blocks or handle returned error objects.
+
+4. **Enable logging in development**: Use `enableLogging: true` during development for easier debugging.
+
+5. **Monitor loading state**: Use the `loading` getter to show loading indicators in your UI.
+
+## Example: Complete Integration
+
+```typescript
+import { EncatchApiSDK } from '@encatch/api-sdk';
+
+class FeedbackService {
+  private sdk: EncatchApiSDK;
+
+  constructor() {
+    this.sdk = new EncatchApiSDK({
+      apiKey: process.env.ENCATCH_API_KEY!,
+      appPackageName: 'com.example.app',
+      hostUrl: 'https://app.encatch.com',
+      enableLogging: process.env.NODE_ENV === 'development',
+    });
+  }
+
+  async loadFeedbackForms(deviceId: string, userId: string) {
+    try {
+      const response = await this.sdk.fetchConfiguration({
+        deviceDetails: {
+          deviceId,
+          platform: 'web',
+        },
+        identifier: userId,
+      });
+
+      return response.configurations;
+    } catch (error) {
+      console.error('Failed to load feedback forms:', error);
+      throw error;
+    }
+  }
+
+  async submitUserFeedback(
+    configId: string,
+    deviceId: string,
+    userId: string,
+    responses: any[]
+  ) {
+    const result = await this.sdk.submitFeedback({
+      formConfig: {
+        feedbackConfigurationId: configId,
+        userAction: 'submit',
+      },
+      deviceDetails: {
+        deviceId,
+        platform: 'web',
+      },
+      identifier: userId,
+      responses,
+    });
+
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to submit feedback');
+    }
+
+    return result;
+  }
+
+  isLoading(): boolean {
+    return this.sdk.loading;
+  }
+
+  getError(): string | null {
+    return this.sdk.error;
+  }
+}
+
+// Usage
+const feedbackService = new FeedbackService();
+const forms = await feedbackService.loadFeedbackForms('device-123', 'user@example.com');
+```
+
+## License
+
+See the main repository for license information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@encatch/api-sdk",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -20,7 +20,7 @@
     "pako": "^2.1.0",
     "ts-case-convert": "^2.1.0",
     "zod": "^4.1.8",
-    "@encatch/schema": "0.1.31"
+    "@encatch/schema": "0.1.33"
   },
   "scripts": {
     "dev": "vite",