@terminal3/t3n-sdk 2.7.0 → 2.9.0

package/dist/index.d.ts

@@ -355,6 +355,27 @@ declare class AuthenticationError extends T3nError {
 declare class HandshakeError extends T3nError {
     constructor(message: string);
 }
+/**
+ * Error thrown when a session-authenticated SDK client detects that the
+ * caller-owned session is no longer usable and the caller must
+ * re-authenticate before the call can succeed.
+ *
+ * Unlike {@link OrgDataClient} (which owns its ETH-secret-driven session
+ * and silently rebuilds it on expiry), {@link SessionOrgDataClient} is
+ * handed a caller-owned `T3nClient` whose session is bound to an
+ * interactive flow (typically SIWE). The SDK can't re-authenticate
+ * non-interactively, so on the same wire patterns that the
+ * self-owned client recovers from, the session-bound client translates
+ * the underlying error into this class and rethrows. The original error
+ * is preserved on the native ES2022 `cause` property.
+ *
+ * Callers branch on `instanceof SessionExpiredError` to route the user
+ * to a re-auth UX (e.g. SIWE modal / login redirect) rather than
+ * parsing the message of a raw {@link RpcError}.
+ */
+declare class SessionExpiredError extends T3nError {
+    constructor(cause: unknown);
+}
 /**
  * Error thrown during RPC communication.
  *
@@ -607,6 +628,13 @@ declare class UserUpsertError extends T3nError {
  * Plain TypeScript interfaces (no zod) — the SDK does not use a
  * validation library for domain types; see the existing `types/` files.
  *
+ * Each response type below is paired with a shallow runtime predicate
+ * (`isMutationResponse`, `isOrgPolicyMeta`, etc.) so the org-data client
+ * can `assertShape` the decoded payload before returning to callers.
+ * Predicates check the top-level structure only; nested elements
+ * (e.g. each `UserGrant` inside `OrgContractGrants.grants`) are not
+ * deeply validated — see `utils/shape.ts` for the rationale.
+ *
  * Reference: `org-data-types/src/lib.rs` and
  * `tee-contract-org-data/src/org_data.rs`.
  */
@@ -645,6 +673,8 @@ interface OrgPolicyMeta {
     /** Unix timestamp (secs) of the most recent policy update. */
     updated_at_secs: number;
 }
+/** Shallow runtime guard for {@link OrgPolicyMeta}. */
+declare function isOrgPolicyMeta(value: unknown): value is OrgPolicyMeta;
 type EmploymentStatus = "Active" | "Terminated";
 /** Singapore CPF residency categories. */
 type ResidencyCategory = "Citizen" | "Pr1" | "Pr2" | "PrThreePlus" | "Foreigner";
@@ -696,6 +726,15 @@ interface MutationResponse {
     deleted_entries?: number;
     tx_hash: string | null;
 }
+/**
+ * Shallow runtime guard for {@link MutationResponse}.
+ *
+ * Only the always-present fields are checked — `status` is mandatory on
+ * every mutation; `tx_hash` is non-optional but nullable. The optional
+ * fields (`entry_id`, `deleted`, `deleted_entries`) are not validated
+ * because their presence depends on which mutation ran.
+ */
+declare function isMutationResponse(value: unknown): value is MutationResponse;
 /**
  * Response type alias for org-writers-get.
  *
@@ -705,6 +744,8 @@ interface MutationResponse {
 interface OrgWriters {
     writers: string[];
 }
+/** Shallow runtime guard for {@link OrgWriters}. */
+declare function isOrgWriters(value: unknown): value is OrgWriters;
 /**
  * Response type alias for org-grants-get.
  *
@@ -714,6 +755,15 @@ interface OrgContractGrants {
     contract_id: string;
     grants: UserGrant[];
 }
+/**
+ * Shallow runtime guard for {@link OrgContractGrants}.
+ *
+ * Validates the immediate envelope (`contract_id: string`, `grants:
+ * array`) without recursing into each `UserGrant`. The Rust contract
+ * is the source of truth for grant element shape; widening the predicate
+ * here would create maintenance churn against benign field additions.
+ */
+declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
 /** Response for `org-data-list`. */
 interface DataListResponse {
     /** Hex-encoded entry IDs for this page. */
@@ -723,12 +773,16 @@ interface DataListResponse {
     /** Total number of entries in the scope (across all pages). */
     total: number;
 }
+/** Shallow runtime guard for {@link DataListResponse}. */
+declare function isDataListResponse(value: unknown): value is DataListResponse;
 /** Response for `org-data-get`. */
 interface DataGetResponse {
     entry_id: string;
     /** Hex-encoded raw payload bytes. */
     payload_hex: string;
 }
+/** Shallow runtime guard for {@link DataGetResponse}. */
+declare function isDataGetResponse(value: unknown): value is DataGetResponse;
 /**
  * Legacy direct-route org-data envelope shape retained for compatibility.
  *
@@ -1735,12 +1789,41 @@ interface PayrollRunRequest {
     batch_cap_cents: bigint;
     /** `employee_id` → previous-cycle baseline net disbursement, cents (decimal string). */
     historical_baselines: Record<string, string>;
+    /**
+     * Per-employee disbursement flag threshold, in cents. Mirrors
+     * `PayrollRunRequest::individual_disbursement_threshold_cents` on the Rust
+     * side. When absent the Rust contract applies its own default (SGD 15,000;
+     * `DEFAULT_INDIVIDUAL_THRESHOLD_CENTS`). When present, the value is
+     * included in the wire shape and participates in the request hash.
+     */
+    individual_disbursement_threshold_cents?: bigint;
 }
-/** Convenience wrapper paired with the matching delegation envelope. */
-interface PayrollInvocation {
+/** Default for `individual_disbursement_threshold_cents` — SGD 15,000. */
+declare const DEFAULT_INDIVIDUAL_THRESHOLD_CENTS = 1500000n;
+/** Delegated invocation: the agent acts on behalf of a user. */
+interface PayrollInvocationDelegated {
     envelope: DelegationEnvelope;
     request: PayrollRunRequest;
 }
+/**
+ * Direct invocation: the agent acts on its own behalf. No delegation
+ * envelope is included. The principal DID is resolved by the service layer
+ * from `DynamicContext.authenticated_did`; authorisation falls through to
+ * `OrgContractGrants[org || "tee:payroll"]` for the agent's own DID.
+ *
+ * Wire shape is `{ request }` — no `envelope` field and no
+ * `authenticated_did` field. The contract's entry-point handler injects
+ * `authenticated_did` from `GenericInput.context` before calling `verify`.
+ */
+interface PayrollInvocationDirect {
+    request: PayrollRunRequest;
+}
+/**
+ * Union of the two invocation variants. The serde-untagged enum on the
+ * contract side disambiguates by presence of `envelope` — delegated calls
+ * carry `{ envelope, request }`, direct calls carry `{ request }` only.
+ */
+type PayrollInvocation = PayrollInvocationDelegated | PayrollInvocationDirect;
 /** Response from `tee:delegation.sign`. */
 interface SignDelegationResponse {
     credential_jcs: Uint8Array;
@@ -1910,12 +1993,35 @@ interface BuildPayrollInvocationOpts {
     agentSecret: Uint8Array;
 }
 /**
- * Assemble a complete {@link PayrollInvocation} (envelope + request)
- * given a user-signed credential and a per-call agent secret. Computes
- * `request_hash` from the canonical request bytes and produces an
+ * Assemble a delegated {@link PayrollInvocationDelegated} (envelope +
+ * request) given a user-signed credential and a per-call agent secret.
+ * Computes `request_hash` from the canonical request bytes and produces an
  * `agent_sig` over `sha256(invocation_preimage)`.
+ *
+ * When `request.individual_disbursement_threshold_cents` is undefined this
+ * function fills in {@link DEFAULT_INDIVIDUAL_THRESHOLD_CENTS} before
+ * hashing so the SDK's hash matches the Rust contract's hash (the contract
+ * applies the same default via `#[serde(default)]`).
  */
-declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocation;
+declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocationDelegated;
+/** Options for {@link buildPayrollDirectInvocation}. */
+interface BuildPayrollDirectInvocationOpts {
+    request: PayrollRunRequest;
+}
+/**
+ * Assemble a direct {@link PayrollInvocationDirect} — no delegation
+ * envelope. The caller supplies only the request body; the contract
+ * entry-point resolves the principal DID from
+ * `DynamicContext.authenticated_did` at runtime.
+ *
+ * Callers in direct mode must hold a grant in
+ * `OrgContractGrants[org || "tee:payroll"]` under their own DID.
+ *
+ * When `request.individual_disbursement_threshold_cents` is undefined this
+ * function fills in {@link DEFAULT_INDIVIDUAL_THRESHOLD_CENTS} so the wire
+ * shape matches the Rust contract's `#[serde(default)]` canonicalisation.
+ */
+declare function buildPayrollDirectInvocation(opts: BuildPayrollDirectInvocationOpts): PayrollInvocationDirect;
 
 /**
  * OrgDataClient — typed wrapper over the existing authenticated
@@ -2106,6 +2212,82 @@ declare class OrgDataClient {
     /** Retrieve a single data entry by entry ID (admin-only). */
     dataGet(input: DataGetInput): Promise<DataGetResponse>;
 }
+/**
+ * Session-authenticated variant of {@link OrgDataClient}.
+ *
+ * Where `OrgDataClient` owns its own ETH-secret-driven session lifecycle,
+ * `SessionOrgDataClient` accepts a caller-owned {@link T3nClient}. The
+ * caller is responsible for completing `handshake()` and `authenticate()`
+ * on that client (e.g. via the SIWE flow used by the orgs admin UI)
+ * BEFORE invoking any method on this class — the constructor performs no
+ * auth lifecycle of its own.
+ *
+ * Dispatches through `action.execute` against `tee:org-data/contracts`,
+ * relying on the caller-owned `T3nClient` for the preceding
+ * `auth.handshake` / `auth.authenticate` steps, so callers get the
+ * identical method surface as `OrgDataClient` without needing a raw ETH
+ * secret key.
+ *
+ * The runtime guard only catches the no-handshake case
+ * (`t3n.getSessionId()` returns `null`); a client that has handshaken but
+ * not authenticated will pass the guard and instead fail later with an
+ * `RpcError` from `action.execute`. Authorisation is similarly the
+ * caller's responsibility — the contract will refuse calls that aren't
+ * backed by a recognised admin / writer DID, surfaced as the usual
+ * `'CODE: detail'` refusal string.
+ */
+declare class SessionOrgDataClient {
+    private readonly t3n;
+    private readonly baseUrl;
+    /**
+     * @param t3n - a `T3nClient` that the caller has already driven through
+     *   `handshake()` and `authenticate()`. The constructor does not verify
+     *   this; the runtime guard on each method only catches the
+     *   no-handshake case (`getSessionId()` returns `null`). A
+     *   handshake-only-no-authenticate client will fail later with an
+     *   `RpcError` from `action.execute`.
+     * @param baseUrl - node base URL (trailing slashes stripped). Mirrors
+     *   `OrgDataClient`'s signature for ergonomic parity; used only for the
+     *   `tee:org-data/contracts` version lookup and should match the node
+     *   the supplied `t3n` is bound to.
+     */
+    constructor(t3n: T3nClient, baseUrl: string);
+    private call;
+    /** Mirrors {@link OrgDataClient.createPolicy}. */
+    createPolicy(input: CreatePolicyInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.updateMeta}. */
+    updateMeta(input: UpdateMetaInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.setWriters}. */
+    setWriters(input: SetWritersInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.setGrants}. */
+    setGrants(input: SetGrantsInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.deleteGrants}. */
+    deleteGrants(input: DeleteGrantsInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.writeData}. */
+    writeData(input: WriteDataInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.deleteData}. */
+    deleteData(input: DeleteDataInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.deleteScope}. */
+    deleteScope(input: DeleteScopeInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.policyGet}. */
+    policyGet(input: PolicyGetInput): Promise<OrgPolicyMeta>;
+    /** Mirrors {@link OrgDataClient.writersGet}. */
+    writersGet(input: WritersGetInput): Promise<OrgWriters>;
+    /** Mirrors {@link OrgDataClient.grantsGet}. */
+    grantsGet(input: GrantsGetInput): Promise<OrgContractGrants>;
+    /** Mirrors {@link OrgDataClient.dataList}. */
+    dataList(input: DataListInput): Promise<DataListResponse>;
+    /** Mirrors {@link OrgDataClient.dataGet}. */
+    dataGet(input: DataGetInput): Promise<DataGetResponse>;
+}
+/**
+ * Construct a {@link SessionOrgDataClient} from a caller-owned
+ * {@link T3nClient} that has already been driven through `handshake()`
+ * and `authenticate()`. Thin convenience wrapper — equivalent to
+ * `new SessionOrgDataClient(t3n, baseUrl)`. See `SessionOrgDataClient`
+ * for the full precondition contract and the runtime guard's limits.
+ */
+declare function createOrgDataClientFromSession(t3n: T3nClient, baseUrl: string): SessionOrgDataClient;
 
 /**
  * Cryptographic utilities for T3n SDK
@@ -2155,6 +2337,37 @@ declare function redactSecrets(value: unknown): unknown;
  */
 declare function redactSecretsFromJson(jsonString: string): string;
 
+/**
+ * Runtime shape guards for SDK response decoding.
+ *
+ * The contract layer is the source of truth for response shapes, but the
+ * SDK's typed wrappers (`result as T`) are pure compile-time casts that
+ * silently accept anything if a contract drifts or returns an unexpected
+ * payload past the heuristic refusal-string check. `assertShape` lets the
+ * outermost SDK boundary throw a deterministic, named error at the call
+ * site rather than letting callers reach for `.admins` on `undefined`
+ * deep in their own code.
+ *
+ * Predicates are intentionally shallow — they validate the immediate
+ * top-level structure (object kind, presence/type of leading fields)
+ * but do not deeply validate nested elements (e.g. each `UserGrant`
+ * inside `OrgContractGrants.grants`). Deep validation would be brittle
+ * against benign contract additions; shallow guards catch the failure
+ * modes that actually surface as runtime crashes (null/string/missing
+ * top-level field).
+ */
+/** Narrowing helper: value is a non-null object record. */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Run a type-predicate guard against `value` and throw a named error if
+ * it fails. Returns the value typed as `T` on success.
+ *
+ * @param where - call-site identifier included in the thrown error
+ *   message (e.g. `'org-policy-get'`) so operators can grep logs back
+ *   to the offending RPC.
+ */
+declare function assertShape<T>(value: unknown, guard: (v: unknown) => v is T, where: string): T;
+
 /**
  * Configuration types for T3n SDK
  */
@@ -2328,5 +2541,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, REQUEST_HASH_LEN, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
-export type { AgeBand, AuthInput, BuildDelegationCredentialOpts, BuildPayrollInvocationOpts, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteOrgDataActionOptions, ExpenseClaim, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, Transport, UpdateMetaInput, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, 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, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
+export type { AgeBand, AuthInput, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteOrgDataActionOptions, ExpenseClaim, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, Transport, UpdateMetaInput, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };