@openbkn/bkn-sdk 0.1.1-alpha.1 → 0.1.1-alpha.11

package/dist/index.d.ts

@@ -14,11 +14,25 @@ interface ClientOptions {
     insecure?: boolean;
 }
 /** Fully resolved request context — every field is known. */
+interface RefreshableTokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+}
 interface RequestContext {
     baseUrl: string;
     token: string;
     businessDomain: string;
     insecure: boolean;
+    /**
+     * Stored-credential refresh: on a 401, swap the refresh token for a fresh
+     * access token, persist it, and retry once. Absent for explicit `--token`/env.
+     */
+    refresh?: {
+        refreshToken: string;
+        clientId?: string;
+        persist: (tokens: RefreshableTokens) => void;
+    };
 }
 declare const DEFAULT_BUSINESS_DOMAIN = "bd_public";
 /** Default list/query limits — see AGENTS.md conventions. */
@@ -112,42 +126,64 @@ interface AuditListOptions {
 }
 type MemberType = "user" | "department" | "group" | "app";
 
-/** Build / render a department hierarchy from flat ISF search entries. */
-
-interface OrgNode {
-    id: string;
-    name: string;
-    children: OrgNode[];
-}
-
 declare function admin(ctx: RequestContext): {
     orgList: (opts?: AdminListOptions) => Promise<unknown>;
     orgGet: (deptId: string) => Promise<unknown>;
-    orgMembers: (deptId: string, opts?: {
-        role?: string;
-        offset?: number;
-        limit?: number;
-    }) => Promise<unknown>;
-    orgTree: (role?: string) => Promise<OrgNode[]>;
-    orgCreate: (input: CreateOrgInput) => Promise<unknown>;
+    orgTree: (_role?: string) => Promise<unknown[]>;
+    orgMembers: (deptId: string, _opts?: unknown) => Promise<unknown>;
+    orgCreate: (input: CreateOrgInput) => Promise<{
+        id: string;
+    }>;
     orgUpdate: (deptId: string, input: UpdateOrgInput) => Promise<unknown>;
-    orgDelete: (deptId: string) => Promise<unknown>;
+    orgDelete: (deptId: string) => Promise<{
+        ok: true;
+    }>;
     userList: (opts?: AdminListOptions) => Promise<unknown>;
     userGet: (userId: string) => Promise<unknown>;
-    userRoles: (userId: string) => Promise<unknown>;
-    userCreate: (input: CreateUserInput) => Promise<unknown>;
+    userRoles: (userId: string) => Promise<{
+        roles: {
+            name: string;
+            id: string;
+        }[];
+    }>;
+    userCreate: (input: CreateUserInput) => Promise<{
+        id: string;
+    }>;
     userUpdate: (userId: string, input: UpdateUserInput) => Promise<unknown>;
-    userDelete: (userId: string) => Promise<unknown>;
-    userResetPassword: (userId: string, newPassword: string) => Promise<unknown>;
-    roleList: (opts?: ListRolesOptions) => Promise<unknown>;
+    userDelete: (userId: string) => Promise<{
+        ok: true;
+    }>;
+    userResetPassword: (userId: string, newPassword: string) => Promise<{
+        ok: true;
+    }>;
+    roleList: (_opts?: ListRolesOptions) => Promise<unknown>;
     roleGet: (roleId: string) => Promise<unknown>;
-    roleMembers: (roleId: string, opts?: {
-        keyword?: string;
-        limit?: number;
+    roleMembers: (roleId: string, _opts?: unknown) => Promise<{
+        members: {
+            account: string;
+            id: string;
+        }[];
+    }>;
+    addRoleMember: (roleId: string, id: string, _type?: MemberType) => Promise<{
+        ok: true;
+    }>;
+    removeRoleMember: (roleId: string, id: string, _type?: MemberType) => Promise<{
+        ok: true;
+    }>;
+    roleCreate: (name: string, description?: string) => Promise<{
+        id: string;
+    }>;
+    roleUpdate: (roleId: string, input: {
+        name?: string;
+        description?: string;
     }) => Promise<unknown>;
-    addRoleMember: (roleId: string, id: string, type?: MemberType) => Promise<unknown>;
-    removeRoleMember: (roleId: string, id: string, type?: MemberType) => Promise<unknown>;
-    auditList: (opts?: AuditListOptions) => Promise<unknown>;
+    roleDelete: (roleId: string) => Promise<{
+        ok: true;
+    }>;
+    rolePermission: (roleId: string, grant: boolean, resourceType: string, resourceId: string, operations: string[]) => Promise<{
+        ok: true;
+    }>;
+    auditList: (_opts?: AuditListOptions) => never;
 };
 
 interface ChatResult {
@@ -209,6 +245,61 @@ declare function agents(ctx: RequestContext): {
     }) => Promise<ChatResult>;
 };
 
+/**
+ * AppKey API (`/api/safe/v1/{me,admin}/api-keys`, OAuth-token-gated). AppKeys
+ * are user-issued long-lived credentials (prefix `bak_`) that authenticate AS
+ * their owner — downstream authorization is identical to that owner's OAuth
+ * token. Issuing/managing them needs a real OAuth session (an AppKey itself
+ * cannot mint AppKeys). The plaintext `key` is returned ONCE, on create.
+ * Usage of an AppKey is drop-in: pass it as the bearer `--token` against the
+ * Context Loader (agent-retrieval) MCP/REST surface. See issue #75.
+ */
+
+/** A key's public metadata — never carries the secret. */
+interface ApiKey {
+    id: string;
+    key_id: string;
+    name: string;
+    enabled: boolean;
+    /** `null` = never expires. */
+    expires_at: string | null;
+    /** `null` = never used (zombie-key signal). */
+    last_used_at: string | null;
+    created_at: string;
+    /** Present only on the admin list. */
+    owner_user_id?: string;
+}
+/** Create response — `key` is the full plaintext, shown only this once. */
+interface CreatedApiKey extends ApiKey {
+    key: string;
+}
+interface CreateApiKeyInput {
+    name: string;
+    /** RFC3339; omit = backend default (1 year). Must be in the future. */
+    expiresAt?: string;
+    /** `true` = never expire (wins over `expiresAt`). */
+    neverExpire?: boolean;
+}
+
+declare function appKeys(ctx: RequestContext): {
+    /** List the caller's own keys (no secrets). */
+    list: () => Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Issue a key — the result's `key` is the plaintext, shown only once. */
+    create: (input: CreateApiKeyInput) => Promise<CreatedApiKey>;
+    /** Revoke one of the caller's keys (immediate). */
+    revoke: (id: string) => Promise<void>;
+    /** Rotate a key in place — new plaintext (shown once); old secret dies now. */
+    regenerate: (id: string) => Promise<CreatedApiKey>;
+    /** Admin: list all keys, or one owner's (adds `owner_user_id`). */
+    adminList: (ownerId?: string) => Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Admin: revoke any key. */
+    adminRevoke: (id: string) => Promise<void>;
+};
+
 /**
  * Context-loader client over the agent-retrieval MCP endpoint (JSON-RPC).
  * Reimplemented slim from kweaver-sdk: initialize → session id →
@@ -227,8 +318,10 @@ 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>;
+    info: () => Promise<unknown>;
     tools: (knId: string) => Promise<unknown>;
     toolCall: (knId: string, name: string, args: Record<string, unknown>) => Promise<unknown>;
+    callMethod: (knId: string, method: string, params?: Record<string, unknown>) => Promise<unknown>;
     queryInstanceSubgraph: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
     logicProperties: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
     actionInfo: (knId: string, args: Record<string, unknown>) => Promise<unknown>;
@@ -790,6 +883,22 @@ declare const BuildTask: z.ZodObject<{
     model_dimensions: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">>;
 type BuildTask = z.infer<typeof BuildTask>;
+interface SqlQueryRequest {
+    /** SQL string (MySQL/MariaDB/PostgreSQL) or an OpenSearch DSL object. */
+    query: string | Record<string, unknown>;
+    /**
+     * 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.
+     */
+    resource_type?: string;
+    /** Streaming batch size (100–10000, default server-side). */
+    stream_size?: number;
+    /** Query timeout in seconds (1–3600). */
+    query_timeout?: number;
+    /** Cursor session id for paged streaming. */
+    query_id?: string;
+}
 interface ListCatalogsOptions {
     limit?: number;
     offset?: number;
@@ -814,6 +923,8 @@ declare function vega(ctx: RequestContext): {
     catalogHealth: (ids: string[]) => Promise<unknown>;
     connectorTypes: () => Promise<unknown>;
     connectorType: (type: string) => Promise<unknown>;
+    /** Run SQL / OpenSearch DSL directly against a data source. */
+    sql: (body: SqlQueryRequest) => Promise<unknown>;
     /** Build a resource's index. With `wait`, polls until terminal. */
     build: (req: CreateBuildTaskRequest, opts?: {
         wait?: boolean;
@@ -848,6 +959,7 @@ interface BknClient {
     readonly toolboxes: ReturnType<typeof toolboxes>;
     readonly trace: ReturnType<typeof trace>;
     readonly admin: ReturnType<typeof admin>;
+    readonly appKeys: ReturnType<typeof appKeys>;
     readonly vega: ReturnType<typeof vega>;
     /** Raw API passthrough (the `call` escape hatch). */
     call(path: string, opts?: RawCallOptions): Promise<RawCallResult>;
@@ -860,7 +972,9 @@ declare class HttpError extends Error {
     readonly status: number;
     readonly statusText: string;
     readonly body: string;
-    constructor(status: number, statusText: string, body: string);
+    /** Optional next-step guidance, overriding the status default (e.g. AppKey re-issue). */
+    readonly hint?: string;
+    constructor(status: number, statusText: string, body: string, hint?: string);
 }
 /** Raised for bad CLI/SDK input before any request is made. */
 declare class InputError extends Error {
@@ -889,6 +1003,8 @@ interface TokenConfig {
     expiresAt?: string;
     /** Skip TLS verification for this platform (saved by `auth login -k`). */
     tlsInsecure?: boolean;
+    /** Platform has no auth stack (no bkn-safe) — requests carry no token. */
+    noAuth?: boolean;
     /** Login name persisted at login time (fallback when JWT lacks claims). */
     username?: string;
     /** Human-readable name from userinfo. */
@@ -914,11 +1030,19 @@ declare function attachToken(baseUrl: string, accessToken: string, opts?: {
     refreshToken?: string;
     idToken?: string;
     insecure?: boolean;
+    username?: string;
 }): {
     baseUrl: string;
     userId: string;
     username?: string;
 };
+/** Register a no-auth platform session (no token; the platform has no bkn-safe). */
+declare function attachNoAuth(baseUrl: string, opts?: {
+    insecure?: boolean;
+}): {
+    baseUrl: string;
+    noAuth: true;
+};
 interface AuthStatus {
     baseUrl?: string;
     userId?: string;
@@ -928,7 +1052,22 @@ interface AuthStatus {
 }
 declare function status(): AuthStatus;
 declare function currentToken(): string;
-declare function whoami(): JwtClaims;
+/**
+ * Like {@link currentToken} but proactively refreshes an expired access token
+ * when a refresh token is stored, persisting the result. API requests already
+ * refresh on a 401 (see api/http.ts); this covers the `auth token` getter,
+ * whose output is copied out and used elsewhere where no 401 retry can help.
+ */
+declare function currentTokenFresh(): Promise<string>;
+interface WhoamiResult extends JwtClaims {
+    /** Platform the active session belongs to. */
+    baseUrl?: string;
+    /** Stored user id (UUID) for the active session. */
+    userId?: string;
+    /** Resolved account/login name — what `auth login` looked up and stored. */
+    username?: string;
+}
+declare function whoami(): WhoamiResult;
 interface PlatformListItem {
     baseUrl: string;
     userId: string;
@@ -941,10 +1080,14 @@ declare function listPlatforms(): PlatformListItem[];
 declare function use(baseUrl: string): void;
 declare function logout(): boolean;
 declare function deletePlatform(baseUrl: string, userId?: string): boolean;
-/** Switch the active user for a platform (token must already be saved). */
-declare function switchUser(baseUrl: string, userId: string): {
+/**
+ * Switch the active user for a platform. Accepts a stored user id OR a username
+ * (the account stored at login), so callers need not know the UUID.
+ */
+declare function switchUser(baseUrl: string, userOrName: string): {
     baseUrl: string;
     userId: string;
+    username?: string;
 };
 /** List saved user profiles for one platform. */
 declare function usersOf(baseUrl: string): PlatformUser[];
@@ -958,8 +1101,11 @@ declare function exportCreds(): {
 
 type auth_AuthStatus = AuthStatus;
 type auth_PlatformListItem = PlatformListItem;
+type auth_WhoamiResult = WhoamiResult;
+declare const auth_attachNoAuth: typeof attachNoAuth;
 declare const auth_attachToken: typeof attachToken;
 declare const auth_currentToken: typeof currentToken;
+declare const auth_currentTokenFresh: typeof currentTokenFresh;
 declare const auth_deletePlatform: typeof deletePlatform;
 declare const auth_exportCreds: typeof exportCreds;
 declare const auth_hostOf: typeof hostOf;
@@ -972,14 +1118,9 @@ declare const auth_userIdFromToken: typeof userIdFromToken;
 declare const auth_usersOf: typeof usersOf;
 declare const auth_whoami: typeof whoami;
 declare namespace auth {
-  export { type auth_AuthStatus as AuthStatus, type auth_PlatformListItem as PlatformListItem, auth_attachToken as attachToken, auth_currentToken as currentToken, auth_deletePlatform as deletePlatform, auth_exportCreds as exportCreds, auth_hostOf as hostOf, auth_listPlatforms as listPlatforms, auth_logout as logout, auth_status as status, auth_switchUser as switchUser, auth_use as use, auth_userIdFromToken as userIdFromToken, auth_usersOf as usersOf, auth_whoami as whoami };
+  export { type auth_AuthStatus as AuthStatus, type auth_PlatformListItem as PlatformListItem, type auth_WhoamiResult as WhoamiResult, auth_attachNoAuth as attachNoAuth, auth_attachToken as attachToken, auth_currentToken as currentToken, auth_currentTokenFresh as currentTokenFresh, auth_deletePlatform as deletePlatform, auth_exportCreds as exportCreds, auth_hostOf as hostOf, auth_listPlatforms as listPlatforms, auth_logout as logout, auth_status as status, auth_switchUser as switchUser, auth_use as use, auth_userIdFromToken as userIdFromToken, auth_usersOf as usersOf, auth_whoami as whoami };
 }
 
-/**
- * Thin fetch wrapper: explicit timeout, auth headers, JSON in/out, typed errors.
- * The single choke point for every backend call — resources build on this.
- */
-
 interface RequestInitEx {
     method?: string;
     /** JSON body — serialized and Content-Type set automatically. */

package/dist/index.js

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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@openbkn/bkn-sdk",
-  "version": "0.1.1-alpha.1",
+  "version": "0.1.1-alpha.11",
   "description": "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22"
+    "node": ">=18"
   },
   "bin": {
     "openbkn": "./dist/cli.js"
@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
+    "@openbkn/bkn-sdk": "^0.1.1-alpha.3",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "csv-parse": "^6.2.1",