@terminal3/t3n-sdk 3.7.0 → 3.8.1

package/README.md

@@ -18,6 +18,14 @@ pnpm add @terminal3/t3n-sdk
 
 ## Quick Start
 
+**Prerequisites:** a T3 account and your T3 API key — the private key of the ETH
+wallet you registered with. The key never leaves your machine; it's used locally to
+sign the login challenge.
+
+**Don't have these yet?** It's self-serve — no approval or waitlist. Claim your
+account, API key, and test tokens at <https://www.terminal3.io/claim-page> (sign in
+with your work email; your key is issued instantly).
+
 ### Basic Usage
 
 ```typescript

package/dist/index.d.ts

@@ -432,6 +432,38 @@ declare class RpcError extends T3nError {
     /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
     requestId?: string | undefined);
 }
+/**
+ * Error thrown when an OTP send is throttled by the node.
+ *
+ * The email-OTP login flow's `InitEmailOtp` step refuses a send when a
+ * still-valid code was issued within the resend cooldown
+ * (`reason: "cooldown_active"`) or the rolling per-recipient send cap is
+ * exhausted (`reason: "send_cap_exceeded"`). Previously a cooldown-
+ * suppressed resend returned a silent success, leaving a user who never
+ * received the first code at a dead end; this typed error lets the app
+ * render a "you just requested a code — retry in {retryAfterSecs}s"
+ * affordance instead.
+ *
+ * Recognised from the node's stable
+ * `OtpRateLimited (reason=…, retry_after_secs=…)` wire token (pinned by a
+ * server-side test). Subclass of {@link RpcError} so callers that catch
+ * the parent still see `httpStatus`/`requestId`; callers that want the
+ * typed surface `instanceof OtpRateLimitedError` to read `reason` and
+ * `retryAfterSecs`.
+ *
+ * Retryable after `retryAfterSecs` (caller-side back-off).
+ */
+declare class OtpRateLimitedError extends RpcError {
+    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
+    readonly reason: string;
+    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
+    readonly retryAfterSecs: number;
+    constructor(message: string, 
+    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
+    reason: string, 
+    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
+    retryAfterSecs: number, rpcMethod?: string, requestId?: string);
+}
 /**
  * Error thrown when WASM operations fail
  */
@@ -3297,5 +3329,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicalTenantName, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, tenantDidHex, toBaseUnits, validateConfig, validateCredentialBody, validateTail, verifyDkgAttestation, verifyTdxQuote };
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, OtpRateLimitedError, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicalTenantName, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, tenantDidHex, toBaseUnits, validateConfig, validateCredentialBody, validateTail, verifyDkgAttestation, verifyTdxQuote };
 export type { AgeBand, AuthInput, BalanceRow, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractPublishInput, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, ExpenseClaim, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, ResidencyCategory, RevokeDelegationOpts, RevokeDelegationResult, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WriterSet, WritersGetInput };