@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.

React Feedback Widget

The @tinycrm/sdk/react subpath ships a drop-in <FeedbackWidget> — a floating button that opens a modal where your users can send feedback (with an optional screenshot of the current page). Submissions land in your TinyCRM feedback inbox.

Add it once to your root layout:

"use client";
import { FeedbackWidget } from "@tinycrm/sdk/react";

export function Feedback() {
  return (
    <FeedbackWidget
      apiKey="tcrm_proj_..."
      projectId="your-project-id"
      email="[email protected]" // optional: who is sending
    />
  );
}

Props

| Prop | Type | Default | Description | | ------------- | ------------------------------------------ | ---------------- | ------------------------------------------------------ | | apiKey | string | — | Project API key (tcrm_proj_...), sent as Bearer. | | projectId | string | — | Project the feedback belongs to. | | email | string | — | Identifies the end-user submitting feedback. | | name | string | — | Display name for the end-user. | | metadata | Record<string, string \| number \| boolean> | — | Arbitrary metadata (max 20 keys). | | position | "bottom-right" \| "bottom-left" | "bottom-right" | Corner the floating button is pinned to. | | theme | "light" \| "dark" \| "auto" | "auto" | auto follows the user's OS color scheme. | | accentColor | string | — | Shorthand to set the brand accent color. | | colors | FeedbackWidgetColors | — | Fine-grained color overrides (see below). | | categories | FeedbackCategoryOption[] | Bug/Idea/Other | Override the category options. | | baseUrl | string | hosted API | Point at a custom API base URL. | | debug | boolean | false | Log network/runtime errors to the console. |

Theming

Light and dark themes are built in. Set theme explicitly, or leave it on "auto" to follow the OS. To match your brand, pass accentColor or the full colors object — each value is applied as a CSS variable, so any CSS color works:

<FeedbackWidget
  apiKey="tcrm_proj_..."
  projectId="your-project-id"
  theme="dark"
  accentColor="#6366f1"
  colors={{ background: "#0b0b12", border: "#27272a" }}
/>

The widget depends on react/react-dom (≥18, as peer deps). Screenshots are captured with html2canvas-pro, which supports modern CSS color functions (oklch, lab, color-mix) so capture works in Tailwind v4 apps. The server entry (@tinycrm/sdk) stays dependency-free.

License

MIT