khotan-data 0.1.1 → 0.3.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/catch.example.ts

@@ -4,29 +4,37 @@
 //
 // Copy this file, rename it for your webhook source/event, and register the
 // exported catch handler in {outputDir}/khotan.ts.
+//
+// IMPORTANT — Workflow step structure:
+// Declare "use step" functions at module top level and pass them only
+// serializable values (the `ctx` object is plain data and is safe to pass).
+// Do NOT nest step functions inside the "use workflow" function — the Workflow
+// compiler cannot hoist closures that capture workflow scope, and they fail at
+// runtime in the sandbox. Keep the workflow body limited to orchestration.
 // ============================================================================
 
 import { catchEvent, type CatchContext } from "./catch";
 
-async function stripeInvoiceCatchWorkflow(ctx: CatchContext) {
-  "use workflow";
-
-  async function persistEvent() {
-    "use step";
-    console.log("Handling webhook event", {
-      eventType: ctx.eventType,
-      khotanRunId: ctx.khotanRunId,
-    });
+// Step: full Node.js access, retried independently. Receives serializable ctx.
+async function persistEvent(ctx: CatchContext) {
+  "use step";
+  console.log("Handling webhook event", {
+    eventType: ctx.eventType,
+    khotanRunId: ctx.khotanRunId,
+  });
 
-    // Khotan already records webhook deliveries. Add app-specific side effects
-    // here, such as updating a local table or enqueueing downstream work.
-    console.log("Webhook payload", {
-      event: ctx.event,
-      headers: ctx.headers,
-    });
-  }
+  // Khotan already records webhook deliveries. Add app-specific side effects
+  // here, such as updating a local table or enqueueing downstream work.
+  console.log("Webhook payload", {
+    event: ctx.event,
+    headers: ctx.headers,
+  });
+}
 
-  await persistEvent();
+// Workflow: orchestration only. Calls top-level steps with serializable args.
+async function stripeInvoiceCatchWorkflow(ctx: CatchContext) {
+  "use workflow";
+  await persistEvent(ctx);
 }
 
 export const stripeInvoiceCatch = catchEvent({

package/dist/templates/catch.ts

@@ -81,26 +81,31 @@ export function catchEvent(config: CatchConfig): CatchRegistration {
 // 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";
+// Declare "use step" functions at MODULE TOP LEVEL and pass them serializable
+// values only (`ctx` is plain data). Do NOT nest steps inside the "use workflow"
+// function — closures over workflow scope cannot be hoisted and fail at runtime.
 //
-//   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;
+// // Step: top-level, full Node.js access, retried independently.
+// async function notifyOps(ctx: CatchContext) {
+//   "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,
-//     });
+//   console.log("Handled webhook", {
+//     eventType: ctx.eventType,
+//     khotanRunId: ctx.khotanRunId,
+//   });
 //
-//     if (eventId) {
-//       await cache.set(eventId, true);
-//     }
+//   if (eventId) {
+//     await cache.set(eventId, true);
 //   }
+// }
 //
-//   await notifyOps();
+// // Workflow: orchestration only.
+// async function pollinateCatchWorkflow(ctx: CatchContext) {
+//   "use workflow";
+//   await notifyOps(ctx);
 // }
 //
 // export const pollinateCatch = catchEvent({

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>
   );
 }