khotan-data 0.0.1 → 0.1.0

package/dist/templates/inflow.ts

@@ -0,0 +1,99 @@
+// ============================================================================
+// Inflow — durable external service → app data movement
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// 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.
+// ============================================================================
+
+import type {
+  FlowRegistration,
+  FlowRunResult,
+  FlowWorkflowContext,
+} from "khotan-data/factory";
+
+export type InflowContext = FlowWorkflowContext & {
+  flow: FlowWorkflowContext["flow"] & { type: "inflow" };
+};
+
+export type InflowWorkflow = (
+  ctx: InflowContext,
+) => Promise<FlowRunResult | void>;
+
+export interface InflowConfig {
+  /** Unique name for this flow (used for DB tracking and Hub display) */
+  name: string;
+  /** Logical resource this flow feeds, e.g. "products" */
+  resource?: string;
+  /** Optional cron schedule used by scheduler integrations */
+  schedule?: string;
+  /** Durable workflow that extracts, transforms, and loads records */
+  workflow: InflowWorkflow;
+}
+
+export function inflow(config: InflowConfig): FlowRegistration {
+  return {
+    name: config.name,
+    type: "inflow",
+    resource: config.resource,
+    schedule: config.schedule,
+    workflow: config.workflow as FlowRegistration["workflow"],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like flows/shopify-products.ts)
+// ---------------------------------------------------------------------------
+//
+// import { inflow, type InflowContext } from "./inflow";
+// 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";
+//
+//   async function extractAndLoad() {
+//     "use step";
+//     console.log("Starting inflow", {
+//       flow: ctx.flow.name,
+//       khotanRunId: ctx.khotanRunId,
+//       runType: ctx.runType,
+//     });
+//     await sendUpdate({ message: "Starting Shopify products inflow" });
+//
+//     const response = await shopifyPlug.get<{ data?: Array<{ id: string; sku?: string }> }>("/products", {
+//       vars: ctx.vars,
+//     });
+//     const records = Array.isArray(response.data) ? response.data : [];
+//     await sendUpdate({ message: `Fetched ${records.length} products`, extracted: records.length });
+//
+//     if (records.length > 0) {
+//       await db.insert(products).values(
+//         records.map((record) => ({
+//           externalId: record.id,
+//           sku: record.sku ?? record.id,
+//         })),
+//       );
+//     }
+//
+//     return {
+//       extracted: records.length,
+//       transformed: records.length,
+//       created: records.length,
+//       metadata: { source: ctx.flow.name },
+//     };
+//   }
+//
+//   return extractAndLoad();
+// }
+//
+// export const shopifyProductsInflow = inflow({
+//   name: "shopify-products-inflow",
+//   resource: "products",
+//   schedule: "0 * * * *",
+//   workflow: shopifyProductsWorkflow,
+// });

package/dist/templates/khotan-config.ts

@@ -0,0 +1,40 @@
+// ============================================================================
+// Khotan Config — register your plugs and flows here
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// Import your Drizzle database instance and register plugs below.
+// Restart the dev server after making changes.
+// ============================================================================
+
+import { khotan, drizzleAdapter } from "khotan-data/factory";
+// TODO: Update this import to your Drizzle database instance
+import { db } from "@/db";
+
+const khotanData = khotan({
+  adapter: drizzleAdapter(db),
+
+  // Resources define logical entity types for cross-referencing across plugs.
+  // The connectField names the field used to match records (e.g. "sku").
+  resources: [
+    // Example resource registration:
+    //
+    // { name: "products", connectField: "sku", description: "Product catalog" },
+    // { name: "orders", connectField: "order_number" },
+  ],
+
+  plugs: [
+    // Example plug registration:
+    //
+    // {
+    //   name: "stripe",
+    //   baseUrl: "https://api.stripe.com",
+    //   authType: "bearer",
+    //   flows: [
+    //     { name: "products-inflow", type: "inflow", schedule: "0 * * * *", resource: "products" },
+    //     { name: "invoices-inflow", type: "inflow", schedule: "0 0 * * *" },
+    //   ],
+    // },
+  ],
+});
+
+export default khotanData;

package/dist/templates/khotan-route.ts

@@ -0,0 +1,13 @@
+// ============================================================================
+// Khotan API Route — catch-all handler for /api/khotan/*
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file wires your khotan config into a Next.js App Router route.
+// ============================================================================
+
+import { toNextJsHandler } from "khotan-data/factory";
+import khotanData from "@/khotan/khotan";
+
+export const { GET, POST, PUT, PATCH, DELETE } = toNextJsHandler(
+  khotanData.handler,
+);

package/dist/templates/logs-page.tsx

@@ -0,0 +1,9 @@
+import { KhotanLogs } from "@/components/khotan/logs";
+
+export default function KhotanLogsPage() {
+  return (
+    <main className="container mx-auto max-w-7xl px-4 py-10">
+      <KhotanLogs />
+    </main>
+  );
+}

package/dist/templates/logs.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { KhotanRunsTable } from "./runs-table";
+import { KhotanWebhookEventsTable } from "./webhook-events-table";
+
+export function KhotanLogs({ pageSize = 10 }: { pageSize?: number } = {}) {
+  return (
+    <div className="space-y-6">
+      <div className="space-y-2">
+        <h2 className="text-2xl font-bold tracking-tight">Khotan Logs</h2>
+        <p className="text-sm text-muted-foreground">
+          Inspect recent flow runs and inbound webhook activity in one place.
+        </p>
+      </div>
+
+      <KhotanRunsTable pageSize={pageSize} />
+      <KhotanWebhookEventsTable pageSize={pageSize} />
+    </div>
+  );
+}

package/dist/templates/outflow.example.ts

@@ -0,0 +1,52 @@
+// ============================================================================
+// Example: Outflow
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// Copy this file, rename it for your destination service/resource, and register
+// the exported flow in {outputDir}/khotan.ts.
+// ============================================================================
+
+import { outflow, type OutflowContext } from "./outflow";
+
+async function hubspotProductsWorkflow(ctx: OutflowContext) {
+  "use workflow";
+
+  async function loadAndPush() {
+    "use step";
+    console.log("Starting outflow", {
+      flow: ctx.flow.name,
+      khotanRunId: ctx.khotanRunId,
+      runType: ctx.runType,
+    });
+
+    // Replace this with your app-specific DB query.
+    const records: Array<Record<string, unknown>> = [];
+
+    for (const record of records) {
+      await fetch("https://api.example.com/products", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${ctx.vars["apiToken"] ?? ""}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(record),
+      });
+    }
+
+    return {
+      extracted: records.length,
+      transformed: records.length,
+      created: records.length,
+      metadata: { destination: ctx.flow.name },
+    };
+  }
+
+  return loadAndPush();
+}
+
+export const hubspotProductsOutflow = outflow({
+  name: "hubspot-products-outflow",
+  resource: "products",
+  schedule: "0 * * * *",
+  workflow: hubspotProductsWorkflow,
+});

