@openbkn/bkn-sdk 0.1.1-alpha.15 → 0.1.1-alpha.18

package/dist/index.d.ts

@@ -58,6 +58,54 @@ interface RawCallResult {
     body: string;
 }
 
+/**
+ * bkn-safe admin API (`/api/safe/v1/admin/*`, token-gated; the gateway-exposed
+ * replacement for the retired ISF UserManagement / Authorization / EACP). The
+ * logged-in user must be an admin: 401 = no/invalid token, 403 = not an admin.
+ * Only `audit list` has no endpoint (login-log retired by design). Response
+ * shapes: `{users|roles|departments, total}`; department `parent_id` (not the
+ * ISF `parent_deps[]`). See docs/exec-plans/admin-bkn-safe-migration.md.
+ * Also carries the cluster license hub (`/admin/license/*`, issue #224).
+ */
+
+/** licverify judgement states. `invalid` also covers "no license installed". */
+type LicenseState = "valid" | "grace" | "fallback_community" | "invalid";
+/** GET /admin/license response (admin detail view). */
+interface LicenseDetail {
+    state: LicenseState;
+    /** Whether the installed license is fingerprint-bound to this instance. */
+    activated: boolean;
+    /** This cluster's machine code (present even with no license installed). */
+    instance_fp: string;
+    error?: string;
+    /** Background auto-renew failure — license itself may still be valid. */
+    renew_error?: string;
+    edition?: string;
+    lic_id?: string;
+    customer?: {
+        name?: string;
+        [k: string]: unknown;
+    };
+    /** Unix seconds; expires_at 0 = never expires (community). */
+    issued_at?: number;
+    expires_at?: number;
+    contract_expires_at?: number;
+    /** Only present in `grace` state. */
+    grace_remaining_days?: number;
+    features?: string[];
+    limits?: Record<string, number>;
+}
+/**
+ * Import outcome. Plain success = the stored license's detail. `stored: true`
+ * = the .lic was verified and stored, but issuer activation failed (HTTP
+ * 409/502) — both facts matter, the import is not lost.
+ */
+type LicenseImportResult = LicenseDetail | {
+    stored: true;
+    error: string;
+    license: LicenseDetail;
+};
+
 /**
  * Admin (operator) client — user-management + authorization.
  * Reads and writes (org/user create/update/delete +
@@ -184,6 +232,17 @@ declare function admin(ctx: RequestContext): {
         ok: true;
     }>;
     auditList: (_opts?: AuditListOptions) => never;
+    licenseGet: () => Promise<LicenseDetail>;
+    licenseImport: (licenseText: string, opts?: {
+        receipt?: boolean;
+    }) => Promise<LicenseImportResult>;
+    licenseActivate: () => Promise<LicenseDetail>;
+    licenseRemove: () => Promise<{
+        ok: true;
+    }>;
+    licenseFingerprint: () => Promise<{
+        instance_fp: string;
+    }>;
 };
 
 interface ChatResult {
@@ -320,6 +379,8 @@ interface SearchSchemaOptions {
     searchScope?: string[];
     maxConcepts?: number;
 }
+/** Progressive KN-detail disclosure level: `summary` (skeleton + property names) | `full`. */
+type DetailLevel = "summary" | "full";
 
 /** Context-loader resource surface (MCP over agent-retrieval). */
 
@@ -327,6 +388,9 @@ declare function context(ctx: RequestContext): {
     searchSchema: (knId: string, query: string, opts?: SearchSchemaOptions) => Promise<unknown>;
     queryObjectInstance: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
     findSkills: (knId: string, objectTypeId: string, topK?: number) => Promise<unknown>;
+    knDetail: (knId: string, detailLevel?: DetailLevel) => Promise<unknown>;
+    objectTypes: (knId: string, ids: string[]) => Promise<unknown>;
+    relationTypes: (knId: string, ids: string[]) => Promise<unknown>;
     info: () => Promise<unknown>;
     tools: (knId: string) => Promise<unknown>;
     toolCall: (knId: string, name: string, args: Record<string, unknown>) => Promise<unknown>;
@@ -431,7 +495,7 @@ interface CreateFromCatalogOptions {
     tables?: string[];
     pkMap?: Record<string, string>;
     build?: boolean;
-    /** Per-table resource columns to vectorize (sets the build task's embedding_fields). */
+    /** Per-table resource columns to vectorize (sets resource schema index features). */
     embeddingFields?: Record<string, string[]>;
     embeddingModel?: string;
     noRollback?: boolean;
@@ -582,13 +646,74 @@ declare function models(ctx: RequestContext): {
  * Responses passed through as parsed JSON.
  */
 
+interface PropertyFeature {
+    name?: string;
+    display_name?: string;
+    feature_type: "keyword" | "fulltext" | "vector" | string;
+    description?: string;
+    ref_property?: string;
+    is_default?: boolean;
+    is_native?: boolean;
+    config?: Record<string, unknown>;
+}
+interface ResourceProperty {
+    name: string;
+    display_name?: string;
+    type?: string;
+    description?: string;
+    original_name?: string;
+    original_type?: string;
+    original_description?: string;
+    features?: PropertyFeature[];
+    attributes?: Record<string, unknown>;
+    extensions?: Record<string, string>;
+}
+interface ResourceIndexConfig {
+    build_key_fields?: string[];
+    default_fulltext_analyzer?: string;
+    default_embedding_model?: string;
+}
 interface ListResourcesOptions {
     datasourceId?: string;
     name?: string;
     /** Resource category, e.g. table | logicview. */
     category?: string;
+    status?: string;
+    database?: string;
     limit?: number;
+    offset?: number;
+    sort?: "name" | "create_time" | "update_time" | string;
+    direction?: "asc" | "desc";
+    includeExtensions?: boolean;
+    includeExtensionKeys?: string;
+    extensionPairs?: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+interface UpdateResourceOptions {
+    name?: string;
+    catalogId?: string;
+    tags?: string[];
+    description?: string;
+    category?: string;
+    status?: string;
+    database?: string;
+    sourceIdentifier?: string;
+    sourceMetadata?: Record<string, unknown>;
+    schemaDefinition?: ResourceProperty[];
+    indexConfig?: ResourceIndexConfig | null;
+    logicDefinition?: unknown;
+    extensions?: Record<string, string>;
+}
+interface ConfigureResourceIndexOptions {
+    buildKeyFields?: string[];
+    embeddingFields?: string[];
+    embeddingModel?: string;
+    fulltextFields?: string[];
+    fulltextAnalyzer?: string;
 }
+declare function configureResourceIndex(ctx: RequestContext, id: string, opts: ConfigureResourceIndexOptions): Promise<unknown>;
 interface FindResourceOptions {
     datasourceId?: string;
     /** Exact name match instead of fuzzy. */
@@ -606,6 +731,8 @@ declare function resources(ctx: RequestContext): {
     list: (opts?: ListResourcesOptions) => Promise<unknown>;
     get: (id: string) => Promise<unknown>;
     delete: (id: string) => Promise<unknown>;
+    update: (id: string, patch: UpdateResourceOptions) => Promise<unknown>;
+    configureIndex: (id: string, opts: Parameters<typeof configureResourceIndex>[2]) => Promise<unknown>;
     find: (name: string, opts?: FindResourceOptions) => Promise<unknown>;
     query: (id: string, opts?: QueryResourceOptions) => Promise<unknown>;
 };
@@ -828,7 +955,8 @@ declare function trace(ctx: RequestContext): {
 
 /**
  * Vega backend client — catalog/resource reads + BuildTask (index build).
- * Build config lives on the task (CreateBuildTaskRequest), per the platform model.
+ * Build config is snapshotted from the Resource's schema_definition/features and
+ * index_config when the BuildTask is created.
  */
 
 declare const BuildMode: z.ZodEnum<["batch", "streaming"]>;
@@ -837,24 +965,15 @@ type BuildMode = z.infer<typeof BuildMode>;
 declare const CreateBuildTaskRequest: z.ZodObject<{
     resource_id: z.ZodString;
     mode: z.ZodEnum<["batch", "streaming"]>;
-    embedding_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    build_key_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    execute_type: z.ZodOptional<z.ZodEnum<["incremental", "full"]>>;
 }, "strip", z.ZodTypeAny, {
     mode: "batch" | "streaming";
     resource_id: string;
-    embedding_fields?: string[] | undefined;
-    build_key_fields?: string[] | undefined;
-    embedding_model?: string | undefined;
-    model_dimensions?: number | undefined;
+    execute_type?: "full" | "incremental" | undefined;
 }, {
     mode: "batch" | "streaming";
     resource_id: string;
-    embedding_fields?: string[] | undefined;
-    build_key_fields?: string[] | undefined;
-    embedding_model?: string | undefined;
-    model_dimensions?: number | undefined;
+    execute_type?: "full" | "incremental" | undefined;
 }>;
 type CreateBuildTaskRequest = z.infer<typeof CreateBuildTaskRequest>;
 declare const BuildTask: z.ZodObject<{
@@ -866,10 +985,21 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
     resource_id: z.ZodOptional<z.ZodString>;
@@ -879,10 +1009,21 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
     resource_id: z.ZodOptional<z.ZodString>;
@@ -892,21 +1033,48 @@ declare const BuildTask: z.ZodObject<{
     total_count: z.ZodOptional<z.ZodNumber>;
     synced_count: z.ZodOptional<z.ZodNumber>;
     vectorized_count: z.ZodOptional<z.ZodNumber>;
-    embedding_fields: z.ZodOptional<z.ZodString>;
-    build_key_fields: z.ZodOptional<z.ZodString>;
-    embedding_model: z.ZodOptional<z.ZodString>;
-    model_dimensions: z.ZodOptional<z.ZodNumber>;
+    index_config: z.ZodOptional<z.ZodUnknown>;
+    catalog_id: z.ZodOptional<z.ZodString>;
+    index_health: z.ZodOptional<z.ZodObject<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        embedding: z.ZodString;
+        fulltext: z.ZodString;
+        usable: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>>;
 }, z.ZodTypeAny, "passthrough">>;
 type BuildTask = z.infer<typeof BuildTask>;
+interface ListBuildTasksOptions {
+    limit?: number;
+    offset?: number;
+    resourceId?: string;
+    catalogId?: string;
+    status?: string | string[];
+    active?: boolean;
+    mode?: BuildMode;
+    orderBy?: "default" | "created_at" | "updated_at" | "status" | "mode";
+    order?: "asc" | "desc";
+}
+interface DeleteBuildTasksOptions {
+    ignoreMissing?: boolean;
+    deleteActiveIndex?: boolean;
+}
 interface SqlQueryRequest {
     /** SQL string (MySQL/MariaDB/PostgreSQL) or an OpenSearch DSL object. */
     query: string | Record<string, unknown>;
+    /** Query mode. `stream` uses cursor-style paging through `query_id`. */
+    query_type?: "standard" | "stream";
     /**
-     * Source type (mysql | mariadb | postgresql | opensearch …). Optional — when
-     * the query carries a `{{<resource-id>}}` placeholder the backend infers the
-     * type from that resource's Catalog connector. Pass it only to override.
+     * Source type (mysql | mariadb | postgresql | opensearch …). Required by the
+     * current vega-backend raw query handler.
      */
-    resource_type?: string;
+    resource_type: string;
     /** Streaming batch size (100–10000, default server-side). */
     stream_size?: number;
     /** Query timeout in seconds (1–3600). */
@@ -917,6 +1085,19 @@ interface SqlQueryRequest {
 interface ListCatalogsOptions {
     limit?: number;
     offset?: number;
+    name?: string;
+    tag?: string;
+    type?: "physical" | "logical" | string;
+    enabled?: boolean;
+    healthCheckStatus?: string;
+    includeExtensions?: boolean;
+    includeExtensionKeys?: string;
+    extensionPairs?: Array<{
+        key: string;
+        value: string;
+    }>;
+    sort?: "name" | "create_time" | "update_time" | string;
+    direction?: "asc" | "desc";
 }
 /** POST /catalogs body. `connector_config` shape varies by connector (raw passthrough). */
 interface CreateCatalogRequest {
@@ -926,13 +1107,20 @@ interface CreateCatalogRequest {
     tags?: string[];
     description?: string;
     enabled?: boolean;
+    id?: string;
+    internal?: boolean;
+    extensions?: Record<string, string>;
 }
 
 declare function vega(ctx: RequestContext): {
     catalogs: (opts?: ListCatalogsOptions) => Promise<unknown>;
     getCatalog: (id: string) => Promise<unknown>;
     createCatalog: (req: CreateCatalogRequest) => Promise<unknown>;
+    updateCatalog: (id: string, req: Partial<CreateCatalogRequest>) => Promise<unknown>;
     enableCatalog: (id: string) => Promise<unknown>;
+    disableCatalog: (id: string) => Promise<unknown>;
+    deleteCatalog: (id: string) => Promise<unknown>;
+    testCatalogConnection: (id: string) => Promise<unknown>;
     discoverCatalog: (id: string, wait?: boolean) => Promise<unknown>;
     catalogResources: (id: string, category?: string) => Promise<unknown>;
     catalogHealth: (ids: string[]) => Promise<unknown>;
@@ -955,11 +1143,28 @@ declare function vega(ctx: RequestContext): {
         total_count: zod.ZodOptional<zod.ZodNumber>;
         synced_count: zod.ZodOptional<zod.ZodNumber>;
         vectorized_count: zod.ZodOptional<zod.ZodNumber>;
-        embedding_fields: zod.ZodOptional<zod.ZodString>;
-        build_key_fields: zod.ZodOptional<zod.ZodString>;
-        embedding_model: zod.ZodOptional<zod.ZodString>;
-        model_dimensions: zod.ZodOptional<zod.ZodNumber>;
+        index_config: zod.ZodOptional<zod.ZodUnknown>;
+        catalog_id: zod.ZodOptional<zod.ZodString>;
+        index_health: zod.ZodOptional<zod.ZodObject<{
+            embedding: zod.ZodString;
+            fulltext: zod.ZodString;
+            usable: zod.ZodBoolean;
+        }, "passthrough", zod.ZodTypeAny, zod.objectOutputType<{
+            embedding: zod.ZodString;
+            fulltext: zod.ZodString;
+            usable: zod.ZodBoolean;
+        }, zod.ZodTypeAny, "passthrough">, zod.objectInputType<{
+            embedding: zod.ZodString;
+            fulltext: zod.ZodString;
+            usable: zod.ZodBoolean;
+        }, zod.ZodTypeAny, "passthrough">>>;
     }, zod.ZodTypeAny, "passthrough">>;
+    buildTasks: (opts?: ListBuildTasksOptions) => Promise<unknown>;
+    deleteBuildTasks: (ids: string[], opts?: DeleteBuildTasksOptions) => Promise<unknown>;
+    startBuildTask: (taskId: string, opts?: {
+        reset?: boolean;
+    }) => Promise<unknown>;
+    stopBuildTask: (taskId: string) => Promise<unknown>;
 };
 
 interface BknClient {
@@ -1145,7 +1350,7 @@ interface RequestInitEx {
     /** JSON body — serialized and Content-Type set automatically. */
     body?: unknown;
     /** Query params appended to the path. */
-    query?: Record<string, string | number | boolean | undefined>;
+    query?: Record<string, string | number | boolean | Array<string | number | boolean> | undefined>;
     headers?: Record<string, string>;
     /** Per-request timeout; defaults to 30s. */
     timeoutMs?: number;

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   toolboxes,
   trace,
   vega
-} from "./chunk-KF3J46WL.js";
+} from "./chunk-LCOMMFH7.js";
 export {
   DEFAULT_BUSINESS_DOMAIN,
   DEFAULT_LIST_LIMIT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbkn/bkn-sdk",
-  "version": "0.1.1-alpha.15",
+  "version": "0.1.1-alpha.18",
   "description": "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -18,7 +18,7 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "README.zh.md", "LICENSE"],
+  "files": ["dist", "README.md", "README.zh.md", "LICENSE", "NOTICE"],
   "publishConfig": {
     "access": "public"
   },