@terminal3/t3n-sdk 4.24.0 → 4.26.0

package/dist/index.d.ts

@@ -1615,6 +1615,112 @@ interface GetAuditEventsOptions {
     cursor?: string;
 }
 
+/**
+ * Agent-activity audit-log wire shapes (the node's `auditlog` RPC).
+ *
+ * Mirrors `service::activity_audit::{ActivityReport, ReportEntry}` and
+ * `primitives::audit_log::AuditLogEntry`. One entry per audited contract
+ * dispatch — who called, for whom, which contract + function, and how it
+ * ended. Entries are reconstructed from the append-only ledger on read, so
+ * `seq_no` (the ledger index) and `hash` are derived server-side rather than
+ * stored with the record.
+ *
+ * Scope is the caller's **own organisation**, resolved node-side from the
+ * session DID: there is no scope parameter, and a page carries **every
+ * member's** activity in that org, not just the caller's own. Metadata only —
+ * DIDs, never display names, call arguments, or payloads.
+ */
+/**
+ * Whether the actor is a registered agent or a human / self principal.
+ * Decided node-side by an existence check on the actor DID in the agent
+ * registry — never inferred from the DID's shape.
+ */
+type ActivityCallerType = "agent" | "human";
+/**
+ * Host-stamped outcome of an audited dispatch.
+ *
+ * - `success` — the business transaction committed.
+ * - `denied` — authorisation refused the call.
+ * - `error` — the call was allowed but failed / rolled back.
+ */
+type ActivityOutcome = "success" | "denied" | "error";
+/** One audited call. */
+interface ActivityEntry {
+    /**
+     * Ledger index of the entry — its unique, ordered id. Use it as the row key
+     * and as the ordering key: it is monotonic, whereas {@link timestamp_ms} is
+     * per-node wall clock.
+     */
+    seq_no: number;
+    /** Hex SHA-256 of the stored entry (64 chars) — read-time tamper evidence. */
+    hash: string;
+    /**
+     * Call time in Unix ms, stamped on the node that took the request. NOT a
+     * cluster-assigned time, so entries from different nodes can be skewed by
+     * their clock offset — order by {@link seq_no}, not by this.
+     */
+    timestamp_ms: number;
+    /** Agent vs human, from the agent-registry check on {@link actor}. */
+    caller_type: ActivityCallerType;
+    /** DID that actually invoked the contract. */
+    actor: string;
+    /**
+     * DID of the owner the caller acted for. Equals {@link actor} on a self /
+     * own-authority call — never null.
+     */
+    on_behalf_of: string;
+    /**
+     * Organisation the acting principal belongs to — the report's scope key, so
+     * it is identical on every row of a page. Falls back to `on_behalf_of` when
+     * that principal is in no organisation.
+     */
+    org: string;
+    /** Contract that ran, e.g. `tee:user/contracts`. */
+    contract: string;
+    /** Contract function invoked, e.g. `user-upsert`. */
+    function: string;
+    /** success / denied / error — host-stamped from the dispatch result. */
+    outcome: ActivityOutcome;
+}
+/**
+ * One page of the organisation's activity report — **newest first**, i.e.
+ * descending `seq_no`.
+ */
+interface ActivityReport {
+    entries: ActivityEntry[];
+    /**
+     * Cursor to resume from — pass it back as
+     * {@link GetActivityLogOptions.before_seq}. `null` once the requested window
+     * is exhausted.
+     *
+     * A live cursor with **fewer rows than `limit`, or none at all**, is normal:
+     * the node also caps how much ledger one call decrypts, and that cap can trip
+     * before the window ends. Page until this is `null`, never on a short or
+     * empty page.
+     */
+    next_seq: number | null;
+}
+/** Params for one activity-report page. All optional; `{}` is valid. */
+interface GetActivityLogOptions {
+    /** Window start, Unix ms, inclusive. Defaults to 0 (no lower bound). */
+    from_ms?: number;
+    /** Window end, Unix ms, inclusive. Defaults to unbounded. */
+    to_ms?: number;
+    /**
+     * Cursor, inclusive — the highest `seq_no` this page may return. Omitted ⇒
+     * start at the newest entry in the window. Pages walk downwards, so this is
+     * the previous page's {@link ActivityReport.next_seq}.
+     */
+    before_seq?: number;
+    /**
+     * Rows returned this page. Clamped server-side to 1–1000 (default 200).
+     *
+     * A page can still be shorter than this (or empty) with a live `next_seq` —
+     * the node's own scan cap can trip first. See {@link ActivityReport.next_seq}.
+     */
+    limit?: number;
+}
+
 /**
  * Contract-discovery wire shapes.
  *
@@ -1947,6 +2053,39 @@ declare class T3nClient {
      * caller DID is bound from the session, never the body.
      */
     getAuditEvents(opts?: GetAuditEventsOptions): Promise<AuditPage>;
+    /**
+     * Fetch one page of the caller's **organisation's** agent-activity audit log
+     * (`auditlog`): every audited contract dispatch — actor, on-behalf-of,
+     * contract, function, outcome — reconstructed from the append-only ledger.
+     *
+     * The scope organisation is resolved node-side from the session DID, so
+     * there is no scope parameter and a caller can only ever read their own org.
+     * The page carries **every member's** activity in that org, not just the
+     * caller's own.
+     *
+     * Like {@link getAuditEvents} / {@link getUsage}, this runs the session
+     * payload encryption: entries carry principal DIDs, so params and response
+     * are sealed to the session key rather than sent plaintext over TLS.
+     *
+     * Rows come back **newest first**. Page by handing the previous page's
+     * `next_seq` back as `before_seq`, and stop when it comes back `null` —
+     * **not** on a short or empty page: the node also caps how much ledger a
+     * single call decrypts, so a page can be shorter than `limit` while the window
+     * still has rows.
+     *
+     * ```ts
+     * let cursor: number | undefined;
+     * do {
+     *   const page = await client.getActivityLog({
+     *     limit: 200,
+     *     ...(cursor !== undefined && { before_seq: cursor }),
+     *   });
+     *   render(page.entries);
+     *   cursor = page.next_seq ?? undefined;
+     * } while (cursor !== undefined);
+     * ```
+     */
+    getActivityLog(opts?: GetActivityLogOptions): Promise<ActivityReport>;
     /**
      * Execute an action with an attached binary blob using multipart RPC.
      */
@@ -4665,4 +4804,4 @@ declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
 export { AGENT_CARDS_SCOPE, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, InvokeError, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, SessionUsageReportClient, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, WireEncodingError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, invoke, isAgentCardResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isUnsafeTrustServer, loadConfig, loadWasmComponent, manifestToTrustAnchor, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyManifestSignature, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, SignedTrustManifest, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export type { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, SignedTrustManifest, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };