@uverify/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,307 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UVerifyApiError: () => UVerifyApiError,
+  UVerifyClient: () => UVerifyClient,
+  UVerifyValidationError: () => UVerifyValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var UVerifyApiError = class extends Error {
+  constructor(message, statusCode, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "UVerifyApiError";
+  }
+};
+var UVerifyValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UVerifyValidationError";
+  }
+};
+
+// src/UVerifyClient.ts
+var DEFAULT_BASE_URL = "https://api.uverify.io";
+var UVerifyClient = class {
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.defaultHeaders = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...options.headers
+    };
+    this.defaultSignMessage = options.signMessage;
+    this.defaultSignTx = options.signTx;
+    this.core = {
+      buildTransaction: this._buildTransaction.bind(this),
+      submitTransaction: this._submitTransaction.bind(this),
+      requestUserAction: this._requestUserAction.bind(this),
+      executeUserAction: this._executeUserAction.bind(this)
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const init = {
+      method,
+      headers: this.defaultHeaders
+    };
+    if (body !== void 0) {
+      init.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = await response.text();
+      }
+      throw new UVerifyApiError(
+        `UVerify API error ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+    const text = await response.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  // ---------------------------------------------------------------------------
+  // Certificate Verification
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this.get(`/api/v1/verify/${hash}`);
+  }
+  /**
+   * 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, dataHash) {
+    return this.get(
+      `/api/v1/verify/by-transaction-hash/${transactionHash}/${dataHash}`
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Low-level API (exposed via .core)
+  // ---------------------------------------------------------------------------
+  _buildTransaction(request) {
+    return this.post(
+      "/api/v1/transaction/build",
+      request
+    );
+  }
+  async _submitTransaction(transaction, witnessSet) {
+    await this.post("/api/v1/transaction/submit", {
+      transaction,
+      witnessSet
+    });
+  }
+  _requestUserAction(request) {
+    return this.post(
+      "/api/v1/user/request/action",
+      request
+    );
+  }
+  _executeUserAction(request) {
+    return this.post(
+      "/api/v1/user/state/action",
+      request
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // High-level helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * 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),
+   * );
+   * ```
+   */
+  async issueCertificates(address, certificates, signCallback, stateId) {
+    const cb = this._resolveTxCallback(signCallback);
+    const { unsignedTransaction } = await this._buildTransaction({
+      type: "default",
+      address,
+      stateId,
+      certificates
+    });
+    const witnessSet = await cb(unsignedTransaction);
+    await this._submitTransaction(unsignedTransaction, witnessSet);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getUserInfo(address, signCallback) {
+    const result = await this._performUserStateAction(
+      { address, action: "USER_INFO" },
+      signCallback
+    );
+    return result.state;
+  }
+  /**
+   * 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.
+   */
+  async invalidateState(address, stateId, signCallback) {
+    return this._performUserStateAction(
+      { address, action: "INVALIDATE_STATE", stateId },
+      signCallback
+    );
+  }
+  /**
+   * 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.
+   */
+  async optOut(address, stateId, signCallback) {
+    return this._performUserStateAction(
+      { address, action: "OPT_OUT", stateId },
+      signCallback
+    );
+  }
+  /**
+   * Internal helper that runs the two-step user state action flow:
+   * request challenge → user signs → execute action.
+   */
+  async _performUserStateAction(request, signCallback) {
+    const cb = this._resolveMessageCallback(signCallback);
+    const challenge = await this._requestUserAction(request);
+    const { key, signature } = await cb(challenge.message);
+    return this._executeUserAction({
+      address: challenge.address,
+      action: challenge.action,
+      message: challenge.message,
+      signature: challenge.signature,
+      timestamp: challenge.timestamp,
+      userSignature: signature,
+      userPublicKey: key
+    });
+  }
+  _resolveMessageCallback(override) {
+    const cb = override ?? this.defaultSignMessage;
+    if (!cb) {
+      throw new UVerifyValidationError(
+        "No message sign callback provided. Pass one to this method or set signMessage in UVerifyClientOptions."
+      );
+    }
+    return cb;
+  }
+  _resolveTxCallback(override) {
+    const cb = override ?? this.defaultSignTx;
+    if (!cb) {
+      throw new UVerifyValidationError(
+        "No transaction sign callback provided. Pass one to this method or set signTx in UVerifyClientOptions."
+      );
+    }
+    return cb;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UVerifyApiError,
+  UVerifyClient,
+  UVerifyValidationError
+});

package/dist/index.mjs

@@ -0,0 +1,278 @@
+// src/errors.ts
+var UVerifyApiError = class extends Error {
+  constructor(message, statusCode, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "UVerifyApiError";
+  }
+};
+var UVerifyValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UVerifyValidationError";
+  }
+};
+
+// src/UVerifyClient.ts
+var DEFAULT_BASE_URL = "https://api.uverify.io";
+var UVerifyClient = class {
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.defaultHeaders = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...options.headers
+    };
+    this.defaultSignMessage = options.signMessage;
+    this.defaultSignTx = options.signTx;
+    this.core = {
+      buildTransaction: this._buildTransaction.bind(this),
+      submitTransaction: this._submitTransaction.bind(this),
+      requestUserAction: this._requestUserAction.bind(this),
+      executeUserAction: this._executeUserAction.bind(this)
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const init = {
+      method,
+      headers: this.defaultHeaders
+    };
+    if (body !== void 0) {
+      init.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = await response.text();
+      }
+      throw new UVerifyApiError(
+        `UVerify API error ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+    const text = await response.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  // ---------------------------------------------------------------------------
+  // Certificate Verification
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this.get(`/api/v1/verify/${hash}`);
+  }
+  /**
+   * 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, dataHash) {
+    return this.get(
+      `/api/v1/verify/by-transaction-hash/${transactionHash}/${dataHash}`
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Low-level API (exposed via .core)
+  // ---------------------------------------------------------------------------
+  _buildTransaction(request) {
+    return this.post(
+      "/api/v1/transaction/build",
+      request
+    );
+  }
+  async _submitTransaction(transaction, witnessSet) {
+    await this.post("/api/v1/transaction/submit", {
+      transaction,
+      witnessSet
+    });
+  }
+  _requestUserAction(request) {
+    return this.post(
+      "/api/v1/user/request/action",
+      request
+    );
+  }
+  _executeUserAction(request) {
+    return this.post(
+      "/api/v1/user/state/action",
+      request
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // High-level helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * 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),
+   * );
+   * ```
+   */
+  async issueCertificates(address, certificates, signCallback, stateId) {
+    const cb = this._resolveTxCallback(signCallback);
+    const { unsignedTransaction } = await this._buildTransaction({
+      type: "default",
+      address,
+      stateId,
+      certificates
+    });
+    const witnessSet = await cb(unsignedTransaction);
+    await this._submitTransaction(unsignedTransaction, witnessSet);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getUserInfo(address, signCallback) {
+    const result = await this._performUserStateAction(
+      { address, action: "USER_INFO" },
+      signCallback
+    );
+    return result.state;
+  }
+  /**
+   * 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.
+   */
+  async invalidateState(address, stateId, signCallback) {
+    return this._performUserStateAction(
+      { address, action: "INVALIDATE_STATE", stateId },
+      signCallback
+    );
+  }
+  /**
+   * 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.
+   */
+  async optOut(address, stateId, signCallback) {
+    return this._performUserStateAction(
+      { address, action: "OPT_OUT", stateId },
+      signCallback
+    );
+  }
+  /**
+   * Internal helper that runs the two-step user state action flow:
+   * request challenge → user signs → execute action.
+   */
+  async _performUserStateAction(request, signCallback) {
+    const cb = this._resolveMessageCallback(signCallback);
+    const challenge = await this._requestUserAction(request);
+    const { key, signature } = await cb(challenge.message);
+    return this._executeUserAction({
+      address: challenge.address,
+      action: challenge.action,
+      message: challenge.message,
+      signature: challenge.signature,
+      timestamp: challenge.timestamp,
+      userSignature: signature,
+      userPublicKey: key
+    });
+  }
+  _resolveMessageCallback(override) {
+    const cb = override ?? this.defaultSignMessage;
+    if (!cb) {
+      throw new UVerifyValidationError(
+        "No message sign callback provided. Pass one to this method or set signMessage in UVerifyClientOptions."
+      );
+    }
+    return cb;
+  }
+  _resolveTxCallback(override) {
+    const cb = override ?? this.defaultSignTx;
+    if (!cb) {
+      throw new UVerifyValidationError(
+        "No transaction sign callback provided. Pass one to this method or set signTx in UVerifyClientOptions."
+      );
+    }
+    return cb;
+  }
+};
+export {
+  UVerifyApiError,
+  UVerifyClient,
+  UVerifyValidationError
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@uverify/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript/JavaScript SDK for the UVerify API",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "uverify",
+    "cardano",
+    "blockchain",
+    "certificate",
+    "verification",
+    "sdk"
+  ],
+  "author": "Fabian Bormann",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UVerify-io/uverify-sdks"
+  },
+  "homepage": "https://docs.uverify.io",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}