@feedinbox/sdk

Secure TypeScript SDK for FeedInbox - Complete API client for feedback collection, user engagement, and customer data management.

Installation

npm install @feedinbox/sdk

Quick Start

import { FeedInboxSDK } from '@feedinbox/sdk';

// Initialize with API key from environment
const feedinbox = new FeedInboxSDK();

// Create feedback
const result = await feedinbox.createFeedback({
  userEmail: '[email protected]',
  message: 'Great product! Love the new features.',
  priority: 'high',
  subject: 'Product Feedback'
});

if (result.success) {
  console.log('Feedback submitted:', result.data);
} else {
  console.error('Error:', result.error);
}

Configuration

Set your API key as an environment variable:

export FEEDINBOX_API_KEY="fb_your_api_key_here"

Or pass it directly to the constructor:

const feedinbox = new FeedInboxSDK({
  apiKey: 'fb_your_api_key_here',
  timeout: 15000,
  retries: 3
});

Config Options

• apiKey - Your FeedInbox API key (uses FEEDINBOX_API_KEY env var if not provided)
• apiUrl - Custom API endpoint URL
• timeout - Request timeout in milliseconds (default: 10000)
• retries - Number of retries for failed requests (default: 2)
• customBackendUrl - Override the API URL completely

API Methods

All methods return Promise<ApiResponse<T>> with consistent error handling:

interface ApiResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

Feedback

Create Feedback

await sdk.createFeedback({
  userEmail: '[email protected]',     // Required
  message: 'Your feedback message',  // Required (max 10,000 chars)
  subject: 'Optional subject',       // Optional
  priority: 'low' | 'medium' | 'high', // Optional (default: 'medium')
  workspaceId: 'workspace_id',       // Optional
  metadata: { key: 'value' }         // Optional
});

Get Feedback

await sdk.getFeedback({
  userEmail: '[email protected]',     // Optional filter
  limit: 10,                         // Optional (1-100)
  page: 1,                          // Optional
  status: 'open' | 'responded' | 'closed' // Optional filter
});

Update Feedback

await sdk.updateFeedback('feedback_id', {
  message: 'Updated message',
  priority: 'high',
  status: 'responded'
});

Delete Feedback

await sdk.deleteFeedback('feedback_id');

Subscribers

Create Subscriber

await sdk.createSubscriber({
  email: '[email protected]',        // Required
  subscriptions: [                  // Required
    { 
      id: 'newsletter', 
      title: 'Weekly Newsletter', 
      description: 'Weekly updates' 
    }
  ],
  consent: true,                    // Optional
  workspaceId: 'workspace_id',      // Optional
  metadata: { source: 'website' }  // Optional
});

Get Subscriber

await sdk.getSubscriber('[email protected]');

Update Subscriber

await sdk.updateSubscriber('[email protected]', [
  { 
    id: 'newsletter', 
    title: 'Weekly Newsletter', 
    description: 'Weekly updates' 
  }
]);

Delete Subscriber

await sdk.deleteSubscriber('[email protected]');

Contacts

Create Contact

await sdk.createContact({
  firstName: 'John',                // Required
  lastName: 'Doe',                  // Optional
  email: '[email protected]',        // Required
  message: 'Your message here',     // Required
  subject: 'Optional subject',      // Optional
  workspaceId: 'workspace_id',      // Optional
  metadata: { source: 'contact_form' } // Optional
});

Get Contacts

await sdk.getContacts({
  userEmail: '[email protected]',    // Optional filter
  limit: 50,                        // Optional (1-100)
  page: 1                          // Optional
});

Update Contact

await sdk.updateContact('contact_id', {
  firstName: 'Jane',
  lastName: 'Smith',
  message: 'Updated message'
});

Delete Contact

await sdk.deleteContact('contact_id');

User Preferences

Create Preferences

await sdk.createPreferences('[email protected]', {
  preferences: [                    // Required
    { 
      id: 'email_frequency', 
      title: 'Email Frequency', 
      description: 'How often to receive emails',
      value: 'weekly'
    }
  ],
  workspaceId: 'workspace_id',      // Optional
  metadata: { theme: 'dark' }       // Optional
});

Get Preferences

await sdk.getPreferences('[email protected]');

Update Preferences

await sdk.updatePreferences('[email protected]', {
  preferences: [
    { 
      id: 'email_frequency', 
      title: 'Email Frequency', 
      description: 'How often to receive emails',
      value: 'daily'  // Updated value
    }
  ]
});

Delete Preferences

await sdk.deletePreferences('[email protected]');

Helper Methods

Toggle Subscription

await sdk.toggleSubscription(
  '[email protected]',
  'newsletter_id',
  true,  // true to subscribe, false to unsubscribe
  { source: 'user_dashboard' }  // Optional metadata
);

Get Complete User Profile

const profile = await sdk.getUserProfile('[email protected]', {
  includePreferences: true,         // Optional
  includeSubscriptions: true,       // Optional
  includeMetadata: true            // Optional
});

Check User Data Existence

const dataCheck = await sdk.hasUserData('[email protected]');
// Returns: { hasPreferences: boolean, hasSubscriptions: boolean, hasAnyData: boolean }

Error Handling

Always check the success property of API responses:

const result = await feedinbox.createFeedback(data);

if (result.success) {
  console.log('Success:', result.data);
} else {
  console.error('Error:', result.error);
  // Handle error appropriately
}

Deprecated Methods

These methods are still supported but deprecated. Use the newer equivalents:

// Deprecated
await sdk.subscribe(data);      // Use createSubscriber() instead
await sdk.submitContact(data);  // Use createContact() instead

Security Features

• API key validation (must start with fb_)
• Input sanitization against XSS attacks
• Email and URL validation
• Rate limiting (100 requests/minute per instance)
• Automatic retry with exponential backoff
• Request timeout protection

Examples

Newsletter Subscription

async function subscribeUser(email: string) {
  const result = await feedinbox.createSubscriber({
    email,
    subscriptions: [
      { id: 'newsletter', title: 'Weekly Newsletter', description: 'Product updates' }
    ],
    consent: true
  });
  
  if (result.success) {
    console.log('Successfully subscribed');
  } else {
    console.error('Subscription failed:', result.error);
  }
}

Contact Form Submission

async function submitContact(formData) {
  const result = await feedinbox.createContact({
    firstName: formData.firstName,
    lastName: formData.lastName,
    email: formData.email,
    message: formData.message,
    subject: formData.subject,
    metadata: {
      source: 'contact_page',
      timestamp: new Date().toISOString()
    }
  });

  return result;
}

Requirements

• Node.js 16+
• TypeScript 5.8+

License

MIT © FeedInbox