LightFunnels SDK

TypeScript SDK for the LightFunnels GraphQL API. Provides type-safe methods for managing customers, products, orders, funnels, stores, and more.

Installation

npm install lf-sdk
# or
pnpm add lf-sdk
# or
yarn add lf-sdk

Quick Start

import { LightFunnelsSDK } from 'lf-sdk';

const sdk = new LightFunnelsSDK();

// Authenticate with your user token
sdk.authenticate('your-user-token');

// Fetch customers
const customers = await sdk.getCustomers({ first: 10 });
console.log(customers.edges.map(e => e.node.email));

Authentication

Using a User Token

const sdk = new LightFunnelsSDK();
sdk.authenticate('your-user-token');

OAuth Flow

import { LightFunnelsSDK, getAuthorizationUrl, exchangeCodeForToken } from 'lf-sdk';

// 1. Generate authorization URL
const authUrl = getAuthorizationUrl({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['funnels', 'products', 'orders', 'customers'],
});

// 2. User authorizes and is redirected back with a code
// 3. Exchange code for token
const tokenResponse = await exchangeCodeForToken('auth-code', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// 4. Use the token
const sdk = new LightFunnelsSDK();
sdk.authenticate(tokenResponse.access_token);

Configuration

const sdk = new LightFunnelsSDK({
  apiUrl: 'https://services.lightfunnels.com/v2', // Custom API URL
  timeout: 30000, // Request timeout in ms (default: 30000)
  retries: 3,     // Number of retries for 5xx errors (default: 3)
});

Available Methods

Customers

• getCustomers(params?) - List customers with pagination and filters
• getCustomer(id) - Get a single customer
• createCustomer(customer) - Create a new customer
• updateCustomer(id, customer) - Update a customer

Products

• getProducts(params?) - List products
• getProduct(id) - Get a single product
• createProduct(product) - Create a new product
• updateProduct(id, product) - Update a product
• deleteProducts(ids) - Delete products
• duplicateProduct(id) - Duplicate a product

Orders

• getOrders(params?) - List orders
• getOrder(id) - Get a single order
• updateOrder(id, order) - Update an order
• refundOrder(orderId, paymentId, amount, reason?) - Refund an order
• fulfillOrderItems(orderId, items, options?) - Fulfill order items
• updateTracking(orderId, itemId, tracking) - Update tracking info

Funnels

• getFunnels(params?) - List funnels
• getFunnel(id) - Get a single funnel
• createFunnel(funnel) - Create a new funnel
• updateFunnel(id, funnel) - Update a funnel
• deleteFunnels(ids) - Delete funnels

Stores

• getStores(params?) - List stores
• getStore(id) - Get a single store
• createStore(store) - Create a new store
• updateStore(id, store) - Update a store
• deleteStores(ids) - Delete stores

Collections

• getCollections(params?) - List collections
• getCollection(id) - Get a single collection
• createCollection(collection) - Create a new collection
• updateCollection(id, collection) - Update a collection
• deleteCollections(ids) - Delete collections

Discounts

• getDiscounts(params?) - List discounts
• getDiscount(id) - Get a single discount
• createDiscount(discount) - Create a new discount
• updateDiscount(id, discount) - Update a discount
• deleteDiscounts(ids) - Delete discounts

Reviews

• getReviews(params?) - List reviews
• getReview(id) - Get a single review
• createReview(review) - Create a new review
• updateReview(id, review) - Update a review
• deleteReviews(ids) - Delete reviews

Analytics

• getAnalytics(params) - Get analytics data
• getLiveAnalytics(params?) - Get live analytics

Additional Resources

• Checkouts: getCheckouts, getCheckout
• Tags: getTags, createTag, deleteTags
• Leads: getLeads
• Segments: getSegments, getSegment, createSegment, updateSegment, deleteSegments
• Webhooks: getWebhooks, getWebhook, createWebhook, updateWebhook, deleteWebhooks
• Webhook Events: getWebhookEvents, getWebhookEvent
• Domains: getDomains, getDomain, createDomain, deleteDomains, checkDomainAvailability, searchDomains
• Shipping: getShippingGroups, getShippingGroup, createShippingGroup, updateShippingGroup, deleteShippingGroups, getShippingLocations, createShippingLocation, updateShippingLocation, deleteShippingLocations
• Cloaks: getCloaks, getCloak, createCloak, updateCloak, deleteCloaks
• Media: getImages, deleteImages, getFiles, deleteFiles, getVideos, deleteVideos, getAudios, deleteAudios
• Price Bundles: getPriceBundles, getPriceBundle, createPriceBundle, updatePriceBundle, deletePriceBundles
• Payment Gateways: getPaymentGateways, getPaymentGateway, createPaymentGateway, updatePaymentGateway, deletePaymentGateways
• Account: getAccount, updateAccount

Pagination

All list methods support pagination:

// Basic pagination
const page1 = await sdk.getCustomers({ first: 20 });
const page2 = await sdk.getCustomers({ first: 20, after: page1.pageInfo.endCursor });

// Iterate through all items
for await (const customer of sdk.paginate(
  (params) => sdk.getCustomers(params),
  { first: 50 }
)) {
  console.log(customer.email);
}

Filtering and Sorting

// Filter customers
const customers = await sdk.getCustomers({
  search: 'john',
  email: '[email protected]',
  tags: ['vip', 'premium'],
  orderBy: 'created_at',
  orderDir: 'desc',
});

// Filter orders
const orders = await sdk.getOrders({
  financial_status: 'paid',
  fulfillment_status: 'unfulfilled',
  funnel_id: 'funnel-id',
});

Custom Queries

For advanced use cases, execute raw GraphQL queries:

const result = await sdk.query<{ customField: string }>(`
  query CustomQuery($id: ID!) {
    node(id: $id) {
      ... on Customer {
        id
        email
        customField
      }
    }
  }
`, { id: 'customer-id' });

Error Handling

import { LightFunnelsError } from 'lf-sdk';

try {
  await sdk.getCustomer('invalid-id');
} catch (error) {
  if (LightFunnelsError.isLightFunnelsError(error)) {
    console.log('Status:', error.statusCode);
    console.log('Message:', error.message);
    console.log('Response:', error.response);
  }
}

TypeScript Support

The SDK is fully typed. All types are exported:

import type {
  Customer,
  Product,
  Order,
  Funnel,
  Store,
  Connection,
  GetCustomersParams,
  InputCustomer,
  // ... and many more
} from 'lf-sdk';

License

MIT