khotan-data 0.1.0 → 0.2.0

package/dist/factory.d.cts

@@ -1,9 +1,24 @@
 import { PgDatabase } from 'drizzle-orm/pg-core';
 
+/**
+ * Derives the CLI auth token: HMAC-SHA256 over the timestamp, keyed by the
+ * KHOTAN_SECRET. One-way, so the raw secret (the encryption key) never travels
+ * over the wire — even a token captured from a dev log can't be reversed into
+ * the secret. Exported so the CLI can compute the same value.
+ */
+declare function deriveCliToken(secret: string, timestamp: string): Promise<string>;
+type ResourceConnectField = string | [string, ...string[]];
+interface ResourcePlugParticipation {
+    uniqueIdentifier: string;
+}
+interface ResourceMappingRegistration {
+    connectField: ResourceConnectField;
+    plugs?: Record<string, ResourcePlugParticipation>;
+}
 interface ResourceRegistration {
     name: string;
-    connectField: string;
     description?: string;
+    mapping: ResourceMappingRegistration;
 }
 type FlowType = "inflow" | "outflow" | "relay" | "webhook";
 type KhotanRunStatus = "pending" | "running" | "completed" | "partial" | "failed" | "cancelled";
@@ -19,31 +34,64 @@ interface FlowRunResult {
     error?: string | null;
     metadata?: Record<string, unknown> | null;
 }
+interface BoundPlug {
+    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>;
+}
+interface BindablePlug {
+    get<T>(path: string, options?: {
+        params?: Record<string, unknown>;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    post<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    put<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    patch<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    delete<T>(path: string, options?: {
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+}
 interface FlowRunContext {
-    plug: {
-        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>;
-    };
+    plug: BoundPlug;
     flow: {
         id: string;
         name: string;
+        plugName: string;
         type: FlowType;
         resource?: string | null;
         to?: string | null;
@@ -52,11 +100,13 @@ interface FlowRunContext {
     body?: unknown;
     vars: Record<string, string>;
     setVars(updates: Record<string, string>): Promise<void>;
+    cache(cacheName: string): CacheInstance;
 }
 interface FlowWorkflowContext {
     flow: {
         id: string;
         name: string;
+        plugName: string;
         type: FlowType;
         resource?: string | null;
         to?: string | null;
@@ -64,8 +114,11 @@ interface FlowWorkflowContext {
     runType: string;
     body?: unknown;
     vars: Record<string, string>;
+    plugVarsByName?: Record<string, Record<string, string>>;
     khotanRunId: string;
+    khotanInstanceId: string;
 }
+declare function bindWorkflowPlug(plug: BindablePlug, ctx: FlowWorkflowContext, plugName?: string): BoundPlug;
 interface KhotanRunUpdate {
     type?: "progress" | "log" | "metric" | "error";
     message: string;
@@ -157,27 +210,98 @@ interface CatchRegistration {
     type: "catch";
     name: string;
     events?: string[];
-    workflow: (ctx: {
-        event: Record<string, unknown>;
-        eventType: string;
-        headers: Record<string, string>;
-        khotanRunId: string;
-    }) => Promise<void>;
+    workflow: (ctx: CatchWorkflowContext) => Promise<void>;
 }
 interface PassRegistration {
     type: "pass";
     name: string;
     to: string;
     events?: string[];
-    workflow: (ctx: {
-        event: Record<string, unknown>;
-        eventType: string;
-        headers: Record<string, string>;
-        destVars: Record<string, string>;
-        khotanRunId: string;
-    }) => Promise<void>;
+    workflow: (ctx: PassWorkflowContext) => Promise<void>;
 }
 type WebhookRegistration = CatchRegistration | PassRegistration;
+interface CacheScope {
+    plug?: string;
+    resource?: string;
+    flow?: string;
+}
+interface CacheRegistration {
+    name: string;
+    scope?: CacheScope;
+    ttl?: string | number;
+}
+interface CacheEntryRecord {
+    id: string;
+    cacheId: string;
+    key: string;
+    value: unknown;
+    expiresAt: Date | null;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+}
+interface CacheInstance {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T): Promise<T>;
+    delete(key: string): Promise<void>;
+}
+interface CatchWorkflowContext {
+    event: Record<string, unknown>;
+    eventType: string;
+    headers: Record<string, string>;
+    khotanRunId: string;
+    khotanInstanceId: string;
+}
+interface PassWorkflowContext {
+    event: Record<string, unknown>;
+    eventType: string;
+    headers: Record<string, string>;
+    destVars: Record<string, string>;
+    khotanRunId: string;
+    khotanInstanceId: string;
+}
+interface KhotanWorkflowContextRef {
+    khotanInstanceId: string;
+}
+declare function khotanCache(ctx: KhotanWorkflowContextRef, cacheName: string): CacheInstance;
+declare function khotanMappings(ctx: KhotanWorkflowContextRef): {
+    list: (params: {
+        resourceId: string;
+        limit?: number;
+        offset?: number;
+        search?: string;
+    }) => Promise<{
+        items: Record<string, unknown>[];
+        page: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+            prevOffset: number;
+            nextOffset: number;
+            total: number;
+        };
+    }>;
+    lookup: (params: {
+        resourceId: string;
+        connectValue: string | string[];
+    } | {
+        resourceId: string;
+        plugName: string;
+        ref: string;
+    }) => Promise<Record<string, unknown> | null>;
+    upsert: (mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }) => Promise<Record<string, unknown>>;
+    update: (id: string, mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }) => Promise<Record<string, unknown>>;
+    delete: (id: string) => Promise<void>;
+};
 interface VarField {
     readonly key: string;
     label: string;
@@ -289,11 +413,30 @@ interface KhotanAdapter {
     }>;
     upsertResource(resource: {
         name: string;
-        connectField: string;
+        connectField: ResourceConnectField;
         description?: string | null;
     }): Promise<{
         id: string;
     }>;
+    upsertCache(cache: {
+        name: string;
+        scope?: CacheScope | null;
+        ttlSeconds?: number | null;
+    }): Promise<{
+        id: string;
+    }>;
+    getCacheByName(name: string): Promise<Record<string, unknown> | null>;
+    getCacheEntry(cacheId: string, key: string): Promise<Record<string, unknown> | null>;
+    upsertCacheEntry(entry: {
+        cacheId: string;
+        key: string;
+        value: unknown;
+        expiresAt?: Date | null;
+    }): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    deleteCacheEntry(cacheId: string, key: string): Promise<void>;
     listResources(): Promise<Record<string, unknown>[]>;
     getResource(id: string): Promise<Record<string, unknown> | null>;
     getResourceFlows(resourceId: string): Promise<Record<string, unknown>[]>;
@@ -308,9 +451,21 @@ interface KhotanAdapter {
         created: boolean;
     }>;
     getMapping(id: string): Promise<Record<string, unknown> | null>;
-    listMappings(resourceId: string): Promise<Record<string, unknown>[]>;
+    listMappings(params: {
+        resourceId: string;
+        limit: number;
+        offset: number;
+        search?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        hasMore: boolean;
+        total: number;
+    }>;
     deleteMapping(id: string): Promise<void>;
     lookupMapping(params: {
+        resourceId: string;
+        connectValue: string;
+    } | {
         resourceId: string;
         plugName: string;
         ref: string;
@@ -403,11 +558,42 @@ interface KhotanAdapter {
         lastRunStatus: KhotanTerminalRunStatus;
     }): Promise<void>;
 }
+/**
+ * Authorize an incoming request to the khotan management API.
+ *
+ * Return `true` to allow the request, `false` to reject it with `401`.
+ * The function receives the raw `Request`, so it composes directly with
+ * session libraries such as better-auth:
+ *
+ * ```ts
+ * authorize: async (request) => {
+ *   const session = await auth.api.getSession({ headers: request.headers });
+ *   return session?.user?.role === "admin";
+ * }
+ * ```
+ *
+ * Throwing is treated the same as returning `false`.
+ *
+ * The following routes are intentionally exempt and are NOT passed to
+ * `authorize` (they have their own protection):
+ * - Inbound webhooks (`POST .../webhook/:plug`) — verified per-plug via `onVerify`.
+ * - The cron dispatcher (`.../cron`) — protected by `CRON_SECRET`.
+ * - Debug routes (`.../debug...`) — gated by `KHOTAN_DEBUG` and disabled in production.
+ */
+type KhotanAuthorize = (request: Request) => boolean | Promise<boolean>;
 interface KhotanConfig {
     adapter: KhotanAdapter;
     plugs: PlugRegistration[];
     resources?: ResourceRegistration[];
+    caches?: CacheRegistration[];
     secret?: string;
+    /**
+     * Gate every management route (plugs, variables, flows, runs, wires,
+     * mappings, caches, resources, webhook handlers/events) behind a custom
+     * authorization check. Strongly recommended for any deployed app — without
+     * it the management API is publicly accessible. See {@link KhotanAuthorize}.
+     */
+    authorize?: KhotanAuthorize;
 }
 type KhotanHandler = (request: Request) => Promise<Response>;
 interface WireInstance {
@@ -430,6 +616,44 @@ interface KhotanInstance {
     init(): Promise<void>;
     flow(flowNameOrId: string, options?: FlowSelectorOptions): FlowInstance;
     wire(plugName: string): WireInstance;
+    cache(cacheName: string): CacheInstance;
+    listMappings(params: {
+        resourceId: string;
+        limit?: number;
+        offset?: number;
+        search?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        page: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+            prevOffset: number;
+            nextOffset: number;
+            total: number;
+        };
+    }>;
+    lookupMapping(params: {
+        resourceId: string;
+        connectValue: string | string[];
+    } | {
+        resourceId: string;
+        plugName: string;
+        ref: string;
+    }): Promise<Record<string, unknown> | null>;
+    upsertMapping(mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<Record<string, unknown>>;
+    updateMapping(id: string, mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<Record<string, unknown>>;
+    deleteMapping(id: string): Promise<void>;
     getVars(plugName: string): Promise<Record<string, string>>;
     setVars(plugName: string, vars: Record<string, string>): Promise<void>;
     clearVars(plugName: string): Promise<void>;
@@ -472,4 +696,4 @@ interface NextJsRouteHandlers {
 }
 declare function toNextJsHandler(factoryHandler: KhotanHandler): NextJsRouteHandlers;
 
-export { type CatchRegistration, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PlugRegistration, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, drizzleAdapter, khotan, sendUpdate, toNextJsHandler };
+export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanAuthorize, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, deriveCliToken, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };