@bunbase-ae/js 3.0.1-next.406.cb900dd → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "3.0.1-next.406.cb900dd",
+  "version": "3.1.0",
   "type": "module",
   "description": "TypeScript/JavaScript SDK for BunBase",
   "license": "UNLICENSED",

package/src/admin.ts

@@ -1307,6 +1307,40 @@ export interface CreateNamedQueryInput {
 
 export type UpdateNamedQueryInput = Partial<Omit<CreateNamedQueryInput, "name">>;
 
+// ─── Query Advisor (#481) ──────────────────────────────────────────────────────
+
+export interface QueryAdvisorCandidate {
+  /** Normalized RPC + filter/sort shape — never raw values. */
+  signature: string;
+  tenant_id: string | null;
+  call_count: number;
+  total_duration_ms: number;
+  avg_duration_ms: number;
+  p50_ms: number;
+  p99_ms: number;
+  last_seen: number;
+  cache_hit_estimate: number;
+  projected_savings_ms: number;
+}
+
+export interface AdvisorListResult {
+  /** False when the advisor is disabled — render the "Enable" CTA. */
+  enabled: boolean;
+  candidates: QueryAdvisorCandidate[];
+  settings: { enabled: boolean; sampleRate: number; retentionDays: number; topK: number };
+}
+
+export interface PromoteAdvisorInput {
+  name: string;
+  description?: string | null;
+  sql: string;
+  params?: Record<string, NamedQueryParamDef>;
+  access?: NamedQueryAccessRule;
+  result_cache_ttl_s?: number;
+  /** The originating advisor signature. Stamped so the suggestion disappears. */
+  signature: string;
+}
+
 class AdminNamedQueriesClient {
   constructor(private readonly http: HttpClient) {}
 
@@ -1375,6 +1409,37 @@ class AdminNamedQueriesClient {
       "/api/v1/admin/queries/install-starter",
     );
   }
+
+  // ─── Query Advisor (#481) ────────────────────────────────────────────────────
+
+  /**
+   * List the top hot read-pattern candidates the advisor suggests promoting
+   * into named queries, ranked by projected savings. `enabled` is false (with
+   * an empty list) when the advisor is turned off — surface the "Enable" CTA.
+   */
+  async advisorList(opts: { tenantId?: string | null } = {}): Promise<AdvisorListResult> {
+    const qs =
+      opts.tenantId !== undefined && opts.tenantId !== null
+        ? `?tenant_id=${encodeURIComponent(opts.tenantId)}`
+        : "";
+    return this.http.request<AdvisorListResult>("GET", `/api/v1/admin/queries/advisor${qs}`);
+  }
+
+  /** Enable the Query Advisor at runtime (existing-deployment opt-in). */
+  async advisorEnable(): Promise<{ enabled: boolean }> {
+    return this.http.request<{ enabled: boolean }>("POST", "/api/v1/admin/queries/advisor/enable");
+  }
+
+  /**
+   * Promote a captured signature into a named query. SQL/params are best-effort
+   * pre-filled by the caller (Studio derives them from the signature). Once
+   * promoted, the advisor stops suggesting that signature.
+   */
+  async advisorPromote(input: PromoteAdvisorInput): Promise<NamedQuery> {
+    return this.http.request<NamedQuery>("POST", "/api/v1/admin/queries/advisor/promote", {
+      body: input,
+    });
+  }
 }
 
 // ─── Write hooks ──────────────────────────────────────────────────────────────