@clivly/sdk 0.3.0-next.2 → 0.3.0-next.4

package/README.md

@@ -12,18 +12,18 @@ This README stays focused on the SDK surface itself.
 ## Install
 
 ```bash
-npm install @clivly/sdk @clivly/core clivly
+npm install clivly
 ```
 
-Add `drizzle-orm` when you use `@clivly/sdk/drizzle`, and `vite` when you use
-the Vite/TanStack Start plugin.
+Add `drizzle-orm` when you use `clivly/drizzle` or `clivly/core/drizzle`, and
+`vite` when you use the Vite/TanStack Start plugin.
 
 ## Usage
 
 ```ts
-import { createClivlySDK } from "@clivly/sdk";
-import { fromDrizzle } from "@clivly/sdk/drizzle";
-import { defineClivlyConfig } from "@clivly/core";
+import { createClivlySDK } from "clivly/sdk";
+import { fromDrizzle } from "clivly/drizzle";
+import { defineClivlyConfig } from "clivly/core";
 import { db, participants, accounts } from "./db";
 
 // Declarative entity config — the non-deprecated source of truth. It maps your
@@ -64,9 +64,11 @@ const remote = createClivlySDK({
   entities,
   source: { /* … */ },
   syncTrigger: {
-    url: "https://yourapp.com/api/clivly/tick",
-    secret: process.env.CLIVLY_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
+    path: "/api/clivly/tick",
+    url: process.env.CLIVLY_SYNC_TRIGGER_URL,
+    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
   },
+  verifyToken: process.env.CLIVLY_VERIFY_TOKEN,
 });
 
 export async function POST(request: Request) {
@@ -90,8 +92,8 @@ the app but cannot start a sync from the dashboard.
 If you rotate a remote-sync secret from Clivly's dashboard after the encryption
 rollout, Clivly stores it encrypted at rest. The server-side deployment must
 have `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` configured, while your app continues
-to use `CLIVLY_TRIGGER_SECRET` unchanged. Existing plaintext rows remain valid
-during rollout, and older rows can be backfilled with
+to use `CLIVLY_SYNC_TRIGGER_SECRET`. Existing plaintext rows remain valid during
+rollout, and older rows can be backfilled with
 `node ./scripts/backfill-sync-trigger-secrets.mjs --write`.
 
 ## Vite / TanStack Start
@@ -99,7 +101,7 @@ during rollout, and older rows can be backfilled with
 For long-lived Vite dev servers, wire the SDK lifecycle through the Vite plugin:
 
 ```ts
-import { clivlyVite } from "@clivly/sdk/vite";
+import { clivlyVite } from "clivly/vite";
 import clivly from "./clivly.config";
 import { defineConfig } from "vite";
 

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DIBgCQca.cjs";
+import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-9wTakLJu.cjs";
 import { Table } from "drizzle-orm";
 
 //#region src/drizzle.d.ts

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DFpvfl7T.mjs";
+import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-BD1-lqlp.mjs";
 import { Table } from "drizzle-orm";
 
 //#region src/drizzle.d.ts

package/dist/index.cjs

