@extrovert.dev/sdk 0.1.0-pre.7 → 0.1.0-pre.9

package/README.md

@@ -30,7 +30,7 @@ for a stable release:
 npm install @extrovert.dev/sdk@next
 ```
 
-Pin `@extrovert.dev/sdk@0.1.0-pre.7` when a dogfood test needs a reproducible contract snapshot.
+Pin `@extrovert.dev/sdk@0.1.0-pre.9` when a dogfood test needs a reproducible contract snapshot.
 Requires Node 18+ for global `fetch` and Web Crypto.
 
 ## Build and use from source
@@ -529,7 +529,7 @@ a wire protocol (there is no `/v1/contract` endpoint).
 ```ts
 import { CONTRACT_VERSION, CONTRACT_MANIFEST } from "@extrovert.dev/sdk";
 
-CONTRACT_VERSION;            // "0.1.0-pre.7": provisional, pre-1.0; pin it
+CONTRACT_VERSION;            // "0.1.0-pre.9": provisional, pre-1.0; pin it
 CONTRACT_MANIFEST.stability; // "provisional"
 CONTRACT_MANIFEST.core_shapes; // ["ReviewIntent","ReviewFeedback","DiffJson","Rule","ReviewEvent"]
 ```
@@ -550,7 +550,7 @@ page and the agent skills (`extrovert-send-email`, `extrovert-writing-rules`).
 The Review-Loop shapes are an **open, documented contract: versioned *with* this SDK** (not a wire
 protocol; there is no `/v1/contract` endpoint). Three guarantees:
 
-- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.7`**, reconciled across the SDK package
+- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.9`**, reconciled across the SDK package
   version, the MCP server, and the OpenAPI `info.version`. Pin it; pin `CONTRACT_MANIFEST` for the
   exact shape set you built against.
 - **Named, documented types.** The five canonical shapes: `ReviewIntent`, `ReviewFeedback`,
@@ -581,7 +581,7 @@ EXTROVERT_API_BASE_URL=mock npx tsx examples/wait-for-otp.ts
 
 ## Status
 
-> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.7`: a
+> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.9`: a
 > deliberate **prerelease**, pre-1.0, expect additive change. The offline `mock` transport models the
 > live server closely enough to reproduce a 422 `intent_required` and a queued review, so build and
 > test against it before you have a key. Install from the `next` tag until a stable release is cut.

package/dist/index.cjs

@@ -268,7 +268,7 @@ var CURRENT_API_VERSION = "2026-06-23";
 var API_VERSION_HEADER = "Extrovert-Version";
 
 // src/http.ts
-var SDK_VERSION = "0.1.0-pre.7";
+var SDK_VERSION = "0.1.0-pre.9";
 function buildUrl(baseUrl, path, query) {
   const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   const rel = path.startsWith("/") ? path : `/${path}`;
@@ -938,6 +938,8 @@ ${parent.text}`;
 var MockBackend = class {
   constructor() {
     this.state = freshState();
+    /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    this.learnedRules = /* @__PURE__ */ new Map();
   }
   reset() {
     this.state = freshState();
@@ -1819,8 +1821,21 @@ var MockBackend = class {
    * is a pure lexical filter (every token must appear in name+description) - NO LLM,
    * mirroring the server.
    */
+  categoryUsage(category) {
+    const now2 = Date.now();
+    const rows = [...this.state.reviews.values()].filter((r) => r.category_id === category.id && Date.parse(r.created_at) <= now2);
+    const count = (days) => rows.filter((r) => Date.parse(r.created_at) >= now2 - days * 864e5).length;
+    return {
+      ...category,
+      message_count_7d: count(7),
+      message_count_30d: count(30),
+      message_count_90d: count(90),
+      last_used_at: rows.map((r) => r.created_at).sort().slice(-1)[0],
+      pending_review_count: rows.filter((r) => ["needs_review", "in_review", "chatting", "rejected", "stale", "approved"].includes(r.state)).length
+    };
+  }
   listCategories(params = {}) {
-    let items = [...this.state.categories.values()].filter((c) => !c.merged_into).sort((a, b) => b.created_at.localeCompare(a.created_at));
+    let items = [...this.state.categories.values()].filter((c) => !c.merged_into).map((c) => this.categoryUsage(c)).sort((a, b) => b.created_at.localeCompare(a.created_at));
     const tokens = (params.match ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
     if (tokens.length) {
       items = items.filter((c) => {
@@ -1828,15 +1843,22 @@ var MockBackend = class {
         return tokens.every((t) => hay.includes(t));
       });
     }
-    return { items, total: items.length };
+    const field = { messages_7d: "message_count_7d", messages_90d: "message_count_90d", pending_reviews: "pending_review_count" }[params.sort] ?? "message_count_30d";
+    items.sort((a, b) => (params.sort === "name" ? a.name.toLowerCase().localeCompare(b.name.toLowerCase()) : params.sort === "last_used" ? 0 : (b[field] ?? 0) - (a[field] ?? 0)) || (b.last_used_at ?? "").localeCompare(a.last_used_at ?? "") || a.id.localeCompare(b.id));
+    const offset = params.page ? JSON.parse(Buffer.from(params.page, "base64url").toString()).o : 0;
+    const total = items.length, limit = params.limit ?? 100;
+    const next = offset + limit < total ? Buffer.from(JSON.stringify({ o: offset + limit, v: 1 })).toString("base64url") : void 0;
+    return { items: items.slice(offset, offset + limit), total, next_cursor: next };
   }
   /** Get one category (mock), or undefined when not found. */
   getCategory(categoryId) {
-    return this.state.categories.get(categoryId);
+    const category = this.state.categories.get(categoryId);
+    return category ? this.categoryUsage(category) : void 0;
   }
   /** Propose a category (mock): stands immediately, author_kind=agent (D9). */
   proposeCategory(req) {
     const name = req.name.trim();
+    if ([...this.state.categories.values()].some((c) => !c.merged_into && c.name.toLowerCase() === name.toLowerCase())) throw new ConflictError({ status: 409, code: "conflict", message: "Category name already exists; browse and reuse it." });
     if (!name) {
       throw new ValidationError({ status: 400, code: "invalid", message: "name is required" });
     }
@@ -2042,7 +2064,27 @@ var MockBackend = class {
       composition_token_expires_at: params.scope ? void 0 : new Date(Date.now() + 6e5).toISOString()
     };
   }
-  /** Save / edit a rule (mock) - append-only by supersession (D11). */
+  learnReviewRule(reviewId, req) {
+    const fingerprint = JSON.stringify({ reviewId, req });
+    const prior = this.learnedRules.get(req.client_id);
+    if (prior) {
+      if (prior.fingerprint !== fingerprint) throw new ValidationError({ status: 409, code: "conflict", message: "learning retry identity changed" });
+      return structuredClone(prior.result);
+    }
+    const turn = (this.state.reviewTurns.get(reviewId) ?? []).find((t) => t.id === req.source_turn_id);
+    if (!turn || turn.actor_kind !== "human" || !turn.actor_id) throw new ValidationError({ status: 403, code: "forbidden_scope", message: "learning requires authenticated human feedback" });
+    const rule = this.saveRule({ ...req, scope: req.target === "category" ? "category" : "general", source_review_id: reviewId, source_turn_id: turn.id });
+    rule.source_turn_id = turn.id;
+    rule.rule_layer = req.target === "org_house" ? "org" : "project";
+    if (req.target === "org_house") delete rule.project_id;
+    rule.source_review_id = reviewId;
+    rule.source_turn_id = turn.id;
+    const audit = [...this.state.ruleAudit.values()].find((entry) => entry.entity_id === rule.id);
+    audit.after_json = ruleSnapshotJSON(rule);
+    const result = { rule, source_review_id: reviewId, source_turn_id: turn.id, human_id: turn.actor_id, audit_id: audit.id, propagation: "queued" };
+    this.learnedRules.set(req.client_id, { fingerprint, result: structuredClone(result) });
+    return result;
+  }
   saveRule(req) {
     const text = req.rule_text.trim();
     if (!text) {
@@ -3683,6 +3725,7 @@ var HttpTransport = class {
       state: Array.isArray(params.state) ? params.state.join(",") : params.state,
       category_id: params.category_id,
       inbox: params.inbox,
+      composer: params.composer,
       limit: params.limit,
       page: params.page
     };
@@ -3765,10 +3808,12 @@ var HttpTransport = class {
     });
   }
   waitForReviewEvent(params, signal) {
+    const waitSeconds = Math.min(55, Math.max(1, params.wait_seconds ?? 55));
     return this.call({
       method: "GET",
       path: "/v1/reviews/events/wait",
-      query: { review_id: params.review_id, limit: params.limit, wait_seconds: params.wait_seconds },
+      query: { review_id: params.review_id, limit: params.limit, wait_seconds: waitSeconds },
+      timeoutMs: (waitSeconds + 10) * 1e3,
       signal
     });
   }
@@ -3781,7 +3826,7 @@ var HttpTransport = class {
     });
   }
   listCategories(params, signal) {
-    return this.call({ method: "GET", path: "/v1/categories", query: { match: params.match }, signal });
+    return this.call({ method: "GET", path: "/v1/categories", query: { ...params }, signal });
   }
   getCategory(categoryId, signal) {
     return this.call({ method: "GET", path: `/v1/categories/${encodeURIComponent(categoryId)}`, signal });
@@ -3837,6 +3882,9 @@ var HttpTransport = class {
       signal
     });
   }
+  learnReviewRule(reviewId, req, signal) {
+    return this.call({ method: "POST", path: `/v1/reviews/${encodeURIComponent(reviewId)}/learned-rules`, body: req, signal });
+  }
   saveRule(req, signal) {
     return this.call({
       method: "PUT",
@@ -4244,6 +4292,9 @@ var MockTransport = class {
   async getRules(params) {
     return this.backend.getRules(params);
   }
+  async learnReviewRule(reviewId, req) {
+    return this.backend.learnReviewRule(reviewId, req);
+  }
   async saveRule(req) {
     return this.backend.saveRule(req);
   }
@@ -5273,6 +5324,10 @@ var Rules = class {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  /** Learn category or organization house rules from verified human review feedback. */
+  learnFromReview(reviewId, req, signal) {
+    return this.ctx.transport.learnReviewRule(reviewId, req, signal);
+  }
   /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
   get(params = {}, signal) {
     return this.ctx.transport.getRules(params, signal);
@@ -5280,8 +5335,8 @@ var Rules = class {
   /**
    * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
    * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-   * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
-   * rules in v1: that is a console/admin action.
+   * key's project. For all authenticated reviewer feedback use learnFromReview at the intended
+   * organization, project, or category scope. This method is project maintenance only.
    */
   save(req, signal) {
     return this.ctx.transport.saveRule(req, signal);
@@ -5558,7 +5613,7 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.7";
+var CONTRACT_VERSION = "0.1.0-pre.9";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,
@@ -5589,6 +5644,8 @@ var CONTRACT_MANIFEST = {
     // realtime (M3)
     "ReviewEventReason",
     "ReviewEventsResult",
+    "LearnReviewRuleRequest",
+    "LearnedReviewRule",
     "ReviewEventCursor",
     // chat / revision / restamp (M5/M7)
     "PostReviewChatRequest",