@usepraxis/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,372 @@
+/**
+ * Signs the wallet-ownership challenge. Implement this to bridge any wallet:
+ * - Node / backend agents: use {@link keypairSigner} with a secret key.
+ * - Browser: wrap a wallet-adapter, e.g.
+ *   `{ address: wallet.publicKey.toBase58(), signMessage: (m) => wallet.signMessage(m) }`.
+ *
+ * `signMessage` must return the raw 64-byte Ed25519 signature; the SDK base58-
+ * encodes it for the API.
+ */
+interface PraxisSigner {
+    /** base58-encoded Solana public key. */
+    readonly address: string;
+    signMessage(message: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+type SecretKeyInput = Uint8Array | number[] | string;
+/**
+ * Build a {@link PraxisSigner} from a Solana secret key — a 64-byte keypair or a
+ * 32-byte seed, as raw bytes, a number array, or a base58 string (Phantom /
+ * `solana-keygen` export). Node and browser friendly; no `@solana/web3.js`
+ * dependency.
+ */
+declare function keypairSigner(secret: SecretKeyInput): PraxisSigner;
+
+/**
+ * Praxis SDK wire types — the JSON contract exposed by `/api/praxis/*`.
+ *
+ * MONEY RULE: every monetary value crosses the wire as a **decimal string of
+ * integer base units** (lamports for SOL, token base units for SPL) — never a
+ * float. On the server these are `bigint`; the API serializes them to strings.
+ * The SDK keeps them as strings and leaves bigint conversion to the caller
+ * (see `toBaseUnits` / `fromBaseUnits` in `units.ts`). This file intentionally
+ * mirrors `@praxis/shared` but with `string` money, so the SDK ships a
+ * self-contained type contract with no internal workspace dependency.
+ */
+/** A base58-encoded Solana public key. */
+type Address = string;
+/** Integer base units as a decimal string (e.g. "500000000" = 0.5 SOL). */
+type BaseUnitString = string;
+/** Mirrors the on-chain `ActionKind` discriminants. */
+declare enum ActionKind {
+    Transfer = 0,
+    TransferSpl = 1
+}
+/** Why Aegis rejected an agent action. Mirrors the on-chain enum order. */
+declare enum RejectReason {
+    Unauthorized = 0,
+    Paused = 1,
+    Expired = 2,
+    OverPerTx = 3,
+    OverDaily = 4,
+    RecipientNotAllowed = 5,
+    Overflow = 6,
+    MintNotAllowed = 7
+}
+/** Returned by `POST /auth/challenge`; sign `message` to prove wallet ownership. */
+interface WalletChallenge {
+    address: Address;
+    /** Opaque signed token echoed back to `/auth/verify`. */
+    nonce: string;
+    /** The exact UTF-8 string the wallet must sign. */
+    message: string;
+    /** ISO-8601 expiry of the challenge. */
+    expiresAt: string;
+}
+interface SessionInfo {
+    authenticated: boolean;
+    walletAddress: Address;
+}
+interface TokenInfo {
+    symbol: string;
+    mint: Address;
+    decimals: number;
+    verified: boolean;
+}
+interface AddressBookEntry {
+    label: string;
+    name: string;
+    address: Address;
+    note?: string;
+}
+interface PolicyView {
+    address: Address;
+    owner: Address;
+    /** `11111…1111` (default) once the agent key is revoked. */
+    agentAuthority: Address;
+    maxPerTx: BaseUnitString;
+    dailyLimit: BaseUnitString;
+    spentToday: BaseUnitString;
+    dayStartTs: number;
+    allowedPrograms: Address[];
+    /** Empty array means "any recipient allowed". */
+    allowedRecipients: Address[];
+    allowedMints: Address[];
+    expiryTs: number;
+    paused: boolean;
+    vaultBalance: BaseUnitString;
+    tokenMint: Address;
+    tokenMaxPerTx: BaseUnitString;
+    tokenDailyLimit: BaseUnitString;
+    tokenSpentToday: BaseUnitString;
+    tokenDayStartTs: number;
+}
+interface PolicyCheckResult {
+    allowed: boolean;
+    reason?: string;
+    reasonCode?: RejectReason;
+    spentToday: BaseUnitString;
+    dailyLimit: BaseUnitString;
+    remaining: BaseUnitString;
+}
+interface PolicyUpdate {
+    maxPerTx?: BaseUnitString;
+    dailyLimit?: BaseUnitString;
+    expiryTs?: number;
+    paused?: boolean;
+}
+interface TokenEnvelopeConfig {
+    tokenMint: Address;
+    tokenMaxPerTx: BaseUnitString;
+    tokenDailyLimit: BaseUnitString;
+}
+type AllowListKind = "programs" | "recipients" | "mints";
+interface TransferDetail {
+    kind: "transfer";
+    amount: BaseUnitString;
+    asset: TokenInfo;
+    recipientName: string;
+    recipientAddress: Address;
+    recipientNote?: string;
+}
+interface SwapDetail {
+    kind: "swap";
+    amountIn: BaseUnitString;
+    assetIn: TokenInfo;
+    estAmountOut: BaseUnitString;
+    assetOut: TokenInfo;
+    route: string;
+    priceImpactBps: number;
+}
+type ProposalDetail = TransferDetail | SwapDetail;
+type ProposalState = "pending" | "signing" | "signed" | "blocked" | "cancelled";
+interface ActionProposal {
+    id: string;
+    detail: ProposalDetail;
+    networkFee: BaseUnitString;
+    simulation: string;
+    check: PolicyCheckResult;
+    state: ProposalState;
+    sig?: string;
+}
+interface ClarifyOption {
+    label: string;
+    value: string;
+    hint?: string;
+}
+interface ResearchMetric {
+    label: string;
+    value: string;
+    trend?: "up" | "down" | "flat";
+}
+interface ResearchData {
+    token: string;
+    mint: Address;
+    metrics: ResearchMetric[];
+    summary: string;
+}
+type AgentBlock = {
+    type: "prose";
+    text: string;
+} | {
+    type: "clarify";
+    text: string;
+    options: ClarifyOption[];
+} | {
+    type: "proposal";
+    text: string;
+    proposalId: string;
+} | {
+    type: "research";
+    text: string;
+    data: ResearchData;
+};
+type UserMessage = {
+    id: string;
+    role: "user";
+    ts: number;
+    text: string;
+};
+type AgentMessage = {
+    id: string;
+    role: "agent";
+    ts: number;
+    blocks: AgentBlock[];
+};
+type Message = UserMessage | AgentMessage;
+interface Thread {
+    id: string;
+    title: string;
+    messages: Message[];
+    updatedAt: number;
+}
+interface ActivityEntry {
+    id: string;
+    kind: "transfer" | "swap";
+    label: string;
+    asset: string;
+    amount: BaseUnitString;
+    decimals: number;
+    result: "allowed" | "rejected";
+    reason?: string;
+    reasonCode?: RejectReason;
+    ts: number;
+    sig?: string;
+}
+interface UnsignedOwnerTransaction {
+    /** base64-encoded unsigned transaction for the owner wallet to sign. */
+    transaction: string;
+    blockhash: string;
+    lastValidBlockHeight: number;
+}
+/** Typed owner action accepted by `POST /owner/build`. */
+type OwnerAction = {
+    kind: "bootstrapPolicy";
+    fundLamports?: BaseUnitString;
+} | {
+    kind: "fundVault";
+    amount: BaseUnitString;
+} | {
+    kind: "withdrawVault";
+    amount: BaseUnitString;
+} | {
+    kind: "closePolicy";
+} | {
+    kind: "revoke";
+} | {
+    kind: "rotate";
+} | {
+    kind: "updatePolicy";
+    patch: PolicyUpdate;
+} | {
+    kind: "allowList";
+    listKind: AllowListKind;
+    address: Address;
+    mode: "add" | "remove";
+};
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface PraxisClientOptions {
+    /** Base origin of the Praxis deployment, e.g. "http://localhost:3000". */
+    baseUrl: string;
+    /** Wallet signer for `connect()`. Optional if you only call public reads after an external login. */
+    signer?: PraxisSigner;
+    /** Custom fetch (defaults to global fetch). Required in runtimes without one. */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms (default 20_000). */
+    timeoutMs?: number;
+}
+/** Result of {@link PraxisClient.ask} — the agent's reply, distilled. */
+interface AskResult {
+    threadId: string;
+    /** The agent's reply message (prose / clarify / proposal / research blocks). */
+    message: AgentMessage;
+    /** Any action proposals the agent produced, hydrated for convenience. */
+    proposals: ActionProposal[];
+}
+/**
+ * Typed client for a hosted Praxis agent. The agent's LLM, scoped agent key, and
+ * Aegis policy enforcement all live server-side; this SDK is an authenticated
+ * client of the `/api/praxis/*` surface.
+ *
+ * ```ts
+ * const praxis = new PraxisClient({ baseUrl, signer: keypairSigner(secret) });
+ * await praxis.connect();
+ * const { proposals } = await praxis.ask("send 0.5 SOL to maya");
+ * if (proposals[0]?.check.allowed) await praxis.signProposal(proposals[0].id);
+ * ```
+ */
+declare class PraxisClient {
+    private readonly baseUrl;
+    private readonly signer?;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    /** Manual cookie jar — Node's fetch does not persist Set-Cookie across calls. */
+    private sessionCookie?;
+    constructor(options: PraxisClientOptions);
+    /** The signer's wallet address, if a signer was provided. */
+    get address(): string | undefined;
+    /**
+     * Run the wallet-ownership handshake: request a challenge, sign its message,
+     * verify it, and store the resulting session cookie. Idempotent.
+     */
+    connect(): Promise<SessionInfo>;
+    /** Current session, or `null` if not signed in. */
+    session(): Promise<SessionInfo | null>;
+    /** Clear the session (server-side cookie + local jar). */
+    logout(): Promise<void>;
+    /** Send a line to the agent. Creates a thread when `threadId` is omitted. */
+    send(text: string, threadId?: string | null): Promise<{
+        threadId: string;
+    }>;
+    /**
+     * Send a line and return the agent's reply in one call. The API resolves
+     * `send` only after the agent has finished, so this needs no polling.
+     */
+    ask(text: string, threadId?: string | null): Promise<AskResult>;
+    newThread(threadId?: string): Promise<{
+        threadId: string;
+    }>;
+    signProposal(proposalId: string): Promise<void>;
+    cancelProposal(proposalId: string): Promise<void>;
+    getThreads(): Promise<Thread[]>;
+    getThread(id: string): Promise<Thread>;
+    getProposal(id: string): Promise<ActionProposal>;
+    getPolicy(): Promise<PolicyView>;
+    getActivity(): Promise<ActivityEntry[]>;
+    getAddressBook(): Promise<AddressBookEntry[]>;
+    isThinking(threadId: string): Promise<boolean>;
+    getVersion(): Promise<number>;
+    bootstrapPolicy(fundLamports?: BaseUnitString): Promise<void>;
+    updatePolicy(patch: PolicyUpdate): Promise<void>;
+    configureToken(config: TokenEnvelopeConfig): Promise<void>;
+    prepareTokenAccounts(recipientAddresses?: string[]): Promise<void>;
+    revokeAgent(): Promise<void>;
+    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. */
+    buildOwnerTransaction(action: OwnerAction): Promise<UnsignedOwnerTransaction>;
+    /** Submit a wallet-signed owner transaction. */
+    submitOwnerTransaction(signed: UnsignedOwnerTransaction): Promise<{
+        sig: string;
+    }>;
+    private get;
+    private post;
+    private request;
+    private captureCookie;
+}
+
+/**
+ * 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
+ * (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);
+    get isAuth(): boolean;
+    get isRateLimited(): boolean;
+    get isInput(): boolean;
+}
+/** Thrown for SDK-side misconfiguration (no fetch, no signer, bad key, …). */
+declare class PraxisConfigError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Money helpers. Praxis money crosses the wire as decimal strings of integer
+ * 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. */
+declare function toBaseUnits(value: string | bigint): bigint;
+/** Serialize a bigint (or number of whole base units) into a base-unit string. */
+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 };