@usepraxis/sdk 0.1.1 → 0.5.0

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;
@@ -127,6 +130,14 @@ interface TransferDetail {
     recipientName: string;
     recipientAddress: Address;
     recipientNote?: string;
+    /** The destination is the owner's own wallet (derived from the address). */
+    toSelf?: true;
+    /**
+     * Server-computed USD value of `amount`, as a decimal string, when a real
+     * price is available. Absent means "not known" — display only, and never an
+     * input to base-unit math.
+     */
+    usdEstimate?: string;
 }
 interface SwapDetail {
     kind: "swap";
@@ -141,6 +152,14 @@ type ProposalDetail = TransferDetail | SwapDetail;
 type ProposalState = "pending" | "signing" | "signed" | "blocked" | "cancelled";
 interface ActionProposal {
     id: string;
+    /**
+     * Unix seconds when the proposal was produced. The signature gate refuses a
+     * proposal older than a week: the amount is fixed and Aegis enforces the
+     * envelope live, but the readings on it (fee, simulation, remaining
+     * envelope, USD figure) drift. Ask again for a fresh one. Absent on
+     * proposals created before this field existed.
+     */
+    createdAt?: number;
     detail: ProposalDetail;
     networkFee: BaseUnitString;
     simulation: string;
@@ -155,15 +174,51 @@ interface ClarifyOption {
 }
 interface ResearchMetric {
     label: string;
+    /** Already display-formatted, and abbreviated where a raw figure is unreadable. */
     value: string;
+    /** The full-precision figure behind an abbreviated `value`, when one was cut. */
+    exact?: string;
+    /** Why the metric is missing, or what it measures. */
+    note?: string;
     trend?: "up" | "down" | "flat";
 }
+/**
+ * One step in how a research card was produced. A card whose whole claim is
+ * "data, no advice" has to be able to show its working: "unavailable" means
+ * something different when an indexer has no pair than when an RPC refused
+ * the query.
+ */
+interface ResearchSource {
+    /** "Solana RPC", "Market data (…)", "PreStocks", "Token resolution". */
+    label: string;
+    status: "ok" | "partial" | "unavailable";
+    detail: string;
+}
 interface ResearchData {
     token: string;
+    /** Project name from the indexer, when it differs from the ticker. */
+    name?: string;
     mint: Address;
     metrics: ResearchMetric[];
+    /** How the card was produced, in the order the steps ran. */
+    sources?: ResearchSource[];
     summary: string;
 }
+/**
+ * Stocklana C07: one PreStocks entry from `GET /get-stock-universe`.
+ * Empty unless the server runs with `PRAXIS_STOCKS_ENABLED=1`.
+ */
+interface StockUniverseEntry {
+    symbol: string;
+    name: string;
+    mint: Address;
+    decimals: number;
+}
+interface PolicyChangeRow {
+    label: string;
+    from: string;
+    to: string;
+}
 type AgentBlock = {
     type: "prose";
     text: string;
@@ -179,6 +234,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;
@@ -203,6 +268,8 @@ interface ActivityEntry {
     id: string;
     kind: "transfer" | "swap";
     label: string;
+    /** Destination address for a transfer. Stable where `label` is a lookup. */
+    target?: Address;
     asset: string;
     amount: BaseUnitString;
     decimals: number;
@@ -212,12 +279,55 @@ interface ActivityEntry {
     ts: number;
     sig?: string;
 }
+/** When a recurring buy fires. `weekday`: 0=Sunday..6=Saturday (UTC). */
+type DcaCadence = {
+    type: "daily";
+} | {
+    type: "weekly";
+    weekday: number;
+} | {
+    type: "monthly";
+    day: number;
+};
+/**
+ * One recurring-buy schedule from `GET /get-schedules`. Each fire emits one
+ * transfer proposal through the same policy checks as a one-off buy — nothing
+ * ever auto-signs. Money is a base-unit string per the money rule above.
+ */
+interface DcaSchedule {
+    id: string;
+    asset: string;
+    amount: BaseUnitString;
+    decimals: number;
+    recipientAddress: Address;
+    recipientName: string;
+    cadence: DcaCadence;
+    /** Unix milliseconds of the next fire. */
+    nextFireTs: number;
+    createdAt: number;
+    threadId: string;
+}
 interface UnsignedOwnerTransaction {
     /** base64-encoded unsigned transaction for the owner wallet to sign. */
     transaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
+    /**
+     * Opaque, backend-signed fingerprint of this draft. Echo it back verbatim in
+     * {@link SignedOwnerTransaction}: the relay refuses any transaction that is
+     * not the one Praxis built, which is what keeps the server-side checks for
+     * this action from being skippable.
+     */
+    draft: string;
 }
+/**
+ * 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";
@@ -242,6 +352,14 @@ type OwnerAction = {
     listKind: AllowListKind;
     address: Address;
     mode: "add" | "remove";
+} | {
+    kind: "configureToken";
+    tokenMint: Address;
+    tokenMaxPerTx: BaseUnitString;
+    tokenDailyLimit: BaseUnitString;
+} | {
+    kind: "prepareTokenAccounts";
+    recipientAddresses?: Address[];
 };
 
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
@@ -252,8 +370,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 +404,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 +412,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<{
@@ -308,15 +441,46 @@ declare class PraxisClient {
     }>;
     signProposal(proposalId: string): Promise<void>;
     cancelProposal(proposalId: string): Promise<void>;
+    /** List recurring-buy schedules (each fire emits one proposal; never signs). */
+    getSchedules(): Promise<DcaSchedule[]>;
+    /** Stop a recurring-buy schedule. Unknown ids are a no-op (idempotent). */
+    cancelSchedule(scheduleId: string): Promise<void>;
+    /** Save (or rename) an address-book contact. Labels have no signing power. */
+    addContact(label: string, address: string): Promise<void>;
+    /** Remove a contact by address or label (case-insensitive, idempotent). */
+    removeContact(key: string): Promise<void>;
     getThreads(): Promise<Thread[]>;
     getThread(id: string): Promise<Thread>;
     getProposal(id: string): Promise<ActionProposal>;
+    /**
+     * 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(): Promise<ActionProposal[]>;
     getPolicy(): Promise<PolicyView>;
     getActivity(): Promise<ActivityEntry[]>;
     getAddressBook(): Promise<AddressBookEntry[]>;
-    isThinking(threadId: string): Promise<boolean>;
     getVersion(): Promise<number>;
+    /**
+     * 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(): Promise<StockUniverseEntry[]>;
+    /**
+     * 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).
+     */
+    getStockResearch(symbol: string): Promise<ResearchData>;
     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,35 +488,88 @@ 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;
     private post;
+    /**
+     * 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.
+     */
     private request;
+    private send1;
     private captureCookie;
 }
 
+/**
+ * A stable, machine-readable classification of a backend failure. Branch on
+ * this rather than on `message`, which is human prose and free to change.
+ * `client_error` is synthesized SDK-side for failures with no HTTP response
+ * (timeout, DNS, TLS).
+ */
+type PraxisErrorCode = "config_error" | "unauthorized" | "invalid_input" | "not_found"
+/** The wallet has no Aegis policy account yet — call `bootstrapPolicy`. */
+ | "policy_not_found" | "rate_limited"
+/** A concurrent writer changed this wallet's state first; reload and retry. */
+ | "conflict" | "internal_error" | "client_error";
 /**
  * Thrown when the Praxis API returns a non-2xx response. The backend's error
- * envelope is `{ error: string, type: string }` with a meaningful HTTP status
+ * envelope is `{ error, type, code, details? }` with a meaningful HTTP status
  * (400 input, 401 auth, 404 not-found, 429 rate-limit, 503 config, 500 other).
  */
 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);
+    /** Stable error classification — the field to branch on. */
+    readonly code: PraxisErrorCode;
+    /** Structured facts about the failure, e.g. `{ policyAddress }` for `policy_not_found`. */
+    readonly details?: Record<string, string | number | boolean>;
+    constructor(status: number, type: string, message: string, options?: {
+        cause?: unknown;
+        code?: PraxisErrorCode;
+        details?: Record<string, string | number | boolean>;
+    });
     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;
+    /** The wallet has no Aegis policy yet — the first-run state, not a fault. */
+    get isPolicyNotFound(): boolean;
+    /** A concurrent writer won; the call is safe to retry after a reload. */
+    get isConflict(): 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 +577,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 DcaCadence, type DcaSchedule, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisErrorCode, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type ResearchSource, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type StockUniverseEntry, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };