@trusset/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,570 @@
+// src/utils/errors.ts
+var TrussetError = class _TrussetError extends Error {
+  constructor(message, code, statusCode, requestId) {
+    super(message);
+    this.name = "TrussetError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.requestId = requestId ?? null;
+    Object.setPrototypeOf(this, _TrussetError.prototype);
+  }
+};
+var AuthError = class _AuthError extends TrussetError {
+  constructor(message, requestId) {
+    super(message, "AUTH_FAILED", 401, requestId);
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends TrussetError {
+  constructor(message) {
+    super(message, "VALIDATION_ERROR", 400);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var NetworkError = class _NetworkError extends TrussetError {
+  constructor(message) {
+    super(message, "NETWORK_ERROR", 0);
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+
+// src/utils/http.ts
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var silentLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+var HttpClient = class {
+  constructor(config) {
+    this.config = {
+      baseUrl: config.baseUrl ?? "https://api.trusset.org",
+      apiKey: config.apiKey,
+      timeoutMs: config.timeoutMs ?? 3e4,
+      maxRetries: config.maxRetries ?? 3,
+      logger: config.logger ?? silentLogger
+    };
+  }
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    return this.request("GET", url);
+  }
+  async post(path, body) {
+    const url = this.buildUrl(path);
+    return this.request("POST", url, body);
+  }
+  async put(path, body) {
+    const url = this.buildUrl(path);
+    return this.request("PUT", url, body);
+  }
+  async delete(path) {
+    const url = this.buildUrl(path);
+    return this.request("DELETE", url);
+  }
+  // -----------------------------------------------------------------------
+  buildUrl(path, params) {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${base}${cleanPath}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== void 0 && v !== null) {
+          url.searchParams.set(k, String(v));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(method, url, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      if (attempt > 0) {
+        const delay = Math.min(1e3 * Math.pow(2, attempt - 1), 1e4);
+        this.config.logger.debug(`Retry ${attempt}/${this.config.maxRetries} after ${delay}ms`, { url });
+        await sleep(delay);
+      }
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        const headers = {
+          "x-api-key": this.config.apiKey,
+          "Accept": "application/json",
+          "User-Agent": "@trusset/sdk/0.1.0"
+        };
+        if (body !== void 0) {
+          headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, {
+          method,
+          headers,
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (res.status === 401) {
+          const json2 = await res.json().catch(() => ({}));
+          throw new AuthError(
+            json2.error?.message ?? "Authentication failed",
+            json2.metadata?.requestId
+          );
+        }
+        if (RETRYABLE_STATUS.has(res.status)) {
+          lastError = new TrussetError(
+            `Server returned ${res.status}`,
+            "SERVER_ERROR",
+            res.status
+          );
+          continue;
+        }
+        const json = await res.json();
+        if (!json.success) {
+          throw new TrussetError(
+            json.error?.message ?? `Request failed with status ${res.status}`,
+            json.error?.code ?? "REQUEST_FAILED",
+            res.status,
+            json.metadata?.requestId
+          );
+        }
+        return json.data;
+      } catch (err) {
+        if (err instanceof TrussetError) {
+          if (!RETRYABLE_STATUS.has(err.statusCode)) throw err;
+          lastError = err;
+          continue;
+        }
+        if (err instanceof TypeError || err instanceof DOMException && err.name === "AbortError") {
+          lastError = new NetworkError(
+            err instanceof DOMException ? "Request timed out" : `Network error: ${err.message}`
+          );
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError ?? new NetworkError("Request failed after retries");
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/utils/validation.ts
+var ETH_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function requireString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(`${field} is required and must be a non-empty string`);
+  }
+  return value.trim();
+}
+function requireAddress(value, field) {
+  const s = requireString(value, field);
+  if (!ETH_ADDRESS_RE.test(s)) {
+    throw new ValidationError(`${field} must be a valid Ethereum address`);
+  }
+  return s;
+}
+function optionalAddress(value, field) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  return requireAddress(value, field);
+}
+function requireCountry(value, field) {
+  const s = requireString(value, field);
+  if (s.length < 2 || s.length > 3) {
+    throw new ValidationError(`${field} must be a 2-3 letter country code`);
+  }
+  return s.toUpperCase();
+}
+function clampInt(value, min, max, fallback) {
+  if (value === void 0 || value === null) return fallback;
+  const n = Math.floor(value);
+  if (isNaN(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+// src/modules/customers/management.ts
+var CustomerManagement = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List customers for the current instance.
+   */
+  async list(options = {}) {
+    const params = {
+      limit: clampInt(options.limit, 1, 200, 100),
+      offset: clampInt(options.offset, 0, Number.MAX_SAFE_INTEGER, 0),
+      includeArchived: options.includeArchived ? "true" : void 0,
+      search: options.search || void 0
+    };
+    return this.http.get("/customers/api/manage", params);
+  }
+  /**
+   * Get a customer by wallet address, ID, externalId, or referenceKey.
+   */
+  async get(identifier) {
+    requireString(identifier, "identifier");
+    return this.http.get(`/customers/api/manage/${encodeURIComponent(identifier)}`);
+  }
+  /**
+   * Create a new customer record.
+   */
+  async create(input) {
+    if (input.walletAddress) optionalAddress(input.walletAddress, "walletAddress");
+    return this.http.post("/customers/api/manage", input);
+  }
+  /**
+   * Update an existing customer.
+   */
+  async update(customerId, input) {
+    requireString(customerId, "customerId");
+    return this.http.put(`/customers/api/manage/${encodeURIComponent(customerId)}`, input);
+  }
+  /**
+   * Archive (soft-delete) a customer.
+   */
+  async archive(customerId) {
+    requireString(customerId, "customerId");
+    return this.http.delete(`/customers/api/manage/${encodeURIComponent(customerId)}`);
+  }
+  /**
+   * Link a wallet address to a customer created via referenceKey.
+   */
+  async linkWallet(input) {
+    requireString(input.referenceKey, "referenceKey");
+    requireAddress(input.walletAddress, "walletAddress");
+    return this.http.post("/customers/api/manage/link-wallet", input);
+  }
+  /**
+   * Batch-fetch country codes for a list of wallet addresses.
+   */
+  async batchGetCountries(addresses) {
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      return {};
+    }
+    return this.http.post("/customers/api/manage/countries/batch", { addresses });
+  }
+  // -----------------------------------------------------------------------
+  // Convenience search helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Search customers by name substring.
+   */
+  async searchByName(name, options) {
+    return this.list({ ...options, search: name });
+  }
+  /**
+   * Find a customer by wallet address.
+   */
+  async searchByWallet(walletAddress) {
+    requireAddress(walletAddress, "walletAddress");
+    return this.get(walletAddress);
+  }
+  /**
+   * Find a customer by external ID (your system's unique identifier).
+   */
+  async searchByExternalId(externalId) {
+    requireString(externalId, "externalId");
+    return this.get(externalId);
+  }
+  /**
+   * Find a customer by reference key (for pre-wallet customers).
+   */
+  async searchByReference(referenceKey) {
+    requireString(referenceKey, "referenceKey");
+    return this.get(referenceKey);
+  }
+};
+
+// src/modules/customers/identity.ts
+var CustomerIdentity = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Verify a customer's identity on-chain via the IdentityRegistry contract.
+   * Requires a configured relayer on the instance.
+   */
+  async verify(input) {
+    requireAddress(input.walletAddress, "walletAddress");
+    requireCountry(input.country, "country");
+    return this.http.post("/customers/api/identity/verify", input);
+  }
+  /**
+   * Batch-verify up to 500 identities in a single transaction.
+   * Requires a configured relayer.
+   */
+  async batchVerify(entries) {
+    if (!Array.isArray(entries) || entries.length === 0 || entries.length > 500) {
+      throw new ValidationError("Provide 1-500 entries for batch verification");
+    }
+    for (const e of entries) {
+      requireAddress(e.walletAddress, "walletAddress");
+      requireCountry(e.country, "country");
+    }
+    return this.http.post("/customers/api/identity/batch-verify", { entries });
+  }
+  /**
+   * Revoke an identity on-chain. Requires a configured relayer.
+   */
+  async revoke(walletAddress) {
+    requireAddress(walletAddress, "walletAddress");
+    return this.http.post("/customers/api/identity/revoke", { walletAddress });
+  }
+  /**
+   * Get combined on-chain and off-chain identity status.
+   */
+  async getStatus(walletAddress) {
+    requireAddress(walletAddress, "walletAddress");
+    return this.http.get(`/customers/api/identity/status/${walletAddress}`);
+  }
+  /**
+   * Check whether a token transfer between two addresses is compliant.
+   * Runs identity checks + all registered compliance modules.
+   */
+  async canTransfer(input) {
+    requireAddress(input.from, "from");
+    requireAddress(input.to, "to");
+    return this.http.post("/customers/api/identity/can-transfer", input);
+  }
+};
+
+// src/modules/customers/id-links.ts
+var CustomerIdLinks = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a KYC verification link to send to an investor.
+   */
+  async create(input) {
+    if (!input.recipientEmail && !input.recipientWallet && !input.recipientPhone) {
+      throw new ValidationError("At least one of recipientEmail, recipientWallet, or recipientPhone is required");
+    }
+    return this.http.post("/customers/api/id-links", input);
+  }
+  /**
+   * List all verification links for the current instance.
+   */
+  async list(options = {}) {
+    const params = {
+      limit: clampInt(options.limit, 1, 200, 50),
+      offset: clampInt(options.offset, 0, Number.MAX_SAFE_INTEGER, 0),
+      status: options.status
+    };
+    return this.http.get("/customers/api/id-links", params);
+  }
+  /**
+   * Revoke (expire) a verification link so it can no longer be used.
+   */
+  async revoke(linkId) {
+    requireString(linkId, "linkId");
+    await this.http.put(`/customers/api/id-links/${encodeURIComponent(linkId)}/revoke`);
+  }
+  /**
+   * Resend a verification link via the specified channels.
+   */
+  async resend(linkId, channels) {
+    requireString(linkId, "linkId");
+    if (!Array.isArray(channels) || channels.length === 0) {
+      throw new ValidationError("channels array is required (email and/or sms)");
+    }
+    return this.http.post(`/customers/api/id-links/${encodeURIComponent(linkId)}/resend`, { channels });
+  }
+};
+
+// src/modules/customers/sync.ts
+var DEFAULT_BATCH_SIZE = 50;
+var MAX_BATCH_SIZE = 200;
+var MAX_VERIFY_BATCH = 500;
+var CustomerSync = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Import customer records from an external system.
+   *
+   * Each record is mapped by `externalId`. If a customer with that externalId
+   * already exists, the `onConflict` strategy determines whether to skip or
+   * update.
+   *
+   * When `verifyOnChain` is true, records that include a `walletAddress` and
+   * `country` will be batch-verified on-chain after the database import.
+   */
+  async importRecords(records, options = {}) {
+    if (!Array.isArray(records) || records.length === 0) {
+      throw new ValidationError("records must be a non-empty array");
+    }
+    const batchSize = clampInt(options.batchSize, 1, MAX_BATCH_SIZE, DEFAULT_BATCH_SIZE);
+    const onConflict = options.onConflict ?? "update";
+    const result = { total: records.length, created: 0, updated: 0, skipped: 0, errors: [] };
+    const verifyQueue = [];
+    for (let i = 0; i < records.length; i += batchSize) {
+      const batch = records.slice(i, i + batchSize);
+      const batchResults = await Promise.allSettled(
+        batch.map((record) => this.processRecord(record, onConflict))
+      );
+      for (let j = 0; j < batchResults.length; j++) {
+        const settled = batchResults[j];
+        const record = batch[j];
+        if (settled.status === "fulfilled") {
+          const outcome = settled.value;
+          if (outcome.action === "created") result.created++;
+          else if (outcome.action === "updated") result.updated++;
+          else result.skipped++;
+          if (options.verifyOnChain && record.walletAddress && record.country && outcome.action !== "skipped") {
+            verifyQueue.push({
+              walletAddress: record.walletAddress,
+              country: record.country,
+              investorType: record.investorType,
+              softExpiryDays: options.verificationDefaults?.softExpiryDays,
+              hardExpiryDays: options.verificationDefaults?.hardExpiryDays
+            });
+          }
+        } else {
+          const err = settled.reason;
+          result.errors.push({
+            externalId: record.externalId,
+            code: err?.code ?? "UNKNOWN",
+            message: err?.message ?? "Unknown error"
+          });
+        }
+      }
+      options.onProgress?.(Math.min(i + batchSize, records.length), records.length);
+    }
+    if (verifyQueue.length > 0) {
+      await this.runBatchVerification(verifyQueue, result);
+    }
+    return result;
+  }
+  /**
+   * Export all customers from Trusset as flat records.
+   * Useful for syncing data back into your system.
+   */
+  async exportRecords(options = {}) {
+    const allRecords = [];
+    let offset = 0;
+    const limit = 200;
+    while (true) {
+      const page = await this.http.get("/customers/api/manage", {
+        limit,
+        offset,
+        includeArchived: options.includeArchived ? "true" : void 0
+      });
+      if (!page.customers || page.customers.length === 0) break;
+      for (const c of page.customers) {
+        allRecords.push({
+          externalId: c.externalId ?? c.id,
+          walletAddress: c.walletAddress ?? void 0,
+          name: c.name ?? void 0,
+          country: c.country ?? void 0,
+          investorType: c.investorType ?? void 0,
+          metadata: c.metadata ?? void 0
+        });
+      }
+      offset += page.customers.length;
+      if (offset >= page.total) break;
+    }
+    return allRecords;
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  async processRecord(record, onConflict) {
+    requireString(record.externalId, "externalId");
+    let existing = null;
+    try {
+      existing = await this.http.get(
+        `/customers/api/manage/${encodeURIComponent(record.externalId)}`
+      );
+    } catch (err) {
+      const code = err?.code;
+      const statusCode = err?.statusCode;
+      if (statusCode !== 404 && code !== "NOT_FOUND") throw err;
+    }
+    if (existing) {
+      if (onConflict === "skip") {
+        return { action: "skipped" };
+      }
+      await this.http.put(`/customers/api/manage/${encodeURIComponent(existing.id)}`, {
+        name: record.name,
+        country: record.country,
+        investorType: record.investorType,
+        walletAddress: record.walletAddress,
+        metadata: record.metadata
+      });
+      return { action: "updated" };
+    }
+    await this.http.post("/customers/api/manage", {
+      externalId: record.externalId,
+      walletAddress: record.walletAddress,
+      name: record.name,
+      country: record.country,
+      investorType: record.investorType,
+      metadata: record.metadata
+    });
+    return { action: "created" };
+  }
+  async runBatchVerification(queue, result) {
+    for (let i = 0; i < queue.length; i += MAX_VERIFY_BATCH) {
+      const batch = queue.slice(i, i + MAX_VERIFY_BATCH);
+      try {
+        await this.http.post("/customers/api/identity/batch-verify", { entries: batch });
+      } catch (err) {
+        for (const entry of batch) {
+          result.errors.push({
+            externalId: entry.walletAddress,
+            code: "VERIFY_FAILED",
+            message: err?.message ?? "On-chain batch verification failed"
+          });
+        }
+      }
+    }
+  }
+};
+
+// src/modules/customers/index.ts
+var Customers = class {
+  constructor(http) {
+    this.manage = new CustomerManagement(http);
+    this.identity = new CustomerIdentity(http);
+    this.idLinks = new CustomerIdLinks(http);
+    this.sync = new CustomerSync(http);
+  }
+};
+
+// src/client.ts
+var TrussetClient = class {
+  constructor(config) {
+    if (!config.apiKey || typeof config.apiKey !== "string" || config.apiKey.length < 20) {
+      throw new ValidationError("A valid apiKey is required");
+    }
+    this.http = new HttpClient({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      timeoutMs: config.timeoutMs,
+      maxRetries: config.maxRetries,
+      logger: config.logger
+    });
+    this.customers = new Customers(this.http);
+  }
+};
+export {
+  AuthError,
+  CustomerIdLinks,
+  CustomerIdentity,
+  CustomerManagement,
+  CustomerSync,
+  Customers,
+  NetworkError,
+  TrussetClient,
+  TrussetError,
+  ValidationError
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@trusset/sdk",
+    "version": "0.1.0",
+    "description": "Trusset SDK - End-to-end tokenization infrastructure for financial institutions",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.js"
+      },
+      "./customers": {
+        "types": "./dist/modules/customers/index.d.ts",
+        "import": "./dist/modules/customers/index.mjs",
+        "require": "./dist/modules/customers/index.js"
+      }
+    },
+    "files": [
+      "dist"
+    ],
+    "scripts": {
+      "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+      "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+      "lint": "eslint src --ext .ts",
+      "test": "vitest run",
+      "test:watch": "vitest",
+      "typecheck": "tsc --noEmit",
+      "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+      "trusset",
+      "tokenization",
+      "mica",
+      "kyc",
+      "security-tokens",
+      "blockchain",
+      "fintech"
+    ],
+    "author": "Trusset UG",
+    "license": "MIT",
+    "engines": {
+      "node": ">=22.0.0"
+    },
+    "dependencies": {},
+    "devDependencies": {
+      "tsup": "^8.3.0",
+      "typescript": "^5.6.0",
+      "vitest": "^2.1.0",
+      "eslint": "^8.57.0",
+      "@typescript-eslint/eslint-plugin": "^7.0.0",
+      "@typescript-eslint/parser": "^7.0.0"
+    }
+  }