@uverify/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,437 @@
+/**
+ * A single certificate entry as stored on-chain and returned by the verification endpoints.
+ */
+interface CertificateResponse {
+    /** SHA-256 or SHA-512 hash of the certified data. */
+    hash: string;
+    /** Cardano address that issued the certificate. */
+    address: string;
+    /** Hash of the block that contains this certificate. */
+    blockHash: string;
+    /** Block height at which the certificate was recorded. */
+    blockNumber: number;
+    /** Transaction hash on the Cardano blockchain. */
+    transactionHash: string;
+    /** Slot number at which the certificate was recorded. */
+    slot: number;
+    /** ISO-8601 timestamp of the block. */
+    creationTime: string;
+    /** Optional metadata attached to the certificate. */
+    metadata?: string;
+    /** Optional issuer identifier. */
+    issuer?: string;
+}
+/**
+ * Certificate data provided when building a new certification transaction.
+ */
+interface CertificateData {
+    /** SHA-256 or SHA-512 hash of the data to be certified. */
+    hash: string;
+    /** Optional metadata string to attach to the certificate. */
+    metadata?: string;
+    /**
+     * Hashing algorithm used to produce the hash.
+     * Common values: "SHA-256", "SHA-512".
+     */
+    algorithm?: string;
+}
+
+/**
+ * The type of transaction to build.
+ *
+ * - `default`        — standard certificate issuance against an existing state.
+ * - `bootstrap`      — initialise a new state (fork) from a bootstrap datum.
+ * - `custom`         — custom certificate transaction.
+ * - `burn_state`     — burn the state token and close the workspace.
+ * - `burn_bootstrap` — burn a bootstrap datum token.
+ * - `init`           — deploy the initial bootstrap datum.
+ * - `deploy`         — deploy a library proxy contract.
+ */
+type TransactionType = 'default' | 'bootstrap' | 'custom' | 'burn_state' | 'burn_bootstrap' | 'init' | 'deploy';
+/** Status information returned alongside an unsigned transaction. */
+interface BuildStatus {
+    message: string;
+    code: number;
+}
+/** Request body for `POST /api/v1/transaction/build`. */
+interface BuildTransactionRequest {
+    /** Array of certificates to issue in this transaction. */
+    certificates: CertificateData[];
+    /** Transaction type. */
+    type: TransactionType;
+    /** Cardano address of the signer / payer. */
+    address: string;
+    /**
+     * Bootstrap datum reference. Required when `type` is `bootstrap`
+     * or when you want to specify which bootstrap datum to fork from.
+     */
+    bootstrapDatum?: Record<string, unknown>;
+    /** Existing state ID to update. Required for `default` and `burn_state` types. */
+    stateId?: string;
+}
+/** Response body for `POST /api/v1/transaction/build`. */
+interface BuildTransactionResponse {
+    /** CBOR-hex encoded unsigned transaction, ready to be signed. */
+    unsignedTransaction: string;
+    /** Echoes back the transaction type. */
+    type: TransactionType;
+    /** Build status with a human-readable message and code. */
+    status: BuildStatus;
+}
+
+/**
+ * Available actions for user state management.
+ *
+ * - `USER_INFO`        — retrieve current state information.
+ * - `INVALIDATE_STATE` — mark the current state as invalid.
+ * - `OPT_OUT`          — opt out and remove the user's state.
+ */
+type UserAction = 'USER_INFO' | 'INVALIDATE_STATE' | 'OPT_OUT';
+/** Request body for `POST /api/v1/user/request/action`. */
+interface UserActionRequest {
+    /** Cardano address of the user. */
+    address: string;
+    /** The action to perform. */
+    action: UserAction;
+    /** State ID to act on (required for INVALIDATE_STATE and OPT_OUT). */
+    stateId?: string;
+}
+/**
+ * Response from `POST /api/v1/user/request/action`.
+ * Contains a server-side signed message that the user must countersign
+ * before calling `POST /api/v1/user/state/action`.
+ */
+interface UserActionRequestResponse {
+    address: string;
+    action: UserAction;
+    /** Server signature over the message. */
+    signature: string;
+    /** UNIX timestamp of the request. */
+    timestamp: number;
+    /** Message that the user must sign with their wallet. */
+    message: string;
+    status: number;
+    error?: string;
+}
+/** Request body for `POST /api/v1/user/state/action`. */
+interface ExecuteUserActionRequest {
+    address: string;
+    action: UserAction;
+    stateId?: string;
+    /** Message returned by the request/action step. */
+    message: string;
+    /** Server signature from the request/action step. */
+    signature: string;
+    /** CIP-30 wallet signature over the message. */
+    userSignature: string;
+    /** Hex-encoded public key of the signing key. */
+    userPublicKey: string;
+    /** Timestamp from the request/action step. */
+    timestamp: number;
+}
+/** An on-chain certificate entry inside a state datum. */
+interface UVerifyCertificate {
+    hash: string;
+    algorithm: string;
+    issuer: string;
+    extra: string[];
+}
+/** On-chain state datum representing a user's issuing workspace. */
+interface UserState {
+    /** Unique identifier of this state (derived from an output reference). */
+    id: string;
+    /** Payment credential of the owner. */
+    owner: string;
+    fee: number;
+    feeInterval: number;
+    feeReceivers: string[];
+    /** UNIX timestamp — expiry of this state. */
+    ttl: number;
+    /** Certificates remaining before renewal is required. */
+    countdown: number;
+    certificates: UVerifyCertificate[];
+    batchSize: number;
+    bootstrapDatumName: string;
+    keepAsOracle: boolean;
+}
+/** Response from `POST /api/v1/user/state/action`. */
+interface ExecuteUserActionResponse {
+    state?: UserState;
+    status: number;
+    error?: string;
+    /** Unsigned transaction hex when the action requires an on-chain transaction. */
+    unsignedTransaction?: string;
+}
+
+/**
+ * Callback used by high-level helpers for message-based user state actions.
+ *
+ * Receives the raw challenge message string from the server and must return
+ * a CIP-30-compatible data signature object (`{ key, signature }`).
+ *
+ * The callback is wallet-agnostic — pass any implementation that speaks
+ * CIP-30 (e.g. mesh.js, blaze, lucid, or a raw browser wallet API).
+ *
+ * @example CIP-30 browser wallet
+ * ```ts
+ * const signMessage: MessageSignCallback = async (message) => {
+ *   const hexAddress = await api.getChangeAddress();
+ *   const hexMessage = Array.from(message)
+ *     .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+ *     .join('');
+ *   return api.signData(hexAddress, hexMessage); // { key, signature }
+ * };
+ * ```
+ */
+type MessageSignCallback = (message: string) => Promise<{
+    key: string;
+    signature: string;
+}>;
+/**
+ * Callback used by high-level helpers that require signing a transaction.
+ *
+ * Receives the CBOR-hex unsigned transaction and must return the CBOR-hex
+ * witness set after signing.
+ *
+ * @example CIP-30 browser wallet
+ * ```ts
+ * const signTx: TransactionSignCallback = (unsignedTx) =>
+ *   api.signTx(unsignedTx, true); // partial = true
+ * ```
+ *
+ * @example mesh.js
+ * ```ts
+ * const signTx: TransactionSignCallback = (unsignedTx) =>
+ *   wallet.signTx(unsignedTx, true);
+ * ```
+ */
+type TransactionSignCallback = (unsignedTx: string) => Promise<string>;
+/**
+ * Low-level API surface, accessible via {@link UVerifyClient.core}.
+ *
+ * Use these methods when you need fine-grained control over the request/response
+ * cycle (e.g. multi-sig flows, custom submission logic). For most use-cases
+ * the high-level helpers on {@link UVerifyClient} are sufficient.
+ */
+interface UVerifyCore {
+    /**
+     * Build an unsigned transaction for certificate issuance or state management.
+     *
+     * The returned `unsignedTransaction` is a CBOR-hex encoded transaction that
+     * must be signed by the user's wallet before being submitted via
+     * {@link submitTransaction}.
+     */
+    buildTransaction(request: BuildTransactionRequest): Promise<BuildTransactionResponse>;
+    /**
+     * Submit a signed transaction to the Cardano blockchain.
+     *
+     * @param transaction  - CBOR-hex encoded signed transaction.
+     * @param witnessSet   - Optional separate witness set in CBOR-hex.
+     */
+    submitTransaction(transaction: string, witnessSet?: string): Promise<void>;
+    /**
+     * Create a server-signed action request that the user must countersign.
+     *
+     * This is step 1 of the two-step user-state-action flow.
+     */
+    requestUserAction(request: UserActionRequest): Promise<UserActionRequestResponse>;
+    /**
+     * Execute a user state action using the signatures from both parties.
+     *
+     * This is step 2 of the two-step flow.
+     */
+    executeUserAction(request: ExecuteUserActionRequest): Promise<ExecuteUserActionResponse>;
+}
+interface UVerifyClientOptions {
+    /** Base URL of the UVerify API. Defaults to `https://api.uverify.io`. */
+    baseUrl?: string;
+    /** Optional HTTP headers added to every request (e.g. an API key). */
+    headers?: Record<string, string>;
+    /**
+     * Default callback for message signing, used by {@link UVerifyClient.getUserInfo},
+     * {@link UVerifyClient.invalidateState}, and {@link UVerifyClient.optOut} when no
+     * per-call callback is provided.
+     *
+     * @example CIP-30 browser wallet
+     * ```ts
+     * signMessage: async (message) => {
+     *   const hexAddress = await api.getChangeAddress();
+     *   const hexMessage = Array.from(message)
+     *     .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+     *     .join('');
+     *   return api.signData(hexAddress, hexMessage);
+     * }
+     * ```
+     */
+    signMessage?: MessageSignCallback;
+    /**
+     * Default callback for transaction signing, used by {@link UVerifyClient.issueCertificates}
+     * when no per-call callback is provided.
+     *
+     * @example CIP-30 browser wallet
+     * ```ts
+     * signTx: (unsignedTx) => api.signTx(unsignedTx, true)
+     * ```
+     */
+    signTx?: TransactionSignCallback;
+}
+/**
+ * Main entry point for the UVerify SDK.
+ *
+ * @example
+ * ```ts
+ * import { UVerifyClient } from '@uverify/sdk';
+ *
+ * const client = new UVerifyClient();
+ *
+ * const certificates = await client.verify('a3b4c5...');
+ * console.log(certificates);
+ * ```
+ */
+declare class UVerifyClient {
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private readonly defaultSignMessage?;
+    private readonly defaultSignTx?;
+    /**
+     * Low-level API access. Use these methods when you need full control over
+     * the request/response cycle. For most use-cases the high-level helpers
+     * (e.g. {@link issueCertificates}, {@link getUserInfo}) are sufficient.
+     *
+     * @example
+     * ```ts
+     * const { unsignedTransaction } = await client.core.buildTransaction({ ... });
+     * const witnessSet = await wallet.signTx(unsignedTransaction, true);
+     * await client.core.submitTransaction(unsignedTransaction, witnessSet);
+     * ```
+     */
+    readonly core: UVerifyCore;
+    constructor(options?: UVerifyClientOptions);
+    private request;
+    private get;
+    private post;
+    /**
+     * Retrieve all on-chain certificates associated with the given data hash.
+     *
+     * @param hash - SHA-256 or SHA-512 hex hash of the data to look up.
+     * @returns Array of certificates, or an empty array if none exist.
+     *
+     * @example
+     * ```ts
+     * const certs = await client.verify('a3b4c5d6...');
+     * if (certs.length > 0) {
+     *   console.log('First issued at block', certs[0].blockNumber);
+     * }
+     * ```
+     */
+    verify(hash: string): Promise<CertificateResponse[]>;
+    /**
+     * Retrieve a single certificate by its Cardano transaction hash and data hash.
+     *
+     * @param transactionHash - 64-character hex transaction hash.
+     * @param dataHash        - SHA-256 or SHA-512 hex hash of the certified data.
+     */
+    verifyByTransaction(transactionHash: string, dataHash: string): Promise<CertificateResponse>;
+    private _buildTransaction;
+    private _submitTransaction;
+    private _requestUserAction;
+    private _executeUserAction;
+    /**
+     * Issue certificates in a single step.
+     *
+     * Builds the unsigned transaction, passes it to `signCallback` to obtain a
+     * witness set, then submits the signed transaction to the blockchain.
+     *
+     * This is the recommended way to issue certificates when you control the full
+     * flow in one place. For more control (e.g. multi-sig flows) use
+     * {@link buildTransaction} and {@link submitTransaction} separately.
+     *
+     * @param address      Cardano address of the signer / payer.
+     * @param stateId      ID of the issuing state.
+     * @param certificates One or more certificates to certify.
+     * @param signCallback Callback that receives the unsigned transaction and
+     *                     returns the CIP-30 witness set CBOR hex.
+     *
+     * @example CIP-30 browser wallet
+     * ```ts
+     * await client.issueCertificates(
+     *   'addr1...',
+     *   'my-state-id',
+     *   [{ hash: 'sha256-hash-of-doc', algorithm: 'SHA-256' }],
+     *   (unsignedTx) => api.signTx(unsignedTx, true),
+     * );
+     * ```
+     *
+     * @example mesh.js
+     * ```ts
+     * await client.issueCertificates(
+     *   'addr1...', 'my-state-id',
+     *   [{ hash: 'sha256-hash-of-doc', algorithm: 'SHA-256' }],
+     *   (unsignedTx) => wallet.signTx(unsignedTx, true),
+     * );
+     * ```
+     */
+    issueCertificates(address: string, certificates: CertificateData[], signCallback?: TransactionSignCallback, stateId?: string): Promise<void>;
+    /**
+     * Retrieve the current state information for a user in a single step.
+     *
+     * Internally calls {@link requestUserAction} to obtain a server-signed
+     * challenge, invokes `signCallback` so the user's wallet can countersign,
+     * then calls {@link executeUserAction} and returns the resolved state.
+     *
+     * @param address      Cardano address of the user.
+     * @param signCallback Callback that signs the challenge message and returns
+     *                     the CIP-30 `{ key, signature }` data signature object.
+     *
+     * @example CIP-30 browser wallet
+     * ```ts
+     * const state = await client.getUserInfo('addr1...', async (message) => {
+     *   const hexAddress = await api.getChangeAddress();
+     *   const hexMessage = Array.from(message)
+     *     .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+     *     .join('');
+     *   return api.signData(hexAddress, hexMessage);
+     * });
+     * console.log('Certificates left before renewal:', state?.countdown);
+     * ```
+     */
+    getUserInfo(address: string, signCallback?: MessageSignCallback): Promise<UserState | undefined>;
+    /**
+     * Invalidate a user state in a single step.
+     *
+     * @param address      Cardano address of the user.
+     * @param stateId      ID of the state to invalidate.
+     * @param signCallback Callback that signs the challenge message.
+     *                     Falls back to the `signMessage` set in the constructor.
+     */
+    invalidateState(address: string, stateId: string, signCallback?: MessageSignCallback): Promise<ExecuteUserActionResponse>;
+    /**
+     * Opt out of UVerify in a single step, removing the user's state.
+     *
+     * @param address      Cardano address of the user.
+     * @param stateId      ID of the state to remove.
+     * @param signCallback Callback that signs the challenge message.
+     *                     Falls back to the `signMessage` set in the constructor.
+     */
+    optOut(address: string, stateId: string, signCallback?: MessageSignCallback): Promise<ExecuteUserActionResponse>;
+    /**
+     * Internal helper that runs the two-step user state action flow:
+     * request challenge → user signs → execute action.
+     */
+    private _performUserStateAction;
+    private _resolveMessageCallback;
+    private _resolveTxCallback;
+}
+
+/** Thrown when the UVerify API returns a non-2xx response. */
+declare class UVerifyApiError extends Error {
+    readonly statusCode: number;
+    readonly responseBody?: unknown | undefined;
+    constructor(message: string, statusCode: number, responseBody?: unknown | undefined);
+}
+/** Thrown when a required parameter is missing or invalid. */
+declare class UVerifyValidationError extends Error {
+    constructor(message: string);
+}
+
+export { type BuildStatus, type BuildTransactionRequest, type BuildTransactionResponse, type CertificateData, type CertificateResponse, type ExecuteUserActionRequest, type ExecuteUserActionResponse, type MessageSignCallback, type TransactionSignCallback, type TransactionType, UVerifyApiError, type UVerifyCertificate, UVerifyClient, type UVerifyClientOptions, type UVerifyCore, UVerifyValidationError, type UserAction, type UserActionRequest, type UserActionRequestResponse, type UserState };