@terminal3/t3n-sdk 3.6.1 → 3.8.0

package/dist/index.d.ts

@@ -281,7 +281,8 @@ declare enum SessionStatus {
  */
 declare enum AuthMethod {
     Ethereum = "eth",
-    OIDC = "oidc"
+    OIDC = "oidc",
+    EmailOtp = "email_otp"
 }
 /**
  * OIDC credentials interface.
@@ -295,6 +296,20 @@ interface OidcCredentials {
     provider: string;
     getIdToken: (nonce: string) => Promise<string>;
 }
+/**
+ * Email-OTP credentials interface.
+ *
+ * The user submits their email; the node sends a one-time code to it.
+ * The `getOtpCode` callback is invoked between the two round-trips and
+ * must return the code the user received in their inbox (e.g. read from
+ * a UI prompt). The resolved DID is keyed on the email, so a user who
+ * previously signed in with the same email via Google (OIDC) resolves
+ * to the SAME DID — one identity, no double accounts.
+ */
+interface EmailOtpCredentials {
+    email: string;
+    getOtpCode: () => Promise<string>;
+}
 /**
  * Base authentication input with method discriminator
  */
@@ -322,15 +337,23 @@ interface OidcAuthInput extends BaseAuthInput {
     method: AuthMethod.OIDC;
     credentials: OidcCredentials;
 }
+/**
+ * Email-OTP authentication input
+ */
+interface EmailOtpAuthInput extends BaseAuthInput {
+    method: AuthMethod.EmailOtp;
+    credentials: EmailOtpCredentials;
+}
 /**
  * Union type for all supported authentication inputs
  */
-type AuthInput = EthAuthInput | OidcAuthInput;
+type AuthInput = EthAuthInput | OidcAuthInput | EmailOtpAuthInput;
 /**
  * Helper functions to create auth inputs
  */
 declare function createEthAuthInput(address: string, options?: EthAuthOptions): EthAuthInput;
 declare function createOidcAuthInput(credentials: OidcCredentials): OidcAuthInput;
+declare function createEmailOtpAuthInput(credentials: EmailOtpCredentials): EmailOtpAuthInput;
 
 /**
  * Error classes for T3n SDK
@@ -409,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
  */
@@ -1577,6 +1632,22 @@ declare class T3nClient {
      *    returns `Finish { did }`.
      */
     private authenticateOidc;
+    /**
+     * Email-OTP two-step authentication.
+     *
+     * Symmetric with {@link authenticateOidc}: bypasses the WASM client
+     * state machine and makes two encrypted RPC calls directly:
+     * 1. `InitEmailOtp { email }` → node sends a one-time code → returns
+     *    an `OtpSent` ack.
+     * 2. App calls `getOtpCode()` to obtain the code the user received.
+     * 3. `SubmitOtpCode { code }` → node verifies the code, resolves the
+     *    DID on the shared `email:<addr>` key → returns `Finish { did }`.
+     *
+     * Because the DID is keyed on the (server-lowercased) email, a user
+     * who previously signed in with the same address via Google (OIDC)
+     * authenticates to the SAME DID — one identity, no double account.
+     */
+    private authenticateEmailOtp;
     /**
      * Execute an action on the T3n node.
      *
@@ -1814,6 +1885,33 @@ declare class T3nClient {
      *   `result.status` for retryable OTP failures.
      */
     otpVerify(input: OtpVerifyInput): Promise<OtpVerifyResult>;
+    /**
+     * Merge the currently-authenticated DID (the *source*) into
+     * `targetDid` (the *survivor*), consolidating two accounts that
+     * belong to the same person. Backed by
+     * `tee:user/contracts::merge-profiles`.
+     *
+     * This is the consolidation path for the wallet ↔ email clash: a user
+     * who claimed with a wallet (one DID) and later proved an email that
+     * already belongs to an OIDC/email DID can fold them into one. The
+     * source's wallets, verified-credential state, and org attribution
+     * are reparented onto the target; the target wins on profile-field
+     * conflicts.
+     *
+     * **Security**: the contract only permits the merge when *both* DIDs
+     * share a verified email or phone — i.e. the caller has OTP-proven
+     * ownership of the same contact on each side. An unproven email can
+     * never absorb a stranger's profile. Typical flow: authenticate
+     * (wallet) → {@link otpVerify} the email → read the returned
+     * `mergeSuggestion.existingDid` → call `mergeProfiles(existingDid)`.
+     *
+     * @param targetDid the surviving DID (absorbs the current session's
+     *   DID). Usually the `existingDid` from a {@link otpVerify}
+     *   `mergeSuggestion`.
+     * @throws {RpcError} if the contract refuses (e.g. the DIDs share no
+     *   verified contact) or on transport / decode failure.
+     */
+    mergeProfiles(targetDid: string): Promise<Record<string, unknown>>;
     /**
      * Submit Level-1 user-input fields to the slim
      * `tee:user/contracts::user-upsert`. The contract merges the
@@ -3231,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, 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, 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 };
+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 };