@terminal3/t3n-sdk 4.14.0 → 4.15.0

package/dist/index.d.ts

@@ -2007,17 +2007,42 @@ 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
+     * `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).
+     *
+     * 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
+     * already exists from creation). All-or-nothing: any refusal creates
+     * no agent, no record, no card.
+     *
      * @param organisationDid - the owning organisation's DID
      *   (`did:t3n:<40-hex>`); the caller must be one of its admins
      * @param name - human-readable agent name (1..=128 bytes)
-     * @returns the new agent's DID and its one-time private key
+     * @param options - optional atomic registration + card hosting
+     * @returns the new agent's DID and its one-time private key, plus
+     *   `agentUri` / `cardEntryId` (the hosted PRIVATE card's entry id)
+     *   when the atomic path ran
      * @throws if the session is not authenticated, or if the contract
-     *   refuses (e.g. the caller is not an admin of `organisationDid`, or the
-     *   name is empty / too long)
-     */
-    createAgent(organisationDid: string, name: string): Promise<{
+     *   refuses (e.g. the caller is not an admin of `organisationDid`, the
+     *   name is empty / too long, or the card fails validation — in which
+     *   case NOTHING was created)
+     */
+    createAgent(organisationDid: string, name: string, options?: {
+        agentUri?: string;
+        card?: object | string;
+        defaultCard?: boolean;
+    }): Promise<{
         agentDid: Did;
         privateKey: string;
+        agentUri?: string;
+        cardEntryId?: string;
     }>;
     /**
      * Read the authenticated user's own agent-auth policy — the standing
@@ -2780,7 +2805,10 @@ declare function isOrgAdminStatus(value: unknown): value is OrgAdminStatus;
  * Mirrors the org-data `MutationResponse` wire shape.
  */
 interface MutationResponse {
-    /** `"created"`, `"updated"`, or `"deleted"`. */
+    /**
+     * `"created"`, `"updated"`, `"deleted"`, or — for the agent-card mutations —
+     * `"published"` / `"unpublished"`.
+     */
     status: string;
     /** Hex-encoded entry ID; present on data write/delete operations. */
     entry_id?: string;
@@ -2847,6 +2875,20 @@ interface DataGetResponse {
 }
 /** Shallow runtime guard for {@link DataGetResponse}. */
 declare function isDataGetResponse(value: unknown): value is DataGetResponse;
+/**
+ * Return shape of `agentCardGet` — composed client-side from the generic
+ * `org-data-get` read of the card's entry (there is no card-specific read
+ * operation on the contract). To check whether a public copy exists, probe
+ * the anonymous `GET /api/agent-card/{did}` endpoint.
+ */
+interface AgentCardResponse {
+    /** The agent whose card this is (`did:t3n:<40-hex>`). */
+    agent_did: string;
+    /** The stored card JSON body, verbatim. */
+    card: string;
+}
+/** Shallow runtime guard for {@link AgentCardResponse}. */
+declare function isAgentCardResponse(value: unknown): value is AgentCardResponse;
 /**
  * Legacy direct-route org-data envelope shape retained for compatibility.
  *
@@ -2883,6 +2925,21 @@ interface OrgDataActionWire {
  * constructing one-shot signed HTTP envelopes per call.
  */
 
+/**
+ * Org-data scope agent cards are stored under. The private card body is
+ * ordinary org-data — written / read / deleted with the generic
+ * `org-data-*` operations under this scope; only publication has dedicated
+ * contract operations.
+ */
+declare const AGENT_CARDS_SCOPE = "agent-cards";
+/**
+ * Derive the canonical org-data entry ID an agent card is stored under:
+ * the first 16 bytes of `SHA-256(owner ‖ "agent-cards" ‖ agent ‖ u64_be(0))`
+ * — byte-identical to the contract's `derive_entry_id(owner, "agent-cards",
+ * agent, 0)`, so `agent-card-publish` finds the entry without a reverse
+ * lookup. Returned as 32 lowercase hex chars (the wire `entry_id` format).
+ */
+declare function deriveAgentCardEntryId(ownerDid: string, agentDid: string): string;
 interface CreatePolicyInput {
     orgDid: string;
     initialAdminDid: string;
@@ -2996,6 +3053,27 @@ interface DataGetInput {
     /** Hex-encoded entry ID (32 hex chars). */
     entryId: string;
 }
+interface AgentCardSetInput {
+    /**
+     * The card owner (`did:t3n:<40-hex>`) — an org DID (written by its
+     * `agent-cards` scope writers) or an individual/agent DID (a self-owned
+     * data space: the owner itself writes, no org needed).
+     */
+    ownerDid: string;
+    /** The agent whose card this is (`did:t3n:<40-hex>`). */
+    agentDid: string;
+    /**
+     * Full card JSON body. Validated locally (non-empty / ≤ 16 KiB / JSON) —
+     * the same gate the contract applies at publish time.
+     */
+    card: string;
+}
+/** Reference to a single agent's card by `(owner, agent)`. */
+interface AgentCardRefInput {
+    /** The card owner — an org DID or an individual/agent DID. */
+    ownerDid: string;
+    agentDid: string;
+}
 interface ExecuteOrgDataActionOptions {
     /**
      * Deprecated. The direct signed-envelope transport used this as the
@@ -3143,6 +3221,33 @@ declare class OrgDataClient {
     dataList(input: DataListInput): Promise<DataListResponse>;
     /** Retrieve a single data entry by entry ID (admin-only). */
     dataGet(input: DataGetInput): Promise<DataGetResponse>;
+    /**
+     * Create or overwrite an agent's private card (org scope-writer, or the
+     * owner itself for a self-owned space). Validates locally with the same
+     * gate the contract applies at publish. The card stays private until
+     * {@link agentCardPublish}.
+     */
+    agentCardSet(input: AgentCardSetInput): Promise<MutationResponse>;
+    /**
+     * Delete an agent's private card. Does NOT unpublish — publication is
+     * explicit state; call {@link agentCardUnpublish} to retract the public copy.
+     */
+    agentCardDelete(input: AgentCardRefInput): Promise<MutationResponse>;
+    /**
+     * Publish an agent's card to the world-readable `public:agent_cards` map
+     * (served at `GET /api/agent-card/{did}`). The contract validates the
+     * stored bytes, then byte-copies them. Publishing under a third-party
+     * agent DID requires the agent's registry record to name this owner
+     * (consent link); implicit when the owner IS the agent.
+     */
+    agentCardPublish(input: AgentCardRefInput): Promise<MutationResponse>;
+    /** Remove an agent's card from `public:agent_cards`. */
+    agentCardUnpublish(input: AgentCardRefInput): Promise<MutationResponse>;
+    /**
+     * Read an agent's private card (org: admin or delegation-credential holder
+     * for the `agent-cards` scope; self-owned: the owner).
+     */
+    agentCardGet(input: AgentCardRefInput): Promise<AgentCardResponse>;
 }
 /**
  * Session-authenticated variant of {@link OrgDataClient}.
@@ -3215,6 +3320,16 @@ declare class SessionOrgDataClient {
     dataList(input: DataListInput): Promise<DataListResponse>;
     /** Mirrors {@link OrgDataClient.dataGet}. */
     dataGet(input: DataGetInput): Promise<DataGetResponse>;
+    /** Mirrors {@link OrgDataClient.agentCardSet}. */
+    agentCardSet(input: AgentCardSetInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.agentCardDelete}. */
+    agentCardDelete(input: AgentCardRefInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.agentCardPublish}. */
+    agentCardPublish(input: AgentCardRefInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.agentCardUnpublish}. */
+    agentCardUnpublish(input: AgentCardRefInput): Promise<MutationResponse>;
+    /** Mirrors {@link OrgDataClient.agentCardGet}. */
+    agentCardGet(input: AgentCardRefInput): Promise<AgentCardResponse>;
 }
 /**
  * Construct a {@link SessionOrgDataClient} from a caller-owned
@@ -4028,5 +4143,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { 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, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, 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, 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 { 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 };