khotan-data 0.1.0 → 0.1.1

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/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.
@@ -14,12 +14,12 @@ 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").
+  // 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 +35,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;