Customerio Upgrade MigrationSAFE

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-upgrade-migration
description: 'Plan and execute Customer.io SDK upgrades and migrations.

  Use when upgrading customerio-node versions, migrating from

  legacy APIs, or updating to new SDK patterns.

  Trigger: "upgrade customer.io", "customer.io migration",

  "update customer.io sdk", "customer.io breaking changes".

  '
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
- migration
- upgrade
compatibility: Designed for Claude Code
---
# Customer.io Upgrade & Migration

## Output

- A staged migration record with schema/template compatibility, environment evidence, owner, and rollback decision.
- A preserved prior configuration and safe observation window before any irreversible cleanup.

## Examples

Migrate a development workspace first using synthetic profiles and versioned event/template contracts. Verify delivery, consent, attributes, and observability before staging and production canaries. If compatibility or recipient behavior differs, roll back to the prior version and stop promotion; do not bulk-replay production events to test a migration.

## Current State

!`npm list customerio-node 2>/dev/null | grep customerio || echo 'customerio-node: not installed'`
!`npm view customerio-node version 2>/dev/null || echo 'Cannot check latest version'`

## Overview

Plan and execute `customerio-node` SDK upgrades safely: assess current version, review breaking changes, apply code migrations, and validate with staged rollout.

## Prerequisites

- Current SDK version identified (`npm list customerio-node`)
- Test environment available
- Version control for rollback

## Major Version Migration Reference

### Legacy `CustomerIO` to Modern `TrackClient` + `APIClient`

Older versions of `customerio-node` used a single `CustomerIO` class. Modern versions split into `TrackClient` (tracking) and `APIClient` (transactional/broadcasts).

```typescript
// BEFORE — Legacy pattern (customerio-node < 2.x)
const CustomerIO = require("customerio-node");
const cio = new CustomerIO(siteId, apiKey);
cio.identify("user-1", { email: "[email protected]" });
cio.track("user-1", { name: "event_name" });

// AFTER — Modern pattern (customerio-node >= 2.x)
import { TrackClient, APIClient, RegionUS } from "customerio-node";

const cio = new TrackClient(siteId, apiKey, { region: RegionUS });
await cio.identify("user-1", { email: "[email protected]" });
await cio.track("user-1", { name: "event_name", data: {} });

const api = new APIClient(appApiKey, { region: RegionUS });
await api.sendEmail(request);
```

**Key changes:**

- `TrackClient` replaces `CustomerIO` for identify/track
- `APIClient` is new — handles transactional + broadcasts
- Region is now explicit (`RegionUS` or `RegionEU`)
- Methods return Promises (must `await`)
- Event tracking uses `{ name, data }` object instead of positional args

## Instructions

### Step 1: Assess Current Version

```typescript
// scripts/cio-version-check.ts
import { readFileSync, existsSync } from "fs";

function assessVersion() {
  // Check installed version
  const lockPath = "package-lock.json";
  if (existsSync(lockPath)) {
    const lock = JSON.parse(readFileSync(lockPath, "utf-8"));
    const installed =
      lock.packages?.["node_modules/customerio-node"]?.version ??
      lock.dependencies?.["customerio-node"]?.version ??
      "not found in lockfile";
    console.log(`Installed: customerio-node@${installed}`);
  }

  // Check package.json declared version
  const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
  const declared = pkg.dependencies?.["customerio-node"] ?? "not declared";
  console.log(`Declared: ${declared}`);

  // Search for usage patterns
  console.log("\nUsage pattern check:");
  console.log("- Look for 'new CustomerIO(' → legacy pattern, needs migration");
  console.log("- Look for 'new TrackClient(' → modern pattern");
  console.log("- Look for 'RegionUS/RegionEU' → region-aware (good)");
}

assessVersion();
```

### Step 2: Review Breaking Changes

```typescript
// Common breaking changes between major versions:

// v1.x → v2.x:
// - CustomerIO class → TrackClient + APIClient
// - Callbacks → Promises (async/await)
// - Region parameter added (defaults to US)
// - SendEmailRequest constructor changed

// v2.x → v3.x:
// - Import path may change
// - TypeScript types improved
// - Error object structure may change

// Always check the official changelog:
// https://github.com/customerio/customerio-node/blob/main/CHANGELOG.md
```

### Step 3: Create Migration Wrapper

```typescript
// lib/customerio-migration.ts
// Adapter that supports both old and new patterns during migration

import { TrackClient, APIClient, RegionUS } from "customerio-node";

export class CioMigrationClient {
  private trackClient: TrackClient;
  private apiClient: APIClient | null;

  constructor(config: {
    siteId: string;
    trackApiKey: string;
    appApiKey?: string;
    region?: "us" | "eu";
  }) {
    const region = config.region === "eu"
      ? (await import("customerio-node")).RegionEU
      : RegionUS;

    this.trackClient = new TrackClient(config.siteId, config.trackApiKey, {
      region,
    });

    this.apiClient = config.appApiKey
      ? new APIClient(config.appApiKey, { region })
      : null;
  }

  // Legacy-compatible identify (accepts both old and new signatures)
  async identify(userId: string, attrs: Record<string, any>): Promise<void> {
    // Ensure timestamps are in seconds, not milliseconds
    if (attrs.created_at && attrs.created_at > 1e12) {
      attrs.created_at = Math.floor(attrs.created_at / 1000);
    }
    await this.trackClient.identify(userId, attrs);
  }

  // Legacy-compatible track (normalizes data format)
  async track(
    userId: string,
    eventOrOpts: string | { name: string; data?: Record<string, any> },
    data?: Record<string, any>
  ): Promise<void> {
    if (ty

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.