package/dist/templates/outflow.ts

@@ -0,0 +1,90 @@
+// ============================================================================
+// Outflow — durable app → external service data movement
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file defines the outflow() builder and types. Create per-service flow
+// files (e.g. crm-audiences.ts) using this builder to read app data and push it
+// to an external service with durable, retryable Vercel Workflow steps.
+// ============================================================================
+
+import type {
+  FlowRegistration,
+  FlowRunResult,
+  FlowWorkflowContext,
+} from "khotan-data/factory";
+
+export type OutflowContext = FlowWorkflowContext & {
+  flow: FlowWorkflowContext["flow"] & { type: "outflow" };
+};
+
+export type OutflowWorkflow = (
+  ctx: OutflowContext,
+) => Promise<FlowRunResult | void>;
+
+export interface OutflowConfig {
+  /** Unique name for this flow (used for DB tracking and Hub display) */
+  name: string;
+  /** Logical resource this flow publishes, e.g. "products" */
+  resource?: string;
+  /** Optional cron schedule used by scheduler integrations */
+  schedule?: string;
+  /** Durable workflow that reads app data and writes it to the plug */
+  workflow: OutflowWorkflow;
+}
+
+export function outflow(config: OutflowConfig): FlowRegistration {
+  return {
+    name: config.name,
+    type: "outflow",
+    resource: config.resource,
+    schedule: config.schedule,
+    workflow: config.workflow as FlowRegistration["workflow"],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like flows/hubspot-products.ts)
+// ---------------------------------------------------------------------------
+//
+// import { outflow, type OutflowContext } from "./outflow";
+// import { db } from "@/db";
+// import { products } from "@/db/schema";
+// import { hubspotPlug } from "../plugs/hubspot";
+//
+// async function hubspotProductsWorkflow(ctx: OutflowContext) {
+//   "use workflow";
+//
+//   async function loadAndPush() {
+//     "use step";
+//     console.log("Starting outflow", {
+//       flow: ctx.flow.name,
+//       khotanRunId: ctx.khotanRunId,
+//       runType: ctx.runType,
+//     });
+//
+//     const records = await db.select().from(products);
+//
+//     for (const record of records) {
+//       await hubspotPlug.post("/products", {
+//         vars: ctx.vars,
+//         body: record,
+//       });
+//     }
+//
+//     return {
+//       extracted: records.length,
+//       transformed: records.length,
+//       created: records.length,
+//       metadata: { destination: ctx.flow.name },
+//     };
+//   }
+//
+//   return loadAndPush();
+// }
+//
+// export const hubspotProductsOutflow = outflow({
+//   name: "hubspot-products-outflow",
+//   resource: "products",
+//   schedule: "0 * * * *",
+//   workflow: hubspotProductsWorkflow,
+// });

package/dist/templates/pass.example.ts

@@ -0,0 +1,51 @@
+// ============================================================================
+// Example: Pass
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// Copy this file, rename it for your source/destination pair, and register the
+// exported pass handler in {outputDir}/khotan.ts.
+// ============================================================================
+
+import { pass, type PassContext } from "./pass";
+
+async function stripeToSlackWorkflow(ctx: PassContext) {
+  "use workflow";
+
+  async function forwardEvent() {
+    "use step";
+    console.log("Forwarding webhook event", {
+      eventType: ctx.eventType,
+      khotanRunId: ctx.khotanRunId,
+    });
+
+    await fetch("https://slack.com/api/chat.postMessage", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${ctx.destVars["botToken"] ?? ""}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        channel: ctx.destVars["channelId"],
+        text: `Received ${ctx.eventType}`,
+        blocks: [
+          {
+            type: "section",
+            text: {
+              type: "mrkdwn",
+              text: `Received ${ctx.eventType} from Stripe`,
+            },
+          },
+        ],
+      }),
+    });
+  }
+
+  await forwardEvent();
+}
+
+export const stripeToSlack = pass({
+  name: "stripe-to-slack",
+  to: "slack",
+  events: ["invoice.paid"],
+  workflow: stripeToSlackWorkflow,
+});

