@terminal3/t3n-sdk 4.12.0 → 4.14.0

package/dist/index.d.ts

@@ -1880,11 +1880,29 @@ declare class T3nClient {
      * entries. `kinds` filters by `TokenTxKind`; an empty array is
      * treated as "no filter".
      *
-     * Unlike {@link execute}, the body of this RPC is plaintext —
-     * `token.get-usage` is a session-authed read endpoint and the
-     * server-side handler does not run the encryption layer.
+     * Like {@link getAuditEvents} / {@link execute}, this runs the
+     * session-payload encryption: balance and ledger history are
+     * self-only data, so the request params and response are sealed to
+     * the session key rather than sent plaintext over TLS. (Transitional:
+     * the node still accepts the legacy plaintext shape during the
+     * staggered rollout, so a leaked `Session-Id` alone is not fully
+     * de-fanged on this endpoint until the sealed shape becomes
+     * mandatory.)
      */
     getUsage(opts?: GetUsageOptions): Promise<UsagePage>;
+    /**
+     * Fetch the caller's own credit row (`token.get-balance`).
+     *
+     * Like {@link getUsage} / {@link getAuditEvents}, this runs the
+     * session-payload encryption: the balance is self-only data, so the
+     * request (an empty sealed blob showing possession of the session
+     * key) and the response are sealed to the session key rather than
+     * sent plaintext over TLS. (Transitional: the node still accepts the
+     * legacy plaintext shape during the staggered rollout.) Prefer this
+     * over reading `getUsage().balance` when only the credit row is
+     * needed.
+     */
+    getBalance(): Promise<BalanceRow>;
     /**
      * List the caller's discoverable contracts (`contracts.list`) — the
      * node-backed source for the MCP `listContracts` funnel tool.
@@ -1896,8 +1914,9 @@ declare class T3nClient {
      * discovery-grant gated and return a uniform, non-disclosive empty page on a
      * gate miss (R5 anti-enumeration).
      *
-     * Plaintext session read (like {@link getUsage}): the response carries only
-     * public contract-registry metadata, so it is not sealed.
+     * Plaintext session read: the response carries only public
+     * contract-registry metadata (no PII), so it is not sealed — unlike
+     * the self-only reads {@link getUsage} / {@link getBalance}, which are.
      */
     listContracts(params?: ListContractsParams): Promise<ListContractsResult>;
     /**
@@ -1911,7 +1930,9 @@ declare class T3nClient {
      * and the verdict is uniform + non-disclosive (`disclosed:false`) when the
      * agent is not registered under the member (R5 anti-enumeration).
      *
-     * Plaintext session read (like {@link getUsage}).
+     * Plaintext session read: the verdict is uniform and non-disclosive,
+     * so it is not sealed (unlike the self-only reads {@link getUsage} /
+     * {@link getBalance}).
      */
     checkDelegation(params: GrantCheckParams): Promise<GrantCheckResult>;
     /**
@@ -1972,6 +1993,32 @@ declare class T3nClient {
      *   empty / too long)
      */
     createOrganisation(name: string): Promise<Did>;
+    /**
+     * Provision a fresh org-owned agent.
+     *
+     * Dispatches `create-agent` on `tee:organisation/contracts` over the
+     * standard authenticated `action.execute` path. The node injects the
+     * caller's DID into the contract call context, and the contract refuses
+     * unless the caller is listed as an admin of `organisationDid`. A brand
+     * new secp256k1 wallet is minted in-TEE for the agent; its eth-derived
+     * DID and its raw private key are both returned. The private key is the
+     * "authentication token" the MCP sidecar uses to authenticate as this
+     * agent (the existing `PRIVATE_KEY` eth auth mode) — it is generated and
+     * returned exactly once here and is never persisted or recoverable
+     * afterwards, so the caller must capture it immediately.
+     *
+     * @param organisationDid - the owning organisation's DID
+     *   (`did:t3n:<40-hex>`); the caller must be one of its admins
+     * @param name - human-readable agent name (1..=128 bytes)
+     * @returns the new agent's DID and its one-time private key
+     * @throws if the session is not authenticated, or if the contract
+     *   refuses (e.g. the caller is not an admin of `organisationDid`, or the
+     *   name is empty / too long)
+     */
+    createAgent(organisationDid: string, name: string): Promise<{
+        agentDid: Did;
+        privateKey: string;
+    }>;
     /**
      * Read the authenticated user's own agent-auth policy — the standing
      * grants delegated to agents. Dispatches `agent-auth-get` on
@@ -2458,8 +2505,10 @@ declare class T3nClient {
     /**
      * Send a session-authenticated JSON-RPC request with plaintext
      * params/result (no SessionEncryption layer). Used for tenant-facing
-     * read endpoints (`token.get-balance`, `token.get-usage`) where the
-     * server-side handler reads the JSON envelope directly.
+     * read endpoints whose payloads carry only public / non-disclosive
+     * metadata (`contracts.list`, `delegation.check`) where the
+     * server-side handler reads the JSON envelope directly. (The token
+     * self-reads moved to the sealed path — see {@link getUsage}.)
      *
      * Auto-attaches the `Session-Id` header; surfaces JSON-RPC errors
      * the same way as {@link sendRpcRequest} (typed