Customerio Sdk PatternsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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 <[email protected]>
tags:
- saas
- customer-io
- sdk
- patterns
- typescript
compatibility: Designed for Claude Code
---
# Customer.io SDK Patterns

## Output

- A reusable SDK integration pattern with scoped configuration, schema validation, idempotency, observability, and error classification.
- A test-backed client boundary that keeps credentials and recipient data out of logs and source control.

## Examples

Instantiate the client from an environment-specific secret reference, validate a synthetic event against the contract, attach a stable idempotency key, and assert the SDK call in a mocked unit test. For a development integration test, use a synthetic profile and record only result status/correlation ID; never log the client token or full event payload.

## 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

```typescript
// 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 } }
  | { name: "subscription_cancelled"; data: { reason: string; feedback?: string } };

// Define user attributes with strict types
interface CioUserAttributes {
  email: string;
  first_name?: string;
  last_name?: string;
  plan?: "free" | "starter" | "pro" | "enterprise";
  company?: string;
  created_at?: number;       // Unix seconds
  last_seen_at?: number;     // Unix seconds
  [key: string]: unknown;    // Allow additional attributes
}

export class TypedCioClient {
  private client: TrackClient;

  constructor(siteId: string, apiKey: string, region: "us" | "eu" = "us") {
    this.client = new TrackClient(siteId, apiKey, {
      region: region === "eu" ? RegionEU : RegionUS,
    });
  }

  async identify(userId: string, attributes: CioUserAttributes): Promise<void> {
    await this.client.identify(userId, {
      ...attributes,
      last_seen_at: Math.floor(Date.now() / 1000),
    });
  }

  async track(userId: string, event: CioEvent): Promise<void> {
    await this.client.track(userId, {
      name: event.name,
      data: { ...event.data, tracked_at: Math.floor(Date.now() / 1000) },
    });
  }

  async suppress(userId: string): Promise<void> {
    await this.client.suppress(userId);
  }

  async destroy(userId: string): Promise<void> {
    await this.client.destroy(userId);
  }
}
```

### Pattern 2: Retry with Exponential Backoff

```typescript
// lib/customerio-retry.ts
interface RetryOptions {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitterFactor: number;  // 0 to 1
}

const DEFAULT_RETRY: RetryOptions = {
  maxRetries: 3,
  baseDelayMs: 1000,
  maxDelayMs: 30000,
  jitterFactor: 0.3,
};

async function withRetry<T>(
  fn: () => Promise<T>,
  opts: RetryOptions = DEFAULT_RETRY
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      lastError = err;
      const statusCode = err.statusCode ?? err.status;

      // Don't retry client errors (except 429 rate limit)
      if (statusCode >= 400 && statusCode < 500 && statusCode !== 429) {
        throw err;
      }

      if (attempt === opts.maxRetries) break;

      // Exponential backoff with jitter
      const delay = Math.min(
        opts.baseDelayMs * Math.pow(2, attempt),
        opts.maxDelayMs
      );
      const jitter = delay * opts.jitterFactor * Math.random();
      await new Promise((r) => setTimeout(r, delay + jitter));
    }
  }
  throw lastError;
}

// Usage with Customer.io client
import { TrackClient, RegionUS } from "customerio-node";

const cio = new TrackClient(
  process.env.CUSTOMERIO_SITE_ID!,
  process.env.CUSTOMERIO_TRACK_API_KEY!,
  { region: RegionUS }
);

// Wrap any operation with retry
await withRetry(() =>
  cio.identify("user-123", { email: "[email protected]" })
);

await withRetry(() =>
  cio.track("user-123", { name: "page_viewed", data: { url: "/pricing" } })
);
```

### Pattern 3: Event Queue with Batching

```typescript
// lib/customerio-batch.ts
import { TrackClient, RegionUS } from "customerio-node";

interface QueuedEvent {
  userId: string;
  name: string;
  data?: Record<string, any>;
}

export class CioBatchTracker {
  private queue: QueuedEvent[] = [];
  private timer: NodeJS.Timeout | null = null;
  private client: TrackClient;

  constructor(
    private readonly batchSize: number = 50,
    private readonly flushIntervalMs: number = 5000
  ) {
    this.client = new TrackClient(
      process.env.CUSTOMERIO_SITE_ID!,
      process.env.CUSTOMERIO_TRACK_API_KEY!,
      { region: RegionUS }
    );
    this.startTimer();
  }

  enqueue(userId: string, name: string, data?: Record<string, any>): void {
    this.queue.push({ userId, name, data });
    if (this.queue.length >= this.batchSize)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.