@terminal3/t3n-sdk 4.8.0 → 4.10.0

package/dist/index.d.ts

@@ -3205,6 +3205,92 @@ declare function formatTokens(baseUnits: number | bigint): string;
  */
 declare function toBaseUnits(tokens: number): number;
 
+/**
+ * SessionUsageReportClient — typed wrapper over the authenticated
+ * `/api/rpc` + `action.execute` pipeline for the per-organisation usage
+ * report served by `tee:admin/contracts#org-usage-report`.
+ *
+ * Unlike the cluster-admin `metering.usage-report` action (reached over
+ * `POST /api/admin` with an EIP-191 cluster-admin signature), this export
+ * is authenticated on the caller's ordinary session DID: the node stamps
+ * the proven `authenticated_did` into the contract context, and the
+ * contract returns the signed report ONLY when that DID is in the
+ * requested org's admin set. An org admin can therefore fetch **only their
+ * own org's** usage.
+ *
+ * Mirrors {@link SessionOrgDataClient}: it accepts a caller-owned
+ * {@link T3nClient} that the caller has already driven through
+ * `handshake()` and `authenticate()` (e.g. the SIWE flow the orgs admin UI
+ * uses). The constructor performs no auth lifecycle of its own.
+ */
+
+interface OrgUsageReportInput {
+    /**
+     * Owning organisation DID (`did:t3n:<40hex>` or bare 40-hex). The
+     * authenticated caller MUST be an admin of this org, else the contract
+     * refuses with a `not_org_admin:` error.
+     */
+    orgDid: string;
+    /** Inclusive window start (cluster-timestamp ms). */
+    fromMs: number;
+    /** Exclusive window end (cluster-timestamp ms). Must be > `fromMs`. */
+    toMs: number;
+    /** Optional cap on rows scanned; `truncated` is set on the reply when hit. */
+    maxScan?: number;
+}
+/** Signature envelope on the signed report (secp256k1 cluster key). */
+interface UsageReportSignature {
+    alg: string;
+    /** Signer eth address, derived from the returned pubkey (never the request). */
+    node_id: string;
+    payload_hash: string;
+    sig: unknown;
+    pub_key: unknown;
+}
+/**
+ * The `completed` envelope returned by `org-usage-report`. Identical shape
+ * to the cluster-admin `metering.usage-report` reply. The signed report
+ * body itself is the base64 `report_b64` (JCS-canonical bytes the
+ * `signature` attests to).
+ */
+interface OrgUsageReport {
+    status: string;
+    report_id: string;
+    org_did: string;
+    from_ms: number;
+    to_ms: number;
+    report_b64: string;
+    signature: UsageReportSignature;
+    truncated: boolean;
+}
+declare function isOrgUsageReport(v: unknown): v is OrgUsageReport;
+/**
+ * Session-authenticated client for the per-org usage report.
+ *
+ * @see SessionOrgDataClient for the precondition contract — the supplied
+ * {@link T3nClient} must already be handshaken + authenticated; the
+ * runtime guard only catches the no-handshake case.
+ */
+declare class SessionUsageReportClient {
+    private readonly t3n;
+    private readonly baseUrl;
+    constructor(t3n: T3nClient, baseUrl: string);
+    /**
+     * Fetch the signed usage report for an org the caller administers.
+     *
+     * Refuses with `not_org_admin: ...` when the authenticated session DID
+     * is not in the org's admin set — an org admin can only read their own
+     * org's usage.
+     */
+    getOrgUsageReport(input: OrgUsageReportInput): Promise<OrgUsageReport>;
+}
+/**
+ * Construct a {@link SessionUsageReportClient} from a caller-owned
+ * {@link T3nClient} that has already been driven through `handshake()` and
+ * `authenticate()`.
+ */
+declare function createUsageReportClientFromSession(t3n: T3nClient, baseUrl: string): SessionUsageReportClient;
+
 /** Closed-vocabulary serialisation annotations for a contract function's body. */
 interface WireBlock {
     /**
@@ -3631,6 +3717,18 @@ type TenantMapUpdatePatch = MapUpdateInput;
 type TenantContractPublishInput = ContractPublishInput;
 type TenantContractSetDescriptorInput = ContractSetDescriptorInput;
 type TenantContractExecuteInput = ContractExecuteInput;
+/**
+ * Coarse lifecycle state of a tenant map, mirroring the contract's
+ * `MapLifecycleStatus` enum on the `tee:tenant/contracts::map-get-status` op.
+ * Exported from the SDK public barrel so FE code has a single source of truth
+ * for the union instead of re-declaring it.
+ *
+ * - `"active"`  — a live map (`Private`/`Public`) exists at this name.
+ * - `"deleting"` — deleted, host sweeper still draining. Poll until `"absent"`.
+ * - `"absent"`  — no row (never created, or deletion fully settled); name is
+ *   free to (re-)create.
+ */
+type MapLifecycleStatus = "active" | "deleting" | "absent";
 /**
  * Options shared by the `tee:tenant` management calls that accept an optional
  * `tenant` target argument.
@@ -3683,6 +3781,45 @@ declare class TenantMapsNamespace {
     create(input: MapCreateInput, opts?: TenantTargetOptions): Promise<unknown>;
     update(tail: string, patch: MapUpdateInput, opts?: TenantTargetOptions): Promise<unknown>;
     delete(tail: string, opts?: TenantTargetOptions): Promise<unknown>;
+    /**
+     * Write a UTF-8 key/value entry into an owned map via the tenant management
+     * surface (`map-entry-set`). Mirrors the `.delete` shape: canonical name is
+     * always rooted at the target tenant, and `payload.tenant` is included only
+     * when `opts.tenantTarget` is supplied (`exactOptionalPropertyTypes` — never
+     * pass a stringified `null`, the contract's `deny_unknown_fields` accepts an
+     * absent field, not a literal `null`).
+     *
+     * SDK-only addition: the `map-entry-set` contract op
+     * has always accepted the optional `tenant` field and routed through
+     * `resolve_tenant_did` — this helper simply completes the SDK's map-entry
+     * surface so `set` / `get` / `getStatus` are all first-class alongside the
+     * lifecycle trio.
+     */
+    entrySet(tail: string, key: string, value: string, opts?: TenantTargetOptions): Promise<void>;
+    /**
+     * Read back a UTF-8 key/value entry from an owned map via the tenant
+     * management surface (`map-entry-get`). Requires the paired contract-side
+     * 1.24.0-or-later registration for the `tenant` argument to be accepted —
+     * a node on an earlier contract rejects `tenant`-bearing requests with
+     * `deny_unknown_fields`.
+     *
+     * Unwraps the contract's `{ value: string | null }` envelope to
+     * `string | null` for caller ergonomics; `null` is the deliberate
+     * "key absent" signal, not an error.
+     */
+    entryGet(tail: string, key: string, opts?: TenantTargetOptions): Promise<string | null>;
+    /**
+     * Report the lifecycle status of an owned map (`map-get-status`),
+     * so a client can poll a delete → recreate cycle instead of guessing.
+     * Requires the paired contract-side 1.24.0-or-later registration for the
+     * `tenant` argument to be accepted.
+     *
+     * `"absent"` (never created, or deletion fully settled) is a *success*
+     * answer meaning the name is free to (re-)create; it is not an error.
+     * `"deleting"` means the host sweeper is still draining the map — poll
+     * again until `"absent"`.
+     */
+    getStatus(tail: string, opts?: TenantTargetOptions): Promise<MapLifecycleStatus>;
 }
 declare class TenantContractsNamespace {
     private readonly client;
@@ -3805,5 +3942,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, 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, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createWorkloadAuthInput, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgWriters, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, 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, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export { AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, 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, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
+export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, 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, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };