@clivly/sdk 0.1.0 → 0.3.0-next.1

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+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";
+
+//#region src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
+  /**
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
+   */
+  static from(result: ClivlyConnectResult): ClivlyError | null;
+}
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };

package/dist/index.d.mts

@@ -1,130 +1,25 @@
-import { ClivlyEntitiesConfig } from "@clivly/core";
+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";
 
-//#region src/types.d.ts
-interface DiscoveredTable {
-  columns: string[];
-  name: string;
-}
-interface ClivlySDKConfig {
-  /** Org-scoped API token (sk_live_…) from Settings → API keys. */
-  apiKey: string;
-  /** Clivly API base URL. Defaults to https://api.clivly.com. */
-  apiUrl?: string;
-  /**
-   * The host table Clivly treats as the contact entity.
-   * @deprecated Prefer `entities` — the same mapping-derived shape
-   * `crm_entity_mappings` (and `@clivly/core`'s `mappingsToEntitiesConfig`)
-   * produce, so the SDK, the mappings table, and the sync engine share one
-   * model. A bare `contactEntity` is treated as a single contact entity.
-   */
-  contactEntity?: string;
-  /** Which columns of the contact entity Clivly may read. */
-  contactFields?: string[];
-  /**
-   * Declarative entity config — the single source of truth shared with
-   * `crm_entity_mappings`. When set, discovery and heartbeat are derived from
-   * it (each entity's `source` table + mapped columns), superseding the flat
-   * `contactEntity`.
-   */
-  entities?: ClivlyEntitiesConfig;
-  /** Reported to the portal so it can show the detected stack. */
-  framework?: string;
-  /** Heartbeat cadence in ms. Defaults to 60s. */
-  heartbeatIntervalMs?: number;
-  /** Whether the crm_* namespace exists in the host DB (self-reported). */
-  namespaceReady?: boolean;
-  orm?: string;
-  /**
-   * Network retry policy for outbound calls (heartbeat + sync push). Transient
-   * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
-   * backoff + jitter; a `Retry-After` header on a 429 is honoured. Non-transient
-   * responses (e.g. 4xx other than 429) are returned immediately, not retried.
-   */
-  retry?: {
-    /** Total attempts including the first. Defaults to 3. Min 1. */maxAttempts?: number; /** Base backoff in ms (doubled each attempt). Defaults to 500. */
-    baseDelayMs?: number;
-  };
-  /** Tables/columns to report for entity discovery + mapping. */
-  schema?: DiscoveredTable[];
-  sdkVersion?: string;
-  /** Host entities to mirror into Clivly Cloud. */
-  source?: {
-    contacts: SyncSource;
-    companies?: SyncSource;
-  };
-  sync?: {
-    onBoot?: boolean;
-    /**
-     * Sync cadence in ms for the background keep-alive loop. Defaults to
-     * `heartbeatIntervalMs` (60s) so sync and heartbeat share a tick unless you
-     * decouple them — e.g. a slow full-mirror alongside frequent heartbeats.
-     */
-    intervalMs?: number;
-    batchSize?: number;
-  };
-  /** Cloudflare Tunnel token — reserved for write-back/tunnel mode. */
-  tunnelToken?: string;
-  /**
-   * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
-   * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
-   * authenticate the caller; without it the handler fails closed (HTTP 500).
-   */
-  verifyToken?: string;
-  writeBack?: {
-    enabled?: boolean; /** Only crm_* tables are ever accepted; this narrows further. */
-    tables?: string[];
-  };
-}
-interface ClivlyUser {
-  email: string;
-  id: string;
-  name?: string;
-}
-interface SyncCursor {
-  /** The row's id, breaking ties when timestamps collide. */
-  id: string;
-  /** The row's cursor-field value (typically `updated_at`). */
-  time: Date;
-}
-interface SyncSource {
-  cursorField: string;
-  entity: string;
-  fetchPage(args: {
-    since: SyncCursor | null;
-    limit: number;
-  }): Promise<Record<string, unknown>[]>;
-  /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
-  idField?: string;
-}
-type SyncMode = "delta" | "full";
-interface ClivlySDK {
-  /**
-   * Build the `/clivly/auth/verify` handler the developer mounts in their app.
-   * Clivly's cloud calls it to validate a CRM user's identity against the host
-   * app's session. Pass a resolver that reads the host session from the request.
-   *
-   * The handler authenticates the caller against `config.verifyToken` (presented
-   * as `Authorization: Bearer <token>`) before invoking the resolver, so the
-   * endpoint can't be used by third parties to probe host sessions. It fails
-   * closed with HTTP 500 if `verifyToken` is unset.
-   */
-  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
-  /** Send a single heartbeat now. Returns true on success. */
-  heartbeat(): Promise<boolean>;
-  /** Connect: send the initial heartbeat and start the keep-alive loop. */
-  start(): Promise<void>;
-  /** Stop the keep-alive loop. */
-  stop(): void;
+//#region src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
   /**
-   * Sync all configured sources now. `delta` (default) pages changed rows since
-   * the last cursor; `full` pushes each complete entity so the server can
-   * reconcile leavers (archive-on-leave). Throws if a push fails, so callers see
-   * the failure — the background keep-alive loop swallows and retries instead.
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
    */
-  sync(options?: {
-    mode?: SyncMode;
-  }): Promise<void>;
+  static from(result: ClivlyConnectResult): ClivlyError | null;
 }
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region src/index.d.ts
 /**
@@ -135,4 +30,4 @@ interface ClivlySDK {
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type DiscoveredTable, createClivlySDK };
+export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };