@terminal3/t3n-sdk 2.7.0 → 2.9.0

package/dist/src/client/delegation.d.ts

@@ -85,12 +85,41 @@ export 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. */
-export interface PayrollInvocation {
+/** Default for `individual_disbursement_threshold_cents` — SGD 15,000. */
+export declare const DEFAULT_INDIVIDUAL_THRESHOLD_CENTS = 1500000n;
+/** Delegated invocation: the agent acts on behalf of a user. */
+export 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`.
+ */
+export 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.
+ */
+export type PayrollInvocation = PayrollInvocationDelegated | PayrollInvocationDirect;
 /** Response from `tee:delegation.sign`. */
 export interface SignDelegationResponse {
     credential_jcs: Uint8Array;
@@ -264,10 +293,33 @@ export 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)]`).
+ */
+export declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocationDelegated;
+/** Options for {@link buildPayrollDirectInvocation}. */
+export 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.
  */
-export declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocation;
+export declare function buildPayrollDirectInvocation(opts: BuildPayrollDirectInvocationOpts): PayrollInvocationDirect;
 export {};

package/dist/src/client/org-data.d.ts

@@ -19,7 +19,6 @@ import { T3nClient } from "./t3n-client";
 import type { WasmComponent } from "../wasm";
 import { type GuestToHostHandlers } from "../types";
 import type { OrgContractGrants, OrgPolicyMeta, OrgWriters, DataListResponse, DataGetResponse, MutationResponse, UserGrant } from "../types/org-data";
