@terminal3/t3n-sdk 3.3.0 → 3.4.0

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

@@ -1,276 +0,0 @@
-/**
- * OrgDataClient — typed wrapper over the existing authenticated
- * `/api/rpc` + `action.execute` pipeline.
- *
- * Unlike the removed direct `/api/user-contract/*` transport, this
- * client reuses Trinity's normal session-backed ETH auth flow:
- *
- * 1. `auth.handshake`
- * 2. `auth.authenticate`
- * 3. `action.execute`
- *
- * The class keeps its public constructor stable for callers that
- * already have an ETH secret key and expected DID, but internally it
- * owns a lazily-authenticated `T3nClient` instance rather than
- * constructing one-shot signed HTTP envelopes per call.
- */
-import type { Transport } from "./transport";
-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";
-export interface CreatePolicyInput {
-    orgDid: string;
-    initialAdminDid: string;
-    maxAdmins?: number;
-}
-export interface UpdateMetaInput {
-    orgDid: string;
-    admins: string[];
-    maxAdmins?: number;
-}
-export interface SetWritersInput {
-    orgDid: string;
-    scope: string;
-    writers: string[];
-}
-export interface SetGrantsInput {
-    orgDid: string;
-    contractId: string;
-    grants: UserGrant[];
-}
-export interface DeleteGrantsInput {
-    orgDid: string;
-    contractId: string;
-}
-export interface WriteDataInput {
-    orgDid: string;
-    scope: string;
-    payloadHex: string;
-    /** Explicit entry ID (32 hex chars). When present, enables idempotent upsert. */
-    entryId?: string;
-    /** Client-supplied monotonic counter for ID derivation when `entryId` is absent. */
-    clientSeqNo?: number;
-}
-export interface DeleteDataInput {
-    orgDid: string;
-    scope: string;
-    /** Hex-encoded entry ID (32 hex chars). */
-    entryId: string;
-}
-export interface DeleteScopeInput {
-    orgDid: string;
-    scope: string;
-}
-export interface PolicyGetInput {
-    orgDid: string;
-}
-export interface WritersGetInput {
-    orgDid: string;
-    scope: string;
-}
-export interface GrantsGetInput {
-    orgDid: string;
-    contractId: string;
-}
-export interface DataListInput {
-    orgDid: string;
-    scope: string;
-    offset?: number;
-    limit?: number;
-}
-export interface DataGetInput {
-    orgDid: string;
-    scope: string;
-    /** Hex-encoded entry ID (32 hex chars). */
-    entryId: string;
-}
-export interface ExecuteOrgDataActionOptions {
-    /**
-     * Deprecated. The direct signed-envelope transport used this as the
-     * envelope expiry window; the session-backed RPC path ignores it.
-     */
-    ttlSecs?: number;
-}
-/**
- * Options used when constructing an {@link OrgDataClient}.
- */
-export interface OrgDataClientOptions extends ExecuteOrgDataActionOptions {
-    /** Optional preloaded WASM component for tests or shared callers. */
-    wasmComponent?: WasmComponent;
-    /** Optional transport override, primarily for tests. */
-    transport?: Transport;
-    /**
-     * Optional handler overrides. If `EthSign` is omitted, the client
-     * uses the supplied `ethSecret` to satisfy Trinity's existing ETH
-     * auth challenge flow automatically.
-     */
-    handlers?: GuestToHostHandlers;
-    /**
-     * Extra headers added to every `/api/rpc` request the internal
-     * `T3nClient` makes. Mirrors `T3nClientConfig.headers` — needed when
-     * the node sits behind an edge policy that gates `/api/rpc` on a
-     * header (e.g. the staging Cloud Armor bypass token).
-     */
-    headers?: Record<string, string>;
-}
-/**
- * Client for session-authenticated org-data contract execution.
- *
- * Constructed with the node's base URL, the caller's 32-byte ETH secret
- * key, and the caller's DID (`did:t3n:<40-hex>`).  The first method call
- * lazily creates a `T3nClient`, completes ETH session auth, verifies that
- * the authenticated DID matches `userDid`, and then reuses that session for
- * subsequent contract calls.
- */
-export declare class OrgDataClient {
-    private readonly baseUrl;
-    private readonly ethSecret;
-    private readonly userDid;
-    private readonly opts;
-    private clientPromise;
-    constructor(baseUrl: string, ethSecret: Uint8Array, userDid: string, opts?: OrgDataClientOptions);
-    private getAuthenticatedClient;
-    private initialiseClient;
-    private call;
-    /**
-     * Initialise the data-tier policy for an existing organisation.
-     *
-     * The calling user must be named as `initialAdminDid`.  New orgs created
-     * after the org-data contract was deployed have their policy seeded
-     * automatically by the organisation contract; call this only for orgs
-     * that pre-date the contract deployment.
-     */
-    createPolicy(input: CreatePolicyInput): Promise<MutationResponse>;
-    /**
-     * Replace the admin list and/or `max_admins` cap on an existing policy.
-     *
-     * The calling user cannot remove themselves when they are the sole
-     * remaining admin; another admin must be added first.
-     */
-    updateMeta(input: UpdateMetaInput): Promise<MutationResponse>;
-    /**
-     * Full replacement of the writer list for a data scope.
-     *
-     * Passing an empty list removes the entry (no writers allowed).
-     * Scope names are canonicalised to lowercase before storage.
-     */
-    setWriters(input: SetWritersInput): Promise<MutationResponse>;
-    /**
-     * Full replacement of the user-grant list for a contract.
-     *
-     * Passing an empty list removes the entry.
-     */
-    setGrants(input: SetGrantsInput): Promise<MutationResponse>;
-    /**
-     * Delete the grant entry for a contract entirely.
-     */
-    deleteGrants(input: DeleteGrantsInput): Promise<MutationResponse>;
-    /**
-     * Write a data entry to the org's scope.
-     *
-     * When `entryId` is supplied, the call is an idempotent upsert.
-     * When absent, `clientSeqNo` is required and the entry ID is derived
-     * via SHA-256 from `(org_did, scope, writer_did, client_seq_no)`.
-     */
-    writeData(input: WriteDataInput): Promise<MutationResponse>;
-    /** Delete a single data entry by entry ID. */
-    deleteData(input: DeleteDataInput): Promise<MutationResponse>;
-    /**
-     * Bulk-delete all entries in a scope.
-     *
-     * Requires admin access (unlike `deleteData` which requires writer access).
-     */
-    deleteScope(input: DeleteScopeInput): Promise<MutationResponse>;
-    /** Read the policy metadata for an org (admin-only). */
-    policyGet(input: PolicyGetInput): Promise<OrgPolicyMeta>;
-    /** Read the writer list for a scope (admin-only). */
-    writersGet(input: WritersGetInput): Promise<OrgWriters>;
-    /** Read the grant list for a contract (admin-only). */
-    grantsGet(input: GrantsGetInput): Promise<OrgContractGrants>;
-    /**
-     * List entry IDs for a scope (admin-only), paginated.
-     *
-     * Pass `offset` from the previous response's `next_offset` to fetch
-     * the next page.
-     */
-    dataList(input: DataListInput): Promise<DataListResponse>;
-    /** 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.
- */
-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/client/request-parser.d.ts

@@ -1,48 +0,0 @@
-/**
- * WASM Request Parser
- *
- * Parses and categorizes requests from the WASM state machine.
- * The WASM component outputs JSON with a `guest_to_host` tag that determines
- * how the SDK should handle the request.
- *
- * See node/session/src/abi.rs for the GuestToHost enum definition.
- */
-/**
- * Types of requests that can come from WASM
- */
-export declare enum WasmRequestType {
-    /** Send data to remote server (PeerReply with action) */
-    SendRemote = "SendRemote",
-    /** Request to host (SDK) for side effects (MlKemPublicKey, Random, EthSign, etc.) */
-    GuestToHost = "GuestToHost",
-    /** Flow complete (Suspend) */
-    Suspend = "Suspend"
-}
-/**
- * Parsed result from WASM request
- */
-export interface ParsedRequest {
-    type: WasmRequestType;
-    data: Record<string, unknown>;
-    raw: string;
-}
-/**
- * Parses WASM request bytes into a categorized request type
- */
-export declare function parseWasmRequest(requestBytes: Uint8Array): ParsedRequest;
-/**
- * Check if a request should be sent to the remote server
- */
-export declare function isSendRemote(parsed: ParsedRequest): boolean;
-/**
- * Check if a request indicates flow completion
- */
-export declare function isCompletion(parsed: ParsedRequest): boolean;
-/**
- * Check if a request needs a guest-to-host handler
- */
-export declare function isGuestToHost(parsed: ParsedRequest): boolean;
-/**
- * Get the guest-to-host request type name (e.g., "MlKemPublicKey", "Random", "EthSign")
- */
-export declare function getGuestToHostType(parsed: ParsedRequest): string | null;