@openbkn/bkn-sdk 0.1.1 → 0.1.2

package/dist/cli.js

@@ -33,9 +33,10 @@ import {
   switchUser,
   toExitCode,
   use,
+  validateFixturePath,
   whoami,
   writePlatformConfig
-} from "./chunk-NC6DZ2AU.js";
+} from "./chunk-LH3ONZGQ.js";
 
 // src/cli.ts
 import { Command as Command17 } from "commander";
@@ -43,7 +44,7 @@ import { Command as Command17 } from "commander";
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.1",
+  version: "0.1.2",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
@@ -78,6 +79,7 @@ var package_default = {
     lint: "npm run check:deps && biome check . && tsc --noEmit",
     format: "biome format --write .",
     test: "vitest run",
+    "test:e2e:trace-business": "npm run build && node test/e2e/bkn-trace-business-interaction.mjs",
     "test:cover": "vitest run --coverage",
     ci: "npm run lint && npm test",
     prepublishOnly: "npm run ci && npm run build"
@@ -174,10 +176,15 @@ function renderOrgTree(nodes, prefix = "") {
 // src/utils/output.ts
 function printJson(value, opts = {}) {
   if (opts.json || opts.compact) {
-    process.stdout.write(`${JSON.stringify(value, null, opts.compact ? 0 : 2)}
+    const json = JSON.stringify(value === void 0 ? null : value, null, opts.compact ? 0 : 2);
+    process.stdout.write(`${json}
 `);
     return;
   }
+  if (value === void 0) {
+    process.stdout.write("(ok)\n");
+    return;
+  }
   const rows = toRows(value);
   if (rows) {
     const fullColumns = columnsOf(rows).filter((c) => rows.some((r) => stringifyCell(r[c]) !== ""));
@@ -322,14 +329,25 @@ function promptLine(query, hidden = false) {
 
 // src/commands/_shared.ts
 import { readFileSync } from "fs";
+function traceOptionsFrom(o) {
+  const conversationId = (typeof o.conversationId === "string" ? o.conversationId : void 0) ?? process.env.BKN_CONVERSATION_ID;
+  const interactionId = (typeof o.interactionId === "string" ? o.interactionId : void 0) ?? process.env.BKN_INTERACTION_ID;
+  if (!conversationId && !interactionId) return void 0;
+  return {
+    ...conversationId ? { conversationId } : {},
+    ...interactionId ? { interactionId } : {}
+  };
+}
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
+  const trace = traceOptionsFrom(o);
   return createClient({
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
     businessDomain: o.bizDomain,
-    insecure: o.insecure
+    insecure: o.insecure,
+    ...trace ? { trace } : {}
   });
 }
 function outputOptions(cmd) {
@@ -1349,9 +1367,6 @@ function bknCommand() {
       outputOptions(cmd)
     );
   });
-  objectType?.command("properties <kn-id> <ot-id>").description("Get an object type's calculated properties").action(async (knId, otId, _opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.objectTypeProperties(knId, otId), outputOptions(cmd));
-  });
   bkn.command("create <name>").description("Create an (empty) knowledge network").option("--branch <b>", "branch", "main").action(async (name, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.create({ name, branch: opts.branch }), outputOptions(cmd));
   });
@@ -1480,19 +1495,6 @@ function bknCommand() {
   sched.command("delete <kn-id> <schedule-ids>").description("Delete action schedule(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
   });
-  const job = bkn.command("job").description("Build jobs \u2014 list/get/tasks");
-  job.command("list <kn-id>").description("List jobs").action(async (knId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobs(knId), outputOptions(cmd));
-  });
-  job.command("get <kn-id> <job-id>").description("Get a job").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.job(knId, jobId), outputOptions(cmd));
-  });
-  job.command("tasks <kn-id> <job-id>").description("List a job's tasks").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobTasks(knId, jobId), outputOptions(cmd));
-  });
-  job.command("delete <kn-id> <job-ids>").description("Delete job(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobDelete(knId, ids), outputOptions(cmd));
-  });
   bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
     "--embedding-model <id>",
     "embedding model id for declared vector indexes (with --build)"
@@ -1584,12 +1586,14 @@ function callCommand() {
     []
   ).option("-v, --verbose", "print request line to stderr").action(async (url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
+    const trace = traceOptionsFrom(g);
     const ctx = resolveContext({
       baseUrl: g.baseUrl,
       token: g.token,
       user: g.user,
       businessDomain: g.bizDomain,
-      insecure: g.insecure
+      insecure: g.insecure,
+      ...trace ? { trace } : {}
     });
     const res = await rawCall(ctx, url, {
       method: opts.request,
@@ -1822,9 +1826,13 @@ function dataflowCommand() {
   cmd.command("list").description("List all dataflows").action(async (_opts, cmd2) => {
     printJson(await clientFrom(cmd2).dataflows.list(), outputOptions(cmd2));
   });
-  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").action(async (dagId, opts, cmd2) => {
+  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").option("--limit <n>", "page size (backend default 20)", int6).option("--page <n>", "page (0-based; backend default 0)", int6).action(async (dagId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).dataflows.runs(dagId, { since: opts.since }),
+      await clientFrom(cmd2).dataflows.runs(dagId, {
+        since: opts.since,
+        page: opts.page,
+        limit: opts.limit
+      }),
       outputOptions(cmd2)
     );
   });
@@ -1899,7 +1907,6 @@ var ROUTES = {
   }),
   "POST /api/bkn/instances": (c, _q, b) => c.kn.objectTypeQuery(str(b.knId), str(b.objectTypeId), b.body ?? {}),
   "POST /api/bkn/subgraph": (c, _q, b) => c.kn.subgraph(str(b.knId), b.body ?? b),
-  "POST /api/bkn/properties": (c, _q, b) => c.kn.objectTypeProperties(str(b.knId), str(b.objectTypeId)),
   "GET /api/vega/catalogs": (c) => c.vega.catalogs(),
   "GET /api/vega/catalog": (c, q) => c.vega.getCatalog(req(q, "catalogId")),
   "GET /api/vega/catalog-resources": (c, q) => c.vega.catalogResources(req(q, "catalogId"), q.get("category") ?? void 0),
@@ -2120,20 +2127,24 @@ function resourceCommand() {
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").action(async (opts, cmd2) => {
+  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").option("--limit <n>", "rows to scan before filtering", int9, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
-      datasourceId: opts.catalogId ?? opts.datasourceId
+      datasourceId: opts.catalogId ?? opts.datasourceId,
+      limit: opts.limit
     });
     printJson(data, outputOptions(cmd2));
   });
   cmd.command("get <id>").description("Get resource details").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.get(id), outputOptions(cmd2));
   });
-  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--need-total", "include total count").action(async (id, opts, cmd2) => {
+  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int9).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.query(id, {
       limit: opts.limit,
       offset: opts.offset,
+      pagingMode: opts.pagingMode,
+      keepAliveSec: opts.keepAliveSec,
+      cursor: opts.cursor,
       needTotal: opts.needTotal
     });
     printJson(data, outputOptions(cmd2));
@@ -2281,8 +2292,15 @@ function toolboxCommand() {
 }
 function toolCommand() {
   const cmd = new Command14("tool").description("Tools inside a toolbox");
-  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).toolboxes.tools(opts.toolbox), outputOptions(cmd2));
+  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int11).option("--page <n>", "page (1-based; backend default 1)", int11).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
+        page: opts.page,
+        pageSize: opts.limit,
+        all: opts.all
+      }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("enable <tool-ids...>").description("Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
     printJson(
@@ -2420,6 +2438,33 @@ function traceCommand() {
   const cmd = new Command15("trace").description(
     "BKN Trace \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
   );
+  cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.graph(traceId), outputOptions(cmd2));
+  });
+  cmd.command("evidence-chain [trace-id]").description("Fetch BKN Trace evidence chain by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.evidenceChain(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("business-graph [trace-id]").description("Fetch BKN Trace business semantic graph by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.businessGraph(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("snapshot-preview [trace-id]").description("Fetch metadata-only evidence snapshot preview by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.snapshotPreview(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
   cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
@@ -2471,8 +2516,26 @@ function traceCommand() {
     printJson(result, outputOptions(cmd2));
     if (!result.valid) process.exitCode = 1;
   });
+  cmd.command("validate-fixture <path>").description("Validate BKN Trace 1.0/2.0/2.1 fixture JSON files").action(async (path, _opts, cmd2) => {
+    const result = validateFixturePath(path);
+    printJson(result, outputOptions(cmd2));
+    if (!result.ok) process.exitCode = 1;
+  });
+  const evidence = cmd.command("evidence").description("Submit BKN Trace 2.x business evidence events");
+  evidence.command("emit <file>").description("Submit a BKN Trace 2.0/2.1 event batch JSON file").action(async (file, _opts, cmd2) => {
+    const body = JSON.parse(readFileSync5(file, "utf8"));
+    printJson(await clientFrom(cmd2).trace.emitEvidenceEvents(body), outputOptions(cmd2));
+  });
   return group(cmd, "TRACE AI");
 }
+function traceScope(traceId, requestId) {
+  if (traceId && requestId) {
+    throw new InputError("Provide either trace id or --request-id, not both.");
+  }
+  if (requestId) return { requestId };
+  if (traceId) return traceId;
+  throw new InputError("Provide a trace id or --request-id.");
+}
 
 // src/commands/vega.ts
 import { Command as Command16 } from "commander";
@@ -2511,8 +2574,11 @@ function vegaCommand() {
   catalog.command("get <id>").description("Get a catalog by id").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.getCatalog(id), outputOptions(cmd));
   });
-  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").action(async (id, opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.catalogResources(id, opts.category), outputOptions(cmd));
+  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (backend default 20, max 1000; -1 = all)", int12).option("--offset <n>", "page offset", int12, 0).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
+      outputOptions(cmd)
+    );
   });
   catalog.command("health <ids...>").description("Health-status for one or more catalogs").action(async (ids, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealth(ids), outputOptions(cmd));
@@ -2581,12 +2647,12 @@ function vegaCommand() {
   connector.command("get <type>").description("Get a connector type").action(async (type, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.connectorType(type), outputOptions(cmd));
   });
-  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").requiredOption("--resource-type <type>", "source type (mysql | postgresql | opensearch | \u2026)").option("--query-type <type>", "query mode: standard | stream").option(
+  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").option(
     "--query <sql>",
     "SQL string; reference a resource with a {{<resource-id>}} placeholder"
-  ).option("--stream-size <n>", "streaming batch size (100\u201310000)", int12).option("--query-timeout <s>", "query timeout in seconds (1\u20133600)", int12).option(
+  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int12).option("--offset <n>", "first-page offset", int12).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int12).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int12).option(
     "-d, --data <json>",
-    "full request body as JSON (advanced; wins over --query/--resource-type)"
+    "full request body as JSON (advanced; wins over individual query flags)"
   ).action(async (opts, cmd) => {
     let body;
     if (opts.data) {
@@ -2595,16 +2661,34 @@ function vegaCommand() {
       } catch {
         throw new InputError("--data must be valid JSON");
       }
+    } else if (opts.cursor) {
+      if (opts.query || opts.inputDialect || opts.pagingMode || opts.limit !== void 0 || opts.offset !== void 0 || opts.keepAliveSec !== void 0 || opts.queryTimeoutSec !== void 0) {
+        throw new InputError("--cursor cannot be combined with initial-query options");
+      }
+      body = {
+        paging: { cursor: opts.cursor },
+        ...opts.needTotal ? { need_total: true } : {}
+      };
     } else {
       if (!opts.query) {
-        throw new InputError("Provide --query (and optionally --resource-type), or --data.");
+        throw new InputError("Provide --query, --cursor, or --data.");
+      }
+      if (opts.pagingMode === "cursor" && opts.limit === void 0) {
+        throw new InputError("--limit is required when --paging-mode cursor");
       }
+      const paging = {
+        ...opts.pagingMode ? { mode: opts.pagingMode } : {},
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts.offset !== void 0 ? { offset: opts.offset } : {},
+        ...opts.keepAliveSec !== void 0 ? { keep_alive_sec: opts.keepAliveSec } : {}
+      };
       body = {
         query: opts.query,
-        resource_type: opts.resourceType,
-        ...opts.queryType ? { query_type: opts.queryType } : {},
-        ...opts.streamSize !== void 0 ? { stream_size: opts.streamSize } : {},
-        ...opts.queryTimeout !== void 0 ? { query_timeout: opts.queryTimeout } : {}
+        query_format: "sql",
+        ...opts.inputDialect ? { input_dialect: opts.inputDialect } : {},
+        ...Object.keys(paging).length ? { paging } : {},
+        ...opts.needTotal ? { need_total: true } : {},
+        ...opts.queryTimeoutSec !== void 0 ? { query_timeout_sec: opts.queryTimeoutSec } : {}
       };
     }
     printJson(await clientFrom(cmd).vega.sql(body), outputOptions(cmd));
@@ -2708,7 +2792,7 @@ function vegaCommand() {
 
 // src/cli.ts
 var program = new Command17();
-program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
+program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
 program.addCommand(authCommand());
 program.addCommand(callCommand());
 program.addCommand(configCommand());