Customerio Hello WorldSAFE

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-hello-world
description: 'Create a minimal working Customer.io example.

  Use when learning Customer.io basics, testing SDK setup,

  or creating your first identify + track integration.

  Trigger: "customer.io hello world", "first customer.io message",

  "test customer.io", "customer.io example", "customer.io quickstart".

  '
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
- quickstart
- testing
compatibility: Designed for Claude Code
---
# Customer.io Hello World

## Output

- A verified synthetic profile/event or message example in a non-production workspace.
- A minimal receipt showing environment, validation result, and cleanup without retaining recipient data.

## Examples

Create a development-only profile using a synthetic identifier, submit one schema-valid event, and confirm its arrival in the development workspace. Remove the test profile or let its documented TTL expire. Never use a real customer email or production segment as a tutorial target.

## Overview

Create a minimal working Customer.io integration: identify a user (create/update their profile), track an event, and send a transactional email. This covers the three fundamental Customer.io operations.

## Prerequisites

- `customerio-node` installed (`npm install customerio-node`)
- `CUSTOMERIO_SITE_ID` and `CUSTOMERIO_TRACK_API_KEY` configured
- `CUSTOMERIO_APP_API_KEY` configured (for transactional email example)

## Instructions

### Step 1: Identify a User (Create/Update Profile)

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

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

// identify() creates the user if they don't exist, or updates if they do.
// The first argument is your internal user ID (immutable — use DB primary key).
await cio.identify("user-123", {
  email: "[email protected]",          // Required for email campaigns
  first_name: "Jane",
  last_name: "Doe",
  plan: "pro",
  created_at: Math.floor(Date.now() / 1000),  // Unix seconds, NOT milliseconds
});

console.log("User identified in Customer.io");
```

**Key rules:**

- `id` (first arg) should be your immutable database ID — never use email as ID
- `email` attribute is required if you want to send email campaigns
- `created_at` must be Unix timestamp in **seconds** (not ms) — `Math.floor(Date.now() / 1000)`
- All custom attributes are stored on the user profile and usable in segments + Liquid templates

### Step 2: Track an Event

```typescript
// Track a custom event on the user's activity timeline.
// Events trigger campaigns — the event name must match exactly in the dashboard.
await cio.track("user-123", {
  name: "signed_up",                   // snake_case, matches campaign trigger
  data: {
    signup_method: "google_oauth",
    referral_source: "product_hunt",
    timestamp: Math.floor(Date.now() / 1000),
  },
});

console.log("Event tracked in Customer.io");
```

**Key rules:**

- User must be identified before tracking events (call `identify()` first)
- Event `name` is case-sensitive and must match your campaign trigger exactly
- Use `snake_case` for event names — `signed_up`, not `Signed Up` or `signedUp`
- `data` properties are accessible in Liquid templates as `{{ event.property_name }}`

### Step 3: Track an Anonymous Event

```typescript
// Track events before the user signs up — merge later on identification
await cio.trackAnonymous({
  anonymous_id: "anon-abc-123",         // Your anonymous tracking ID (cookie, device ID)
  name: "page_viewed",
  data: {
    url: "/pricing",
    referrer: "https://google.com",
  },
});

console.log("Anonymous event tracked");
```

When the anonymous user signs up, include `anonymous_id` in the `identify()` call to merge their pre-signup activity:

```typescript
await cio.identify("user-123", {
  email: "[email protected]",
  anonymous_id: "anon-abc-123",         // Merges anonymous activity
});
```

### Step 4: Send a Transactional Email

```typescript
import { APIClient, SendEmailRequest, RegionUS } from "customerio-node";

const api = new APIClient(process.env.CUSTOMERIO_APP_API_KEY!, {
  region: RegionUS,
});

const request = new SendEmailRequest({
  to: "[email protected]",
  transactional_message_id: "1",        // ID from Customer.io dashboard
  message_data: {                       // Populates {{ liquid }} variables
    welcome_name: "Jane",
    login_url: "https://app.example.com/login",
  },
  identifiers: { id: "user-123" },      // Links delivery to user profile
});

const response = await api.sendEmail(request);
console.log("Email queued:", response.delivery_id);
```

### Step 5: Verify in Dashboard

1. Go to https://fly.customer.io
2. Navigate to **People** and search for "[email protected]"
3. Verify the profile shows `first_name`, `plan`, and other attributes
4. Click the **Activity** tab to see the `signed_up` event
5. Check **Deliveries** for the transactional email

## Complete Example

```typescript
// scripts/hello-customerio.ts
import {
  TrackClient, APIClient, SendEmailRequest, RegionUS
} from "customerio-node";

async function main() {
  // Track API client — identify and track
  const cio = new TrackClient(
    process.env.CUSTOMERIO_SITE_ID!,
    process.env.CUSTOMERIO_TRACK_API_KEY!,
    { region: RegionUS }
  );

  // 1. Identify
  await cio.identify("user-hello-world", {
    email: "[email protected]",
    first_name: "Jane",
    created_at: Math.floor(Date.now() / 1000),
  });
  console.log("1. User identified");

  // 2. Track event
  await cio.track("user-hello-world", {
    name: "hello_world_completed",
    data: { sdk: "customerio-node", step: "quickstart" },
  });
  console.log("2. Event tracked");

  // 3. Clean up test user (optional)
  await cio.suppress("user-hello-world");

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.