contackd-sync (TS/JS)

TypeScript/JavaScript SDK for pushing and syncing customer data (contacts, leads, prospects).

Install

npm install contackd-sync

2-Minute Start (Push Customer Details)

import { ContackdClient } from "contackd-sync";

const client = new ContackdClient({
  apiKey: "sk_live_...",
  baseUrl: "https://api.yourapp.com/api/v1", // no trailing slash required
});

// Create/update a customer contact by email
const customer = await client.contacts.upsert({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Doe",
  phone: "+14155550199",
  tags: ["customer", "vip"],
  custom: {
    customerId: "CUST-1001",
    plan: "pro",
    country: "US",
  },
});

console.log(customer);

Common Customer Push Patterns

1) Push one new customer

await client.contacts.create({
  email: "[email protected]",
  firstName: "New",
  lastName: "Customer",
});

2) Push many customers (bulk upsert)

const result = await client.contacts.bulkUpsert([
  { email: "[email protected]", firstName: "A" },
  { email: "[email protected]", firstName: "B", tags: ["trial"] },
]);

console.log(result.created.length, result.updated.length, result.errors);

3) Read/filter customers

const page1 = await client.contacts.list(1, 50, { email: "[email protected]" });

API Key Setup

1. Choose API base URL:

# uvicorn mode
export API_BASE_URL=http://localhost:8000/api/v1

# docker compose mode
# export API_BASE_URL=http://localhost:9127/api/v1

2. Create key (JWT required):

curl -X POST "$API_BASE_URL/auth/api-keys" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ts-sdk"}'

3. Use returned api_key as apiKey in ContackdClient.

4. Revoke key:

curl -X DELETE "$API_BASE_URL/auth/api-keys/<API_KEY_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Backend Routes Expected by SDK

Given baseUrl = https://api.yourapp.com/api/v1:

• GET /health
• POST /contacts|leads|prospects
• GET /contacts|leads|prospects/{id}
• PUT /contacts|leads|prospects/{id}
• DELETE /contacts|leads|prospects/{id}
• GET /contacts|leads|prospects
• POST /contacts|leads|prospects/upsert
• POST /contacts|leads|prospects/bulk
• POST /contacts|leads|prospects/bulk/upsert
• POST /contacts|leads|prospects/bulk/delete