@kweaver-ai/kweaver-sdk 0.5.0 → 0.5.2

package/dist/commands/bkn-query.d.ts

@@ -0,0 +1,14 @@
+export declare function runKnSubgraphCommand(args: string[]): Promise<number>;
+export declare function runKnActionExecutionCommand(args: string[]): Promise<number>;
+export declare function runKnActionLogCommand(args: string[]): Promise<number>;
+export declare function parseKnSearchArgs(args: string[]): {
+    knId: string;
+    query: string;
+    maxConcepts: number;
+    mode: string;
+    pretty: boolean;
+    businessDomain: string;
+};
+export declare function runKnSearchCommand(args: string[]): Promise<number>;
+export declare function runKnRelationTypePathsCommand(args: string[]): Promise<number>;
+export declare function runKnResourcesCommand(args: string[]): Promise<number>;

package/dist/commands/bkn-query.js

@@ -0,0 +1,370 @@
+import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { subgraph, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "../api/ontology-query.js";
+import { queryRelationTypePaths, listBknResources } from "../api/bkn-backend.js";
+import { semanticSearch } from "../api/semantic-search.js";
+import { formatCallOutput } from "./call.js";
+import { resolveBusinessDomain } from "../config/store.js";
+import { parseOntologyQueryFlags } from "./bkn-utils.js";
+// ── subgraph ─────────────────────────────────────────────────────────────────
+export async function runKnSubgraphCommand(args) {
+    let filteredArgs;
+    let pretty;
+    let businessDomain;
+    try {
+        const parsed = parseOntologyQueryFlags(args);
+        filteredArgs = parsed.filteredArgs;
+        pretty = parsed.pretty;
+        businessDomain = parsed.businessDomain;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn subgraph <kn-id> '<json>' [--pretty] [-bd value]
+
+Query subgraph via ontology-query API. JSON body format see references/json-formats.md#subgraph.`);
+            return 0;
+        }
+        throw error;
+    }
+    const [knId, body] = filteredArgs;
+    if (!knId || !body) {
+        console.error("Usage: kweaver bkn subgraph <kn-id> '<json>' [options]");
+        return 1;
+    }
+    try {
+        // Auto-detect query_type=relation_path when body contains source_object_type_id
+        let queryType;
+        try {
+            const parsedBody = JSON.parse(body);
+            if (parsedBody.source_object_type_id) {
+                queryType = "relation_path";
+            }
+        }
+        catch {
+            // Not valid JSON — let the API return the error
+        }
+        const token = await ensureValidToken();
+        const result = await subgraph({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            knId,
+            body,
+            businessDomain,
+            queryType,
+        });
+        if (result.length > 100_000) {
+            console.error(`[warn] Response is ${(result.length / 1024).toFixed(0)}KB. Consider narrowing the subgraph query.`);
+        }
+        console.log(formatCallOutput(result, pretty));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+// ── action-execution ─────────────────────────────────────────────────────────
+export async function runKnActionExecutionCommand(args) {
+    let filteredArgs;
+    let pretty;
+    let businessDomain;
+    try {
+        const parsed = parseOntologyQueryFlags(args);
+        filteredArgs = parsed.filteredArgs;
+        pretty = parsed.pretty;
+        businessDomain = parsed.businessDomain;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn action-execution get <kn-id> <execution-id> [--pretty] [-bd value]
+
+Get action execution status.`);
+            return 0;
+        }
+        throw error;
+    }
+    const [subAction, knId, executionId] = filteredArgs;
+    if (subAction !== "get" || !knId || !executionId) {
+        console.error("Usage: kweaver bkn action-execution get <kn-id> <execution-id> [options]");
+        return 1;
+    }
+    try {
+        const token = await ensureValidToken();
+        const result = await actionExecutionGet({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            knId,
+            executionId,
+            businessDomain,
+        });
+        console.log(formatCallOutput(result, pretty));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+// ── action-log ───────────────────────────────────────────────────────────────
+export async function runKnActionLogCommand(args) {
+    const [action, ...rest] = args;
+    if (!action || action === "--help" || action === "-h") {
+        console.log(`kweaver bkn action-log list <kn-id> [options]
+kweaver bkn action-log get <kn-id> <log-id> [options]
+kweaver bkn action-log cancel <kn-id> <log-id> [options]
+
+List/get execution logs. cancel has side effects - only use when explicitly requested.
+Options for list: --limit, --need-total, --action-type-id, --status, --trigger-type, --search-after`);
+        return 0;
+    }
+    let pretty = true;
+    let businessDomain = "";
+    let limit = 30;
+    let needTotal;
+    let actionTypeId;
+    let status;
+    let triggerType;
+    let searchAfter;
+    const filteredArgs = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--help" || arg === "-h") {
+            throw new Error("help");
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && rest[i + 1]) {
+            businessDomain = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === "--limit" && rest[i + 1]) {
+            limit = parseInt(rest[i + 1], 10);
+            i += 1;
+            continue;
+        }
+        if (arg === "--need-total" && rest[i + 1]) {
+            needTotal = rest[i + 1].toLowerCase() === "true";
+            i += 1;
+            continue;
+        }
+        if (arg === "--action-type-id" && rest[i + 1]) {
+            actionTypeId = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === "--status" && rest[i + 1]) {
+            status = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === "--trigger-type" && rest[i + 1]) {
+            triggerType = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === "--search-after" && rest[i + 1]) {
+            searchAfter = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        filteredArgs.push(arg);
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    try {
+        const token = await ensureValidToken();
+        const base = {
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            businessDomain,
+        };
+        if (action === "list") {
+            const [knId] = filteredArgs;
+            if (!knId) {
+                console.error("Usage: kweaver bkn action-log list <kn-id> [options]");
+                return 1;
+            }
+            const result = await actionLogsList({
+                ...base,
+                knId,
+                limit,
+                needTotal,
+                actionTypeId,
+                status,
+                triggerType,
+                searchAfter,
+            });
+            console.log(formatCallOutput(result, pretty));
+            return 0;
+        }
+        if (action === "get") {
+            const [knId, logId] = filteredArgs;
+            if (!knId || !logId) {
+                console.error("Usage: kweaver bkn action-log get <kn-id> <log-id> [options]");
+                return 1;
+            }
+            const result = await actionLogGet({ ...base, knId, logId });
+            console.log(formatCallOutput(result, pretty));
+            return 0;
+        }
+        if (action === "cancel") {
+            const [knId, logId] = filteredArgs;
+            if (!knId || !logId) {
+                console.error("Usage: kweaver bkn action-log cancel <kn-id> <log-id> [options]");
+                return 1;
+            }
+            const result = await actionLogCancel({ ...base, knId, logId });
+            console.log(formatCallOutput(result, pretty));
+            return 0;
+        }
+        console.error(`Unknown action-log action: ${action}. Use list, get, or cancel.`);
+        return 1;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+// ── search ───────────────────────────────────────────────────────────────────
+const KN_SEARCH_HELP = `kweaver bkn search <kn-id> <query> [--max-concepts <n>] [--mode <mode>] [--pretty] [-bd value]
+
+Semantic search within a knowledge network via agent-retrieval API.
+Returns matched concepts (object types, relation types, action types).
+
+Options:
+  --max-concepts <n>   Max concepts to return (default: 10)
+  --mode <mode>        Search mode (default: keyword_vector_retrieval)
+  --pretty             Pretty-print JSON output
+  -bd, --biz-domain    Override x-business-domain`;
+export function parseKnSearchArgs(args) {
+    let knId = "";
+    let query = "";
+    let maxConcepts = 10;
+    let mode = "keyword_vector_retrieval";
+    let pretty = false;
+    let businessDomain = process.env.KWEAVER_BUSINESS_DOMAIN ?? "";
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--max-concepts") {
+            maxConcepts = Number(args[++i]);
+        }
+        else if (arg === "--mode") {
+            mode = args[++i];
+        }
+        else if (arg === "--pretty") {
+            pretty = true;
+        }
+        else if (arg === "-bd" || arg === "--biz-domain") {
+            businessDomain = args[++i];
+        }
+        else if (arg === "--help" || arg === "-h") {
+            throw Object.assign(new Error("help"), { isHelp: true });
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    knId = positional[0] ?? "";
+    query = positional.slice(1).join(" ");
+    if (!knId || !query) {
+        throw new Error("Usage: kweaver bkn search <kn-id> <query> [options]");
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return { knId, query, maxConcepts, mode, pretty, businessDomain };
+}
+export async function runKnSearchCommand(args) {
+    let options;
+    try {
+        options = parseKnSearchArgs(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.isHelp) {
+            console.log(KN_SEARCH_HELP);
+            return 0;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    try {
+        const token = await ensureValidToken();
+        const result = await semanticSearch({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            knId: options.knId,
+            query: options.query,
+            businessDomain: options.businessDomain,
+            maxConcepts: options.maxConcepts,
+            mode: options.mode,
+        });
+        console.log(formatCallOutput(result, options.pretty));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+// ── relation-type-paths ───────────────────────────────────────────────────────
+export async function runKnRelationTypePathsCommand(args) {
+    let parsed;
+    try {
+        parsed = parseOntologyQueryFlags(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn relation-type-paths <kn-id> '<json>' [--pretty] [-bd value]
+
+Query relation type paths between object types.`);
+            return 0;
+        }
+        throw error;
+    }
+    const [knId, body] = parsed.filteredArgs;
+    if (!knId || !body) {
+        console.log(`kweaver bkn relation-type-paths <kn-id> '<json>' [--pretty] [-bd value]
+
+Query relation type paths between object types.`);
+        return knId && !body ? 1 : 0;
+    }
+    const token = await ensureValidToken();
+    const result = await queryRelationTypePaths({
+        baseUrl: token.baseUrl,
+        accessToken: token.accessToken,
+        knId,
+        body,
+        businessDomain: parsed.businessDomain,
+    });
+    console.log(formatCallOutput(result, parsed.pretty));
+    return 0;
+}
+// ── resources ─────────────────────────────────────────────────────────────────
+export async function runKnResourcesCommand(args) {
+    let parsed;
+    try {
+        parsed = parseOntologyQueryFlags(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn resources [--pretty] [-bd value]
+
+List available resources.`);
+            return 0;
+        }
+        throw error;
+    }
+    const token = await ensureValidToken();
+    const result = await listBknResources({
+        baseUrl: token.baseUrl,
+        accessToken: token.accessToken,
+        businessDomain: parsed.businessDomain,
+    });
+    console.log(formatCallOutput(result, parsed.pretty));
+    return 0;
+}

package/dist/commands/bkn-schema.d.ts

@@ -0,0 +1,135 @@
+export interface KnObjectTypeQueryOptions {
+    knId: string;
+    otId: string;
+    body: string;
+    pretty: boolean;
+    businessDomain: string;
+}
+export declare function parseKnObjectTypeQueryArgs(args: string[]): KnObjectTypeQueryOptions;
+export declare function normalizeAdpFieldType(raw: string | undefined): string;
+/**
+ * Ensure each data_property has mapped_field (same-name mapping) for build engine compatibility.
+ */
+export declare function ensureMappedFieldOnDataProperty(prop: Record<string, unknown>): Record<string, unknown>;
+/** Result of parsing `object-type create`; may require async dataview GET to fill properties. */
+export type ObjectTypeCreateParsed = {
+    mode: "complete";
+    knId: string;
+    body: string;
+    businessDomain: string;
+    branch: string;
+    pretty: boolean;
+} | {
+    mode: "needsDataview";
+    knId: string;
+    dataviewId: string;
+    entry: Record<string, unknown>;
+    businessDomain: string;
+    branch: string;
+    pretty: boolean;
+};
+/** Parse object-type create args: --name --dataview-id --primary-key --display-key [--property '<json>' ...] */
+export declare function parseObjectTypeCreateArgs(args: string[]): ObjectTypeCreateParsed;
+/**
+ * Load dataview fields and build data_properties (with mapped_field). Used when no --property flags.
+ */
+export declare function finalizeObjectTypeCreateFromDataview(options: {
+    baseUrl: string;
+    accessToken: string;
+    dataviewId: string;
+    entry: Record<string, unknown>;
+    businessDomain: string;
+}): Promise<string>;
+/** Fields merged via GET → modify → PUT (not raw body mode). */
+export interface ObjectTypeMergeFields {
+    name?: string;
+    displayKey?: string;
+    addProperties: Record<string, unknown>[];
+    removeProperties: string[];
+    tags?: string[];
+    comment?: string;
+    icon?: string;
+    color?: string;
+}
+export type ObjectTypeUpdateParsed = {
+    mode: "body";
+    knId: string;
+    otId: string;
+    body: string;
+    businessDomain: string;
+    pretty: boolean;
+} | {
+    mode: "merge";
+    knId: string;
+    otId: string;
+    merge: ObjectTypeMergeFields;
+    businessDomain: string;
+    pretty: boolean;
+    branch: string;
+};
+/** Prepare a GET response entry for PUT (drop read-only fields). */
+export declare function stripObjectTypeForPut(entry: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Apply merge flags onto a stripped object-type object (mutates copy).
+ * - Add: property `name` not in list → append.
+ * - Update: property `name` exists → replace entry (same as add; CLI also accepts `--update-property`).
+ * - Delete: `--remove-property` removes by `name` before adds are applied.
+ */
+export declare function applyObjectTypeMerge(target: Record<string, unknown>, merge: ObjectTypeMergeFields): Record<string, unknown>;
+/** Parse object-type update: raw JSON body OR merge flags (GET-merge-PUT). */
+export declare function parseObjectTypeUpdateArgs(args: string[]): ObjectTypeUpdateParsed;
+/** Parse object-type delete args: <kn-id> <ot-ids> [-y] */
+export declare function parseObjectTypeDeleteArgs(args: string[]): {
+    knId: string;
+    otIds: string;
+    businessDomain: string;
+    yes: boolean;
+};
+export interface KnActionTypeExecuteOptions {
+    knId: string;
+    atId: string;
+    body: string;
+    pretty: boolean;
+    businessDomain: string;
+    wait: boolean;
+    timeout: number;
+}
+export declare function parseKnActionTypeExecuteArgs(args: string[]): KnActionTypeExecuteOptions;
+/** Parse relation-type create args: --name --source --target [--mapping src:tgt ...] */
+export declare function parseRelationTypeCreateArgs(args: string[]): {
+    knId: string;
+    body: string;
+    businessDomain: string;
+    branch: string;
+    pretty: boolean;
+};
+/** Parse relation-type update args: --source and --target are required by the API */
+export declare function parseRelationTypeUpdateArgs(args: string[]): {
+    knId: string;
+    rtId: string;
+    body: string;
+    businessDomain: string;
+    pretty: boolean;
+};
+/** Parse relation-type delete args: <kn-id> <rt-ids> [-y] */
+export declare function parseRelationTypeDeleteArgs(args: string[]): {
+    knId: string;
+    rtIds: string;
+    businessDomain: string;
+    yes: boolean;
+};
+export declare function runKnObjectTypeCommand(args: string[]): Promise<number>;
+export declare function runKnRelationTypeCommand(args: string[]): Promise<number>;
+export declare function runKnActionTypeCommand(args: string[]): Promise<number>;
+export interface ConceptGroupParsed {
+    action: string;
+    knId: string;
+    itemId: string;
+    body: string;
+    extra: string;
+    yes: boolean;
+    pretty: boolean;
+    businessDomain: string;
+}
+export declare function parseConceptGroupArgs(args: string[]): ConceptGroupParsed;
+export declare function runKnConceptGroupCommand(args: string[]): Promise<number>;