@bunbase-ae/js 3.0.1-next.403.265841b → 3.0.1-next.407.08bf4a7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "3.0.1-next.403.265841b",
+  "version": "3.0.1-next.407.08bf4a7",
   "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 ──────────────────────────────────────────────────────────────
@@ -1387,6 +1452,21 @@ export type HookEvent =
   | "beforeDelete"
   | "afterDelete";
 
+/**
+ * Per-hook delivery options (issue #682). `mode: "durable"` persists each
+ * after-hook delivery before its first attempt and retries with backoff until
+ * acked or dead-lettered, surviving restarts. Default is fire-and-forget.
+ */
+export interface HookDeliveryConfig {
+  mode?: "fire_and_forget" | "durable";
+  /** Max attempts before dead-lettering (durable mode). Default 10. */
+  max_retries?: number;
+  /** Per-attempt request timeout in ms. Default 10000. */
+  timeout_ms?: number;
+  /** Park exhausted deliveries in the dead-letter store for replay. Default true. */
+  dead_letter?: boolean;
+}
+
 export interface HookConfig {
   id: string;
   collection: string;
@@ -1397,6 +1477,8 @@ export interface HookConfig {
   timeout_ms: number;
   enabled: boolean;
   sort_order: number;
+  /** Durable-delivery options, or null for legacy fire-and-forget (#682). */
+  delivery?: HookDeliveryConfig | null;
   created_at: number;
 }
 
@@ -1412,10 +1494,35 @@ export interface CreateHookInput {
   enabled?: boolean;
   /** Ascending order for hooks sharing the same (collection, event). Default 0. */
   sort_order?: number;
+  /** Durable, at-least-once delivery options (after-hooks only). (#682) */
+  delivery?: HookDeliveryConfig | null;
 }
 
 export type UpdateHookInput = Partial<Omit<CreateHookInput, "collection" | "event">>;
 
+/** Status of a durable delivery as surfaced to the admin replay API (#682). */
+export type WebhookDeliveryStatus = "pending" | "in_flight" | "delivered" | "dead_letter";
+
+/** Admin-facing view of a durable delivery. The signing secret is never included. */
+export interface WebhookDeliverySummary {
+  id: string;
+  idempotency_key: string;
+  hook_id: string | null;
+  collection: string;
+  event: string;
+  url: string;
+  has_secret: boolean;
+  status: WebhookDeliveryStatus;
+  attempts: number;
+  max_attempts: number;
+  timeout_ms: number;
+  next_attempt_at: number;
+  last_error: string | null;
+  last_status: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
 class AdminHooksClient {
   constructor(private readonly http: HttpClient) {}
 
@@ -1453,6 +1560,37 @@ class AdminHooksClient {
   async delete(id: string): Promise<void> {
     await this.http.request("DELETE", `/api/v1/admin/hooks/${encodeURIComponent(id)}`);
   }
+
+  /**
+   * List durable deliveries (issue #682). `status: "pending"` returns rows
+   * still in the live queue; `status: "dead_letter"` returns exhausted
+   * deliveries parked for inspection/replay. Secrets are never returned.
+   */
+  async deliveries(opts?: {
+    status?: "pending" | "dead_letter";
+    limit?: number;
+  }): Promise<WebhookDeliverySummary[]> {
+    const query: Record<string, string> = {};
+    if (opts?.status) query.status = opts.status;
+    if (opts?.limit != null) query.limit = String(opts.limit);
+    const res = await this.http.request<{ items: WebhookDeliverySummary[] }>(
+      "GET",
+      "/api/v1/admin/hooks/deliveries",
+      { query },
+    );
+    return res.items;
+  }
+
+  /**
+   * Replay a durable delivery (issue #682) — re-arm a queue row or re-enqueue
+   * a dead-letter row back to pending. Returns the (possibly new) queue id.
+   */
+  async replayDelivery(id: string): Promise<{ id: string; source: "queue" | "dead_letter" }> {
+    return this.http.request<{ id: string; source: "queue" | "dead_letter" }>(
+      "POST",
+      `/api/v1/admin/hooks/deliveries/${encodeURIComponent(id)}/replay`,
+    );
+  }
 }
 
 // Tenant membership management — surfaces the /api/v1/admin/tenants/* endpoints