khotan-data 0.0.1 → 0.1.1

package/dist/templates/wire-panel.tsx

@@ -0,0 +1,216 @@
+"use client";
+
+import { useEffect, useState, useCallback } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+
+// ============================================================================
+// Wire Panel — UI for managing webhook subscriptions
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file is yours. Restyle, extend, or embed it however you like.
+// It uses shadcn/ui primitives and fetches from /api/khotan/wires.
+// ============================================================================
+
+interface WireRecord {
+  id: string;
+  plugId: string;
+  remoteId: string;
+  callbackUrl: string;
+  eventTypes: string[];
+  status: "active" | "disabled" | "pending";
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface WirePanelProps {
+  plugName: string;
+  label?: string;
+  basePath?: string;
+  webhookUrl?: string;
+}
+
+export function WirePanel({
+  plugName,
+  label,
+  basePath = "/api/khotan",
+  webhookUrl,
+}: WirePanelProps) {
+  const displayName = label ?? plugName;
+  const resolvedWebhookUrl =
+    webhookUrl || (typeof window !== "undefined" ? window.location.origin : "");
+  const [wire, setWire] = useState<WireRecord | null>(null);
+  const [configured, setConfigured] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [acting, setActing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchWire = useCallback(async () => {
+    try {
+      const res = await fetch(`${basePath}/wires/${plugName}`);
+      if (!res.ok) {
+        setConfigured(false);
+        setWire(null);
+        return;
+      }
+      const data = await res.json();
+      setConfigured(data.configured ?? false);
+      setWire(data.wire ?? null);
+      setError(null);
+    } catch {
+      setConfigured(false);
+    } finally {
+      setLoading(false);
+    }
+  }, [basePath, plugName]);
+
+  useEffect(() => {
+    fetchWire();
+  }, [fetchWire]);
+
+  async function handleCreate() {
+    setActing(true);
+    setError(null);
+    try {
+      const callbackUrl = `${resolvedWebhookUrl}/api/khotan/webhook/${plugName}`;
+
+      const res = await fetch(`${basePath}/wires/${plugName}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ callbackUrl }),
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        setError(data.error ?? "Failed to create wire");
+        return;
+      }
+
+      const data = await res.json();
+      setWire(data.wire ?? null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Network error");
+    } finally {
+      setActing(false);
+    }
+  }
+
+  async function handleDelete() {
+    if (!wire) return;
+    setActing(true);
+    setError(null);
+    try {
+      const res = await fetch(`${basePath}/wires/${plugName}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ wireId: wire.id }),
+      });
+
+      if (!res.ok && res.status !== 204) {
+        const data = await res.json();
+        setError(data.error ?? "Failed to disconnect");
+        return;
+      }
+
+      await fetchWire();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Network error");
+    } finally {
+      setActing(false);
+    }
+  }
+
+  if (loading) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium capitalize">
+            {displayName} Wire
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="h-4 w-2/3 animate-pulse rounded bg-muted" />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  if (!configured) return null;
+
+  const isActive = wire?.status === "active";
+  const isPending = wire?.status === "pending";
+
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+        <CardTitle className="text-sm font-medium capitalize">
+          {displayName} Wire
+        </CardTitle>
+        <Badge
+          variant={isActive ? "default" : isPending ? "outline" : "secondary"}
+        >
+          {isActive
+            ? "Connected"
+            : isPending
+              ? "Not Connected"
+              : "Disconnected"}
+        </Badge>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {error && <p className="text-sm text-destructive">{error}</p>}
+
+        {isActive ? (
+          <div className="space-y-2">
+            <div className="text-xs text-muted-foreground space-y-1">
+              <p>
+                <span className="font-medium">Callback:</span>{" "}
+                <code className="bg-muted px-1 py-0.5 rounded text-[11px]">
+                  {wire!.callbackUrl}
+                </code>
+              </p>
+              <p>
+                <span className="font-medium">Remote ID:</span>{" "}
+                <code className="bg-muted px-1 py-0.5 rounded text-[11px]">
+                  {wire!.remoteId}
+                </code>
+              </p>
+              <p>
+                <span className="font-medium">Events:</span>{" "}
+                {wire!.eventTypes.join(", ")}
+              </p>
+              <p>
+                <span className="font-medium">Created:</span>{" "}
+                {new Date(wire!.createdAt).toLocaleString()}
+              </p>
+            </div>
+            <Button
+              variant="destructive"
+              size="sm"
+              onClick={handleDelete}
+              disabled={acting}
+            >
+              {acting ? "Disconnecting..." : "Disconnect"}
+            </Button>
+          </div>
+        ) : (
+          <div className="space-y-2">
+            <p className="text-xs text-muted-foreground">
+              No active webhook subscription. Click below to register one with{" "}
+              <span className="capitalize">{displayName}</span>.
+            </p>
+            <p className="text-xs text-muted-foreground">
+              <span className="font-medium">Webhook URL:</span>{" "}
+              <code className="bg-muted px-1 py-0.5 rounded text-[11px]">
+                {resolvedWebhookUrl}/api/khotan/webhook/{plugName}
+              </code>
+            </p>
+            <Button size="sm" onClick={handleCreate} disabled={acting}>
+              {acting ? "Connecting..." : "Connect Webhook"}
+            </Button>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/dist/templates/wire.ts

@@ -0,0 +1,155 @@
+// ============================================================================
+// Wire — webhook subscription lifecycle hooks
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file defines the wire() builder and types. Create per-service wire
+// files (e.g. pollinate-wire.ts) using this builder to handle subscribe,
+// unsubscribe, and verification logic for each external service.
+//
+// Wire hooks receive a "bound plug" — the plug with vars and auth
+// auto-injected by the factory. Just call ctx.plug.post/delete/etc.
+// ============================================================================
+
+import type { Plug } from "../plugs/plug";
+
+// ---------------------------------------------------------------------------
+// Bound Plug — plug with vars auto-injected by the factory
+// ---------------------------------------------------------------------------
+
+export interface BoundPlug {
+  readonly name: string;
+  readonly baseUrl: string;
+  get<T>(
+    path: string,
+    options?: {
+      params?: Record<string, unknown>;
+      headers?: Record<string, string>;
+    },
+  ): Promise<T>;
+  post<T>(
+    path: string,
+    options?: { body?: unknown; headers?: Record<string, string> },
+  ): Promise<T>;
+  put<T>(
+    path: string,
+    options?: { body?: unknown; headers?: Record<string, string> },
+  ): Promise<T>;
+  patch<T>(
+    path: string,
+    options?: { body?: unknown; headers?: Record<string, string> },
+  ): Promise<T>;
+  delete<T>(
+    path: string,
+    options?: { headers?: Record<string, string> },
+  ): Promise<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Hook Contexts
+// ---------------------------------------------------------------------------
+
+export interface WireSubscribeContext {
+  /** Plug instance with vars and auth auto-injected */
+  plug: BoundPlug;
+  /** The callback URL to register with the external service */
+  callbackUrl: string;
+  /** Event types this wire subscribes to */
+  events: string[];
+  /** Previously stored wire-specific vars (empty on first subscribe) */
+  wireVars: Record<string, string>;
+  /** Persist wire-specific vars (webhook secrets, tokens, etc.) */
+  setWireVars(updates: Record<string, string>): Promise<void>;
+}
+
+export interface WireUnsubscribeContext {
+  /** Plug instance with vars and auth auto-injected */
+  plug: BoundPlug;
+  /** The remote subscription ID returned from onSubscribe */
+  remoteId: string;
+  /** Wire-specific vars stored during subscribe */
+  wireVars: Record<string, string>;
+  /** Persist wire-specific var updates */
+  setWireVars(updates: Record<string, string>): Promise<void>;
+}
+
+export interface WireVerifyContext {
+  /** Incoming request headers as plain key-value pairs */
+  headers: Record<string, string>;
+  /** Raw request body as text (for signature verification) */
+  body: string;
+  /** Wire-specific vars (e.g. webhook signing secret) */
+  wireVars: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Wire Config
+// ---------------------------------------------------------------------------
+
+export interface WireConfig {
+  /** Event types this wire subscribes to */
+  events: string[];
+
+  /**
+   * Called when the wire is being connected.
+   * Make the API call to register the webhook subscription and return the remoteId.
+   */
+  onSubscribe(ctx: WireSubscribeContext): Promise<{ remoteId: string }>;
+
+  /**
+   * Called when the wire is being disconnected.
+   * Make the API call to remove the webhook subscription.
+   */
+  onUnsubscribe(ctx: WireUnsubscribeContext): Promise<void>;
+
+  /**
+   * Optional: verify incoming webhook signatures.
+   * Return true if the signature is valid.
+   */
+  onVerify?(ctx: WireVerifyContext): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+export function wire(config: WireConfig): WireConfig {
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like wires/stripe-wire.ts)
+// ---------------------------------------------------------------------------
+//
+// import { wire } from "./wire";
+//
+// export const stripeWire = wire({
+//   events: ["invoice.paid", "invoice.payment_failed"],
+//
+//   async onSubscribe(ctx) {
+//     const res = await ctx.plug.post<{ id: string; secret: string }>(
+//       "/webhook_endpoints",
+//       {
+//         body: {
+//           url: ctx.callbackUrl,
+//           enabled_events: ctx.events,
+//         },
+//       },
+//     );
+//
+//     // Store the webhook signing secret for verification
+//     await ctx.setWireVars({ webhookSecret: res.secret });
+//
+//     return { remoteId: res.id };
+//   },
+//
+//   async onUnsubscribe(ctx) {
+//     await ctx.plug.delete(`/webhook_endpoints/${ctx.remoteId}`);
+//   },
+//
+//   async onVerify(ctx) {
+//     const signature = ctx.headers["stripe-signature"];
+//     if (!signature) return false;
+//     // Verify using ctx.wireVars.webhookSecret and ctx.body (raw text)
+//     return true;
+//   },
+// });

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "khotan-data",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Data primitives for TypeScript — ETL pipelines, transforms, and Drizzle Postgres integration.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "khotan": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "import": {
@@ -46,10 +49,32 @@
         "types": "./dist/drizzle.d.cts",
         "default": "./dist/drizzle.cjs"
       }
+    },
+    "./factory": {
+      "import": {
+        "types": "./dist/factory.d.ts",
+        "default": "./dist/factory.js"
+      },
+      "require": {
+        "types": "./dist/factory.d.cts",
+        "default": "./dist/factory.cjs"
+      }
+    },
+    "./plug": {
+      "import": {
+        "types": "./dist/plug-client.d.ts",
+        "default": "./dist/plug-client.js"
+      },
+      "require": {
+        "types": "./dist/plug-client.d.cts",
+        "default": "./dist/plug-client.cjs"
+      }
     }
   },
   "files": [
     "dist",
+    "dist/templates",
+    "AGENTS.md",
     "README.md",
     "LICENSE"
   ],
@@ -66,7 +91,7 @@
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
     "check": "npm run typecheck && npm run lint && npm run format:check && npm run test",
-    "prepublishOnly": "npm run check && npm run build",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
     "changeset": "changeset",
     "release": "npm run build && changeset publish"
   },
@@ -92,11 +117,22 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.35.0"
+    "drizzle-orm": ">=0.35.0",
+    "workflow": ">=0.1.0",
+    "zod": ">=3.22.0"
+  },
+  "peerDependenciesMeta": {
+    "workflow": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.4",
     "@eslint/js": "^9.28.0",
+    "@types/prompts": "^2.4.9",
     "@vitest/coverage-v8": "^4.1.7",
     "drizzle-orm": "^0.45.2",
     "eslint": "^9.28.0",
@@ -104,7 +140,12 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.34.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.7",
+    "zod": "^3.25.76"
   },
-  "packageManager": "npm@11.12.1"
+  "packageManager": "npm@11.12.1",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "prompts": "^2.4.2"
+  }
 }