@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
• Documentation: https://encatch.com/docs

Installation

npm install @encatch/api-sdk
# or
pnpm add @encatch/api-sdk
# or
yarn add @encatch/api-sdk

Quick Start

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.

const response = await sdk.fetchConfiguration({
  deviceDetails: {
    deviceId: 'unique-device-id',
    platform: 'web',
    osVersion: '10.0',
    appVersion: '1.0.0',
  },
  identifier: '[email protected]',
});

fetchNewDeviceConfiguration

Fetches configurations specifically for new devices.

const response = await sdk.fetchNewDeviceConfiguration({
  deviceDetails: {
    deviceId: 'new-device-id',
    platform: 'web',
  },
  identifier: '[email protected]',
});

fetchConfigurationDetails

Fetches detailed information about a specific feedback configuration.

const details = await sdk.fetchConfigurationDetails({
  formConfig: {
    feedbackConfigurationId: 'config-uuid',
    userAction: 'view',
  },
  deviceDetails: {
    deviceId: 'unique-device-id',
    platform: 'web',
  },
  identifier: '[email protected]',
});

submitFeedback

Submits user feedback data. The payload is automatically compressed using gzip.

const result = await sdk.submitFeedback({
  formConfig: {
    feedbackConfigurationId: 'config-uuid',
    userAction: 'submit',
  },
  deviceDetails: {
    deviceId: 'unique-device-id',
    platform: 'web',
  },
  identifier: '[email protected]',
  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.

const result = await sdk.viewFeedback({
  formConfig: {
    feedbackConfigurationId: 'config-uuid',
    userAction: 'view',
  },
  deviceDetails: {
    deviceId: 'unique-device-id',
    platform: 'web',
  },
  identifier: '[email protected]',
});

refineText

Uses Encatch AI services to refine or improve text.

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:

// 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:

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:

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:

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):

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:

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

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', '[email protected]');

License

See the main repository for license information.