Poketto SDK

Official JavaScript/TypeScript SDK for Poketto feedback forms. Easily submit form responses from your web applications, mobile apps, or server-side applications.

Installation

npm install poketto-sdk

Quick Start

import { PokettoClient } from 'poketto-sdk';

// Initialize the client
const client = new PokettoClient({
  apiKey: 'your-api-key'
});

// Submit a form response
await client.submitResponse('form-id', [
  { field_id: 'name', value: 'John Doe' },
  { field_id: 'email', value: '[email protected]' },
  { field_id: 'feedback', value: 'Great product!' }
]);

Features

• ✅ TypeScript Support - Full type safety and IntelliSense
• ✅ Auto Browser Detection - Automatically captures browser, OS, and device info
• ✅ UTM Parameter Extraction - Automatically extracts marketing parameters
• ✅ Retry Logic - Built-in retry mechanism for failed requests
• ✅ Validation - Client-side validation for common errors
• ✅ Multiple Formats - ES Modules, CommonJS, and UMD builds
• ✅ Cross-Platform - Works in browsers, Node.js, React Native, and more

API Reference

PokettoClient

Constructor

new PokettoClient(config: PokettoSDKConfig, options?: PokettoSDKOptions)

Config Options:

• apiKey (required): Your Poketto API key
• timeout (optional): Request timeout in milliseconds (default: 10000)

SDK Options:

• retries (optional): Number of retry attempts (default: 3)
• retryDelay (optional): Delay between retries in milliseconds (default: 1000)
• validateFields (optional): Enable client-side validation (default: true)

Methods

submitResponse(formId, fieldResponses, respondent?, options?)

Submit a form response with manual data.

await client.submitResponse(
  'form-123',
  [
    { field_id: 'name', value: 'John Doe' },
    { field_id: 'email', value: '[email protected]' }
  ],
  {
    name: 'John Doe',
    email: '[email protected]',
    metadata: { source: 'website' }
  }
);

submitResponseWithBrowserInfo(formId, fieldResponses, respondent?, options?)

Submit a form response with auto-detected browser information.

await client.submitResponseWithBrowserInfo(
  'form-123',
  [
    { field_id: 'feedback', value: 'Great service!' }
  ],
  {
    email: '[email protected]' // Optional respondent data
  }
);

Usage Examples

Basic Form Submission

import { PokettoClient } from 'poketto-sdk';

const client = new PokettoClient({ apiKey: 'your-api-key' });

try {
  const response = await client.submitResponse('form-id', [
    { field_id: 'rating', value: '5' },
    { field_id: 'comment', value: 'Excellent service!' }
  ]);
  
  console.log('Response submitted:', response.data.responseId);
} catch (error) {
  console.error('Submission failed:', error.message);
}

With Custom Respondent Data

await client.submitResponse(
  'feedback-form',
  [
    { field_id: 'satisfaction', value: 'very-satisfied' },
    { field_id: 'suggestions', value: 'Keep up the great work!' }
  ],
  {
    name: 'Jane Smith',
    email: '[email protected]',
    metadata: {
      customerType: 'premium',
      accountId: 'acc-123'
    }
  }
);

Auto-Detect Browser Info (Recommended for Web Apps)

// This automatically captures browser, OS, device info, UTM parameters, etc.
await client.submitResponseWithBrowserInfo(
  'survey-form',
  [
    { field_id: 'experience', value: 'positive' }
  ],
  {
    email: '[email protected]' // Optional additional data
  }
);

Helper Methods

// Create field responses from an object
const responses = PokettoClient.createFieldResponses({
  'name': 'John Doe',
  'email': '[email protected]',
  'rating': '5'
});

// Create a single field response
const response = PokettoClient.createFieldResponse('feedback', 'Great!');

Error Handling

import { PokettoError } from 'poketto-sdk';

try {
  await client.submitResponse('form-id', responses);
} catch (error) {
  if (error instanceof PokettoError) {
    console.error('Poketto Error:', {
      message: error.message,
      code: error.code,
      statusCode: error.statusCode,
      details: error.details
    });
  } else {
    console.error('Unknown error:', error);
  }
}

React Example

import React, { useState } from 'react';
import { PokettoClient } from 'poketto-sdk';

const client = new PokettoClient({ apiKey: 'your-api-key' });

function FeedbackForm() {
  const [feedback, setFeedback] = useState('');
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      await client.submitResponseWithBrowserInfo(
        'feedback-form-id',
        [{ field_id: 'feedback', value: feedback }]
      );
      alert('Thank you for your feedback!');
      setFeedback('');
    } catch (error) {
      alert('Failed to submit feedback. Please try again.');
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <textarea
        value={feedback}
        onChange={(e) => setFeedback(e.target.value)}
        placeholder="Your feedback..."
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Submitting...' : 'Submit Feedback'}
      </button>
    </form>
  );
}

Node.js Example

const { PokettoClient } = require('poketto-sdk');

const client = new PokettoClient({
  apiKey: process.env.POKETTO_API_KEY
});

async function submitServerFeedback(userId, feedback) {
  try {
    const response = await client.submitResponse(
      'server-feedback-form',
      [
        { field_id: 'user_id', value: userId },
        { field_id: 'feedback', value: feedback }
      ],
      {
        metadata: {
          source: 'server',
          timestamp: new Date().toISOString()
        }
      }
    );
    
    return response.data.responseId;
  } catch (error) {
    console.error('Failed to submit feedback:', error);
    throw error;
  }
}

Configuration

Environment Variables

You can set your API key using environment variables:

POKETTO_API_KEY=your-api-key

const client = new PokettoClient({
  apiKey: process.env.POKETTO_API_KEY || 'fallback-key'
});

Custom Configuration

const client = new PokettoClient(
  {
    apiKey: 'your-api-key',
    timeout: 15000
  },
  {
    retries: 5,
    retryDelay: 2000,
    validateFields: true
  }
);

Types

The SDK includes full TypeScript definitions. Key types include:

• PokettoClient - Main client class
• FieldResponse - Individual field response
• RespondentData - Respondent information
• PokettoError - SDK-specific error class
• BrowserInfo - Auto-detected browser information
• UtmParams - UTM parameter extraction

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• iOS Safari 12+
• Android Chrome 60+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [email protected]
• 📖 Documentation: https://docs.poketto.com
• 🐛 Issues: https://github.com/poketto/poketto-sdk/issues