customerio-sdk-patterns

name	customerio-sdk-patterns
description	Apply production-ready Customer.io SDK patterns. Use when implementing typed clients, retry logic, event batching, or singleton management for customerio-node. Trigger: "customer.io best practices", "customer.io patterns", "production customer.io", "customer.io architecture", "customer.io singleton".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*), Glob, Grep
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","customer-io","sdk","patterns","typescript"]
compatibility	Designed for Claude Code

Customer.io SDK Patterns

Overview

Production-ready patterns for customerio-node: type-safe wrappers with enum-constrained events, retry with exponential backoff, event batching for high-volume scenarios, and singleton lifecycle management.

Prerequisites

• customerio-node installed
• TypeScript project (recommended for type-safe patterns)
• Understanding of your event taxonomy

Instructions

Pattern 1: Type-Safe Client Wrapper

// lib/customerio-typed.ts
import { TrackClient, RegionUS, RegionEU } from "customerio-node";

// Define your event taxonomy as a union type
type CioEvent =
  | { name: "signed_up"; data: { method: string; source?: string } }
  | { name: "plan_changed"; data: { from: string; to: string; mrr: number } }
  | { name: "feature_used"; data: { feature: string; duration_ms?: number } }
  | { name: "checkout_completed"; data: { order_id: string; total: number; items: number } }
  | { : ; : { : ; ?:  } };


  {
  : ;
  ?: ;
  ?: ;
  ?:  |  |  | ;
  ?: ;
  ?: ;       
  ?: ;     
  [: ]: ;    
}

   {
   : ;

  () {
    . =  (siteId, apiKey, {
      : region ===  ?  : ,
    });
  }

   (: , : ): <> {
     ..(userId, {
      ...attributes,
      : .(.() / ),
    });
  }

   (: , : ): <> {
     ..(userId, {
      : event.,
      : { ...event., : .(.() / ) },
    });
  }

   (: ): <> {
     ..(userId);
  }

   (: ): <> {
     ..(userId);
  }
}