@usepraxis/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -64,7 +64,10 @@ interface WalletChallenge {
 }
 interface SessionInfo {
     authenticated: boolean;
+    /** The signed-in wallet (owner). Present whenever `authenticated` is true. */
     walletAddress: Address;
+    /** Unix seconds at which the session expires (from `GET /auth/session`). */
+    expiresAt?: number;
 }
 interface TokenInfo {
     symbol: string;
@@ -164,6 +167,11 @@ interface ResearchData {
     metrics: ResearchMetric[];
     summary: string;
 }
+interface PolicyChangeRow {
+    label: string;
+    from: string;
+    to: string;
+}
 type AgentBlock = {
     type: "prose";
     text: string;
@@ -179,6 +187,16 @@ type AgentBlock = {
     type: "research";
     text: string;
     data: ResearchData;
+} | {
+    type: "notice";
+    tone: "success" | "info";
+    text: string;
+} | {
+    type: "policy_change";
+    text: string;
+    patch: PolicyUpdate;
+    changes: PolicyChangeRow[];
+    applied: boolean;
 };
 type UserMessage = {
     id: string;
@@ -218,6 +236,14 @@ interface UnsignedOwnerTransaction {
     blockhash: string;
     lastValidBlockHeight: number;
 }
+/**
+ * An {@link UnsignedOwnerTransaction} after the owner wallet has signed it — the
+ * base64 `transaction` now carries the owner's signature. This is what you pass
+ * to {@link PraxisClient.submitOwnerTransaction}. Signing a Solana transaction
+ * requires a transaction-capable wallet (browser wallet adapter / `@solana/web3.js`);
+ * the SDK's `keypairSigner` only signs the sign-in *message*, not transactions.
+ */
+type SignedOwnerTransaction = UnsignedOwnerTransaction;
 /** Typed owner action accepted by `POST /owner/build`. */
 type OwnerAction = {
     kind: "bootstrapPolicy";
@@ -252,8 +278,14 @@ interface PraxisClientOptions {
     signer?: PraxisSigner;
     /** Custom fetch (defaults to global fetch). Required in runtimes without one. */
     fetch?: FetchLike;
-    /** Per-request timeout in ms (default 20_000). */
+    /** Per-request timeout in ms for reads/mutations (default 20_000). */
     timeoutMs?: number;
+    /**
+     * Per-request timeout in ms for agent conversation turns (`send`/`ask`), which
+     * block on the full LLM round-trip (default 60_000). Effective value is never
+     * below `timeoutMs`.
+     */
+    agentTimeoutMs?: number;
 }
 /** Result of {@link PraxisClient.ask} — the agent's reply, distilled. */
 interface AskResult {
@@ -280,6 +312,7 @@ declare class PraxisClient {
     private readonly signer?;
     private readonly fetchImpl;
     private readonly timeoutMs;
+    private readonly agentTimeoutMs;
     /** Manual cookie jar — Node's fetch does not persist Set-Cookie across calls. */
     private sessionCookie?;
     constructor(options: PraxisClientOptions);
@@ -287,12 +320,20 @@ declare class PraxisClient {
     get address(): string | undefined;
     /**
      * 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).
      */
     connect(): Promise<SessionInfo>;
-    /** 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`.
+     */
     session(): Promise<SessionInfo | null>;
-    /** 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.
+     */
     logout(): Promise<void>;
     /** Send a line to the agent. Creates a thread when `threadId` is omitted. */
     send(text: string, threadId?: string | null): Promise<{
@@ -317,6 +358,12 @@ declare class PraxisClient {
     isThinking(threadId: string): Promise<boolean>;
     getVersion(): Promise<number>;
     bootstrapPolicy(fundLamports?: BaseUnitString): Promise<void>;
+    /** Deposit SOL (lamports, base-unit string) from the owner into the vault. */
+    fundVault(amount: BaseUnitString): Promise<void>;
+    /** Withdraw SOL (lamports, base-unit string) from the vault to the owner. */
+    withdrawVault(amount: BaseUnitString): Promise<void>;
+    /** Tear the agent down — drain the vault and close the policy. Irreversible. */
+    deleteAgent(): Promise<void>;
     updatePolicy(patch: PolicyUpdate): Promise<void>;
     configureToken(config: TokenEnvelopeConfig): Promise<void>;
     prepareTokenAccounts(recipientAddresses?: string[]): Promise<void>;
@@ -324,10 +371,15 @@ declare class PraxisClient {
     rotateAgent(): Promise<void>;
     addToAllowList(kind: AllowListKind, address: string): Promise<void>;
     removeFromAllowList(kind: AllowListKind, address: string): Promise<void>;
-    /** 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: OwnerAction): Promise<UnsignedOwnerTransaction>;
-    /** Submit a wallet-signed owner transaction. */
-    submitOwnerTransaction(signed: UnsignedOwnerTransaction): Promise<{
+    /** Submit a wallet-signed owner transaction; resolves with its signature. */
+    submitOwnerTransaction(signed: SignedOwnerTransaction): Promise<{
         sig: string;
     }>;
     private get;
@@ -345,14 +397,28 @@ declare class PraxisApiError extends Error {
     readonly status: number;
     /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
     readonly type: string;
-    constructor(status: number, type: string, message: string);
+    constructor(status: number, type: string, message: string, options?: {
+        cause?: unknown;
+    });
     get isAuth(): boolean;
     get isRateLimited(): boolean;
     get isInput(): boolean;
+    /** Resource not found (404). */
+    get isNotFound(): boolean;
+    /** Server reported a configuration problem (503) — usually transient. */
+    get isConfig(): boolean;
+    /** The request timed out client-side before any HTTP response. */
+    get isTimeout(): boolean;
+    /** A connection-level failure (DNS, refused, TLS) before any HTTP response. */
+    get isNetwork(): boolean;
+    /** Any server-side failure (HTTP >= 500). */
+    get isServer(): boolean;
 }
 /** Thrown for SDK-side misconfiguration (no fetch, no signer, bad key, …). */
 declare class PraxisConfigError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 
 /**
@@ -360,13 +426,21 @@ declare class PraxisConfigError extends Error {
  * base units (lamports / token base units). These convert to/from `bigint` and
  * human decimal amounts without floats.
  */
-/** Parse a base-unit string (or bigint) into a bigint. */
+/**
+ * Parse a base-unit string (or bigint) into a bigint. Rejects floats, hex, and
+ * other non-decimal-integer input so the SDK and server agree on what a valid
+ * base-unit string is (mirrors the server's `parseUnits`).
+ */
 declare function toBaseUnits(value: string | bigint): bigint;
-/** Serialize a bigint (or number of whole base units) into a base-unit string. */
+/**
+ * Serialize a bigint (or a whole, safe-integer number of base units) into a
+ * base-unit string. A non-integer or unsafe `number` throws rather than
+ * silently losing precision.
+ */
 declare function fromBaseUnits(value: bigint | number): string;
 /** Convert a human decimal amount ("0.5") into base units for `decimals` places. */
 declare function humanToBaseUnits(amount: string, decimals: number): string;
 /** Convert base units into a human decimal string for `decimals` places. */
 declare function baseUnitsToHuman(value: string | bigint, decimals: number): string;
 
-export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };
+export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };

package/dist/index.d.ts

@@ -64,7 +64,10 @@ interface WalletChallenge {
 }
 interface SessionInfo {
     authenticated: boolean;
+    /** The signed-in wallet (owner). Present whenever `authenticated` is true. */
     walletAddress: Address;
+    /** Unix seconds at which the session expires (from `GET /auth/session`). */
+    expiresAt?: number;
 }
 interface TokenInfo {
     symbol: string;
@@ -164,6 +167,11 @@ interface ResearchData {
     metrics: ResearchMetric[];
     summary: string;
 }
+interface PolicyChangeRow {
+    label: string;
+    from: string;
+    to: string;
+}
 type AgentBlock = {
     type: "prose";
     text: string;
@@ -179,6 +187,16 @@ type AgentBlock = {
     type: "research";
     text: string;
     data: ResearchData;
+} | {
+    type: "notice";
+    tone: "success" | "info";
+    text: string;
+} | {
+    type: "policy_change";
+    text: string;
+    patch: PolicyUpdate;
+    changes: PolicyChangeRow[];
+    applied: boolean;
 };
 type UserMessage = {
     id: string;
@@ -218,6 +236,14 @@ interface UnsignedOwnerTransaction {
     blockhash: string;
     lastValidBlockHeight: number;
 }
+/**
+ * An {@link UnsignedOwnerTransaction} after the owner wallet has signed it — the
+ * base64 `transaction` now carries the owner's signature. This is what you pass
+ * to {@link PraxisClient.submitOwnerTransaction}. Signing a Solana transaction
+ * requires a transaction-capable wallet (browser wallet adapter / `@solana/web3.js`);
+ * the SDK's `keypairSigner` only signs the sign-in *message*, not transactions.
+ */
+type SignedOwnerTransaction = UnsignedOwnerTransaction;
 /** Typed owner action accepted by `POST /owner/build`. */
 type OwnerAction = {
     kind: "bootstrapPolicy";
@@ -252,8 +278,14 @@ interface PraxisClientOptions {
     signer?: PraxisSigner;
     /** Custom fetch (defaults to global fetch). Required in runtimes without one. */
     fetch?: FetchLike;
-    /** Per-request timeout in ms (default 20_000). */
+    /** Per-request timeout in ms for reads/mutations (default 20_000). */
     timeoutMs?: number;
+    /**
+     * Per-request timeout in ms for agent conversation turns (`send`/`ask`), which
+     * block on the full LLM round-trip (default 60_000). Effective value is never
+     * below `timeoutMs`.
+     */
+    agentTimeoutMs?: number;
 }
 /** Result of {@link PraxisClient.ask} — the agent's reply, distilled. */
 interface AskResult {
@@ -280,6 +312,7 @@ declare class PraxisClient {
     private readonly signer?;
     private readonly fetchImpl;
     private readonly timeoutMs;
+    private readonly agentTimeoutMs;
     /** Manual cookie jar — Node's fetch does not persist Set-Cookie across calls. */
     private sessionCookie?;
     constructor(options: PraxisClientOptions);
@@ -287,12 +320,20 @@ declare class PraxisClient {
     get address(): string | undefined;
     /**
      * 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).
      */
     connect(): Promise<SessionInfo>;
-    /** 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`.
+     */
     session(): Promise<SessionInfo | null>;
-    /** 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.
+     */
     logout(): Promise<void>;
     /** Send a line to the agent. Creates a thread when `threadId` is omitted. */
     send(text: string, threadId?: string | null): Promise<{
@@ -317,6 +358,12 @@ declare class PraxisClient {
     isThinking(threadId: string): Promise<boolean>;
     getVersion(): Promise<number>;
     bootstrapPolicy(fundLamports?: BaseUnitString): Promise<void>;
+    /** Deposit SOL (lamports, base-unit string) from the owner into the vault. */
+    fundVault(amount: BaseUnitString): Promise<void>;
+    /** Withdraw SOL (lamports, base-unit string) from the vault to the owner. */
+    withdrawVault(amount: BaseUnitString): Promise<void>;
+    /** Tear the agent down — drain the vault and close the policy. Irreversible. */
+    deleteAgent(): Promise<void>;
     updatePolicy(patch: PolicyUpdate): Promise<void>;
     configureToken(config: TokenEnvelopeConfig): Promise<void>;
     prepareTokenAccounts(recipientAddresses?: string[]): Promise<void>;
@@ -324,10 +371,15 @@ declare class PraxisClient {
     rotateAgent(): Promise<void>;
     addToAllowList(kind: AllowListKind, address: string): Promise<void>;
     removeFromAllowList(kind: AllowListKind, address: string): Promise<void>;
-    /** 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: OwnerAction): Promise<UnsignedOwnerTransaction>;
-    /** Submit a wallet-signed owner transaction. */
-    submitOwnerTransaction(signed: UnsignedOwnerTransaction): Promise<{
+    /** Submit a wallet-signed owner transaction; resolves with its signature. */
+    submitOwnerTransaction(signed: SignedOwnerTransaction): Promise<{
         sig: string;
     }>;
     private get;
@@ -345,14 +397,28 @@ declare class PraxisApiError extends Error {
     readonly status: number;
     /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
     readonly type: string;
-    constructor(status: number, type: string, message: string);
+    constructor(status: number, type: string, message: string, options?: {
+        cause?: unknown;
+    });
     get isAuth(): boolean;
     get isRateLimited(): boolean;
     get isInput(): boolean;
+    /** Resource not found (404). */
+    get isNotFound(): boolean;
+    /** Server reported a configuration problem (503) — usually transient. */
+    get isConfig(): boolean;
+    /** The request timed out client-side before any HTTP response. */
+    get isTimeout(): boolean;
+    /** A connection-level failure (DNS, refused, TLS) before any HTTP response. */
+    get isNetwork(): boolean;
+    /** Any server-side failure (HTTP >= 500). */
+    get isServer(): boolean;
 }
 /** Thrown for SDK-side misconfiguration (no fetch, no signer, bad key, …). */
 declare class PraxisConfigError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 
 /**
@@ -360,13 +426,21 @@ declare class PraxisConfigError extends Error {
  * base units (lamports / token base units). These convert to/from `bigint` and
  * human decimal amounts without floats.
  */
-/** Parse a base-unit string (or bigint) into a bigint. */
+/**
+ * Parse a base-unit string (or bigint) into a bigint. Rejects floats, hex, and
+ * other non-decimal-integer input so the SDK and server agree on what a valid
+ * base-unit string is (mirrors the server's `parseUnits`).
+ */
 declare function toBaseUnits(value: string | bigint): bigint;
-/** Serialize a bigint (or number of whole base units) into a base-unit string. */
+/**
+ * Serialize a bigint (or a whole, safe-integer number of base units) into a
+ * base-unit string. A non-integer or unsafe `number` throws rather than
+ * silently losing precision.
+ */
 declare function fromBaseUnits(value: bigint | number): string;
 /** Convert a human decimal amount ("0.5") into base units for `decimals` places. */
 declare function humanToBaseUnits(amount: string, decimals: number): string;
 /** Convert base units into a human decimal string for `decimals` places. */
 declare function baseUnitsToHuman(value: string | bigint, decimals: number): string;
 
-export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };
+export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };

package/dist/index.js

@@ -8,8 +8,8 @@ var PraxisApiError = class _PraxisApiError extends Error {
   status;
   /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
   type;
-  constructor(status, type, message) {
-    super(message);
+  constructor(status, type, message, options) {
+    super(message, options);
     this.name = "PraxisApiError";
     this.status = status;
     this.type = type;
@@ -24,10 +24,30 @@ 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;
+  }
 };
 var PraxisConfigError = class _PraxisConfigError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = "PraxisConfigError";
     Object.setPrototypeOf(this, _PraxisConfigError.prototype);
   }
@@ -40,6 +60,7 @@ var PraxisClient = class {
   signer;
   fetchImpl;
   timeoutMs;
+  agentTimeoutMs;
   /** Manual cookie jar — Node's fetch does not persist Set-Cookie across calls. */
   sessionCookie;
   constructor(options) {
@@ -52,6 +73,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. */
@@ -60,7 +82,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) {
@@ -76,24 +99,37 @@ var PraxisClient = class {
       signature: bs582.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
@@ -148,6 +184,18 @@ var PraxisClient = class {
   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 });
   }
@@ -170,11 +218,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);
   }
@@ -182,8 +235,8 @@ 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 });
   }
   async request(method, path, opts = {}) {
     const url = new URL(this.baseUrl + API_PREFIX + path);
@@ -191,8 +244,9 @@ var PraxisClient = class {
     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(), {
@@ -205,9 +259,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);
     }
@@ -269,6 +327,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;
@@ -282,10 +343,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) {