@clivly/sdk 0.9.5 → 0.9.7

package/dist/{types-Dz1LQYvQ.d.mts → types-B7HKG2Ph.d.mts}

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState, ProjectionMapping } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -18,6 +18,43 @@ interface DrizzleSourceMeta {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Build a runnable sync source from a projection, for derived objects
+   * authored in the dashboard rather than in `clivly.config.ts`.
+   *
+   * Optional for the same reason `runProjection` is: an introspector may be
+   * hand-written. Absent, remote projections report `skipped` with a reason
+   * naming this method, rather than failing the run.
+   *
+   * This is deliberately the only route to a database handle for remote
+   * projections. `drizzleIntrospector(db)` already closes over the
+   * connection, so `introspector:` is the single config line that turns
+   * dashboard-authored objects on — and the SDK core never holds a raw
+   * client.
+   */
+  projectionSource?(projection: ProjectionMapping, opts: {
+    basePkColumn?: string;
+    objectType: string;
+  }): SyncSource & {
+    objectType: string;
+  };
+  /**
+   * Read a few rows through an unsaved projection, for the dashboard's derived
+   * object preview. Rows are keyed by field name.
+   *
+   * Optional because it is the only capability here that needs more than a
+   * table name, and because an introspector may be hand-written. Absent, the
+   * dashboard says preview is unavailable rather than failing — see
+   * `previewProjection`.
+   *
+   * This is what makes preview cost the host an SDK upgrade and nothing else:
+   * `drizzleIntrospector(db)` already closes over the connection, so a config
+   * that set `introspector` for the "Namespace reachable" check gains preview
+   * without touching a line.
+   */
+  runProjection?(projection: ProjectionMapping, opts: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
   /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
   sampleSelect(table: string): Promise<void>;
 }
@@ -347,6 +384,31 @@ interface CursorStore {
   get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
   set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
 }
+/** @see ClivlySDK.describeSyncTrigger */
+interface SyncTriggerDescription {
+  /**
+   * `syncTrigger.url` exactly as configured, placeholder and all. The raw
+   * value, so a caller can say what is in the file rather than what survived
+   * resolution.
+   */
+  configured?: string;
+  /**
+   * The URL that would be reported to Clivly on the next heartbeat, or
+   * `undefined` when nothing resolves. An unedited placeholder never resolves.
+   */
+  resolved?: string;
+}
+/** @see ClivlySDK.describeRemoteProjections */
+interface RemoteProjectionsDescription {
+  /** False when no `introspector` is configured — nothing can run. */
+  capable: boolean;
+  failed: number;
+  invalid: number;
+  ok: number;
+  /** False until a sync has run in this process. */
+  ran: boolean;
+  skipped: number;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -382,6 +444,27 @@ interface ClivlySDK {
    * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
+  /**
+   * What this app would tell Clivly about dashboard-authored derived objects,
+   * right now. Counts rather than the outcomes themselves: this reports
+   * health, and the per-object reasons already travel to the dashboard, which
+   * is where an author fixes them.
+   *
+   * Read by `clivly status`.
+   */
+  describeRemoteProjections(): RemoteProjectionsDescription;
+  /**
+   * What this app would tell Clivly about its sync trigger route, right now.
+   *
+   * Computed per call rather than frozen at creation: `resolved` can start as
+   * `undefined` and become a real URL once the mounted route has served its
+   * first request and observed its own origin.
+   *
+   * Exists for `clivly status`, which has to tell "no trigger configured"
+   * apart from "configured, but still the scaffolded placeholder" — a
+   * distinction `resolved` alone erases, since it skips placeholders by design.
+   */
+  describeSyncTrigger(): SyncTriggerDescription;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
   /**
@@ -454,4 +537,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-export { NamespaceIntrospector as _, ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, SyncSource as g, EnsuredObjectTypeResult as h, ClivlyConnectResult as i, CursorStore as l, EnsuredMappingResult as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, EnsureSchemaResult as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u };
+export { SyncSource as _, ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, RemoteProjectionsDescription as g, EnsuredObjectTypeResult as h, ClivlyConnectResult as i, CursorStore as l, EnsuredMappingResult as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, EnsureSchemaResult as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u, SyncTriggerDescription as v, NamespaceIntrospector as y };

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-Dz1LQYvQ.cjs";
+import { a as ClivlySDK } from "./types-B7HKG2Ph.cjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-Dz1LQYvQ.mjs";
+import { a as ClivlySDK } from "./types-B7HKG2Ph.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.9.5"
+    "@clivly/core": "0.9.7"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",