-declare function executeOrgDataAction(client: T3nClient, baseUrl: string, functionName: string, args: Record<string, unknown>): Promise<unknown>;
 export interface CreatePolicyInput {
     orgDid: string;
     initialAdminDid: string;
@@ -192,4 +191,79 @@ export declare class OrgDataClient {
     /** Retrieve a single data entry by entry ID (admin-only). */
     dataGet(input: DataGetInput): Promise<DataGetResponse>;
 }
-export { executeOrgDataAction };
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function createOrgDataClientFromSession(t3n: T3nClient, baseUrl: string): SessionOrgDataClient;

package/dist/src/index.d.ts

@@ -20,17 +20,19 @@ export type { KycStatus, KycStatusKind, KycPollOptions, KycPollCadence, } from "
 export { DEFAULT_KYC_POLL_CADENCE, TERMINAL_KYC_STATUSES, KycStatusTimeoutError, } from "./types/kyc";
 export type { OtpChannel, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, OtpMergeSuggestion, UserInputProfile, SubmitUserInputArgs, SubmitUserInputResult, UserUpsertErrorKind, } from "./types/user";
 export { UserUpsertError } from "./types/user";
-export { OrgDataClient } from "./client/org-data";
+export { OrgDataClient, SessionOrgDataClient, createOrgDataClientFromSession, } from "./client/org-data";
 export type { OrgDataClientOptions, CreatePolicyInput, UpdateMetaInput, SetWritersInput, SetGrantsInput, DeleteGrantsInput, WriteDataInput, DeleteDataInput, DeleteScopeInput, PolicyGetInput, WritersGetInput, GrantsGetInput, DataListInput, DataGetInput, ExecuteOrgDataActionOptions, } from "./client/org-data";
 export type { OrgDataActionWire, OrgPolicyMeta, OrgWriters, OrgContractGrants, UserGrant, EmployeeRecord, EmploymentStatus, ResidencyCategory, AgeBand, ExpenseClaim, MutationResponse, DataListResponse, DataGetResponse, } from "./types/org-data";
 export { DelegationCustodialClient } from "./client/delegation";
 export type { DelegationCustodialClientOpts, SignCustodialResult, } from "./client/delegation";
-export { DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, VC_ID_LEN, NONCE_LEN, REQUEST_HASH_LEN, AGENT_PUBKEY_LEN, ETH_SIG_LEN, buildDelegationCredential, validateCredentialBody, canonicaliseCredential, canonicaliseRequest, requestHash, buildInvocationPreimage, eip191Digest, signCredential, ethRecoverEip191, signAgentInvocation, buildPayrollInvocation, compactDidFromBytes, b64uEncodeBytes, b64uDecodeStrict, _b64uEncode, } from "./client/delegation";
-export type { DelegationCredential, DelegationEnvelope, PayrollRunRequest, PayrollInvocation, SignDelegationResponse, BuildDelegationCredentialOpts, BuildPayrollInvocationOpts, } from "./client/delegation";
+export { DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, VC_ID_LEN, NONCE_LEN, REQUEST_HASH_LEN, AGENT_PUBKEY_LEN, ETH_SIG_LEN, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, buildDelegationCredential, validateCredentialBody, canonicaliseCredential, canonicaliseRequest, requestHash, buildInvocationPreimage, eip191Digest, signCredential, ethRecoverEip191, signAgentInvocation, buildPayrollInvocation, buildPayrollDirectInvocation, compactDidFromBytes, b64uEncodeBytes, b64uDecodeStrict, _b64uEncode, } from "./client/delegation";
+export type { DelegationCredential, DelegationEnvelope, PayrollRunRequest, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollInvocation, SignDelegationResponse, BuildDelegationCredentialOpts, BuildPayrollInvocationOpts, BuildPayrollDirectInvocationOpts, } from "./client/delegation";
 export { metamask_sign, metamask_get_address, eth_get_address, createDefaultHandlers, createMlKemPublicKeyHandler, createRandomHandler, } from "./client/handlers";
 export type { WasmComponent, ClientHandshake, ClientAuth, SessionCrypto, WasmNextResult, } from "./wasm";
 export { loadWasmComponent } from "./wasm";
 export { generateRandomString, generateUUID, getScriptVersion, stringToBytes, bytesToString, redactSecrets, redactSecretsFromJson, } from "./utils";
-export { T3nError, SessionStateError, AuthenticationError, HandshakeError, RpcError, WasmError, decodeWasmErrorMessage, extractWasmError, } from "./utils/errors";
+export { T3nError, SessionStateError, AuthenticationError, HandshakeError, RpcError, SessionExpiredError, WasmError, decodeWasmErrorMessage, extractWasmError, } from "./utils/errors";
+export { assertShape, isObject } from "./utils/shape";
+export { isMutationResponse, isOrgPolicyMeta, isOrgWriters, isOrgContractGrants, isDataListResponse, isDataGetResponse, } from "./types/org-data";
 export type { SdkConfig, Environment, ConfigValidationResult, DkgAttestation, QuoteVerifyResult, DkgVerifyResult, PeerQuoteResult, } from "./config";
 export { loadConfig, fetchMlKemPublicKey, fetchDkgAttestation, verifyTdxQuote, verifyDkgAttestation, clearKeyCache, getEnvironmentName, getEnvironment, setEnvironment, setNodeUrl, getNodeUrl, NODE_URLS, validateConfig, } from "./config";

package/dist/src/types/org-data.d.ts

@@ -5,6 +5,13 @@
  * 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`.
  */
@@ -43,6 +50,8 @@ export interface OrgPolicyMeta {
     /** Unix timestamp (secs) of the most recent policy update. */
     updated_at_secs: number;
 }
+/** Shallow runtime guard for {@link OrgPolicyMeta}. */
+export declare function isOrgPolicyMeta(value: unknown): value is OrgPolicyMeta;
 export type EmploymentStatus = "Active" | "Terminated";
 /** Singapore CPF residency categories. */
 export type ResidencyCategory = "Citizen" | "Pr1" | "Pr2" | "PrThreePlus" | "Foreigner";
@@ -94,6 +103,15 @@ export 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.
+ */
+export declare function isMutationResponse(value: unknown): value is MutationResponse;
 /**
  * Response type alias for org-writers-get.
  *
@@ -103,6 +121,8 @@ export interface MutationResponse {
 export interface OrgWriters {
     writers: string[];
 }
+/** Shallow runtime guard for {@link OrgWriters}. */
+export declare function isOrgWriters(value: unknown): value is OrgWriters;
 /**
  * Response type alias for org-grants-get.
  *
@@ -112,6 +132,15 @@ export 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.
+ */
+export declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
 /** Response for `org-data-list`. */
 export interface DataListResponse {
     /** Hex-encoded entry IDs for this page. */
@@ -121,12 +150,16 @@ export interface DataListResponse {
     /** Total number of entries in the scope (across all pages). */
     total: number;
 }
+/** Shallow runtime guard for {@link DataListResponse}. */
+export declare function isDataListResponse(value: unknown): value is DataListResponse;
 /** Response for `org-data-get`. */
 export interface DataGetResponse {
     entry_id: string;
     /** Hex-encoded raw payload bytes. */
     payload_hex: string;
 }
+/** Shallow runtime guard for {@link DataGetResponse}. */
+export declare function isDataGetResponse(value: unknown): value is DataGetResponse;
 /**
  * Legacy direct-route org-data envelope shape retained for compatibility.
  *

package/dist/src/utils/errors.d.ts

@@ -28,6 +28,27 @@ export declare class AuthenticationError extends T3nError {
 export 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}.
+ */
+export declare class SessionExpiredError extends T3nError {
+    constructor(cause: unknown);
+}
 /**
  * Error thrown during RPC communication.
  *

package/dist/src/utils/index.d.ts

@@ -7,3 +7,4 @@ export * from "./errors";
 export * from "./logger";
 export * from "./redaction";
 export * from "./session";
+export * from "./shape";

package/dist/src/utils/shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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. */
+export 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.
+ */
+export declare function assertShape<T>(value: unknown, guard: (v: unknown) => v is T, where: string): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",