@terminal3/t3n-sdk 4.7.0 → 4.9.0

package/dist/index.d.ts

@@ -2272,6 +2272,33 @@ declare class T3nClient {
      *   a JSON array.
      */
     getWalletHistory(walletAddress: string): Promise<unknown[]>;
+    /**
+     * Return the organisations the authenticated user is a member of, as
+     * canonical `did:t3n:<40-hex>` strings.
+     *
+     * Backed by `tee:user/my-organisations`, which reads the caller's
+     * membership set (`UserOrganisations`) keyed on the session DID — the
+     * request carries no body, and a user cannot query anyone else's
+     * memberships. An **empty array means the user belongs to no
+     * organisation**; this is the intended signal for an org-scoped app to
+     * gate entry on (authentication itself is org-agnostic — a user in no
+     * org still authenticates successfully).
+     *
+     * Note this reflects *affiliation*, not per-contract authorisation:
+     * membership does not by itself grant admin rights or a scope grant.
+     * Org-scoped operations remain gated server-side (403) on the org's
+     * admin list / grants regardless of what this returns.
+     *
+     * `my-organisations` is an additive export, so any registered
+     * user-contract version exposes it; {@link executeUserContract}
+     * resolves `"latest"` to the current version so this wrapper doesn't
+     * drift on every `CONTRACT_VERSION` bump.
+     *
+     * @returns the caller's organisation DIDs (`did:t3n:<40-hex>`), possibly empty.
+     * @throws if unauthenticated, if the node rejects the action, or if the
+     *   response shape is unexpected.
+     */
+    myOrgs(): Promise<Did[]>;
     /**
      * Remove the authenticated user's account AND explicitly abandon
      * any wallets. Writes `Abandoned` audit rows to wallet history,
@@ -3178,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 {
     /**
@@ -3778,5 +3891,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, 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 };