khotan-data 0.0.1 → 0.1.0

package/dist/plug-client.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+// src/plug-client.ts
+function defineContract(contract) {
+  return contract;
+}
+function isPlugError(err) {
+  return err instanceof Error && "status" in err && typeof err.status === "number" && "body" in err;
+}
+function parseBody(body) {
+  if (typeof body === "string") {
+    try {
+      return JSON.parse(body);
+    } catch {
+      return body;
+    }
+  }
+  return body;
+}
+function interpolatePath(path, params) {
+  return path.replace(/:([^/]+)/g, (_, key) => {
+    const value = params[key];
+    if (value === void 0) {
+      throw new Error(`Missing path parameter: "${key}"`);
+    }
+    return encodeURIComponent(value);
+  });
+}
+function createPlugClient(contract, plug, options) {
+  const globalValidateResponse = options?.validateResponse ?? true;
+  function buildClient(router) {
+    const client = {};
+    for (const [key, value] of Object.entries(router)) {
+      const route = value;
+      if ("method" in route && "path" in route) {
+        client[key] = async (input) => {
+          const def = route;
+          const params = input?.["params"] ?? {};
+          const query = input?.["query"];
+          const body = input?.["body"];
+          const headers = input?.["headers"];
+          const shouldValidateResponse = input?.["validateResponse"] ?? globalValidateResponse;
+          if (def.pathParams) {
+            def.pathParams.parse(params);
+          }
+          if (def.query && query !== void 0) {
+            def.query.parse(query);
+          }
+          if (def.body && body !== void 0) {
+            def.body.parse(body);
+          }
+          const interpolatedPath = interpolatePath(def.path, params);
+          const responses = def.responses;
+          try {
+            const responseBody = await plug.request(
+              def.method,
+              interpolatedPath,
+              {
+                ...query !== void 0 ? { params: query } : {},
+                ...body !== void 0 ? { body } : {},
+                ...headers !== void 0 ? { headers } : {}
+              }
+            );
+            const status = 200;
+            if (!responses[status]) {
+              return { status, body: responseBody };
+            }
+            if (shouldValidateResponse) {
+              const validated = responses[status].parse(responseBody);
+              return { status, body: validated };
+            }
+            return { status, body: responseBody };
+          } catch (err) {
+            if (!isPlugError(err)) throw err;
+            const status = err.status;
+            if (responses[status]) {
+              const parsed = parseBody(err.body);
+              if (shouldValidateResponse) {
+                const validated = responses[status].parse(parsed);
+                return { status, body: validated };
+              }
+              return { status, body: parsed };
+            }
+            throw err;
+          }
+        };
+      } else {
+        client[key] = buildClient(route);
+      }
+    }
+    return client;
+  }
+  return buildClient(contract);
+}
+
+exports.createPlugClient = createPlugClient;
+exports.defineContract = defineContract;
+//# sourceMappingURL=plug-client.cjs.map
+//# sourceMappingURL=plug-client.cjs.map

package/dist/plug-client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plug-client.ts"],"names":[],"mappings":"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","file":"plug-client.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// Schema interface — works with zod v3, v4, or any validator with .parse()\n// ---------------------------------------------------------------------------\n\nexport interface Schema<TOutput = unknown, TInput = unknown> {\n  parse(data: unknown): TOutput;\n  _input?: TInput;\n  _output?: TOutput;\n}\n\n// ---------------------------------------------------------------------------\n// Contract types\n// ---------------------------------------------------------------------------\n\nexport interface RouteDefinition {\n  method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  path: string;\n  query?: Schema;\n  body?: Schema;\n  pathParams?: Schema;\n  responses: Record<number, Schema>;\n}\n\nexport interface ContractRouter {\n  [key: string]: RouteDefinition | ContractRouter;\n}\n\n// ---------------------------------------------------------------------------\n// Type-level utilities\n// ---------------------------------------------------------------------------\n\ntype SchemaInput<T> = T extends Schema<unknown, infer I> ? I : never;\ntype SchemaOutput<T> = T extends Schema<infer O> ? O : never;\n\ntype PathParams<T extends string> =\n  T extends `${string}:${infer Param}/${infer Rest}`\n    ? Record<Param | keyof PathParams<Rest>, string>\n    : T extends `${string}:${infer Param}`\n      ? Record<Param, string>\n      : never;\n\ntype HasKeys<T> = keyof T extends never ? false : true;\n\ntype EndpointInput<TRoute extends RouteDefinition> = (HasKeys<\n  PathParams<TRoute[\"path\"]>\n> extends true\n  ? { params: PathParams<TRoute[\"path\"]> }\n  : { params?: never }) &\n  (TRoute extends { query: Schema }\n    ? { query: SchemaInput<TRoute[\"query\"]> }\n    : { query?: never }) &\n  (TRoute extends { body: Schema }\n    ? { body: SchemaInput<TRoute[\"body\"]> }\n    : { body?: never }) & {\n    headers?: Record<string, string>;\n    validateResponse?: boolean;\n  };\n\ntype ResponseSchemas<TRoute extends RouteDefinition> = {\n  [K in keyof TRoute[\"responses\"]]: K extends number\n    ? { status: K; body: SchemaOutput<TRoute[\"responses\"][K]> }\n    : never;\n}[keyof TRoute[\"responses\"]];\n\ntype PlugClient<T extends ContractRouter> = {\n  [K in keyof T]: T[K] extends RouteDefinition\n    ? HasKeys<PathParams<T[K][\"path\"]>> extends true\n      ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n      : T[K] extends { query: Schema }\n        ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n        : T[K] extends { body: Schema }\n          ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n          : (input?: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n    : T[K] extends ContractRouter\n      ? PlugClient<T[K]>\n      : never;\n};\n\n// ---------------------------------------------------------------------------\n// defineContract — type-narrowing identity function\n// ---------------------------------------------------------------------------\n\nexport function defineContract<const T extends ContractRouter>(contract: T): T {\n  return contract;\n}\n\n// ---------------------------------------------------------------------------\n// PlugLike interface\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal interface expected from a Plug instance.\n * Matches the scaffolded Plug class's public API.\n */\nexport interface PlugLike {\n  request<T>(\n    method: string,\n    path: string,\n    options?: {\n      params?: Record<string, unknown>;\n      body?: unknown;\n      headers?: Record<string, string>;\n    },\n  ): Promise<T>;\n}\n\nexport interface PlugClientOptions {\n  validateResponse?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// PlugError detection — works without importing the user's PlugError class\n// ---------------------------------------------------------------------------\n\ninterface PlugErrorLike {\n  name: string;\n  status: number;\n  body: unknown;\n}\n\nfunction isPlugError(err: unknown): err is PlugErrorLike {\n  return (\n    err instanceof Error &&\n    \"status\" in err &&\n    typeof (err as unknown as PlugErrorLike).status === \"number\" &&\n    \"body\" in err\n  );\n}\n\nfunction parseBody(body: unknown): unknown {\n  if (typeof body === \"string\") {\n    try {\n      return JSON.parse(body);\n    } catch {\n      return body;\n    }\n  }\n  return body;\n}\n\n// ---------------------------------------------------------------------------\n// Path interpolation\n// ---------------------------------------------------------------------------\n\nfunction interpolatePath(path: string, params: Record<string, string>): string {\n  return path.replace(/:([^/]+)/g, (_, key: string) => {\n    const value = params[key];\n    if (value === undefined) {\n      throw new Error(`Missing path parameter: \"${key}\"`);\n    }\n    return encodeURIComponent(value);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// createPlugClient\n// ---------------------------------------------------------------------------\n\nexport function createPlugClient<T extends ContractRouter>(\n  contract: T,\n  plug: PlugLike,\n  options?: PlugClientOptions,\n): PlugClient<T> {\n  const globalValidateResponse = options?.validateResponse ?? true;\n\n  function buildClient(router: ContractRouter): Record<string, unknown> {\n    const client: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(router)) {\n      const route = value;\n\n      if (\"method\" in route && \"path\" in route) {\n        client[key] = async (input?: Record<string, unknown>) => {\n          const def = route as RouteDefinition;\n          const params = (input?.[\"params\"] ?? {}) as Record<string, string>;\n          const query = input?.[\"query\"] as Record<string, unknown> | undefined;\n          const body = input?.[\"body\"];\n          const headers = input?.[\"headers\"] as\n            | Record<string, string>\n            | undefined;\n          const shouldValidateResponse =\n            (input?.[\"validateResponse\"] as boolean | undefined) ??\n            globalValidateResponse;\n\n          if (def.pathParams) {\n            def.pathParams.parse(params);\n          }\n          if (def.query && query !== undefined) {\n            def.query.parse(query);\n          }\n          if (def.body && body !== undefined) {\n            def.body.parse(body);\n          }\n\n          const interpolatedPath = interpolatePath(def.path, params);\n          const responses = def.responses;\n\n          try {\n            const responseBody = await plug.request<unknown>(\n              def.method,\n              interpolatedPath,\n              {\n                ...(query !== undefined ? { params: query } : {}),\n                ...(body !== undefined ? { body } : {}),\n                ...(headers !== undefined ? { headers } : {}),\n              },\n            );\n\n            const status = 200;\n            if (!responses[status]) {\n              return { status, body: responseBody };\n            }\n\n            if (shouldValidateResponse) {\n              const validated = responses[status].parse(responseBody);\n              return { status, body: validated };\n            }\n\n            return { status, body: responseBody };\n          } catch (err) {\n            if (!isPlugError(err)) throw err;\n\n            const status = err.status;\n            if (responses[status]) {\n              const parsed = parseBody(err.body);\n              if (shouldValidateResponse) {\n                const validated = responses[status].parse(parsed);\n                return { status, body: validated };\n              }\n              return { status, body: parsed };\n            }\n\n            throw err;\n          }\n        };\n      } else {\n        client[key] = buildClient(route);\n      }\n    }\n\n    return client;\n  }\n\n  return buildClient(contract) as PlugClient<T>;\n}\n"]}

package/dist/plug-client.d.cts

@@ -0,0 +1,71 @@
+interface Schema<TOutput = unknown, TInput = unknown> {
+    parse(data: unknown): TOutput;
+    _input?: TInput;
+    _output?: TOutput;
+}
+interface RouteDefinition {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Schema;
+    body?: Schema;
+    pathParams?: Schema;
+    responses: Record<number, Schema>;
+}
+interface ContractRouter {
+    [key: string]: RouteDefinition | ContractRouter;
+}
+type SchemaInput<T> = T extends Schema<unknown, infer I> ? I : never;
+type SchemaOutput<T> = T extends Schema<infer O> ? O : never;
+type PathParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? Record<Param | keyof PathParams<Rest>, string> : T extends `${string}:${infer Param}` ? Record<Param, string> : never;
+type HasKeys<T> = keyof T extends never ? false : true;
+type EndpointInput<TRoute extends RouteDefinition> = (HasKeys<PathParams<TRoute["path"]>> extends true ? {
+    params: PathParams<TRoute["path"]>;
+} : {
+    params?: never;
+}) & (TRoute extends {
+    query: Schema;
+} ? {
+    query: SchemaInput<TRoute["query"]>;
+} : {
+    query?: never;
+}) & (TRoute extends {
+    body: Schema;
+} ? {
+    body: SchemaInput<TRoute["body"]>;
+} : {
+    body?: never;
+}) & {
+    headers?: Record<string, string>;
+    validateResponse?: boolean;
+};
+type ResponseSchemas<TRoute extends RouteDefinition> = {
+    [K in keyof TRoute["responses"]]: K extends number ? {
+        status: K;
+        body: SchemaOutput<TRoute["responses"][K]>;
+    } : never;
+}[keyof TRoute["responses"]];
+type PlugClient<T extends ContractRouter> = {
+    [K in keyof T]: T[K] extends RouteDefinition ? HasKeys<PathParams<T[K]["path"]>> extends true ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends {
+        query: Schema;
+    } ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends {
+        body: Schema;
+    } ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : (input?: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends ContractRouter ? PlugClient<T[K]> : never;
+};
+declare function defineContract<const T extends ContractRouter>(contract: T): T;
+/**
+ * Minimal interface expected from a Plug instance.
+ * Matches the scaffolded Plug class's public API.
+ */
+interface PlugLike {
+    request<T>(method: string, path: string, options?: {
+        params?: Record<string, unknown>;
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+interface PlugClientOptions {
+    validateResponse?: boolean;
+}
+declare function createPlugClient<T extends ContractRouter>(contract: T, plug: PlugLike, options?: PlugClientOptions): PlugClient<T>;
+
+export { type ContractRouter, type PlugClientOptions, type PlugLike, type RouteDefinition, type Schema, createPlugClient, defineContract };

package/dist/plug-client.d.ts

@@ -0,0 +1,71 @@
+interface Schema<TOutput = unknown, TInput = unknown> {
+    parse(data: unknown): TOutput;
+    _input?: TInput;
+    _output?: TOutput;
+}
+interface RouteDefinition {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Schema;
+    body?: Schema;
+    pathParams?: Schema;
+    responses: Record<number, Schema>;
+}
+interface ContractRouter {
+    [key: string]: RouteDefinition | ContractRouter;
+}
+type SchemaInput<T> = T extends Schema<unknown, infer I> ? I : never;
+type SchemaOutput<T> = T extends Schema<infer O> ? O : never;
+type PathParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? Record<Param | keyof PathParams<Rest>, string> : T extends `${string}:${infer Param}` ? Record<Param, string> : never;
+type HasKeys<T> = keyof T extends never ? false : true;
+type EndpointInput<TRoute extends RouteDefinition> = (HasKeys<PathParams<TRoute["path"]>> extends true ? {
+    params: PathParams<TRoute["path"]>;
+} : {
+    params?: never;
+}) & (TRoute extends {
+    query: Schema;
+} ? {
+    query: SchemaInput<TRoute["query"]>;
+} : {
+    query?: never;
+}) & (TRoute extends {
+    body: Schema;
+} ? {
+    body: SchemaInput<TRoute["body"]>;
+} : {
+    body?: never;
+}) & {
+    headers?: Record<string, string>;
+    validateResponse?: boolean;
+};
+type ResponseSchemas<TRoute extends RouteDefinition> = {
+    [K in keyof TRoute["responses"]]: K extends number ? {
+        status: K;
+        body: SchemaOutput<TRoute["responses"][K]>;
+    } : never;
+}[keyof TRoute["responses"]];
+type PlugClient<T extends ContractRouter> = {
+    [K in keyof T]: T[K] extends RouteDefinition ? HasKeys<PathParams<T[K]["path"]>> extends true ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends {
+        query: Schema;
+    } ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends {
+        body: Schema;
+    } ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : (input?: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>> : T[K] extends ContractRouter ? PlugClient<T[K]> : never;
+};
+declare function defineContract<const T extends ContractRouter>(contract: T): T;
+/**
+ * Minimal interface expected from a Plug instance.
+ * Matches the scaffolded Plug class's public API.
+ */
+interface PlugLike {
+    request<T>(method: string, path: string, options?: {
+        params?: Record<string, unknown>;
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+interface PlugClientOptions {
+    validateResponse?: boolean;
+}
+declare function createPlugClient<T extends ContractRouter>(contract: T, plug: PlugLike, options?: PlugClientOptions): PlugClient<T>;
+
+export { type ContractRouter, type PlugClientOptions, type PlugLike, type RouteDefinition, type Schema, createPlugClient, defineContract };

package/dist/plug-client.js

@@ -0,0 +1,96 @@
+// src/plug-client.ts
+function defineContract(contract) {
+  return contract;
+}
+function isPlugError(err) {
+  return err instanceof Error && "status" in err && typeof err.status === "number" && "body" in err;
+}
+function parseBody(body) {
+  if (typeof body === "string") {
+    try {
+      return JSON.parse(body);
+    } catch {
+      return body;
+    }
+  }
+  return body;
+}
+function interpolatePath(path, params) {
+  return path.replace(/:([^/]+)/g, (_, key) => {
+    const value = params[key];
+    if (value === void 0) {
+      throw new Error(`Missing path parameter: "${key}"`);
+    }
+    return encodeURIComponent(value);
+  });
+}
+function createPlugClient(contract, plug, options) {
+  const globalValidateResponse = options?.validateResponse ?? true;
+  function buildClient(router) {
+    const client = {};
+    for (const [key, value] of Object.entries(router)) {
+      const route = value;
+      if ("method" in route && "path" in route) {
+        client[key] = async (input) => {
+          const def = route;
+          const params = input?.["params"] ?? {};
+          const query = input?.["query"];
+          const body = input?.["body"];
+          const headers = input?.["headers"];
+          const shouldValidateResponse = input?.["validateResponse"] ?? globalValidateResponse;
+          if (def.pathParams) {
+            def.pathParams.parse(params);
+          }
+          if (def.query && query !== void 0) {
+            def.query.parse(query);
+          }
+          if (def.body && body !== void 0) {
+            def.body.parse(body);
+          }
+          const interpolatedPath = interpolatePath(def.path, params);
+          const responses = def.responses;
+          try {
+            const responseBody = await plug.request(
+              def.method,
+              interpolatedPath,
+              {
+                ...query !== void 0 ? { params: query } : {},
+                ...body !== void 0 ? { body } : {},
+                ...headers !== void 0 ? { headers } : {}
+              }
+            );
+            const status = 200;
+            if (!responses[status]) {
+              return { status, body: responseBody };
+            }
+            if (shouldValidateResponse) {
+              const validated = responses[status].parse(responseBody);
+              return { status, body: validated };
+            }
+            return { status, body: responseBody };
+          } catch (err) {
+            if (!isPlugError(err)) throw err;
+            const status = err.status;
+            if (responses[status]) {
+              const parsed = parseBody(err.body);
+              if (shouldValidateResponse) {
+                const validated = responses[status].parse(parsed);
+                return { status, body: validated };
+              }
+              return { status, body: parsed };
+            }
+            throw err;
+          }
+        };
+      } else {
+        client[key] = buildClient(route);
+      }
+    }
+    return client;
+  }
+  return buildClient(contract);
+}
+
+export { createPlugClient, defineContract };
+//# sourceMappingURL=plug-client.js.map
+//# sourceMappingURL=plug-client.js.map

package/dist/plug-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plug-client.ts"],"names":[],"mappings":"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","file":"plug-client.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Schema interface — works with zod v3, v4, or any validator with .parse()\n// ---------------------------------------------------------------------------\n\nexport interface Schema<TOutput = unknown, TInput = unknown> {\n  parse(data: unknown): TOutput;\n  _input?: TInput;\n  _output?: TOutput;\n}\n\n// ---------------------------------------------------------------------------\n// Contract types\n// ---------------------------------------------------------------------------\n\nexport interface RouteDefinition {\n  method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  path: string;\n  query?: Schema;\n  body?: Schema;\n  pathParams?: Schema;\n  responses: Record<number, Schema>;\n}\n\nexport interface ContractRouter {\n  [key: string]: RouteDefinition | ContractRouter;\n}\n\n// ---------------------------------------------------------------------------\n// Type-level utilities\n// ---------------------------------------------------------------------------\n\ntype SchemaInput<T> = T extends Schema<unknown, infer I> ? I : never;\ntype SchemaOutput<T> = T extends Schema<infer O> ? O : never;\n\ntype PathParams<T extends string> =\n  T extends `${string}:${infer Param}/${infer Rest}`\n    ? Record<Param | keyof PathParams<Rest>, string>\n    : T extends `${string}:${infer Param}`\n      ? Record<Param, string>\n      : never;\n\ntype HasKeys<T> = keyof T extends never ? false : true;\n\ntype EndpointInput<TRoute extends RouteDefinition> = (HasKeys<\n  PathParams<TRoute[\"path\"]>\n> extends true\n  ? { params: PathParams<TRoute[\"path\"]> }\n  : { params?: never }) &\n  (TRoute extends { query: Schema }\n    ? { query: SchemaInput<TRoute[\"query\"]> }\n    : { query?: never }) &\n  (TRoute extends { body: Schema }\n    ? { body: SchemaInput<TRoute[\"body\"]> }\n    : { body?: never }) & {\n    headers?: Record<string, string>;\n    validateResponse?: boolean;\n  };\n\ntype ResponseSchemas<TRoute extends RouteDefinition> = {\n  [K in keyof TRoute[\"responses\"]]: K extends number\n    ? { status: K; body: SchemaOutput<TRoute[\"responses\"][K]> }\n    : never;\n}[keyof TRoute[\"responses\"]];\n\ntype PlugClient<T extends ContractRouter> = {\n  [K in keyof T]: T[K] extends RouteDefinition\n    ? HasKeys<PathParams<T[K][\"path\"]>> extends true\n      ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n      : T[K] extends { query: Schema }\n        ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n        : T[K] extends { body: Schema }\n          ? (input: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n          : (input?: EndpointInput<T[K]>) => Promise<ResponseSchemas<T[K]>>\n    : T[K] extends ContractRouter\n      ? PlugClient<T[K]>\n      : never;\n};\n\n// ---------------------------------------------------------------------------\n// defineContract — type-narrowing identity function\n// ---------------------------------------------------------------------------\n\nexport function defineContract<const T extends ContractRouter>(contract: T): T {\n  return contract;\n}\n\n// ---------------------------------------------------------------------------\n// PlugLike interface\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal interface expected from a Plug instance.\n * Matches the scaffolded Plug class's public API.\n */\nexport interface PlugLike {\n  request<T>(\n    method: string,\n    path: string,\n    options?: {\n      params?: Record<string, unknown>;\n      body?: unknown;\n      headers?: Record<string, string>;\n    },\n  ): Promise<T>;\n}\n\nexport interface PlugClientOptions {\n  validateResponse?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// PlugError detection — works without importing the user's PlugError class\n// ---------------------------------------------------------------------------\n\ninterface PlugErrorLike {\n  name: string;\n  status: number;\n  body: unknown;\n}\n\nfunction isPlugError(err: unknown): err is PlugErrorLike {\n  return (\n    err instanceof Error &&\n    \"status\" in err &&\n    typeof (err as unknown as PlugErrorLike).status === \"number\" &&\n    \"body\" in err\n  );\n}\n\nfunction parseBody(body: unknown): unknown {\n  if (typeof body === \"string\") {\n    try {\n      return JSON.parse(body);\n    } catch {\n      return body;\n    }\n  }\n  return body;\n}\n\n// ---------------------------------------------------------------------------\n// Path interpolation\n// ---------------------------------------------------------------------------\n\nfunction interpolatePath(path: string, params: Record<string, string>): string {\n  return path.replace(/:([^/]+)/g, (_, key: string) => {\n    const value = params[key];\n    if (value === undefined) {\n      throw new Error(`Missing path parameter: \"${key}\"`);\n    }\n    return encodeURIComponent(value);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// createPlugClient\n// ---------------------------------------------------------------------------\n\nexport function createPlugClient<T extends ContractRouter>(\n  contract: T,\n  plug: PlugLike,\n  options?: PlugClientOptions,\n): PlugClient<T> {\n  const globalValidateResponse = options?.validateResponse ?? true;\n\n  function buildClient(router: ContractRouter): Record<string, unknown> {\n    const client: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(router)) {\n      const route = value;\n\n      if (\"method\" in route && \"path\" in route) {\n        client[key] = async (input?: Record<string, unknown>) => {\n          const def = route as RouteDefinition;\n          const params = (input?.[\"params\"] ?? {}) as Record<string, string>;\n          const query = input?.[\"query\"] as Record<string, unknown> | undefined;\n          const body = input?.[\"body\"];\n          const headers = input?.[\"headers\"] as\n            | Record<string, string>\n            | undefined;\n          const shouldValidateResponse =\n            (input?.[\"validateResponse\"] as boolean | undefined) ??\n            globalValidateResponse;\n\n          if (def.pathParams) {\n            def.pathParams.parse(params);\n          }\n          if (def.query && query !== undefined) {\n            def.query.parse(query);\n          }\n          if (def.body && body !== undefined) {\n            def.body.parse(body);\n          }\n\n          const interpolatedPath = interpolatePath(def.path, params);\n          const responses = def.responses;\n\n          try {\n            const responseBody = await plug.request<unknown>(\n              def.method,\n              interpolatedPath,\n              {\n                ...(query !== undefined ? { params: query } : {}),\n                ...(body !== undefined ? { body } : {}),\n                ...(headers !== undefined ? { headers } : {}),\n              },\n            );\n\n            const status = 200;\n            if (!responses[status]) {\n              return { status, body: responseBody };\n            }\n\n            if (shouldValidateResponse) {\n              const validated = responses[status].parse(responseBody);\n              return { status, body: validated };\n            }\n\n            return { status, body: responseBody };\n          } catch (err) {\n            if (!isPlugError(err)) throw err;\n\n            const status = err.status;\n            if (responses[status]) {\n              const parsed = parseBody(err.body);\n              if (shouldValidateResponse) {\n                const validated = responses[status].parse(parsed);\n                return { status, body: validated };\n              }\n              return { status, body: parsed };\n            }\n\n            throw err;\n          }\n        };\n      } else {\n        client[key] = buildClient(route);\n      }\n    }\n\n    return client;\n  }\n\n  return buildClient(contract) as PlugClient<T>;\n}\n"]}

package/dist/templates/agent-skill.md

@@ -0,0 +1,73 @@
+---
+name: khotan-probe
+description: >
+  Inspect and debug khotan plugs via the CLI. Prefer `khotan plug`
+  (legacy alias: `khotan probe`). Use when verifying API
+  response shapes against typed endpoint definitions, debugging type
+  mismatches between declared schemas and actual responses, or exploring
+  available plugs and their endpoints.
+---
+
+Inspect and debug khotan plugs via the CLI. Prefer `khotan plug` (legacy alias: `khotan probe`). Use when verifying API response shapes against typed endpoint definitions, debugging type mismatches between declared schemas and actual responses, or exploring available plugs and their endpoints.
+
+**Requires**: A running dev server with `KHOTAN_DEBUG=1` set.
+
+## Commands
+
+### List all plugs
+```bash
+npx khotan plug --list
+```
+Returns: `{ ok, plugs: [{ name, baseUrl, authType, varsConfigured }] }`
+
+### Show plug info and endpoints
+```bash
+npx khotan plug <plugName> --info
+```
+Returns: `{ ok, plug: { name, baseUrl, authType, vars, endpoints } }`
+
+### Fire a request through a plug
+```bash
+npx khotan plug <plugName> GET /products
+npx khotan plug <plugName> POST /subscriptions --body '{"url":"https://example.com"}'
+npx khotan plug <plugName> GET /products --params '{"limit":"10"}'
+npx khotan plug <plugName> GET /products --headers '{"X-Custom":"value"}'
+```
+Returns: `{ ok, request, response: { status, timing, size, body }, matchedEndpoint }`
+
+### Fire via named endpoint
+```bash
+npx khotan plug <plugName> --endpoint listProducts
+```
+Resolves method and path from the endpoint definition automatically.
+
+### Compare response against schema
+```bash
+npx khotan plug <plugName> --endpoint listProducts --compare
+```
+Returns: `{ ..., comparison: { match, expected, actual, mismatches } }`
+
+Each mismatch has `{ path, issue, note }` where issue is `missing`, `extra`, or `type_mismatch` and path uses JSONPath notation (e.g. `$.items[].sku`).
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--port <n>` | Dev server port (default: from .env.local → .env → 3000) |
+| `--base-path <p>` | API base path (default: `/api/khotan`) |
+| `--list` | List registered plugs |
+| `--info` | Show plug metadata |
+| `--endpoint <name>` | Fire using named endpoint |
+| `--compare` | Diff response against schema |
+| `--body <json>` | Request body |
+| `--params <json>` | Query params |
+| `--headers <json>` | Extra headers |
+
+## Workflow
+
+1. **Discover**: `--list` to find plugs, `--info` to see endpoints
+2. **Probe**: Fire a request via endpoint name or raw method/path
+3. **Compare**: Add `--compare` to check response shape against Zod schema
+4. **Fix**: If mismatches found, update the endpoint's response schema or adjust API expectations
+
+All output is JSON on stdout — parse with standard JSON tools.

package/dist/templates/agents.md

@@ -0,0 +1,41 @@
+# khotan-data
+
+Production-grade data flow, ETL, and webhook components for Next.js + Drizzle + Postgres.
+
+## Skills
+
+| Skill | When to use |
+|-------|-------------|
+| [khotan-setup](skills/khotan-setup/SKILL.md) | Initializing khotan in a new project, adding the database schema, configuring the factory |
+| [khotan-plug](skills/khotan-plug/SKILL.md) | Connecting to a new API, defining endpoint contracts, configuring authentication |
+| [khotan-dashboard](skills/khotan-dashboard/SKILL.md) | Adding a management interface, configuring plug variables in the browser |
+| [khotan-webhook](skills/khotan-webhook/SKILL.md) | Receiving webhooks, registering callback URLs, processing incoming events |
+| [khotan-probe](skills/khotan-probe/SKILL.md) | Debugging plugs via CLI with `khotan plug` (legacy alias: `probe`) |
+
+## Quick Reference
+
+```bash
+npx khotan init              # Initialize project
+npx khotan add plug --yes    # Add HTTP client component
+npx khotan add hub --yes     # Add dashboard UI
+npx khotan generate          # Scaffold Drizzle schema
+npx khotan migrate           # Apply database migrations
+npx khotan plug --list       # Debug: list registered plugs
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `khotan.config.ts` | CLI config — sets outputDir |
+| `{outputDir}/khotan.ts` | Factory config — register plugs, resources, adapter |
+| `src/app/api/khotan/[...all]/route.ts` | Catch-all API route |
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `DATABASE_URL` | Postgres connection (Drizzle) |
+| `KHOTAN_SECRET` | AES-256-GCM key for encrypting plug variables |
+| `KHOTAN_DEBUG` | Enables debug routes and the `plug` CLI (`probe` alias) |
+| `KHOTAN_WEBHOOK_URL` | Public URL for webhook callbacks |

package/dist/templates/catch.example.ts

@@ -0,0 +1,36 @@
+// ============================================================================
+// Example: Catch
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// Copy this file, rename it for your webhook source/event, and register the
+// exported catch handler in {outputDir}/khotan.ts.
+// ============================================================================
+
+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,
+    });
+
+    // 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();
+}
+
+export const stripeInvoiceCatch = catchEvent({
+  name: "stripe-invoices",
+  events: ["invoice.paid"],
+  workflow: stripeInvoiceCatchWorkflow,
+});

package/dist/templates/catch.ts

@@ -0,0 +1,107 @@
+// ============================================================================
+// Catch — durable webhook event processing via Vercel Workflow
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file defines the catchEvent() builder and types. Create per-service
+// catch files (e.g. pollinate-catch.ts) using this builder to handle verified
+// webhook events with durable, retryable workflow steps.
+//
+// Catch workflows receive a CatchContext with the parsed event payload,
+// event type, and headers. Steps have full Node.js access — import your
+// own db, services, etc.
+// ============================================================================
+
+// ---------------------------------------------------------------------------
+// Context — serializable data passed to the workflow
+// ---------------------------------------------------------------------------
+
+export interface CatchContext {
+  /** 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>;
+  /** Khotan run ID created for this webhook handler execution */
+  khotanRunId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow type — the function signature your workflow must conform to
+// ---------------------------------------------------------------------------
+
+export type CatchWorkflow = (ctx: CatchContext) => Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Config — passed to the catchEvent() builder
+// ---------------------------------------------------------------------------
+
+export interface CatchConfig {
+  /** Unique name for this catch handler (used for DB tracking and Hub display) */
+  name: string;
+  /** Event types this catch should receive */
+  events?: string[];
+  /** Workflow function that processes the event */
+  workflow: CatchWorkflow;
+}
+
+// ---------------------------------------------------------------------------
+// Registration — returned by catchEvent(), consumed by factory config
+// ---------------------------------------------------------------------------
+
+export interface CatchRegistration {
+  type: "catch";
+  name: string;
+  events?: string[];
+  workflow: CatchWorkflow;
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+export function catchEvent(config: CatchConfig): CatchRegistration {
+  return {
+    type: "catch",
+    name: config.name,
+    events: config.events,
+    workflow: config.workflow,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Usage Example (create a file like webhooks/pollinate-catch.ts)
+// ---------------------------------------------------------------------------
+//
+// 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.
+//
+// async function pollinateCatchWorkflow(ctx: CatchContext) {
+//   "use workflow";
+//
+//   async function notifyOps() {
+//     "use step";
+//     console.log("Handled webhook", {
+//       eventType: ctx.eventType,
+//       khotanRunId: ctx.khotanRunId,
+//     });
+//   }
+//
+//   await notifyOps();
+// }
+//
+// export const pollinateCatch = catchEvent({
+//   name: "pollinate-orders",
+//   events: ["order.created"],
+//   workflow: pollinateCatchWorkflow,
+// });
+//
+// Then register in your khotan config:
+//
+// plugs: [{
+//   name: "pollinate",
+//   plug: pollinatePlug,
+//   wires: [pollinateWire],
+//   catches: [pollinateCatch],
+// }]