khotan-data 0.1.1 → 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/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/khotan-config.ts

@@ -13,6 +13,23 @@ 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 mapping block declares the shared identity contract for that resource.
   resources: [

package/dist/templates/mapping-browser.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useEffect, useMemo, useState } from "react";
+import { khotanFetch, ApiErrorState } from "./api-state";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
@@ -60,7 +61,9 @@ function readErrorMessage(error: unknown): string {
   return "Unknown error";
 }
 
-function toPrettyJson(value: Record<string, unknown> | null | undefined): string {
+function toPrettyJson(
+  value: Record<string, unknown> | null | undefined,
+): string {
   return value ? JSON.stringify(value, null, 2) : "";
 }
 
@@ -92,7 +95,10 @@ function parseConnectValueInput(
   }
 
   const parsed = JSON.parse(trimmed) as unknown;
-  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== "string")) {
+  if (
+    !Array.isArray(parsed) ||
+    parsed.some((value) => typeof value !== "string")
+  ) {
     throw new Error(
       "Composite connect values must be provided as a JSON string array in declared field order.",
     );
@@ -119,7 +125,7 @@ export function KhotanMappingBrowser({
   const [mappingsLoading, setMappingsLoading] = useState(false);
   const [search, setSearch] = useState("");
   const [offset, setOffset] = useState(0);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<unknown>(null);
   const [actionError, setActionError] = useState<string | null>(null);
   const [submitting, setSubmitting] = useState(false);
   const [formMode, setFormMode] = useState<FormMode | null>(null);
@@ -142,11 +148,7 @@ export function KhotanMappingBrowser({
     setResourcesLoading(true);
     setError(null);
     try {
-      const res = await fetch("/api/khotan/resources");
-      if (!res.ok) {
-        throw new Error("Failed to fetch resources from /api/khotan/resources");
-      }
-      const data = (await res.json()) as ResourceRecord[];
+      const data = await khotanFetch<ResourceRecord[]>("/api/khotan/resources");
       setResources(data);
 
       setSelectedResourceId((current) => {
@@ -156,13 +158,17 @@ export function KhotanMappingBrowser({
         return current || data[0]!.id;
       });
     } catch (error) {
-      setError(readErrorMessage(error));
+      setError(error);
     } finally {
       setResourcesLoading(false);
     }
   }
 
-  async function fetchMappings(resourceId: string, nextOffset: number, term: string) {
+  async function fetchMappings(
+    resourceId: string,
+    nextOffset: number,
+    term: string,
+  ) {
     setMappingsLoading(true);
     setError(null);
     try {
@@ -175,15 +181,11 @@ export function KhotanMappingBrowser({
       if (term.trim()) {
         url.searchParams.set("search", term.trim());
       }
-      const res = await fetch(url.toString());
-      if (!res.ok) {
-        throw new Error("Failed to fetch mappings for the selected resource");
-      }
-      const data = (await res.json()) as MappingPage;
+      const data = await khotanFetch<MappingPage>(url.toString());
       setMappings(data.items);
       setPage(data.page);
     } catch (error) {
-      setError(readErrorMessage(error));
+      setError(error);
       setMappings([]);
       setPage(null);
     } finally {
@@ -238,7 +240,10 @@ export function KhotanMappingBrowser({
 
     if (declaredPlugNames.length > 0) {
       const nextDeclaredRefs = Object.fromEntries(
-        declaredPlugNames.map((plugName) => [plugName, mapping.refs[plugName] ?? ""]),
+        declaredPlugNames.map((plugName) => [
+          plugName,
+          mapping.refs[plugName] ?? "",
+        ]),
       );
       setDeclaredRefs(nextDeclaredRefs);
       setDynamicRefs([]);
@@ -355,7 +360,9 @@ export function KhotanMappingBrowser({
       }
 
       const nextOffset =
-        mappings.length === 1 && offset > 0 ? Math.max(offset - pageSize, 0) : offset;
+        mappings.length === 1 && offset > 0
+          ? Math.max(offset - pageSize, 0)
+          : offset;
       setOffset(nextOffset);
       await fetchMappings(mapping.resourceId, nextOffset, search);
     } catch (error) {
@@ -460,33 +467,30 @@ export function KhotanMappingBrowser({
           </div>
 
           {resourcesLoading ? (
-            <div className="text-muted-foreground text-sm">Loading resources...</div>
+            <div className="text-muted-foreground text-sm">
+              Loading resources...
+            </div>
           ) : null}
 
           {!resourcesLoading && resources.length === 0 ? (
             <div className="text-muted-foreground text-sm">
-              No resources are registered yet. Mappings require registered resources
-              in your `khotan()` config.
+              No resources are registered yet. Mappings require registered
+              resources in your `khotan()` config.
             </div>
           ) : null}
 
           {error ? (
-            <div className="space-y-2 rounded-md border border-destructive/30 bg-destructive/5 p-4">
-              <p className="text-sm text-destructive">{error}</p>
-              <Button
-                variant="outline"
-                size="sm"
-                onClick={() => {
-                  if (selectedResourceId) {
-                    void fetchMappings(selectedResourceId, offset, search);
-                  } else {
-                    void fetchResources();
-                  }
-                }}
-              >
-                Retry
-              </Button>
-            </div>
+            <ApiErrorState
+              error={error}
+              onRetry={() => {
+                if (selectedResourceId) {
+                  void fetchMappings(selectedResourceId, offset, search);
+                } else {
+                  void fetchResources();
+                }
+              }}
+              compact
+            />
           ) : null}
         </CardContent>
       </Card>
@@ -537,8 +541,8 @@ export function KhotanMappingBrowser({
                         id={`ref-${plugName}`}
                         value={declaredRefs[plugName] ?? ""}
                         placeholder={
-                          selectedResource?.mapping.plugs?.[plugName]?.uniqueIdentifier ??
-                          "External ID"
+                          selectedResource?.mapping.plugs?.[plugName]
+                            ?.uniqueIdentifier ?? "External ID"
                         }
                         onChange={(event) =>
                           setDeclaredRefs((current) => ({
@@ -590,7 +594,9 @@ export function KhotanMappingBrowser({
                           setDynamicRefs((current) =>
                             current.length === 1
                               ? [{ plugName: "", ref: "" }]
-                              : current.filter((_, itemIndex) => itemIndex !== index),
+                              : current.filter(
+                                  (_, itemIndex) => itemIndex !== index,
+                                ),
                           )
                         }
                       >
@@ -643,7 +649,11 @@ export function KhotanMappingBrowser({
                     ? "Create Mapping"
                     : "Save Changes"}
               </Button>
-              <Button variant="outline" onClick={resetForm} disabled={submitting}>
+              <Button
+                variant="outline"
+                onClick={resetForm}
+                disabled={submitting}
+              >
                 Cancel
               </Button>
             </div>
@@ -662,7 +672,9 @@ export function KhotanMappingBrowser({
         </CardHeader>
         <CardContent>
           {mappingsLoading ? (
-            <div className="text-muted-foreground text-sm">Loading mappings...</div>
+            <div className="text-muted-foreground text-sm">
+              Loading mappings...
+            </div>
           ) : null}
 
           {!mappingsLoading &&
@@ -729,8 +741,8 @@ export function KhotanMappingBrowser({
               {page ? (
                 <div className="flex flex-wrap items-center justify-between gap-3">
                   <p className="text-muted-foreground text-sm">
-                    Showing {page.offset + 1}-
-                    {page.offset + mappings.length} of {page.total}
+                    Showing {page.offset + 1}-{page.offset + mappings.length} of{" "}
+                    {page.total}
                   </p>
                   <div className="flex gap-2">
                     <Button