@extrovert.dev/sdk 0.1.0-pre.16 → 0.1.0-pre.17

package/README.md

@@ -590,6 +590,23 @@ EXTROVERT_API_BASE_URL=mock npx tsx examples/wait-for-otp.ts
 
 MIT © Message Science. *A side gate for agents.*
 
+## Incoming-email activation
+
+When signup returns `activation_method: "incoming_email"`, ask the human to send an
+email from `human_email` to `address`. The inbox reservation expires at
+`activation_expires_at`. Keep the temporary key and call `activationStatus()` until
+`state` is `"proven"`, then call `verify({})` to receive the durable key. Pending keys
+cannot read or send mail. `correctActivationEmail(humanEmail, revision)` clears any
+previous proof and keeps the original deadline. Legacy signup responses that issued
+an OTP still require that OTP until its original expiry.
+
+Mail responses expose advisory `X-Extrovert-Storage-*` headers from 90% usage.
+Use the exported `storageWarningFromHeaders(response.headers)` in a custom fetch
+wrapper to read the threshold, byte counts, and cleanup/billing links without
+consuming the response body. A missing or unavailable measurement is not zero usage.
+Native writes enforce the cap; reads and deletion remain available. Deduplicate
+human-facing suggestions within your session instead of repeating them on every read.
+
 For choosing access and handing setup over to workers, read
 [Connections and access](https://docs.extrovert.dev/concepts/connections-and-access/).
 

package/dist/index.cjs

@@ -1122,11 +1122,31 @@ ${parent.text}`;
 }
 var MockBackend = class {
   constructor() {
+    this.incomingActivation = false;
     this.administrativeFixtures = new AdministrativeFixtures();
     this.state = freshState();
     /** Save / edit a rule (mock) - append-only by supersession (D11). */
     this.learnedRules = /* @__PURE__ */ new Map();
   }
+  activationStatus() {
+    const activation = this.pendingActivation;
+    if (!activation) throw new Error("No incoming-email activation exists");
+    if (activation.expires_ms <= Date.now() && activation.state !== "activated") activation.state = "expired";
+    return { ...activation };
+  }
+  correctActivationEmail(email, revision) {
+    const activation = this.activationStatus();
+    if (activation.revision !== revision || !["pending", "proven"].includes(activation.state)) throw new Error("Activation changed or expired");
+    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new Error("Invalid human email");
+    this.pendingActivation = { ...activation, human_email: email, revision: revision + 1, state: "pending" };
+    return this.activationStatus();
+  }
+  /** Test-only trusted delivery; never available through a production client. */
+  proveFixtureActivation(sender) {
+    const activation = this.activationStatus();
+    if (activation.state !== "pending" || sender !== activation.human_email) throw new Error("Activation sender mismatch or expired");
+    this.pendingActivation = { ...activation, state: "proven" };
+  }
   configureAdministrativeFixture(credential) {
     this.administrativeFixtures = new AdministrativeFixtures(credential);
   }
@@ -1172,6 +1192,10 @@ var MockBackend = class {
     const agentId = existing?.agentId ?? rid("agt");
     const address = existing?.address ?? `${validatedSharedLocalPart(req.username ?? randomHandle())}@${FREE_SHARED_DOMAIN}`;
     const otp = "492013";
+    if (this.incomingActivation) {
+      if (existing) throw new Error("Activation already pending; use the existing key");
+      this.pendingActivation = { agent_id: agentId, address, human_email: email, created_ms: Date.now(), expires_ms: Date.now() + 864e5, revision: 1, state: "pending" };
+    }
     this.state.signupByEmail.set(email, { customerId, agentId, address, otp, verified: false });
     return {
       customer_id: customerId,
@@ -1181,16 +1205,24 @@ var MockBackend = class {
       scopes: ["signup:verify"],
       address,
       verified: false,
-      otp_sent_to: email,
-      otp_expires_at: new Date(Date.now() + 15 * 60 * 1e3).toISOString(),
-      message: "A verification code was sent to your email. Call verify with it."
+      ...this.incomingActivation ? {
+        activation_method: "incoming_email",
+        human_email: email,
+        activation_expires_at: new Date(this.pendingActivation.expires_ms).toISOString(),
+        message: `Your agent\u2019s inbox is almost ready. Send an email from ${email} to ${address} to activate it and link it to your human email.`
+      } : {
+        otp_sent_to: email,
+        otp_expires_at: new Date(Date.now() + 15 * 60 * 1e3).toISOString(),
+        message: "A verification code was sent to your email. Call verify with it."
+      }
     };
   }
   /** Confirm a signup OTP and return a full-scope key (mock). */
   verify(req) {
     for (const [, s] of this.state.signupByEmail) {
-      if (!s.verified && s.otp === req.otp.trim()) {
+      if (!s.verified && (this.incomingActivation ? this.activationStatus().state === "proven" && this.pendingActivation?.agent_id === s.agentId : s.otp === (req.otp ?? "").trim())) {
         s.verified = true;
+        if (this.incomingActivation && this.pendingActivation) this.pendingActivation.state = "activated";
         return {
           agent_id: s.agentId,
           agent_key: `pk_agent_${s.agentId.slice(4)}_${rid("sk").slice(3)}`,
@@ -3564,6 +3596,12 @@ var HttpTransport = class {
   signUp(req, signal) {
     return this.call({ method: "POST", path: "/v1/agent/sign-up", body: req, signal });
   }
+  activationStatus(signal) {
+    return this.call({ method: "GET", path: "/v1/agent/activation", signal });
+  }
+  correctActivationEmail(human_email, revision, signal) {
+    return this.call({ method: "PATCH", path: "/v1/agent/activation", body: { human_email, revision }, signal });
+  }
   verify(req, signal) {
     return this.call({ method: "POST", path: "/v1/agent/verify", body: req, signal });
   }
@@ -4196,6 +4234,12 @@ var MockTransport = class {
   async signUp(req) {
     return this.backend.signUp(req);
   }
+  async activationStatus() {
+    return this.backend.activationStatus();
+  }
+  async correctActivationEmail(email, revision) {
+    return this.backend.correctActivationEmail(email, revision);
+  }
   async verify(req) {
     return this.backend.verify(req);
   }
@@ -5739,6 +5783,12 @@ var ExtrovertClient = class _ExtrovertClient {
    * Pending verification is also fail-closed with 403 `signup_disabled` while
    * free signup is paused.
    */
+  activationStatus(signal) {
+    return this.transport.activationStatus(signal);
+  }
+  correctActivationEmail(human_email, revision, signal) {
+    return this.transport.correctActivationEmail(human_email, revision, signal);
+  }
   verify(req, signal) {
     return this.transport.verify(req, signal);
   }
@@ -5906,7 +5956,7 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.16";
+var CONTRACT_VERSION = "0.1.0-pre.17";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,
@@ -5982,6 +6032,26 @@ var CONTRACT_MANIFEST = {
   skills: ["extrovert-send-email", "extrovert-writing-rules"]
 };
 
+// src/storage.ts
+function storageWarningFromHeaders(headers) {
+  if (headers.get("x-extrovert-storage-status") !== "available") return;
+  const threshold = Number(headers.get("x-extrovert-storage-threshold"));
+  if (!headers.has("x-extrovert-storage-used-bytes") || !headers.has("x-extrovert-storage-limit-bytes")) return;
+  const used = Number(headers.get("x-extrovert-storage-used-bytes"));
+  const limit = Number(headers.get("x-extrovert-storage-limit-bytes"));
+  if (![90, 95, 99, 100].includes(threshold) || !Number.isSafeInteger(used) || used < 0 || !Number.isSafeInteger(limit) || limit < 0) return;
+  const link = (name) => {
+    const raw = headers.get(name);
+    if (!raw || raw.length > 2048) return;
+    try {
+      const url = new URL(raw);
+      if (url.protocol === "https:" && !url.username && !url.password) return url.href;
+    } catch {
+    }
+  };
+  return { threshold, used_bytes: used, limit_bytes: limit, cleanup_url: link("x-extrovert-storage-cleanup-url"), billing_url: link("x-extrovert-storage-billing-url") };
+}
+
 exports.ADMINISTRATIVE_FIXTURE_KEY = ADMINISTRATIVE_FIXTURE_KEY;
 exports.API_VERSION_HEADER = API_VERSION_HEADER;
 exports.Administration = Administration;
@@ -6049,6 +6119,7 @@ exports.reviewIdOf = reviewIdOf;
 exports.sentMessageIdOf = sentMessageIdOf;
 exports.serializeInclude = serializeInclude;
 exports.signWebhook = signWebhook;
+exports.storageWarningFromHeaders = storageWarningFromHeaders;
 exports.threadIdOf = threadIdOf;
 exports.tierAllowsOrgWildcard = tierAllowsOrgWildcard;
 exports.tierNeedsExplicitBreadth = tierNeedsExplicitBreadth;