@usepraxis/sdk 0.1.1 → 0.5.0

package/README.md

@@ -33,6 +33,12 @@ for (const p of proposals) {
 }
 ```
 
+A proposal stays signable for a week. Its amount is fixed when it is built and
+Aegis enforces the envelope live at submit, so an older card still moves
+exactly what it says — what drifts are the readings on it (fee, simulated
+outcome, remaining daily envelope). Past a week the backend refuses it and you
+ask again.
+
 `ask()` returns once the agent has finished — the API resolves `send` only after
 the reply is ready, so there is no polling.
 
@@ -47,6 +53,12 @@ the reply is ready, so there is no polling.
 
 The signed-in wallet is the **owner** whose Aegis policy PDA scopes everything.
 
+Sessions are short on purpose — holding one is enough to move value *within*
+the Aegis envelope, with no further wallet signature — so a long-running
+process will outlive its cookie. When a signer is configured, the SDK runs the
+handshake again on a `401` and retries the call once; you do not need your own
+reconnect loop. Without a signer, the `401` is returned as-is.
+
 ## Signers
 
 Provide any `PraxisSigner` — `{ address, signMessage(bytes) }`.
@@ -83,14 +95,35 @@ toBaseUnits("500000000");            // 500000000n
 |------|---------|
 | Auth | `connect()`, `session()`, `logout()` |
 | Conversation | `ask()`, `send()`, `newThread()`, `signProposal()`, `cancelProposal()` |
-| Reads | `getPolicy()`, `getThreads()`, `getThread()`, `getProposal()`, `getActivity()`, `getAddressBook()`, `isThinking()`, `getVersion()` |
-| Policy (server-key) | `bootstrapPolicy()`, `updatePolicy()`, `configureToken()`, `prepareTokenAccounts()`, `revokeAgent()`, `rotateAgent()`, `addToAllowList()`, `removeFromAllowList()` |
+| Reads | `getPolicy()`, `getThreads()`, `getThread()`, `getProposal()`, `getProposals()`, `getActivity()`, `getAddressBook()`, `getSchedules()`, `getVersion()` |
+| Contacts | `addContact()`, `removeContact()` — labels only, no signing power |
+| Recurring | `cancelSchedule()` — stop a recurring buy (fires only ever emit proposals) |
+| Policy (server-key) | `bootstrapPolicy()`, `fundVault()`, `withdrawVault()`, `updatePolicy()`, `configureToken()`, `prepareTokenAccounts()`, `revokeAgent()`, `rotateAgent()`, `addToAllowList()`, `removeFromAllowList()`, `deleteAgent()` |
 | Owner (wallet-signed) | `buildOwnerTransaction()`, `submitOwnerTransaction()` |
+| Stocks (PreStocks) | `getTokenUniverse()`, `getStockResearch()` — see `examples/stocks-dca.ts` |
+
+`session()` returns the current `SessionInfo` or `null` when signed out.
+
+> **Owner wallet-signed path.** `buildOwnerTransaction()` returns an *unsigned*
+> transaction; you sign it with a transaction-capable wallet (a browser wallet
+> adapter or `@solana/web3.js`) and submit the result with
+> `submitOwnerTransaction()`. The SDK's `keypairSigner` signs the sign-in
+> *message* only, not transactions — so a pure-Node owner-action flow must bring
+> its own transaction signer.
+>
+> Pass the whole draft back. Since **0.5.0** it carries a `draft` token: the
+> backend refuses to relay a transaction it did not build, which is what keeps
+> the server-side checks on an action (a token balance still in the vault, a
+> mint Aegis cannot drive) from being skippable by assembling your own bytes.
+> Mutate `transaction` only; leave the other fields alone.
 
 ## Errors
 
-Non-2xx responses throw `PraxisApiError` with `.status`, `.type`, and helpers
-`.isAuth` / `.isRateLimited` / `.isInput`.
+Non-2xx responses throw `PraxisApiError` with `.status`, `.type`, a stable
+`.code` to branch on, and helpers `.isAuth` / `.isRateLimited` / `.isInput` /
+`.isNotFound` / `.isConfig` / `.isConflict` / `.isPolicyNotFound` / `.isServer`. A client-side timeout or connection failure throws
+`PraxisApiError` with `.isTimeout` / `.isNetwork` (and `.status === 0`, with the
+original error on `.cause`). SDK-side misconfiguration throws `PraxisConfigError`.
 
 ```ts
 import { PraxisApiError } from "@usepraxis/sdk";

package/dist/index.cjs

@@ -15,11 +15,17 @@ var PraxisApiError = class _PraxisApiError extends Error {
   status;
   /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
   type;
-  constructor(status, type, message) {
-    super(message);
+  /** Stable error classification — the field to branch on. */
+  code;
+  /** Structured facts about the failure, e.g. `{ policyAddress }` for `policy_not_found`. */
+  details;
+  constructor(status, type, message, options) {
+    super(message, options);
     this.name = "PraxisApiError";
     this.status = status;
     this.type = type;
+    this.code = options?.code ?? codeFromStatus(status);
+    this.details = options?.details;
     Object.setPrototypeOf(this, _PraxisApiError.prototype);
   }
   get isAuth() {
@@ -31,10 +37,48 @@ var PraxisApiError = class _PraxisApiError extends Error {
   get isInput() {
     return this.status === 400;
   }
+  /** Resource not found (404). */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** Server reported a configuration problem (503) — usually transient. */
+  get isConfig() {
+    return this.status === 503;
+  }
+  /** The request timed out client-side before any HTTP response. */
+  get isTimeout() {
+    return this.status === 0 && this.type === "TimeoutError";
+  }
+  /** A connection-level failure (DNS, refused, TLS) before any HTTP response. */
+  get isNetwork() {
+    return this.status === 0 && this.type === "NetworkError";
+  }
+  /** Any server-side failure (HTTP >= 500). */
+  get isServer() {
+    return this.status >= 500;
+  }
+  /** The wallet has no Aegis policy yet — the first-run state, not a fault. */
+  get isPolicyNotFound() {
+    return this.code === "policy_not_found";
+  }
+  /** A concurrent writer won; the call is safe to retry after a reload. */
+  get isConflict() {
+    return this.code === "conflict";
+  }
 };
+function codeFromStatus(status) {
+  if (status === 400) return "invalid_input";
+  if (status === 401) return "unauthorized";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 429) return "rate_limited";
+  if (status === 503) return "config_error";
+  if (status === 0) return "client_error";
+  return "internal_error";
+}
 var PraxisConfigError = class _PraxisConfigError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = "PraxisConfigError";
     Object.setPrototypeOf(this, _PraxisConfigError.prototype);
   }
@@ -47,6 +91,7 @@ var PraxisClient = class {
   signer;
   fetchImpl;
   timeoutMs;
+  agentTimeoutMs;
   /** Manual cookie jar — Node's fetch does not persist Set-Cookie across calls. */
   sessionCookie;
   constructor(options) {
@@ -59,6 +104,7 @@ var PraxisClient = class {
     }
     this.fetchImpl = resolvedFetch;
     this.timeoutMs = options.timeoutMs ?? 2e4;
+    this.agentTimeoutMs = Math.max(options.agentTimeoutMs ?? 6e4, this.timeoutMs);
   }
   // --- auth ----------------------------------------------------------------
   /** The signer's wallet address, if a signer was provided. */
@@ -67,7 +113,8 @@ var PraxisClient = class {
   }
   /**
    * Run the wallet-ownership handshake: request a challenge, sign its message,
-   * verify it, and store the resulting session cookie. Idempotent.
+   * verify it, and store the resulting session cookie. Safe to call again to
+   * refresh the session (each call issues a new challenge + cookie).
    */
   async connect() {
     if (!this.signer) {
@@ -83,24 +130,37 @@ var PraxisClient = class {
       signature: bs582__default.default.encode(signature)
     });
   }
-  /** Current session, or `null` if not signed in. */
+  /**
+   * Current session, or `null` if not signed in. The endpoint answers `200`
+   * with `{ authenticated: false }` when signed out, so this normalizes both
+   * that shape and a `401` to `null`.
+   */
   async session() {
     try {
-      return await this.get("/auth/session");
+      const info = await this.get("/auth/session");
+      return info && info.authenticated ? info : null;
     } catch (error) {
       if (error instanceof PraxisApiError && error.isAuth) return null;
       throw error;
     }
   }
-  /** Clear the session (server-side cookie + local jar). */
+  /**
+   * Clear the session (server-side cookie + local jar). Idempotent: if there is
+   * no active session, the local jar is still cleared and no error is thrown.
+   */
   async logout() {
-    await this.request("DELETE", "/auth/session");
-    this.sessionCookie = void 0;
+    try {
+      await this.request("DELETE", "/auth/session");
+    } catch (error) {
+      if (!(error instanceof PraxisApiError && error.isAuth)) throw error;
+    } finally {
+      this.sessionCookie = void 0;
+    }
   }
   // --- conversation --------------------------------------------------------
   /** Send a line to the agent. Creates a thread when `threadId` is omitted. */
   send(text, threadId = null) {
-    return this.post("/send", { text, threadId });
+    return this.post("/send", { text, threadId }, this.agentTimeoutMs);
   }
   /**
    * Send a line and return the agent's reply in one call. The API resolves
@@ -114,7 +174,9 @@ var PraxisClient = class {
       throw new PraxisApiError(500, "Error", "Agent produced no reply message.");
     }
     const proposalIds = message.blocks.filter((b) => b.type === "proposal").map((b) => b.proposalId);
-    const proposals = await Promise.all(proposalIds.map((id) => this.getProposal(id)));
+    if (proposalIds.length === 0) return { threadId: tid, message, proposals: [] };
+    const byId = new Map((await this.getProposals()).map((p) => [p.id, p]));
+    const proposals = proposalIds.map((id) => byId.get(id)).filter((p) => p !== void 0);
     return { threadId: tid, message, proposals };
   }
   newThread(threadId) {
@@ -126,6 +188,22 @@ var PraxisClient = class {
   cancelProposal(proposalId) {
     return this.post("/cancel-proposal", { proposalId });
   }
+  /** List recurring-buy schedules (each fire emits one proposal; never signs). */
+  getSchedules() {
+    return this.get("/get-schedules");
+  }
+  /** Stop a recurring-buy schedule. Unknown ids are a no-op (idempotent). */
+  cancelSchedule(scheduleId) {
+    return this.post("/cancel-schedule", { scheduleId });
+  }
+  /** Save (or rename) an address-book contact. Labels have no signing power. */
+  addContact(label, address) {
+    return this.post("/add-contact", { label, address });
+  }
+  /** Remove a contact by address or label (case-insensitive, idempotent). */
+  removeContact(key) {
+    return this.post("/remove-contact", { key });
+  }
   // --- reads ---------------------------------------------------------------
   getThreads() {
     return this.get("/get-threads");
@@ -136,6 +214,14 @@ var PraxisClient = class {
   getProposal(id) {
     return this.get("/get-proposal", { id });
   }
+  /**
+   * Every proposal this wallet holds, in one request. Prefer this over a loop
+   * of {@link getProposal}: a per-id fetch is what trips the read rate limit
+   * on a busy thread.
+   */
+  getProposals() {
+    return this.get("/get-proposals");
+  }
   getPolicy() {
     return this.get("/get-policy");
   }
@@ -145,16 +231,47 @@ var PraxisClient = class {
   getAddressBook() {
     return this.get("/get-address-book");
   }
-  isThinking(threadId) {
-    return this.get("/is-thinking", { threadId });
-  }
   getVersion() {
     return this.get("/get-version");
   }
+  // --- stocks (PreStocks universe; empty unless the server enables it) ------
+  /**
+   * The server's stock universe (`[]` when `PRAXIS_STOCKS_ENABLED` is off).
+   * Read-only; symbols/mints here are the only pre-IPO stocks Praxis will
+   * touch (bounty exclusivity is enforced server-side).
+   */
+  getTokenUniverse() {
+    return this.get("/get-stock-universe");
+  }
+  /**
+   * Read-only research for a stock symbol, via the agent (`research <symbol>`).
+   * Returns neutral market data — never advice. Throws when the agent has no
+   * research to show (unknown symbol or unavailable quotes).
+   */
+  async getStockResearch(symbol) {
+    const { message } = await this.ask(`research ${symbol}`);
+    const block = message.blocks.find((b) => b.type === "research");
+    if (!block || block.type !== "research") {
+      throw new PraxisApiError(404, "NotFound", `No research available for ${symbol}.`);
+    }
+    return block.data;
+  }
   // --- policy / owner mutations (server-key mode) --------------------------
   bootstrapPolicy(fundLamports) {
     return this.post("/bootstrap-policy", fundLamports ? { fundLamports } : {});
   }
+  /** Deposit SOL (lamports, base-unit string) from the owner into the vault. */
+  fundVault(amount) {
+    return this.post("/fund-vault", { amount });
+  }
+  /** Withdraw SOL (lamports, base-unit string) from the vault to the owner. */
+  withdrawVault(amount) {
+    return this.post("/withdraw-vault", { amount });
+  }
+  /** Tear the agent down — drain the vault and close the policy. Irreversible. */
+  deleteAgent() {
+    return this.post("/delete-agent", {});
+  }
   updatePolicy(patch) {
     return this.post("/update-policy", { patch });
   }
@@ -177,11 +294,16 @@ var PraxisClient = class {
     return this.post("/remove-from-allow-list", { kind, address });
   }
   // --- owner wallet-signed transaction path --------------------------------
-  /** Build an unsigned owner transaction for the wallet to sign. */
+  /**
+   * Build an unsigned owner transaction for the wallet to sign. The caller signs
+   * the returned base64 `transaction` with a transaction-capable wallet, then
+   * passes the result to {@link submitOwnerTransaction}. (The SDK's
+   * `keypairSigner` signs sign-in messages only, not transactions.)
+   */
   buildOwnerTransaction(action) {
     return this.post("/owner/build", { action });
   }
-  /** Submit a wallet-signed owner transaction. */
+  /** Submit a wallet-signed owner transaction; resolves with its signature. */
   submitOwnerTransaction(signed) {
     return this.post("/owner/submit", signed);
   }
@@ -189,17 +311,41 @@ var PraxisClient = class {
   get(path, query) {
     return this.request("GET", path, { query });
   }
-  post(path, body) {
-    return this.request("POST", path, { body });
+  post(path, body, timeoutMs) {
+    return this.request("POST", path, { body, timeoutMs });
   }
+  /**
+   * Run a request, and if the session has expired, sign in again and retry it
+   * once.
+   *
+   * Sessions are deliberately short — holding one is enough to move value
+   * within the Aegis envelope — so a long-lived agent process WILL outlive its
+   * cookie. Without this, every caller writes the same catch-401-and-reconnect
+   * block, and the ones who do not simply stop working after a day. Retried
+   * once only, never for the auth endpoints themselves, and only when a signer
+   * is configured; without one there is nothing to re-authenticate with and the
+   * 401 is the honest answer.
+   */
   async request(method, path, opts = {}) {
+    try {
+      return await this.send1(method, path, opts);
+    } catch (error) {
+      const recoverable = error instanceof PraxisApiError && error.isAuth && Boolean(this.signer) && !path.startsWith("/auth/");
+      if (!recoverable) throw error;
+      this.sessionCookie = void 0;
+      await this.connect();
+      return this.send1(method, path, opts);
+    }
+  }
+  async send1(method, path, opts = {}) {
     const url = new URL(this.baseUrl + API_PREFIX + path);
     for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
     const headers = { accept: "application/json" };
     if (opts.body !== void 0) headers["content-type"] = "application/json";
     if (this.sessionCookie) headers["cookie"] = this.sessionCookie;
+    const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     let res;
     try {
       res = await this.fetchImpl(url.toString(), {
@@ -212,9 +358,13 @@ var PraxisClient = class {
       });
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new PraxisApiError(0, "TimeoutError", `Praxis request timed out after ${this.timeoutMs}ms`);
+        throw new PraxisApiError(0, "TimeoutError", `Praxis request timed out after ${timeoutMs}ms`, {
+          cause: error
+        });
       }
-      throw error;
+      if (error instanceof PraxisApiError) throw error;
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new PraxisApiError(0, "NetworkError", `Praxis request failed: ${detail}`, { cause: error });
     } finally {
       clearTimeout(timer);
     }
@@ -224,7 +374,10 @@ var PraxisClient = class {
     if (!res.ok) {
       const message = (parsed && typeof parsed === "object" && "error" in parsed && typeof parsed.error === "string" ? parsed.error : void 0) ?? `Praxis API error ${res.status}`;
       const type = parsed && typeof parsed === "object" && "type" in parsed && typeof parsed.type === "string" ? parsed.type : "Error";
-      throw new PraxisApiError(res.status, type, message);
+      const record = parsed && typeof parsed === "object" ? parsed : void 0;
+      const code = typeof record?.code === "string" ? record.code : void 0;
+      const details = record?.details && typeof record.details === "object" && !Array.isArray(record.details) ? record.details : void 0;
+      throw new PraxisApiError(res.status, type, message, { code, details });
     }
     return parsed;
   }
@@ -276,6 +429,9 @@ function normalizeSecret(secret) {
       throw new PraxisConfigError("secret key string must be base58-encoded");
     }
   } else if (Array.isArray(secret)) {
+    if (!secret.every((b) => Number.isInteger(b) && b >= 0 && b <= 255)) {
+      throw new PraxisConfigError("secret key array must contain only byte values (integers 0\u2013255)");
+    }
     bytes = Uint8Array.from(secret);
   } else {
     bytes = secret;
@@ -289,10 +445,19 @@ function normalizeSecret(secret) {
 }
 
 // src/units.ts
+var INTEGER_RE = /^-?\d+$/;
 function toBaseUnits(value) {
-  return typeof value === "bigint" ? value : BigInt(value.trim());
+  if (typeof value === "bigint") return value;
+  const trimmed = value.trim();
+  if (!INTEGER_RE.test(trimmed)) {
+    throw new Error(`toBaseUnits: expected an integer base-unit string, got "${value}"`);
+  }
+  return BigInt(trimmed);
 }
 function fromBaseUnits(value) {
+  if (typeof value === "number" && !Number.isSafeInteger(value)) {
+    throw new Error(`fromBaseUnits: number must be a safe integer, got ${value}`);
+  }
   return BigInt(value).toString();
 }
 function humanToBaseUnits(amount, decimals) {