@terminal3/t3n-sdk 3.4.4 → 3.5.0

package/dist/index.d.ts

@@ -953,6 +953,79 @@ interface GetUsageOptions {
     kinds?: TokenTxKind[];
 }
 
+/**
+ * Tenant audit-event wire shapes.
+ *
+ * Mirrors `tenant_types::AuditEvent` and the `audit.get-mine` response
+ * (`service::tenant_logs::{AuditBatch, AuditPage}`). A tenant contract
+ * emits an audit event via the `logging::audit` host call; the host
+ * stamps the identity fields (`subject` / `actor` / `vc_id`) from the
+ * verified dispatch context, so a contract can never forge who acted or
+ * on whom. Events are permanent (encrypted, append-only) and scoped to a
+ * user — distinct from the evicting debug ring read via `getContractLogs`.
+ */
+/**
+ * One host-stamped audit event. `subject` / `actor` are canonical DID
+ * strings. On a self-call `actor === subject` and `vc_id` is `null`; on a
+ * delegated call `actor` is the agent and `vc_id` is the delegation
+ * credential. The remaining fields are supplied verbatim by the contract.
+ */
+interface AuditEvent {
+    /** Cluster-deterministic flush timestamp (ms). */
+    ts_ms: number;
+    /** The user whose data the call touched (host-stamped `pii_did`). */
+    subject: string;
+    /** The agent (delegated) or user (self-call) who acted (host-stamped). */
+    actor: string;
+    /** Delegation credential id on a delegated call; `null` on a self-call. */
+    vc_id?: string | null;
+    /** Contract-supplied: what happened, e.g. `"kyc.approve"`. */
+    action: string;
+    /** Contract-supplied: what it acted on, e.g. `"user-profile"`. */
+    target: string;
+    /** Contract-supplied: the result, e.g. `"success"` / `"denied"`. */
+    outcome: string;
+    /** Contract-supplied: optional free-text / JSON detail. */
+    details?: string | null;
+}
+/**
+ * One archived batch — the events committed in a single tenant dispatch.
+ * Every event in a batch shares the same `subject` / `actor` / `vc_id`.
+ */
+interface AuditBatch {
+    /** Hex of the archive key — usable directly as `cursor` for the next page. */
+    key: string;
+    /**
+     * Host-stamped: did the emitting dispatch's contract transaction
+     * commit? `false` means the call rolled back or trapped, so an event's
+     * `outcome: "success"` in this batch is the contract's *claim*, not a
+     * committed fact — filter on this when you need only durable events.
+     */
+    committed: boolean;
+    events: AuditEvent[];
+}
+/**
+ * `audit.get-mine` response — a page of audit batches, newest scan order.
+ * `next_cursor` is present (a key hex) when more batches remain; `null`
+ * once the scan reaches the end.
+ */
+interface AuditPage {
+    batches: AuditBatch[];
+    next_cursor?: string | null;
+}
+/**
+ * Request shape for {@link T3nClient.getAuditEvents} — all fields
+ * optional. Omit `pii_did` to read your own trail (all actors); set it to
+ * another user's DID to read, as a delegated agent, the events you
+ * performed for them — admitted only while that user's agent-auth grant
+ * to you is live. `cursor` is the `next_cursor` from a prior page.
+ */
+interface GetAuditEventsOptions {
+    pii_did?: string;
+    limit?: number;
+    cursor?: string;
+}
+
 /**
  * Public types export for T3n SDK
  */
@@ -1521,6 +1594,21 @@ declare class T3nClient {
      * server-side handler does not run the encryption layer.
      */
     getUsage(opts?: GetUsageOptions): Promise<UsagePage>;
+    /**
+     * Fetch a page of audit events. With no `pii_did`, returns
+     * the caller's own audit trail (every actor). With a `pii_did` set to
+     * another user's DID, returns — as a delegated agent — the events the
+     * caller performed for that user; admitted ONLY while that user's
+     * `agent-auth` grant to the caller is live (revocable). `cursor` is the
+     * `next_cursor` from a prior page; `limit` clamps server-side.
+     *
+     * Unlike {@link getUsage}, this runs the SAME session-payload
+     * encryption as {@link executeAction}: audit events carry PII
+     * (`action`/`target`/`details`), so the request and response are
+     * sealed to the session key rather than sent plaintext over TLS. The
+     * caller DID is bound from the session, never the body.
+     */
+    getAuditEvents(opts?: GetAuditEventsOptions): Promise<AuditPage>;
     /**
      * Execute an action with an attached binary blob using multipart RPC.
      */
@@ -1883,6 +1971,19 @@ declare class T3nClient {
      * caller will narrow to the endpoint's response type.
      */
     private sendUnencryptedSessionRpc;
+    /**
+     * Send a session-authenticated JSON-RPC request whose params/result
+     * are sealed with the same {@link SessionEncryption} layer
+     * `action.execute` uses — for read endpoints that return PII
+     * (`audit.get-mine`) and therefore must not travel plaintext over
+     * TLS. Unlike {@link sendRpcRequest}, this is not tied to the WASM
+     * client `Method` state machine: it takes the raw RPC method string
+     * and only does encrypt → send → decrypt.
+     *
+     * Requires an established (>= Encrypted) session; returns the
+     * decrypted plaintext response string for the caller to `JSON.parse`.
+     */
+    private sendEncryptedSessionRpc;
     /**
      * Inspect a JSON-RPC response for an `error` field and throw the
      * appropriate typed exception. No-op when `response.error` is
@@ -3013,6 +3114,29 @@ declare class TenantContractsNamespace {
     disable(tail: string): Promise<unknown>;
     enable(tail: string): Promise<unknown>;
     unregister(tail: string): Promise<unknown>;
+    /**
+     * Read back debug log entries the tenant's own contract emitted via
+     * `logging::info/debug/error`. Scans the per-(tenant, contract) ring written
+     * by the Trinity host's post-execution flush path and returns the entries in
+     * seq order, newest paging via `next_seq`. Requires the tenant's
+     * `log_max_entries` quota to be non-zero (the master enable; logs are off
+     * by default); returns an empty `entries` array when the feature is
+     * disabled or no logs have been emitted yet.
+     */
+    logs(tail: string, options?: {
+        sinceSeq?: number;
+        limit?: number;
+        minLevel?: "info" | "debug" | "error";
+    }): Promise<{
+        entries: Array<{
+            ts_ms: number;
+            level: "info" | "debug" | "error";
+            message: string;
+            span_id: number | null;
+        }>;
+        next_seq: number | null;
+        truncated: boolean;
+    }>;
     execute(tail: string, input: ContractExecuteInput): Promise<unknown>;
     private contractStateChange;
 }