ReviewsFlow SDK

TypeScript SDK for ReviewsFlow API - Send WhatsApp messages, manage reviews, register webhooks, and create templates.

Installation

npm install reviewsflow-sdk
# or
yarn add reviewsflow-sdk
# or
pnpm add reviewsflow-sdk
# or
bun add reviewsflow-sdk

Note: This package is fully standalone - all runtime code and TypeScript types are bundled. No additional dependencies needed!

Runtime Compatibility

The SDK is compatible with:

• Node.js 18+ - Native fetch and FormData support
• Bun - Full native support
• Deno - Full native support
• Modern Browsers - All Web APIs supported

Note: For Node.js < 18, you'll need to install a fetch polyfill like node-fetch or use a bundler that provides it.

Quick Start

import { ReviewsFlowSDK } from 'reviewsflow-sdk';

// Option 1: Provide API key directly
const sdk = new ReviewsFlowSDK({
  apiKey: 'your-api-key'
});

// Option 2: Load API key from environment variable
// Set REVIEWSFLOW_API_KEY in your .env file
const sdk = new ReviewsFlowSDK();

// Option 3: Custom configuration
const sdk = new ReviewsFlowSDK({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.reviewsflow.in', // default
  timeout: 30000 // optional, default: 30000ms
});

Environment Variables

The SDK automatically loads the API key from the REVIEWSFLOW_API_KEY environment variable if not provided in the config:

# .env file
REVIEWSFLOW_API_KEY=your-api-key-here

Features

🔄 Response Mapping

Every API call supports an optional mapper function to transform response data to your own structure. If the response is an array, each item is automatically mapped.

// Map single response
const customer = await sdk.customers.get(
  'customer-id',
  (c) => ({
    id: c.id,
    fullName: c.name,
    contact: c.phone,
    emailAddress: c.email
  })
);

// Map array responses - each item gets mapped automatically
const customers = await sdk.customers.list(
  { limit: 20 },
  (customer) => ({
    id: customer.id,
    label: customer.name,
    value: customer.phone
  })
);

// Map paginated responses - data array is mapped, metadata preserved
const result = await sdk.whatsapp.listMessages(
  { phone: '+919876543210' },
  (message) => ({
    messageId: message.id,
    phoneNumber: message.phone,
    text: message.textBody
  })
);
// Result: { data: [...mapped messages], nextCursor, prevCursor }

👥 Customer Management

• Create, read, update, delete customers
• Search customers for autocomplete
• Bulk update operations
• CSV import functionality
• Response mapping support

📱 WhatsApp Messaging

Send various types of WhatsApp messages with a simple, unified API.

Template Messages

// Send template message
await sdk.whatsapp.sendTemplate({
  phone: '+919876543210',
  templateName: 'welcome_message',
  templateAttributes: ['John', 'Welcome']
});

Text Messages

// Send text message
await sdk.whatsapp.sendText({
  phone: '+919876543210',
  text: 'Hello! How can I help you?',
  previewUrl: false
});

Media Messages

// Send image
await sdk.whatsapp.sendImage({
  phone: '+919876543210',
  imageUrl: 'https://example.com/image.jpg',
  caption: 'Check this out!'
});

// Send document
await sdk.whatsapp.sendDocument({
  phone: '+919876543210',
  documentUrl: 'https://example.com/file.pdf',
  filename: 'document.pdf',
  caption: 'Please review'
});

Location Messages

await sdk.whatsapp.sendLocation({
  phone: '+919876543210',
  latitude: '28.6139',
  longitude: '77.2090',
  name: 'Delhi',
  address: 'New Delhi, India'
});

Interactive Messages

// Send button message
await sdk.whatsapp.sendButton({
  phone: '+919876543210',
  bodyText: 'Choose an option:',
  buttons: [
    { id: 'yes', title: 'Yes' },
    { id: 'no', title: 'No' }
  ],
  footerText: 'Select one'
});

// Send list message (using generic send method)
await sdk.whatsapp.send({
  phone: '+919876543210',
  message_type: 'list',
  body_text: 'Select an option:',
  button_text: 'View Options',
  sections: [
    {
      title: 'Category A',
      rows: [
        { id: '1', title: 'Option 1', description: 'First option' },
        { id: '2', title: 'Option 2', description: 'Second option' }
      ]
    }
  ]
});

Advanced Usage

// Use generic send method for full control
await sdk.whatsapp.send({
  phone: '+919876543210',
  message_type: 'template',
  template_name: 'welcome',
  template_attributes: ['John'],
  customerId: 'customer-id', // optional
  numberId: 'number-id', // optional
  custom_data: { source: 'api' } // optional metadata
});

📝 Reviews

Submit and manage customer reviews and review requests.

Simple Review Submission

await sdk.reviews.submitSimple({
  phone: '+919876543210',
  channel: 'whatsapp',
  overAllRating: 5,
  comments: 'Great service!',
  npsScore: 10,
  npsCategory: 'promoter'
});

Full Review Submission

await sdk.reviews.submit({
  phone: '+919876543210',
  profileId: 'profile-id',
  reviewType: 'post_visit',
  channel: 'whatsapp',
  overAllRating: 5,
  comments: 'Excellent experience!',
  npsScore: 10,
  npsCategory: 'promoter',
  publishedPlatforms: ['google', 'practo'],
  sentiment: 'positive'
});

List and Get Reviews

// List reviews
const reviews = await sdk.reviews.list({
  phone: '+919876543210',
  page: 1,
  perPage: 20
});

// Get specific review
const review = await sdk.reviews.get('review-id');

Review Request Operations

// Create review request
const request = await sdk.reviews.createRequest({
  phone: '+919876543210',
  profileId: 'profile-id',
  channels: ['whatsapp'],
  tags: ['post-visit'],
  metadata: { source: 'api', campaignId: 'campaign-123' }
});

// Get review request
const request = await sdk.reviews.getRequest('request-id');

// List review requests
const requests = await sdk.reviews.listRequests({
  profileId: 'profile-id',
  status: 'pending',
  page: 1,
  limit: 20
});

// Update review request
await sdk.reviews.updateRequest('request-id', {
  tags: ['post-visit', 'follow-up'],
  note: 'Updated note'
});

🔔 Webhooks

Register and manage webhooks to receive WhatsApp events.

Register Webhook

const webhook = await sdk.webhooks.register({
  title: 'My Webhook',
  url: 'https://myapp.com/webhooks/whatsapp',
  events: ['incoming', 'sent', 'delivered', 'read', 'failed'],
  active: true
});

Manage Webhooks

// List all webhooks
const webhooks = await sdk.webhooks.list();

// Get webhook
const webhook = await sdk.webhooks.get('webhook-id');

// Update webhook
await sdk.webhooks.update('webhook-id', {
  active: false,
  events: ['incoming', 'sent']
});

// Delete webhook
await sdk.webhooks.delete('webhook-id');

👥 Customers

Create and manage customer records.

Create Customer

const customer = await sdk.customers.create({
  name: 'John Doe',
  phone: '+919876543210',
  email: '[email protected]',
  customerType: 'new',
  source: 'walk_in',
  communicationPreference: 'whatsapp',
  preferredLanguage: 'en'
});

Manage Customers

// Get customer
const customer = await sdk.customers.get('customer-id');

// List customers
const customers = await sdk.customers.list({
  search: 'John',
  limit: 20,
  sort: 'desc'
});

// Search customers (for autocomplete)
const results = await sdk.customers.search({
  search: '+919876543210',
  limit: 10
});

// Update customer
await sdk.customers.update('customer-id', {
  name: 'John Smith',
  email: '[email protected]',
  customerType: 'returning'
});

// Bulk update customers
await sdk.customers.bulkUpdate([
  { id: 'customer-1', name: 'Updated Name 1' },
  { id: 'customer-2', name: 'Updated Name 2' }
]);

// Delete customer
await sdk.customers.delete('customer-id');

Import Customers from CSV

// In browser environment
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
await sdk.customers.import(file);

// In Node.js/Bun environment
import { readFileSync } from 'fs';
const fileBuffer = readFileSync('customers.csv');
const blob = new Blob([fileBuffer], { type: 'text/csv' });
await sdk.customers.import(blob);

📋 Templates

Create and manage WhatsApp message templates.

Create Template

const template = await sdk.templates.create({
  category: 'UTILITY',
  numberId: 'number-uuid',
  metadata: {
    name: 'welcome_message',
    language: 'en'
  },
  header: {
    type: 'TEXT',
    text: 'Welcome!'
  },
  body: {
    text: 'Hello {{1}}, welcome to our service!',
    variables: ['name']
  },
  footer: {
    text: 'Thank you'
  },
  buttons: {
    buttons: [
      { type: 'QUICK_REPLY', text: 'Get Started' }
    ]
  }
});

Manage Templates

// List templates
const templates = await sdk.templates.list({
  category: 'UTILITY',
  status: 'APPROVED'
});

// Get template
const template = await sdk.templates.get('template-id');

// Update template
await sdk.templates.update('template-id', {
  body: { text: 'Updated message' }
});

// Search templates
const results = await sdk.templates.search('welcome');

// Delete template
await sdk.templates.delete('template-id');

// Bulk create templates
const templates = await sdk.templates.bulkCreate([
  {
    category: 'UTILITY',
    numberId: 'number-uuid',
    metadata: { name: 'template1', language: 'en' },
    body: { text: 'Template 1 message' }
  },
  {
    category: 'UTILITY',
    numberId: 'number-uuid',
    metadata: { name: 'template2', language: 'en' },
    body: { text: 'Template 2 message' }
  }
]);

Error Handling

The SDK provides typed error classes for better error handling:

import {
  ReviewsFlowSDKError,
  ValidationError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ServerError
} from '@reviewsflow/sdk';

try {
  await sdk.whatsapp.send({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof ReviewsFlowSDKError) {
    console.error('SDK error:', error.message, error.code);
  }
}

Configuration

const sdk = new ReviewsFlowSDK({
  baseUrl: 'https://api.reviewsflow.in', // optional, default: https://api.reviewsflow.in
  apiKey: 'your-api-key', // optional if REVIEWSFLOW_API_KEY env var is set
  timeout: 30000, // optional, default: 30000ms
  headers: { // optional custom headers
    'X-Custom-Header': 'value'
  }
});

Note: The orgId is no longer needed as it's automatically handled by the API based on your API key authentication.

TypeScript Support

Full TypeScript support with comprehensive type definitions and mapper type inference:

import type {
  WhatsAppMessage,
  WhatsAppMessageResponse,
  ReviewSubmitData,
  WebhookConfig,
  WebhookResponse,
  CreateTemplateData,
  Customer,
  CreateCustomerData
} from '@reviewsflow/sdk';

// Mapper functions are fully typed
const customer = await sdk.customers.get(
  'customer-id',
  (c: Customer) => ({
    id: c.id,
    name: c.name
  })
);
// TypeScript infers the return type automatically

Health Check

const isHealthy = await sdk.healthCheck();
console.log('API is healthy:', isHealthy);

License

UNLICENSED - Proprietary software

Support

For issues and questions, contact: [email protected]