Reference

Config schema

The shape of clivly.config.ts — the quickstart shape, a derived-object projection, and the sync trigger block.

Quickstart shape

The full clivly.config.ts produced by the five-minute path, wiring entities, a Drizzle source, and the sync trigger.

clivly.config.ts

import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
import { discoverFromDrizzle, fromDrizzle } from "clivly/drizzle";
import { db, participants, accounts } from "./db";
import * as schema from "./db/schema";

const entities = defineClivlyConfig({
entities: {
  participants: {
    concept: "contact",
    source: "participants",
    fields: { name: "full_name", email: "email" },
  },
  accounts: {
    concept: "company",
    source: "accounts",
    fields: { name: "legal_name", domain: "website" },
  },
},
});

export default createClivlySDK({
apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY!,
entities,
schema: discoverFromDrizzle(schema),
source: {
  contacts: fromDrizzle(db, participants, {
    entity: "participants",
    cursorField: "updatedAt",
  }),
  companies: fromDrizzle(db, accounts, {
    entity: "accounts",
    cursorField: "updatedAt",
  }),
},
syncTrigger: {
  path: "/api/clivly/tick",
  url: process.env.CLIVLY_SYNC_TRIGGER_URL,
  secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
},
// Long-lived Node hosts only. The HTTP heartbeat resumes automatically
// while a socket is connecting or reconnecting.
presence: { transport: "websocket" },
});

Derived-object projection

An advanced custom entity is a custom entity with a projection. source is the base table; fields is derived from the bindings.

clivly.config.ts

// An advanced custom entity is a `custom` entity with a `projection`.
// `source` is the base table; `fields` is derived from the bindings.
client_accounts: {
concept: "custom",
source: "accounts",              // === projection.baseTable
objectType: { name: "Client account" },
projection: {
  version: 1,
  kind: "projection",
  entityKey: "client_accounts",
  baseTable: "accounts",
  joins: [
    {
      key: "cl",
      table: "clients",
      type: "inner",
      on: [
        {
          left: { table: "cl", column: "id" },
          op: "eq",
          right: { table: "base", column: "client_id" },
        },
      ],
    },
  ],
  fieldBindings: {
    client_name: { from: { table: "cl", column: "full_name" } },
    currency: { from: { table: "base", column: "currency" } },
  },
  identity: { kind: "base_pk" },
},
}

See Advanced custom entities for identity kinds, fan-out rules, and CI validation.

Sync trigger block

Lets remote sync call back into your app. path lets the SDK build its own public URL from the hosting platform's environment, so on those platforms you never set the URL by hand.

clivly.config.ts

syncTrigger: {
// `path` lets the SDK build its own public URL from the hosting platform's
// environment, so on those platforms you never set the URL by hand.
path: "/api/clivly/tick",
url: process.env.CLIVLY_SYNC_TRIGGER_URL,
secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
},

See Environment variables for what each variable does, and How Clivly reaches your app for how the URL resolves in development versus production.