package/dist/templates/pass.ts

@@ -0,0 +1,124 @@
+// ============================================================================
+// Pass — durable webhook event forwarding via Vercel Workflow
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file defines the pass() builder and types. Create per-service pass
+// files (e.g. pollinate-to-slack.ts) using this builder to forward verified
+// webhook events to another service with durable, retryable workflow steps.
+//
+// Pass workflows receive a PassContext with the parsed event, event type,
+// headers, and destVars (variables for the destination plug). Steps have
+// full Node.js access — construct destination plugs from destVars.
+// ============================================================================
+
+// ---------------------------------------------------------------------------
+// Context — serializable data passed to the workflow
+// ---------------------------------------------------------------------------
+
+export interface PassContext {
+  /** Parsed webhook payload */
+  event: Record<string, unknown>;
+  /** Event type extracted from payload (e.g. "order.created") */
+  eventType: string;
+  /** Incoming request headers */
+  headers: Record<string, string>;
+  /** Decrypted variables for the destination plug (auto-injected by factory) */
+  destVars: Record<string, string>;
+  /** Khotan run ID created for this webhook handler execution */
+  khotanRunId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow type — the function signature your workflow must conform to
+// ---------------------------------------------------------------------------
+
+export type PassWorkflow = (ctx: PassContext) => Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Config — passed to the pass() builder
+// ---------------------------------------------------------------------------
+
+export interface PassConfig {
+  /** Unique name for this pass handler (used for DB tracking and Hub display) */
+  name: string;
+  /** Name of the destination plug to forward events to */
+  to: string;
+  /** Event types this pass should receive */
+  events?: string[];
+  /** Workflow function that handles the forwarding */
+  workflow: PassWorkflow;
+}
+
+// ---------------------------------------------------------------------------
+// Registration — returned by pass(), consumed by factory config
+// ---------------------------------------------------------------------------
+
+export interface PassRegistration {
+  type: "pass";
+  name: string;
+  to: string;
+  events?: string[];
+  workflow: PassWorkflow;
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+export function pass(config: PassConfig): PassRegistration {
+  return {
+    type: "pass",
+    name: config.name,
+    to: config.to,
+    events: config.events,
+    workflow: config.workflow,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like webhooks/pollinate-to-slack.ts)
+// ---------------------------------------------------------------------------
+//
+// import { pass, type PassContext } from "./pass";
+// import { plug } from "../plugs/plug";
+//
+// async function pollinateToSlackWorkflow(ctx: PassContext) {
+//   "use workflow";
+//
+//   async function forwardEvent() {
+//     "use step";
+//
+//     // Construct destination plug from destVars
+//     const slackPlug = plug({
+//       name: "slack",
+//       baseUrl: "https://hooks.slack.com",
+//       authType: "bearer",
+//       auth: { bearer: { token: ctx.destVars["token"] ?? "" } },
+//     });
+//
+//     await slackPlug.post("/services/webhook", {
+//       body: {
+//         text: `Received ${ctx.eventType} event from pollinate`,
+//         event: ctx.event,
+//       },
+//     });
+//   }
+//
+//   await forwardEvent();
+// }
+//
+// export const pollinateToSlack = pass({
+//   name: "pollinate-to-slack",
+//   to: "slack",
+//   events: ["order.created"],
+//   workflow: pollinateToSlackWorkflow,
+// });
+//
+// Then register in your khotan config:
+//
+// plugs: [{
+//   name: "pollinate",
+//   plug: pollinatePlug,
+//   wires: [pollinateWire],
+//   passes: [pollinateToSlack],
+// }]