tinycrm-sdk

Sync your customers to TinyCRM — see every customer across all your projects in one filterable table, merged by email.

• Zero dependencies
• < 2 kB gzipped
• Works anywhere — Node.js, Edge, serverless, or the browser (uses native fetch)

Install

npm install tinycrm-sdk

Quick Start

import { TinyCRM } from "tinycrm-sdk";

const crm = new TinyCRM("tcrm_proj_your_api_key");

// Identify a customer
await crm.identify({
  email: "[email protected]",
  name: "Alice Smith",
  status: "paid",
  params: { plan: "pro", source: "product-hunt" },
});

// Track an event
await crm.track("[email protected]", "subscription_created", {
  plan: "pro",
  interval: "monthly",
});

// Update last activity
await crm.ping("[email protected]");

API

new TinyCRM(apiKey)

Create a new client. Pass your project API key as a string or a config object.

// String shorthand
const crm = new TinyCRM("tcrm_proj_...");

// Config object
const crm = new TinyCRM({ apiKey: "tcrm_proj_..." });

crm.identify(payload)

Identifies a customer and syncs them to TinyCRM. If a customer with the same email already exists, their record is updated.

| Field | Type | Required | Description | | -------- | ------------------------------------------ | -------- | ------------------------------------ | | email | string | Yes | Customer email (merge key) | | name | string | No | Customer name | | status | "free" \| "paid" | No | Customer status for this project | | params | Record<string, string \| number \| boolean> | No | Custom key-value data |

await crm.identify({
  email: "[email protected]",
  name: "Alice Smith",
  status: "paid",
  params: { plan: "pro", role: "admin" },
});

crm.track(email, event, properties?)

Tracks a custom event for a customer. The customer must already exist (call identify() first). Events appear in the customer's activity timeline in TinyCRM.

| Field | Type | Required | Description | | ------------ | ------------------------------------------ | -------- | ------------------------------------ | | email | string | Yes | Customer email | | event | string | Yes | Event name (max 128 chars) | | properties | Record<string, string \| number \| boolean> | No | Event properties (max 20 keys) |

await crm.track("[email protected]", "subscription_created", {
  plan: "pro",
  interval: "monthly",
});

await crm.track("[email protected]", "feature_used", {
  feature: "csv-import",
  count: 3,
});

crm.ping(email)

Updates the last_activity timestamp for a customer. Call this on meaningful user actions to keep activity data fresh.

await crm.ping("[email protected]");

Types

The SDK exports TypeScript types for all payloads:

import type { IdentifyPayload, TrackEventPayload, TinyCRMConfig } from "tinycrm-sdk";

Error Handling

Errors are logged to console.error with a [tinycrm] prefix and never thrown, so the SDK won't break your app.

License

MIT