@@ -1,5 +1,42 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_drizzle_meta = require("./drizzle-meta-iAu8w1hj.cjs");
+//#region src/custom-slug.ts
+const NON_ALNUM = /[^a-z0-9]+/g;
+const EDGE_HYPHENS = /(^-|-$)/g;
+function slugify(value) {
+	return value.toLowerCase().trim().replace(NON_ALNUM, "-").replace(EDGE_HYPHENS, "");
+}
+function checkCustomObjectSlugs(config) {
+	const custom = config.source?.custom ?? [];
+	if (custom.length === 0) return {
+		name: "Custom object slugs",
+		ok: false,
+		skipped: true,
+		detail: "No custom objects configured."
+	};
+	const problems = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const source of custom) {
+		const declared = source.objectType;
+		const canonical = slugify(declared);
+		if (canonical === "") problems.push(`"${source.entity}" has an empty objectType.`);
+		else if (canonical !== declared) problems.push(`"${declared}" is not a slug — the dashboard would store it as "${canonical}".`);
+		const prior = seen.get(canonical);
+		if (prior && canonical !== "") problems.push(`duplicate slug "${canonical}" declared by "${prior}" and "${source.entity}".`);
+		else seen.set(canonical, source.entity);
+	}
+	if (problems.length > 0) return {
+		name: "Custom object slugs",
+		ok: false,
+		detail: problems.join(" ")
+	};
+	return {
+		name: "Custom object slugs",
+		ok: true,
+		detail: `Ensure these object types exist in Clivly: ${custom.map((source) => source.objectType).join(", ")}.`
+	};
+}
+//#endregion
 //#region src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -160,6 +197,7 @@ async function runDoctor(args) {
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
+	checks.push(checkCustomObjectSlugs(config));
 	checks.push(await namespaceCheck(config));
 	return {
 		ok: checks.every((check) => check.skipped || check.ok),
@@ -258,6 +296,85 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/trigger-url.ts
+const SCHEME_REGEX = /^https?:\/\//;
+const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
+const PLATFORM_ORIGIN_SOURCES = [
+	{
+		key: "VERCEL_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "CF_PAGES_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "RAILWAY_PUBLIC_DOMAIN",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "RENDER_EXTERNAL_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "FLY_APP_NAME",
+		toOrigin: (value) => `https://${value}.fly.dev`
+	}
+];
+function withScheme(value) {
+	return SCHEME_REGEX.test(value) ? value : `https://${value}`;
+}
+function stripTrailingSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+/**
+* Derive the app's public origin from known platform environment variables.
+* Returns an origin with no trailing slash, or undefined when nothing matches.
+*/
+function originFromPlatformEnv(env) {
+	for (const source of PLATFORM_ORIGIN_SOURCES) {
+		const raw = env[source.key]?.trim();
+		if (raw) return stripTrailingSlash(source.toOrigin(raw));
+	}
+}
+function observedTriggerUrl(req) {
+	const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host"))?.trim();
+	if (!host) return;
+	if (INVALID_HOST_CHARS_REGEX.test(host)) return;
+	const forwardedProto = req.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+	let requestUrl;
+	try {
+		requestUrl = new URL(req.url);
+	} catch {
+		return;
+	}
+	const proto = forwardedProto || requestUrl.protocol.replace(":", "");
+	try {
+		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
+	} catch {
+		return;
+	}
+}
+/**
+* Decide which trigger URL to report, in precedence order:
+*
+*   1. `configuredUrl` — an explicit `syncTrigger.url`. Someone typed this on
+*      purpose, so it beats anything inferred.
+*   2. platform env origin + `configuredPath` — available at boot, before any
+*      request has arrived. Needs the path because platform variables only give
+*      an origin.
+*   3. `observedUrl` — accurate but only after the route has served a request.
+*
+* A URL set in the Clivly dashboard overrides all of these server-side; the SDK
+* doesn't need to know about it.
+*/
+function resolveTriggerUrl(args) {
+	if (args.configuredUrl) return args.configuredUrl;
+	const origin = originFromPlatformEnv(args.env);
+	if (origin && args.configuredPath) return `${origin}${args.configuredPath.startsWith("/") ? args.configuredPath : `/${args.configuredPath}`}`;
+	return args.observedUrl;
+}
+//#endregion
 //#region src/errors.ts
 var ClivlyError = class ClivlyError extends Error {
 	/** HTTP status, or null when the request never completed (network error). */
@@ -548,6 +665,7 @@ function createClivlySDK(config) {
 	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let observedUrl;
 	let lastPushFailure = null;
 	const createPush = (runId) => async (path, body) => {
 		const response = await fetcher(`${apiUrl}${path}`, {
@@ -632,7 +750,15 @@ function createClivlySDK(config) {
 			contactEntity: resolveContactEntity(config),
 			namespaceReady: config.namespaceReady ?? false,
 			schema: buildSchema(config),
-			...config.syncTrigger?.url ? { syncTrigger: { url: config.syncTrigger.url } } : {}
+			...(() => {
+				const url = resolveTriggerUrl({
+					configuredUrl: config.syncTrigger?.url,
+					configuredPath: config.syncTrigger?.path,
+					env: config.env ?? process.env,
+					observedUrl
+				});
+				return url ? { syncTrigger: { url } } : {};
+			})()
 		})
 	});
 	const heartbeat = async () => {
@@ -686,6 +812,7 @@ function createClivlySDK(config) {
 		}
 	};
 	const createClivlyHandler = () => async (req) => {
+		observedUrl = observedTriggerUrl(req) ?? observedUrl;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-DIBgCQca.cjs";
+import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-9wTakLJu.cjs";
 
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-DFpvfl7T.mjs";
+import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-BD1-lqlp.mjs";
 
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {

package/dist/index.mjs

@@ -1,4 +1,41 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-DMx_9nlj.mjs";
+//#region src/custom-slug.ts
+const NON_ALNUM = /[^a-z0-9]+/g;
+const EDGE_HYPHENS = /(^-|-$)/g;
+function slugify(value) {
+	return value.toLowerCase().trim().replace(NON_ALNUM, "-").replace(EDGE_HYPHENS, "");
+}
+function checkCustomObjectSlugs(config) {
+	const custom = config.source?.custom ?? [];
+	if (custom.length === 0) return {
+		name: "Custom object slugs",
+		ok: false,
+		skipped: true,
+		detail: "No custom objects configured."
+	};
+	const problems = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const source of custom) {
+		const declared = source.objectType;
+		const canonical = slugify(declared);
+		if (canonical === "") problems.push(`"${source.entity}" has an empty objectType.`);
+		else if (canonical !== declared) problems.push(`"${declared}" is not a slug — the dashboard would store it as "${canonical}".`);
+		const prior = seen.get(canonical);
+		if (prior && canonical !== "") problems.push(`duplicate slug "${canonical}" declared by "${prior}" and "${source.entity}".`);
+		else seen.set(canonical, source.entity);
+	}
+	if (problems.length > 0) return {
+		name: "Custom object slugs",
+		ok: false,
+		detail: problems.join(" ")
+	};
+	return {
+		name: "Custom object slugs",
+		ok: true,
+		detail: `Ensure these object types exist in Clivly: ${custom.map((source) => source.objectType).join(", ")}.`
+	};
+}
+//#endregion
 //#region src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -159,6 +196,7 @@ async function runDoctor(args) {
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
+	checks.push(checkCustomObjectSlugs(config));
 	checks.push(await namespaceCheck(config));
 	return {
 		ok: checks.every((check) => check.skipped || check.ok),
@@ -257,6 +295,85 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/trigger-url.ts
+const SCHEME_REGEX = /^https?:\/\//;
+const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
+const PLATFORM_ORIGIN_SOURCES = [
+	{
+		key: "VERCEL_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "CF_PAGES_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "RAILWAY_PUBLIC_DOMAIN",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "RENDER_EXTERNAL_URL",
+		toOrigin: (value) => withScheme(value)
+	},
+	{
+		key: "FLY_APP_NAME",
+		toOrigin: (value) => `https://${value}.fly.dev`
+	}
+];
+function withScheme(value) {
+	return SCHEME_REGEX.test(value) ? value : `https://${value}`;
+}
+function stripTrailingSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+/**
+* Derive the app's public origin from known platform environment variables.
+* Returns an origin with no trailing slash, or undefined when nothing matches.
+*/
+function originFromPlatformEnv(env) {
+	for (const source of PLATFORM_ORIGIN_SOURCES) {
+		const raw = env[source.key]?.trim();
+		if (raw) return stripTrailingSlash(source.toOrigin(raw));
+	}
+}
+function observedTriggerUrl(req) {
+	const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host"))?.trim();
+	if (!host) return;
+	if (INVALID_HOST_CHARS_REGEX.test(host)) return;
+	const forwardedProto = req.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+	let requestUrl;
+	try {
+		requestUrl = new URL(req.url);
+	} catch {
+		return;
+	}
+	const proto = forwardedProto || requestUrl.protocol.replace(":", "");
+	try {
+		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
+	} catch {
+		return;
+	}
+}
+/**
+* Decide which trigger URL to report, in precedence order:
+*
+*   1. `configuredUrl` — an explicit `syncTrigger.url`. Someone typed this on
+*      purpose, so it beats anything inferred.
+*   2. platform env origin + `configuredPath` — available at boot, before any
+*      request has arrived. Needs the path because platform variables only give
+*      an origin.
+*   3. `observedUrl` — accurate but only after the route has served a request.
+*
+* A URL set in the Clivly dashboard overrides all of these server-side; the SDK
+* doesn't need to know about it.
+*/
+function resolveTriggerUrl(args) {
+	if (args.configuredUrl) return args.configuredUrl;
+	const origin = originFromPlatformEnv(args.env);
+	if (origin && args.configuredPath) return `${origin}${args.configuredPath.startsWith("/") ? args.configuredPath : `/${args.configuredPath}`}`;
+	return args.observedUrl;
+}
+//#endregion
 //#region src/errors.ts
 var ClivlyError = class ClivlyError extends Error {
 	/** HTTP status, or null when the request never completed (network error). */
@@ -547,6 +664,7 @@ function createClivlySDK(config) {
 	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let observedUrl;
 	let lastPushFailure = null;
 	const createPush = (runId) => async (path, body) => {
 		const response = await fetcher(`${apiUrl}${path}`, {
@@ -631,7 +749,15 @@ function createClivlySDK(config) {
 			contactEntity: resolveContactEntity(config),
 			namespaceReady: config.namespaceReady ?? false,
 			schema: buildSchema(config),
-			...config.syncTrigger?.url ? { syncTrigger: { url: config.syncTrigger.url } } : {}
+			...(() => {
+				const url = resolveTriggerUrl({
+					configuredUrl: config.syncTrigger?.url,
+					configuredPath: config.syncTrigger?.path,
+					env: config.env ?? process.env,
+					observedUrl
+				});
+				return url ? { syncTrigger: { url } } : {};
+			})()
 		})
 	});
 	const heartbeat = async () => {
@@ -685,6 +811,7 @@ function createClivlySDK(config) {
 		}
 	};
 	const createClivlyHandler = () => async (req) => {
+		observedUrl = observedTriggerUrl(req) ?? observedUrl;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,

package/dist/{namespace-probe-DFpvfl7T.d.mts → namespace-probe-9wTakLJu.d.cts}

@@ -64,6 +64,12 @@ interface ClivlySDKConfig {
    * `contactEntity`.
    */
   entities?: ClivlyEntitiesConfig;
+  /**
+   * Environment to read platform variables from when discovering the public
+   * trigger URL. Defaults to `process.env`. Injectable so tests and non-Node
+   * runtimes can supply their own.
+   */
+  env?: Record<string, string | undefined>;
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -140,8 +146,19 @@ interface ClivlySDKConfig {
      * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
      * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
      * heartbeat; a URL set in the dashboard overrides it.
+     *
+     * Optional — leave it unset and the SDK discovers the URL itself, from the
+     * hosting platform's environment or from the first request the route
+     * serves. Set it only to pin an address the SDK can't infer.
      */
     url?: string;
+    /**
+     * Path where `createClivlyHandler()` is mounted, e.g. `/api/clivly/tick`.
+     * Written by `clivly init`. Combined with the origin detected from the
+     * hosting platform so the SDK can report a trigger URL on its very first
+     * heartbeat, before any request has arrived to observe.
+     */
+    path?: string;
     /**
      * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
      * sync. When set, `createClivlyHandler()` rejects any request that isn't

package/dist/{namespace-probe-DIBgCQca.d.cts → namespace-probe-BD1-lqlp.d.mts}

@@ -64,6 +64,12 @@ interface ClivlySDKConfig {
    * `contactEntity`.
    */
   entities?: ClivlyEntitiesConfig;
+  /**
+   * Environment to read platform variables from when discovering the public
+   * trigger URL. Defaults to `process.env`. Injectable so tests and non-Node
+   * runtimes can supply their own.
+   */
+  env?: Record<string, string | undefined>;
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -140,8 +146,19 @@ interface ClivlySDKConfig {
      * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
      * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
      * heartbeat; a URL set in the dashboard overrides it.
+     *
+     * Optional — leave it unset and the SDK discovers the URL itself, from the
+     * hosting platform's environment or from the first request the route
+     * serves. Set it only to pin an address the SDK can't infer.
      */
     url?: string;
+    /**
+     * Path where `createClivlyHandler()` is mounted, e.g. `/api/clivly/tick`.
+     * Written by `clivly init`. Combined with the origin detected from the
+     * hosting platform so the SDK can report a trigger URL on its very first
+     * heartbeat, before any request has arrived to observe.
+     */
+    path?: string;
     /**
      * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
      * sync. When set, `createClivlyHandler()` rejects any request that isn't

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { i as ClivlySDK } from "./namespace-probe-DIBgCQca.cjs";
+import { i as ClivlySDK } from "./namespace-probe-9wTakLJu.cjs";
 import { Plugin } from "vite";
 
 //#region src/vite.d.ts

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { i as ClivlySDK } from "./namespace-probe-DFpvfl7T.mjs";
+import { i as ClivlySDK } from "./namespace-probe-BD1-lqlp.mjs";
 import { Plugin } from "vite";
 
 //#region src/vite.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.3.0-next.2",
+  "version": "0.3.0-next.4",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.3.0-next.2"
+    "@clivly/core": "0.3.0-next.4"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30",