@terminal3/t3n-sdk 4.16.1 → 4.18.0

package/dist/index.d.ts

@@ -2004,15 +2004,19 @@ declare class T3nClient {
      * returned exactly once here and is never persisted or recoverable
      * afterwards, so the caller must capture it immediately.
      *
-     * Atomic registration + card hosting: pass `options.agentUri` and the
-     * SAME transaction also writes the agent-registry record (URI + the
-     * org's publish-consent link, born together) and — unless
-     * `options.defaultCard === false` — hosts a PRIVATE card for the new
-     * agent in the org's `agent-cards` scope. The card body is
+     * Atomic provisioning + card hosting: the SAME transaction mints the
+     * agent, writes the agent-registry record (owner binding + the org's
+     * publish-consent link), and — unless `options.defaultCard === false` —
+     * hosts a PRIVATE card in the org's `agent-cards` scope. The card body is
      * `options.card` when given (object or pre-serialised JSON string);
      * otherwise the CONTRACT builds and hosts its default (which can even
      * name the agent DID, minted inside the same transaction).
      *
+     * `options.agentUri` is **optional**: a T3N-hosted card is served at
+     * `/api/agent-card/<did>`, so an agent needs no external URI. Pass one
+     * only to record an external endpoint in the DID document's
+     * `AgentService`; the card is hosted either way.
+     *
      * The card is deliberately NOT published: an org-bound agent must not
      * become world-discoverable as a side effect of provisioning. Publish
      * explicitly with `agentCardPublish` (one call — the consent link
@@ -2041,6 +2045,124 @@ declare class T3nClient {
         agentUri?: string;
         cardEntryId?: string;
     }>;
+    /**
+     * Normalise an organisation / user DID to the bare 40-hex form the
+     * `tee:organisation` contract's `organisation_did` / `user_did` fields
+     * expect (those take a hex string, not the `did:t3n:` display form).
+     * Accepts `did:t3n:<40 hex>` or bare 40 hex.
+     */
+    private static didToCompactHex;
+    /**
+     * Dispatch a `tee:organisation/contracts` function over the authenticated
+     * `action.execute` path (org-scoped writes are gated in-contract on the
+     * caller's org-admin membership). Shared glue for the
+     * organisation-lifecycle wrappers below.
+     */
+    private executeOrganisationContract;
+    /**
+     * Rename or change the status of an organisation the caller administers.
+     * Dispatches `organisation-update`; the contract gates on the caller being
+     * an org-admin of `orgDid`. Omitted fields are left unchanged.
+     *
+     * @param orgDid - the target organisation (`did:t3n:<hex>` or bare hex)
+     * @param updates - `name` and/or `status` (`"Active"` | `"Suspended"`)
+     */
+    updateOrganisation(orgDid: string, updates: {
+        name?: string;
+        status?: "Active" | "Suspended";
+    }): Promise<void>;
+    /**
+     * Delete an organisation the caller administers, footprint and all.
+     *
+     * A single `organisation-delete` dispatch tears down both stores the org
+     * spans: the contract removes the `OrganisationRecord`, memberships, and
+     * `OrgPolicyMeta`, and purges the org's `tee:org-data` footprint (every
+     * grant, writer list, data entry, and index row keyed under the org DID)
+     * in-contract, in the same consensus tx. Purge and delete therefore commit
+     * or roll back together — a purge failure aborts the whole delete, so a
+     * successful call never strands org-data.
+     *
+     * The org record's emptiness guards still apply (the org must have no
+     * non-admin members and no children).
+     *
+     * @param orgDid - the target organisation (`did:t3n:<hex>` or bare hex)
+     * @throws if the session is not authenticated, or if `organisation-delete`
+     *   refuses (including a refused in-contract org-data purge)
+     */
+    deleteOrganisation(orgDid: string): Promise<void>;
+    /**
+     * Dispatch a `tee:org-data/contracts` mutation on the authenticated session
+     * and require a `MutationResponse` back. A successful mutation returns a
+     * `MutationResponse` object; a refusal surfaces as a `"Code: message"` string
+     * on an otherwise-2xx response. This surfaces the refusal reason verbatim and
+     * then requires the success shape via `assertShape`, so any non-success
+     * (refusal string, or any other malformed payload) throws rather than being
+     * treated as success — letting callers abort a multi-step teardown.
+     */
+    private executeOrgDataMutation;
+    /**
+     * Attach an existing registered user to an organisation the caller
+     * administers. Dispatches `user-add-organisation-attribution` (org-admin
+     * gated).
+     *
+     * @param orgDid - the target organisation
+     * @param userDid - the user to attach
+     * @param opts.setAsOriginator - when the user has no originator yet, also
+     *   stamp this org as their write-once originator (backfill; ignored if one
+     *   is already set)
+     */
+    addOrganisationMember(orgDid: string, userDid: string, opts?: {
+        setAsOriginator?: boolean;
+    }): Promise<void>;
+    /**
+     * Detach a member from an organisation the caller administers (an org-admin
+     * "kick") and revoke their standing org-data capability (detach cascade):
+     *
+     * 1. `user-remove-organisation-attribution` — drop the membership edge
+     *    (org-admin gated; idempotent on an already-absent membership). The host
+     *    membership gate makes the detach effective immediately.
+     * 2. `org-remove-member-grants` — sweep the member from the org's
+     *    per-contract `UserGrant` lists, so the capability does not silently
+     *    reactivate if the member later rejoins.
+     *
+     * The member's `agent_auth` delegations are self-scoped (`AGENT_AUTH_MAP` is a
+     * per-user document an admin cannot reach), so this cannot sweep them; the host
+     * membership gate denies them regardless, and the member's own session can run
+     * {@link revokeAgentAuthForOrg} for full cleanup.
+     *
+     * @param orgDid - the organisation
+     * @param userDid - the member to detach
+     */
+    removeOrganisationMember(orgDid: string, userDid: string): Promise<void>;
+    /**
+     * Leave an organisation the caller is a member of (self-detach) and revoke
+     * the caller's own standing capability for it (detach cascade):
+     *
+     * 1. `user-remove-organisation-attribution` with the caller's own DID as the
+     *    target — the contract's self-leave branch (`caller == target`) admits it
+     *    without org-admin rights. The host membership gate makes the detach
+     *    effective immediately.
+     * 2. `org-remove-member-grants` — sweep the caller's own grants for the org
+     *    (the self-revocation branch, `caller == member`).
+     * 3. `agent-auth-revoke-org` — drop the caller's own org-scoped agent
+     *    delegations.
+     *
+     * Steps 2–3 leave no stale capability rows that would reactivate on a rejoin.
+     *
+     * @param orgDid - the organisation to leave
+     */
+    leaveOrganisation(orgDid: string): Promise<void>;
+    /**
+     * Revoke the caller's own agent delegations scoped to one org
+     * (detach-cascade `agent_auth` half). Dispatches
+     * `agent-auth-revoke-org` on `tee:user/contracts` (**SelfOnly**): every
+     * `ScriptGrant` targeting a `z:<orgTid>:*` contract is removed from the
+     * caller's own agent-auth document.
+     *
+     * @param orgTid - the org's z-space tenant id (`did:t3n:<hex>` or bare
+     *   40-hex) — i.e. the `<tid>` in the org's `z:<tid>:…` contract names
+     */
+    revokeAgentAuthForOrg(orgTid: string): Promise<void>;
     /**
      * Read the authenticated user's own agent-auth policy — the standing
      * grants delegated to agents. Dispatches `agent-auth-get` on
@@ -3020,6 +3142,14 @@ interface DeleteScopeInput {
     orgDid: string;
     scope: string;
 }
+interface PurgeOrgInput {
+    orgDid: string;
+}
+interface RemoveMemberGrantsInput {
+    orgDid: string;
+    /** DID (`did:t3n:<40-hex>` or bare hex) to drop from every grant list. */
+    memberDid: string;
+}
 interface PolicyGetInput {
     orgDid: string;
 }
@@ -3175,6 +3305,22 @@ declare class OrgDataClient {
      * Requires admin access (unlike `deleteData` which requires writer access).
      */
     deleteScope(input: DeleteScopeInput): Promise<MutationResponse>;
+    /**
+     * Full teardown of an org's org-data footprint — every
+     * grant, writer list, data entry, and index row keyed under the org DID.
+     * Org-admin-gated. Run this **before** `T3nClient.deleteOrganisation`,
+     * which removes the `OrgPolicyMeta` this call authorises against — together
+     * they leave the org with no org-data residue. `deleted_entries` reports the
+     * row count cleared.
+     */
+    purgeOrg(input: PurgeOrgInput): Promise<MutationResponse>;
+    /**
+     * Detach-cascade grant sweep: drop `memberDid` from every
+     * one of the org's per-contract `UserGrant` lists. Authorised for an
+     * org-admin of the subject, or the member removing their own grants.
+     * `deleted_entries` reports how many contract grant lists were rewritten.
+     */
+    removeMemberGrants(input: RemoveMemberGrantsInput): Promise<MutationResponse>;
     /** Read the policy metadata for an org (admin-only). */
     policyGet(input: PolicyGetInput): Promise<OrgPolicyMeta>;
     /**
@@ -3296,6 +3442,10 @@ declare class SessionOrgDataClient {
     deleteData(input: DeleteDataInput): Promise<MutationResponse>;
     /** Mirrors {@link OrgDataClient.deleteScope}. */
     deleteScope(input: DeleteScopeInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.purgeOrg}. */
+    purgeOrg(input: PurgeOrgInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.removeMemberGrants}. */
+    removeMemberGrants(input: RemoveMemberGrantsInput): Promise<MutationResponse>;
     /** Mirrors {@link OrgDataClient.policyGet}. */
     policyGet(input: PolicyGetInput): Promise<OrgPolicyMeta>;
     /** Mirrors {@link OrgDataClient.policyView}. */
@@ -4134,4 +4284,4 @@ declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
 export { AGENT_CARDS_SCOPE, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, SessionUsageReportClient, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, WireEncodingError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isAgentCardResponse, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };