@terminal3/t3n-sdk 5.15.2 → 5.16.0

package/dist/index.d.ts

@@ -3460,22 +3460,37 @@ declare class T3nClient {
      * already exists from creation). All-or-nothing: any refusal creates
      * no agent, no record, no card.
      *
+     * `options.initialCredits` pre-funds the new agent, in the SAME
+     * transaction as creation, from the owning organisation's own T3N
+     * balance — a freshly created agent otherwise starts with zero credit
+     * and every metered action it takes fails, since metered actions bill
+     * the acting DID's own balance. Internally dispatches into
+     * `tee:admin.agent-credit-transfer` over contracts-call; the caller must
+     * still be an admin of `organisationDid` (already required for
+     * `create-agent` itself) and the org's own balance must cover the
+     * amount, or the whole call refuses and nothing is created. To instead
+     * fund an agent from your own personal balance, or any time after
+     * creation, use {@link fundAgent}.
+     *
      * @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)
-     * @param options - optional atomic registration + card hosting
+     * @param options - optional atomic registration + card hosting +
+     *   initial credit funding (`initialCredits`, in base units)
      * @returns the new agent's DID and its one-time opaque `apiKey` + `keyId`,
      *   plus `agentUri` / `cardEntryId` (the hosted PRIVATE card's entry id)
      *   when the atomic path ran
      * @throws if the session is not authenticated, or if the contract
      *   refuses (e.g. the caller is not an admin of `organisationDid`, the
-     *   name is empty / too long, or the card fails validation — in which
+     *   name is empty / too long, the card fails validation, or
+     *   `initialCredits` exceeds the org's available balance — in which
      *   case NOTHING was created)
      */
     createAgent(organisationDid: string, name: string, options?: {
         agentUri?: string;
         card?: object | string;
         defaultCard?: boolean;
+        initialCredits?: number;
     }): Promise<{
         agentDid: Did;
         apiKey: string;
@@ -3483,6 +3498,52 @@ declare class T3nClient {
         agentUri?: string;
         cardEntryId?: string;
     }>;
+    /**
+     * Fund an agent DID's T3N credit balance so it can act. A freshly
+     * created agent starts with zero credit (unless `createAgent` was called
+     * with `initialCredits`), and every metered action is billed to the
+     * agent's own DID — so an unfunded agent's first call fails.
+     * Use this to fund an agent any time after it was created (not just at
+     * creation).
+     *
+     * Dispatches `fund-agent` on `tee:organisation/contracts`, which forwards
+     * into `tee:admin.agent-credit-transfer` over contracts-call. By default
+     * the transfer comes from the CALLER'S OWN balance (self-funding) —
+     * `tee:admin` requires the caller to administer at least one organisation
+     * `agentDid` belongs to. Pass `options.fromOrg` to instead fund from an
+     * organisation's own balance — `tee:admin` then requires the caller to
+     * administer `fromOrg` AND `agentDid` to actually be a member of it.
+     *
+     * Authorisation is organisation MEMBERSHIP, not a check that `agentDid`
+     * is specifically an agent: a human member of the same organisation is
+     * an equally valid recipient (deliberate — see the WIT doc on
+     * `agent-credit-transfer` in the contracts repo). `tee:admin`
+     * independently re-verifies this before moving any credit, regardless of
+     * what this SDK call or `tee:organisation` checked — this call can never
+     * reach a DID with no membership row under an organisation the caller
+     * administers, or move more than the source's real available balance.
+     *
+     * @param agentDid - the agent to fund (`did:t3n:<40-hex>` or bare hex)
+     * @param amount - credit to transfer, in base units (see
+     *   {@link formatTokens} / {@link toBaseUnits} in `src/token/`). u128 on
+     *   the wire as a JSON number, same convention as {@link BalanceRow} —
+     *   values above `Number.MAX_SAFE_INTEGER` are not currently
+     *   representable; split into multiple calls if you need to move more.
+     * @param options - `note` (recorded on the ledger's tx log — never put
+     *   secrets or PII in it, it's visible in both parties' usage feeds) and
+     *   `fromOrg` (fund from an org's balance instead of the caller's own)
+     * @returns the ledger transaction's sequence number for this transfer
+     * @throws if the session is not authenticated, if the caller does not
+     *   administer any organisation `agentDid` belongs to (or isn't an admin
+     *   of `options.fromOrg`, or `agentDid` isn't a member of `fromOrg`), or
+     *   if the source balance is insufficient
+     */
+    fundAgent(agentDid: string, amount: number, options?: {
+        note?: string;
+        fromOrg?: string;
+    }): Promise<{
+        seqNo: number;
+    }>;
     /**
      * Normalise an organisation / user DID to the bare 40-hex form the
      * `tee:organisation` contract's organisation-lifecycle exports