@terminal3/t3n-sdk 5.0.0 → 5.2.0

package/dist/index.d.ts

@@ -1483,6 +1483,12 @@ interface OrgDataActionWire {
  * calling agent to be the `grantee` of at least one grant (subject binding), so
  * an unregistered agent discovers nothing regardless of this list.
  *
+ * Every entry must be a canonical `did:t3n:<40-hex>` identifier. The contract
+ * decodes each one to its 20 bytes, so a value of any other shape refuses the
+ * whole document (the error names the failing index), and two hex casings of one
+ * DID are a duplicate rather than two entries — also a refusal. Use
+ * {@link mergeDiscoverDids} to build the list rather than concatenating.
+ *
  * The document IS the new state on a write: an empty `grants` list revokes all
  * delegated access, and an empty `discover_dids` persists an empty
  * discovery-grant list (there is no per-field merge). Use {@link mergeGrants} /
@@ -1519,8 +1525,20 @@ declare function mergeGrants(existing: BoundGrant[], additions: BoundGrant[]): G
 /**
  * Order-preserving deduplicating union of discovery-grant DID lists — the
  * read-merge-write counterpart of {@link mergeGrants} for the document-level
- * `discover_dids` (the contract rejects duplicate entries, so the union must
- * dedupe).
+ * `discover_dids`.
+ *
+ * A DID's identity is the 20 bytes it decodes to, not its spelling. The contract
+ * dedupes on those bytes and treats a repeat as a hard error over the WHOLE
+ * document, so unioning `did:t3n:AABB…` with `did:t3n:aabb…` has to yield one
+ * entry — matching on the raw string would emit both and lose the write. Each
+ * recognised entry is emitted in canonical lowercase, the form the contract
+ * stores and a later `member-delegation-get` returns, so repeated
+ * read-merge-write cycles converge instead of oscillating.
+ *
+ * An entry that is not a `did:t3n:<40-hex>` identifier at all passes through
+ * verbatim and dedupes by exact string: the contract refuses it and names its
+ * index, which is more use to the caller than this helper dropping it or folding
+ * it into an unrelated entry.
  */
 declare function mergeDiscoverDids(existing: string[], additions: string[]): string[];
 /**
@@ -1617,10 +1635,16 @@ interface AgentAuthEntry {
  * in `agents` (subject binding), so an unregistered agent discovers nothing
  * regardless of this list.
  *
+ * Every entry must be a canonical `did:t3n:<40-hex>` identifier. The legacy
+ * document is converted onto the current one before it is stored, and that
+ * conversion decodes each entry, so anything else refuses the write with the
+ * failing index named.
+ *
  * @deprecated Use {@link MemberDelegationDoc}.
  */
 interface AgentAuthPolicy {
     agents: AgentAuthEntry[];
+    /** Document-level discovery grants (`did:t3n:<40-hex>` entries). */
     discoverDids: string[];
 }
 /**
@@ -1668,6 +1692,10 @@ interface AgentAuthUpdateInput {
  * deny-all egress. The document-level `discover_dids` is emitted only when
  * non-empty; the contract defaults an absent list to empty.
  *
+ * Discovery DIDs are copied through verbatim — no canonicalisation, no dedupe —
+ * so a non-canonical or repeated entry is refused by the contract rather than
+ * quietly repaired here. Build the list with `mergeDiscoverDids`.
+ *
  * @deprecated The new write path passes `MemberDelegationDoc` straight through
  * with no casing transform.
  */
@@ -2398,6 +2426,44 @@ interface GetActivityLogOptions {
      */
     function?: string;
 }
+/**
+ * Params for a CSV export of the activity log (`exportActivityLog`).
+ *
+ * The read's options minus the paging fields: an export walks the whole window
+ * itself, and the node refuses a request carrying either. Nothing caps the size,
+ * so `{}` on a long-lived organisation is a long walk — send a date range.
+ */
+type ExportActivityLogOptions = Omit<GetActivityLogOptions, "limit" | "before_seq">;
+/**
+ * Where an export has got to. Discriminate on `status`; the shape follows it.
+ *
+ * `pending` carries nothing — a half-walked row count is not a fact about the
+ * report. On `failed`, show `reason`: it decides between retrying and narrowing.
+ */
+type ActivityExportStatus = {
+    status: "pending";
+} | {
+    status: "ready";
+    rows: number;
+    bytes: number;
+} | {
+    status: "failed";
+    reason: string;
+};
+/** A finished export, as the node hands it back. */
+interface ActivityExportFile {
+    /** Data rows, excluding the header line. */
+    rows: number;
+    /** Size of {@link csv} in bytes. */
+    bytes: number;
+    /**
+     * The CSV text, header row first. Columns are fixed: `seq_no`, `timestamp_ms`,
+     * `caller_type`, `actor`, `on_behalf_of`, `org`, `contract`, `function`,
+     * `outcome`. For a browser download, wrap it in a `Blob` and click
+     * an `<a download>` — the response is sealed, so there is no URL to navigate.
+     */
+    csv: string;
+}
 
 /**
  * Contract-discovery wire shapes.
@@ -2901,6 +2967,38 @@ declare class T3nClient {
      * ```
      */
     getActivityLog(opts?: GetActivityLogOptions): Promise<ActivityReport>;
+    /**
+     * Start a CSV export of the caller's organisation's activity log, returning
+     * its id. Scope and filters are {@link getActivityLog}'s — the export is that
+     * read walked to exhaustion. Poll {@link getActivityLogExportStatus}, then
+     * {@link downloadActivityLogExport}, or let {@link exportActivityLog} do all
+     * three. A caller who already has one running gets `-32002`.
+     */
+    startActivityLogExport(opts?: ExportActivityLogOptions): Promise<string>;
+    /**
+     * Where one of the caller's own exports has got to. Anyone else's id reads as
+     * absent — an export id is not a capability.
+     */
+    getActivityLogExportStatus(exportId: string): Promise<ActivityExportStatus>;
+    /**
+     * Fetch a finished export — the whole file in one sealed response, so hold the
+     * result rather than re-fetching per render. Fetchable until your next export
+     * replaces it, so a dead transfer retries on the same id; called while the walk
+     * still runs, it throws instead of waiting.
+     */
+    downloadActivityLogExport(exportId: string): Promise<ActivityExportFile>;
+    /**
+     * Export the activity log to CSV: start, poll, return the file. Use the three
+     * calls above instead when the UI must own the polling (to survive a page
+     * reload). Rejects with the node's reason if the export gives up, and on
+     * `timeoutMs` — after which the job keeps running, so the id stays pollable.
+     */
+    exportActivityLog(opts?: ExportActivityLogOptions, poll?: {
+        /** Gap between status polls. Default 1s. */
+        pollIntervalMs?: number;
+        /** Give up waiting after this. Default 5 minutes. */
+        timeoutMs?: number;
+    }): Promise<ActivityExportFile>;
     /**
      * Execute an action with an attached binary blob using multipart RPC.
      */
@@ -5960,4 +6058,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, T3nConfigError, 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, buildSecretWriteArgs, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, discoverCheckDelegation, discoverDescribeContract, discoverDescribeFunction, discoverListContracts, discoverWhoami, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getContractVersion, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, invoke, isAgentCardResponse, isAgentEgressGetResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isListHumanMembersResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractDelegation, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isSecretListResponse, isSecretRecord, isSecretView, isUnsafeTrustServer, loadConfig, loadWasmComponent, manifestToTrustAnchor, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, mergeGrants, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, parseMemberDelegationDoc, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyManifestSignature, verifyTdxQuote };
-export type { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentEgressEntry, AgentEgressGetResponse, AgentEgressRefInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, BoundGrant, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorDocument, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DescribeContractParams, DescribeContractResult, DescribeFunctionParams, DescribeFunctionResult, DetailedContract, Did, Direction, DiscoverOptions, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, FunctionDescriptorEntry, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GrantsMergeResult, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberDelegationDoc, MemberRole, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractDelegation, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgDelegationAddGrantsInput, OrgDelegationDeleteInput, OrgDelegationGetInput, OrgDelegationRemoveGrantsInput, OrgDelegationSetInput, OrgPolicyMeta, OrgPolicyView, OrgRemoveGrantTarget, OrgRemoveMemberDelegationInput, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RemoveTarget, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetAgentEgressInput, 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, TrustAnchorSource, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, Validity, WasmComponent, WasmNextResult, WhoamiResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export type { ActivityCallerType, ActivityEntry, ActivityExportFile, ActivityExportStatus, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentEgressEntry, AgentEgressGetResponse, AgentEgressRefInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, BoundGrant, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorDocument, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DescribeContractParams, DescribeContractResult, DescribeFunctionParams, DescribeFunctionResult, DetailedContract, Did, Direction, DiscoverOptions, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, ExportActivityLogOptions, FetchTrustedManifestOptions, FunctionDescriptorEntry, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GrantsMergeResult, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberDelegationDoc, MemberRole, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractDelegation, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgDelegationAddGrantsInput, OrgDelegationDeleteInput, OrgDelegationGetInput, OrgDelegationRemoveGrantsInput, OrgDelegationSetInput, OrgPolicyMeta, OrgPolicyView, OrgRemoveGrantTarget, OrgRemoveMemberDelegationInput, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RemoveTarget, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetAgentEgressInput, 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, TrustAnchorSource, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, Validity, WasmComponent, WasmNextResult, WhoamiResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };