khotan-data 0.1.0 → 0.2.0

package/dist/templates/api-state.tsx

@@ -0,0 +1,249 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+// ============================================================================
+// Khotan API helpers — typed fetch + graceful error/empty UI states
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file is yours. Every khotan dashboard component imports `khotanFetch`
+// and `<ApiErrorState>` from here so that 401 (auth), 403, 404, 5xx, and
+// network failures render a simple, consistent UI instead of a blank screen
+// or a thrown error. Restyle it however you like.
+// ============================================================================
+
+/**
+ * Error thrown by {@link khotanFetch} when a request fails. Carries the HTTP
+ * status so the UI can branch on it. `status === 0` means a network-level
+ * failure (server unreachable) rather than an HTTP error response.
+ */
+export class KhotanApiError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  readonly body: unknown;
+
+  constructor(status: number, statusText: string, body?: unknown) {
+    super(
+      status === 0
+        ? "Could not reach the server"
+        : `Request failed: ${String(status)} ${statusText}`,
+    );
+    this.name = "KhotanApiError";
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+  }
+}
+
+export function isKhotanApiError(error: unknown): error is KhotanApiError {
+  return error instanceof KhotanApiError;
+}
+
+/**
+ * `fetch` wrapper that throws a typed {@link KhotanApiError} on any non-2xx
+ * response (or network failure) and returns parsed JSON otherwise. Use it for
+ * every call to the khotan API so error handling stays consistent.
+ */
+export async function khotanFetch<T = unknown>(
+  input: string,
+  init?: RequestInit,
+): Promise<T> {
+  let res: Response;
+  try {
+    res = await fetch(input, init);
+  } catch (err) {
+    throw new KhotanApiError(
+      0,
+      "Network Error",
+      err instanceof Error ? err.message : undefined,
+    );
+  }
+
+  if (!res.ok) {
+    let body: unknown;
+    try {
+      body = await res.clone().json();
+    } catch {
+      try {
+        body = await res.text();
+      } catch {
+        body = undefined;
+      }
+    }
+    throw new KhotanApiError(res.status, res.statusText, body);
+  }
+
+  if (res.status === 204) return undefined as T;
+
+  try {
+    return (await res.json()) as T;
+  } catch {
+    return undefined as T;
+  }
+}
+
+interface ErrorCopy {
+  /** HTTP status code, or null for non-HTTP failures. */
+  code: number | null;
+  title: string;
+  message: string;
+  /** Auth errors (401/403) show a lock icon instead of the alert icon. */
+  isAuth: boolean;
+}
+
+function describeError(error: unknown): ErrorCopy {
+  const status = isKhotanApiError(error) ? error.status : null;
+
+  if (status === 401 || status === 403) {
+    return {
+      code: status,
+      title: "Access denied",
+      message: "You don't have permission to view this.",
+      isAuth: true,
+    };
+  }
+  if (status === 404) {
+    return {
+      code: 404,
+      title: "Not found",
+      message: "This resource doesn't exist.",
+      isAuth: false,
+    };
+  }
+  if (status === 429) {
+    return {
+      code: 429,
+      title: "Too many requests",
+      message: "Slow down and try again in a moment.",
+      isAuth: false,
+    };
+  }
+  if (status !== null && status >= 500) {
+    return {
+      code: status,
+      title: "Server error",
+      message: "Something went wrong on the server.",
+      isAuth: false,
+    };
+  }
+  if (status !== null && status >= 400) {
+    return {
+      code: status,
+      title: "Request error",
+      message: "The request couldn't be completed.",
+      isAuth: false,
+    };
+  }
+  return {
+    code: null,
+    title: "Connection error",
+    message: "Couldn't reach the server.",
+    isAuth: false,
+  };
+}
+
+function LockIcon({ className = "" }: { className?: string }): ReactNode {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={className}
+    >
+      <rect x="3.5" y="10.5" width="17" height="10" rx="2" />
+      <path d="M7.5 10.5V7a4.5 4.5 0 0 1 9 0v3.5" />
+      <circle cx="12" cy="15.5" r="1.25" />
+    </svg>
+  );
+}
+
+function AlertIcon({ className = "" }: { className?: string }): ReactNode {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={className}
+    >
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 8v5" />
+      <path d="M12 16.5h.01" />
+    </svg>
+  );
+}
+
+export interface ApiErrorStateProps {
+  error: unknown;
+  /** Called when the user clicks Retry. Omit to hide the Retry button. */
+  onRetry?: () => void;
+  /** Render a smaller inline banner (for nested panels) instead of a full card. */
+  compact?: boolean;
+  className?: string;
+}
+
+/**
+ * Simple UI for a failed khotan API request — shows an icon, the HTTP status,
+ * and a short message, plus an optional Retry button. Intentionally minimal.
+ */
+export function ApiErrorState({
+  error,
+  onRetry,
+  compact = false,
+  className = "",
+}: ApiErrorStateProps): ReactNode {
+  const { code, title, message, isAuth } = describeError(error);
+  const Icon = isAuth ? LockIcon : AlertIcon;
+
+  if (compact) {
+    return (
+      <div
+        role="alert"
+        className={`flex flex-wrap items-center justify-between gap-2 rounded-md border border-border bg-muted/30 px-3 py-2 ${className}`}
+      >
+        <span className="flex items-center gap-2 text-xs font-medium text-foreground">
+          <Icon className="h-4 w-4 text-muted-foreground" />
+          {code ? `${String(code)} — ${title}` : title}
+        </span>
+        {onRetry && (
+          <button
+            type="button"
+            onClick={onRetry}
+            className="text-xs text-muted-foreground underline-offset-2 hover:underline"
+          >
+            Retry
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      role="alert"
+      className={`flex flex-col items-center justify-center rounded-lg border border-border bg-card px-6 py-12 text-center ${className}`}
+    >
+      <Icon className="h-8 w-8 text-muted-foreground" />
+      <p className="mt-3 text-sm font-medium text-foreground">
+        {code ? `${String(code)} — ${title}` : title}
+      </p>
+      <p className="mt-1 text-sm text-muted-foreground">{message}</p>
+      {onRetry && (
+        <button
+          type="button"
+          onClick={onRetry}
+          className="mt-4 text-xs text-muted-foreground underline-offset-2 hover:underline"
+        >
+          Retry
+        </button>
+      )}
+    </div>
+  );
+}

package/dist/templates/cache.example.ts

@@ -0,0 +1,11 @@
+import { cache } from "./cache";
+
+export const cin7ProductsSnapshotCache = cache({
+  name: "cin7-products-snapshot",
+  scope: {
+    plug: "cin7",
+    resource: "products",
+    flow: "cin7-to-pollinate-products-relay",
+  },
+  ttl: "6h",
+});

package/dist/templates/cache.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// Cache — durable sync-state storage for flows, relays, and webhooks
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file defines the cache() builder and types. Create named cache
+// definitions for expensive upstream snapshots, checkpoints, and dedupe markers,
+// then register them in your khotan.ts factory config.
+// ============================================================================
+
+import type { CacheRegistration, CacheScope } from "khotan-data/factory";
+
+export interface CacheConfig {
+  /** Unique cache name used by runtime helpers and DB registration */
+  name: string;
+  /** Optional ownership metadata for humans and runtime validation */
+  scope?: CacheScope;
+  /** Optional default TTL like "30m", "6h", or 86400 */
+  ttl?: string | number;
+}
+
+export function cache(config: CacheConfig): CacheRegistration {
+  return {
+    name: config.name,
+    scope: config.scope,
+    ttl: config.ttl,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like caches/cin7-products-snapshot.ts)
+// ---------------------------------------------------------------------------
+//
+// import { cache } from "./cache";
+//
+// export const cin7ProductsSnapshotCache = cache({
+//   name: "cin7-products-snapshot",
+//   scope: {
+//     plug: "cin7",
+//     resource: "products",
+//     flow: "cin7-to-pollinate-products-relay",
+//   },
+//   ttl: "6h",
+// });
+//
+// Then register in your khotan config:
+//
+// import { cin7ProductsSnapshotCache } from "./caches/cin7-products-snapshot";
+//
+// const khotanData = khotan({
+//   adapter: drizzleAdapter(db),
+//   caches: [cin7ProductsSnapshotCache],
+//   plugs: [...],
+// });
+//
+// Flow, relay, catch, and pass workflows can then use:
+//   await khotanCache(ctx, "cin7-products-snapshot").get("all-products");
+//   await khotanCache(ctx, "cin7-products-snapshot").set("all-products", payload);
+//   await khotanCache(ctx, "cin7-products-snapshot").delete("all-products");

package/dist/templates/catch.ts

@@ -24,6 +24,8 @@ export interface CatchContext {
   headers: Record<string, string>;
   /** Khotan run ID created for this webhook handler execution */
   khotanRunId: string;
+  /** Internal Khotan instance identifier for helper APIs */
+  khotanInstanceId: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -73,19 +75,29 @@ export function catchEvent(config: CatchConfig): CatchRegistration {
 // Usage Example (create a file like webhooks/pollinate-catch.ts)
 // ---------------------------------------------------------------------------
 //
+// import { khotanCache } from "khotan-data/factory";
 // import { catchEvent, type CatchContext } from "./catch";
 // Khotan already records webhook deliveries in khotan_webhook_events and links
-// them to khotan_runs. Use your catch workflow for app-specific side effects.
+// them to khotan_runs. Use your catch workflow for app-specific side effects
+// and optionally khotanCache(ctx, "name") for dedupe or cursor state.
 //
 // async function pollinateCatchWorkflow(ctx: CatchContext) {
 //   "use workflow";
 //
 //   async function notifyOps() {
 //     "use step";
+//     const cache = khotanCache(ctx, "pollinate-webhook-markers");
+//     const eventId = String(ctx.event["id"] ?? "");
+//     if (eventId && (await cache.get<boolean>(eventId))) return;
+//
 //     console.log("Handled webhook", {
 //       eventType: ctx.eventType,
 //       khotanRunId: ctx.khotanRunId,
 //     });
+//
+//     if (eventId) {
+//       await cache.set(eventId, true);
+//     }
 //   }
 //
 //   await notifyOps();

package/dist/templates/debug-index-page.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import Link from "next/link";
+import { khotanFetch, ApiErrorState } from "@/components/khotan/api-state";
 
 // ============================================================================
 // Debug Index — Lists all registered plugs for debugging
@@ -23,20 +24,28 @@ export default function DebugIndexPage() {
   const [plugs, setPlugs] = useState<Plug[]>([]);
   const [loading, setLoading] = useState(true);
   const [debugEnabled, setDebugEnabled] = useState<boolean | null>(null);
+  const [error, setError] = useState<unknown>(null);
 
-  useEffect(() => {
-    Promise.all([
-      fetch("/api/khotan/debug").then((r) => r.ok),
-      fetch("/api/khotan/plugs").then((r) => (r.ok ? r.json() : [])),
-    ])
-      .then(([enabled, data]) => {
-        setDebugEnabled(enabled);
-        setPlugs(data as Plug[]);
-      })
-      .catch(() => setDebugEnabled(false))
-      .finally(() => setLoading(false));
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const enabled = await fetch("/api/khotan/debug").then((r) => r.ok);
+      setDebugEnabled(enabled);
+      if (enabled) {
+        setPlugs(await khotanFetch<Plug[]>("/api/khotan/plugs"));
+      }
+    } catch (err) {
+      setError(err);
+    } finally {
+      setLoading(false);
+    }
   }, []);
 
+  useEffect(() => {
+    void load();
+  }, [load]);
+
   if (loading) {
     return (
       <main className="container mx-auto max-w-3xl px-4 py-10">
@@ -71,31 +80,42 @@ export default function DebugIndexPage() {
         </a>
       </div>
       <h1 className="text-2xl font-bold tracking-tight mb-6">Debug</h1>
-      <p className="text-muted-foreground mb-6">
-        Select a plug to test requests through its real code path.
-      </p>
-      <div className="grid gap-3">
-        {plugs.map((plug) => (
-          <Link
-            key={plug.id}
-            href={`/debug/${plug.name}`}
-            className="flex items-center justify-between rounded-lg border border-border p-4 transition-colors hover:border-foreground/30 hover:bg-muted/50"
-          >
-            <div>
-              <p className="font-medium">{plug.name}</p>
-              <p className="text-xs text-muted-foreground truncate">
-                {plug.baseUrl}
+      {error ? (
+        <ApiErrorState error={error} onRetry={() => void load()} />
+      ) : (
+        <>
+          <p className="text-muted-foreground mb-6">
+            Select a plug to test requests through its real code path.
+          </p>
+          <div className="grid gap-3">
+            {plugs.map((plug) => (
+              <Link
+                key={plug.id}
+                href={`/debug/${plug.name}`}
+                className="flex items-center justify-between rounded-lg border border-border p-4 transition-colors hover:border-foreground/30 hover:bg-muted/50"
+              >
+                <div>
+                  <p className="font-medium">{plug.name}</p>
+                  <p className="text-xs text-muted-foreground truncate">
+                    {plug.baseUrl}
+                  </p>
+                </div>
+                <div className="flex items-center gap-2">
+                  <span className="text-xs text-muted-foreground">
+                    {plug.authType}
+                  </span>
+                  <span className="text-muted-foreground">→</span>
+                </div>
+              </Link>
+            ))}
+            {plugs.length === 0 && (
+              <p className="text-sm text-muted-foreground">
+                No plugs registered yet.
               </p>
-            </div>
-            <div className="flex items-center gap-2">
-              <span className="text-xs text-muted-foreground">
-                {plug.authType}
-              </span>
-              <span className="text-muted-foreground">→</span>
-            </div>
-          </Link>
-        ))}
-      </div>
+            )}
+          </div>
+        </>
+      )}
     </main>
   );
 }

package/dist/templates/hub.tsx

@@ -15,6 +15,7 @@ import { Switch } from "@/components/ui/switch";
 import { Button } from "@/components/ui/button";
 import { WirePanel } from "./wire";
 import { VarPanel } from "./var-panel";
+import { khotanFetch, ApiErrorState } from "./api-state";
 
 // ============================================================================
 // Khotan Hub — Dashboard for configured plugs and flows
@@ -108,7 +109,7 @@ export function KhotanHub({
   const [flows, setFlows] = useState<Flow[]>([]);
   const [webhookHandlers, setWebhookHandlers] = useState<WebhookHandler[]>([]);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<unknown>(null);
   const [selectedPlugId, setSelectedPlugId] = useState<string | null>(null);
   const [debugEnabled, setDebugEnabled] = useState(false);
 
@@ -122,17 +123,14 @@ export function KhotanHub({
     setLoading(true);
     setError(null);
     try {
-      const [plugsRes, flowsRes] = await Promise.all([
-        fetch("/api/khotan/plugs"),
-        fetch("/api/khotan/flows"),
+      const [plugsData, flowsData] = await Promise.all([
+        khotanFetch<Plug[]>("/api/khotan/plugs"),
+        khotanFetch<Flow[]>("/api/khotan/flows"),
       ]);
-      if (!plugsRes.ok || !flowsRes.ok) {
-        throw new Error("Failed to fetch khotan data");
-      }
-      setPlugs(await plugsRes.json());
-      setFlows(await flowsRes.json());
+      setPlugs(plugsData);
+      setFlows(flowsData);
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Unknown error");
+      setError(err);
     } finally {
       setLoading(false);
     }
@@ -201,19 +199,7 @@ export function KhotanHub({
   }
 
   if (error) {
-    return (
-      <Card>
-        <CardContent className="py-8 text-center">
-          <p className="text-destructive mb-4">{error}</p>
-          <button
-            onClick={fetchData}
-            className="text-sm underline hover:no-underline"
-          >
-            Retry
-          </button>
-        </CardContent>
-      </Card>
-    );
+    return <ApiErrorState error={error} onRetry={fetchData} />;
   }
 
   if (plugs.length === 0) {

package/dist/templates/inflow.ts

@@ -5,7 +5,8 @@
 // This file defines the inflow() builder and types. Create per-service flow
 // files (e.g. shopify-products.ts) using this builder to pull records from an
 // external service, transform them, and load them into your app with durable,
-// retryable Vercel Workflow steps.
+// retryable Vercel Workflow steps. Inflow workflows can also use
+// khotanCache(ctx, "name") for checkpoints and last-seen markers across runs.
 // ============================================================================
 
 import type {
@@ -47,11 +48,10 @@ export function inflow(config: InflowConfig): FlowRegistration {
 // Usage Example (create a file like flows/shopify-products.ts)
 // ---------------------------------------------------------------------------
 //
-// import { inflow, type InflowContext } from "./inflow";
+// import { bindWorkflowPlug, inflow, type InflowContext, sendUpdate } from "khotan-data/factory";
 // import { db } from "@/db";
 // import { products } from "@/db/schema";
 // import { shopifyPlug } from "../plugs/shopify";
-// import { sendUpdate } from "khotan-data/factory";
 //
 // async function shopifyProductsWorkflow(ctx: InflowContext) {
 //   "use workflow";
@@ -64,10 +64,9 @@ export function inflow(config: InflowConfig): FlowRegistration {
 //       runType: ctx.runType,
 //     });
 //     await sendUpdate({ message: "Starting Shopify products inflow" });
+//     const shopify = bindWorkflowPlug(shopifyPlug, ctx);
 //
-//     const response = await shopifyPlug.get<{ data?: Array<{ id: string; sku?: string }> }>("/products", {
-//       vars: ctx.vars,
-//     });
+//     const response = await shopify.get<{ data?: Array<{ id: string; sku?: string }> }>("/products");
 //     const records = Array.isArray(response.data) ? response.data : [];
 //     await sendUpdate({ message: `Fetched ${records.length} products`, extracted: records.length });
 //

package/dist/templates/khotan-config.ts

@@ -1,5 +1,5 @@
 // ============================================================================
-// Khotan Config — register your plugs and flows here
+// Khotan Config — register your plugs, caches, and flows here
 // Generated by khotan CLI · https://github.com/khotan-data
 //
 // Import your Drizzle database instance and register plugs below.
@@ -13,13 +13,30 @@ import { db } from "@/db";
 const khotanData = khotan({
   adapter: drizzleAdapter(db),
 
+  // ── Security ──────────────────────────────────────────────────────────────
+  // The management API (/api/khotan/*) and the Hub dashboard expose plug
+  // credentials and operational controls. Gate every management route behind
+  // your auth layer with `authorize`. It receives the raw Request, so it works
+  // directly with session libraries like better-auth:
+  //
+  //   import { auth } from "@/lib/auth";
+  //
+  //   authorize: async (request) => {
+  //     const session = await auth.api.getSession({ headers: request.headers });
+  //     return Boolean(session?.user); // or: session?.user?.role === "admin"
+  //   },
+  //
+  // Inbound webhooks, the cron dispatcher (CRON_SECRET), and debug routes are
+  // exempt automatically. Without `authorize`, the API is PUBLIC.
+  // authorize: async (request) => { /* return true to allow */ return false; },
+
   // Resources define logical entity types for cross-referencing across plugs.
-  // The connectField names the field used to match records (e.g. "sku").
+  // The mapping block declares the shared identity contract for that resource.
   resources: [
     // Example resource registration:
     //
-    // { name: "products", connectField: "sku", description: "Product catalog" },
-    // { name: "orders", connectField: "order_number" },
+    // { name: "products", mapping: { connectField: "sku" }, description: "Product catalog" },
+    // { name: "orders", mapping: { connectField: "order_number" } },
   ],
 
   plugs: [
@@ -35,6 +52,15 @@ const khotanData = khotan({
     //   ],
     // },
   ],
+
+  // Caches store durable key/value state for relays, inflows, outflows, and
+  // webhook workflows. Register named caches you want to access via
+  // khotanCache(ctx, "cache-name") or khotanData.cache("cache-name").
+  caches: [
+    // Example cache registration:
+    //
+    // cin7ProductsSnapshotCache,
+  ],
 });
 
 export default khotanData;