@aithos/sdk 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.0";
+export declare const VERSION = "0.1.0-alpha.2";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -6,7 +6,7 @@ export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
-export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, } from "./wallet.js";
+export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
 export * as ethos from "./ethos.js";
 export * as onboarding from "./onboarding.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.0";
+export const VERSION = "0.1.0-alpha.2";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";

package/dist/src/sdk.js

@@ -47,6 +47,8 @@ export class AithosSDK {
             fetch: fetchImpl,
         });
         this.wallet = new WalletNamespace({
+            identity: config.identity,
+            appDid: config.appDid,
             userDid: config.identity.did,
             endpoints: this.endpoints,
             fetch: fetchImpl,

package/dist/src/wallet.d.ts

@@ -1,3 +1,4 @@
+import { type BrowserIdentity } from "@aithos/protocol-client";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 /**
  * Canonical credit-pack identifiers. Pricing and microcredit amounts are
@@ -24,7 +25,30 @@ export interface CreateTopupSessionResult {
     /** Stripe Checkout session id (for diagnostics). */
     readonly sessionId: string;
 }
+export interface GetBalanceArgs {
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+export interface GetBalanceResult {
+    /** Current wallet balance in microcredits. 0 if the wallet does not yet exist. */
+    readonly balance: number;
+    /**
+     * Microcredits spent today. Resets server-side at midnight UTC.
+     * Useful for showing "X / daily cap" UI.
+     */
+    readonly dailySpent: number;
+    /**
+     * Whether a wallet row exists for this DID. False on a never-funded
+     * identity — `balance` will be 0 in that case.
+     */
+    readonly exists: boolean;
+}
 export interface WalletNamespaceDeps {
+    /** User identity — needed to sign the balance-lookup envelope. */
+    readonly identity: BrowserIdentity;
+    /** App DID — sent as audit attribution alongside the balance request. */
+    readonly appDid: string;
+    /** Pre-resolved DID convenience accessor (mirrors identity.did). */
     readonly userDid: string;
     readonly endpoints: AithosSdkEndpoints;
     readonly fetch: typeof fetch;
@@ -45,5 +69,23 @@ export declare class WalletNamespace {
      * use the same DID.
      */
     createTopupSession(args: CreateTopupSessionArgs): Promise<CreateTopupSessionResult>;
+    /**
+     * Read the user's current wallet balance.
+     *
+     * Routed through the compute proxy at `${compute}/v1/invoke` because
+     * that's where the Aithos-platform DDB IAM lives — keeps the wallet
+     * Lambda focused on Stripe and avoids granting read-on-wallet to a
+     * second function. The call is gated by the same signed-envelope
+     * verification as `invokeBedrock`: only the owner of the user's
+     * `#public` key can read their balance.
+     *
+     * Returns `{ balance: 0, exists: false, dailySpent: 0 }` for an
+     * identity that has never been funded — the call still succeeds,
+     * the row just doesn't exist yet.
+     *
+     * @throws {AithosSDKError} on protocol errors (network, http,
+     *   envelope-verify failures from the proxy).
+     */
+    getBalance(args?: GetBalanceArgs): Promise<GetBalanceResult>;
 }
 //# sourceMappingURL=wallet.d.ts.map

package/dist/src/wallet.js

@@ -1,17 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Wallet namespace — Stripe Checkout for credit-pack top-ups.
+// Wallet namespace — credit-pack top-ups (Stripe) and balance lookup.
 //
-// Posts to `${wallet}/v1/wallet/topup/checkout`. The Lambda creates a
-// Stripe Checkout session bound to the user's DID via `metadata`, returns
-// the hosted URL. The frontend then redirects the user. Stripe webhook
-// (server-side) credits the wallet on `checkout.session.completed`.
-//
-// v0 scope: no envelope verify on the checkout endpoint — the link is
-// single-use and metadata-bound to `user_did`. Anyone creating a session
-// for someone else's DID would just gift them credits, no value to an
-// attacker. Envelope-verify gets added in a follow-up if abuse appears.
-import { walletTopupCheckoutUrl, } from "./endpoints.js";
+// Two methods:
+//   - createTopupSession() — posts to `${wallet}/v1/wallet/topup/checkout`
+//     to create a Stripe Checkout session. The Lambda binds the session
+//     to the user's DID via metadata; the Stripe webhook credits the
+//     wallet on `checkout.session.completed`. No envelope verify on this
+//     endpoint at v0 (the link is single-use and metadata-bound — anyone
+//     creating a session for someone else's DID just gifts them credits).
+//   - getBalance() — JSON-RPC `aithos.wallet_get_balance` against the
+//     compute proxy at `${compute}/v1/invoke`. Read-only DDB GetItem on
+//     the wallet table, gated by the same signed envelope verification
+//     as compute_invoke. Returns the current balance + daily spent.
+import { buildSignedEnvelope, } from "@aithos/protocol-client";
+import { computeInvokeUrl, walletTopupCheckoutUrl, } from "./endpoints.js";
 import { AithosSDKError } from "./types.js";
 /**
  * `sdk.wallet` namespace.
@@ -67,5 +70,67 @@ export class WalletNamespace {
         }
         return { checkoutUrl: ok.checkout_url, sessionId: ok.session_id };
     }
+    /**
+     * Read the user's current wallet balance.
+     *
+     * Routed through the compute proxy at `${compute}/v1/invoke` because
+     * that's where the Aithos-platform DDB IAM lives — keeps the wallet
+     * Lambda focused on Stripe and avoids granting read-on-wallet to a
+     * second function. The call is gated by the same signed-envelope
+     * verification as `invokeBedrock`: only the owner of the user's
+     * `#public` key can read their balance.
+     *
+     * Returns `{ balance: 0, exists: false, dailySpent: 0 }` for an
+     * identity that has never been funded — the call still succeeds,
+     * the row just doesn't exist yet.
+     *
+     * @throws {AithosSDKError} on protocol errors (network, http,
+     *   envelope-verify failures from the proxy).
+     */
+    async getBalance(args = {}) {
+        const { identity, appDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const url = computeInvokeUrl(endpoints);
+        const params = { app_did: appDid };
+        const envelope = buildSignedEnvelope({
+            iss: identity.did,
+            aud: url,
+            method: "aithos.wallet_get_balance",
+            verificationMethod: `${identity.did}#public`,
+            params,
+            signer: identity.public,
+        });
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: "aithos.wallet_get_balance",
+                    method: "aithos.wallet_get_balance",
+                    params: { ...params, _envelope: envelope },
+                }),
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        if (!res.ok) {
+            throw new AithosSDKError("http", `HTTP ${res.status} ${res.statusText}`, { status: res.status });
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new AithosSDKError(String(body.error.code), body.error.message, body.error.data ? { data: body.error.data } : undefined);
+        }
+        if (!body.result) {
+            throw new AithosSDKError("empty", "empty result from wallet_get_balance");
+        }
+        return {
+            balance: typeof body.result.balance === "number" ? body.result.balance : 0,
+            dailySpent: typeof body.result.dailySpent === "number" ? body.result.dailySpent : 0,
+            exists: body.result.exists === true,
+        };
+    }
 }
 //# sourceMappingURL=wallet.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",