timefi-sdk 0.1.3 → 0.2.0

package/README.md

@@ -3,58 +3,104 @@
 The official JavaScript SDK for interacting with the **TimeFi Protocol** on the Stacks blockchain.
 
 [![npm version](https://img.shields.io/npm/v/timefi-sdk.svg)](https://www.npmjs.com/package/timefi-sdk)
+[![Downloads](https://img.shields.io/npm/dm/timefi-sdk.svg)](https://www.npmjs.com/package/timefi-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Features
+## Features
 
-- **Protocol Client**: Easy-to-use `TimeFiClient` for read and write interactions.
-- **On-chain Data**: Fetch TVL, vault status, and lock durations directly from smart contracts.
-- **Formatting Utilities**: Standardized formatting for STX (microSTX to STX), addresses, and dates.
-- **Mainnet/Testnet Support**: Unified interface for both networks.
+- Protocol Client: Easy-to-use `TimeFiClient` for read and write interactions.
+- On-chain Data: Fetch TVL, vault status, and lock durations directly from smart contracts.
+- Formatting Utilities: Standardized formatting for STX (microSTX to STX), addresses, dates, and timestamps.
+- Shared Helpers: Utility helpers and protocol models from the old `timefi-utils` and `timefi-types` packages are now included directly in `timefi-sdk`.
+- Mainnet/Testnet Support: Unified interface for both networks.
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install timefi-sdk
-
-### Running Tests
-
-```bash
-npm test
 ```
-## 🛠️ Quick Start
+
+## Quick Start
 
 ### Fetch Protocol Stats
 
 ```javascript
 import { TimeFiClient, formatSTX } from 'timefi-sdk';
 
-// Initialize for Stacks Mainnet
 const client = new TimeFiClient('mainnet');
-
-// Get Total Value Locked
 const tvl = await client.getTVL();
+
 console.log(`Current TVL: ${formatSTX(tvl)} STX`);
 ```
 
+### Build a Create-Vault Transaction
+
+```javascript
+import { TimeFiClient } from 'timefi-sdk';
+
+const client = new TimeFiClient('mainnet');
+
+const txOptions = client.getCreateVaultOptions('1.25', 4320);
+```
+
 ### Format a Stacks Address
 
 ```javascript
 import { formatAddress } from 'timefi-sdk';
 
-const shortAddress = formatAddress('SP3...XYZ123');
-console.log(shortAddress); // SP3...Z123
+const shortAddress = formatAddress('SP3F1234567890ABCDEFG1234567890XYZ123');
+console.log(shortAddress);
 ```
 
-## 📖 Documentation
+### Use Integrated Utilities and Protocol Helpers
+
+```javascript
+import {
+  calculateTimeRemaining,
+  getProtocolConfig,
+  validateAddress,
+} from 'timefi-sdk';
+
+const config = getProtocolConfig();
+const remaining = calculateTimeRemaining(Date.now() + 60_000);
+const isValid = validateAddress('SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N');
+```
 
-The SDK provides the following exports:
+## Running Tests
 
-- `TimeFiClient`: Core class for blockchain interactions.
-- `formatSTX(microStx)`: Converts microSTX to a human-readable STX string.
-- `formatAddress(address)`: Truncates addresses for UI display.
-- `CONTRACT_ADDRESS`: The main TimeFi Protocol contract address on Stacks.
+```bash
+npm test
+```
 
-## 📄 License
+## Documentation
+
+The SDK exports:
+
+- `TimeFiClient`
+- `formatSTX(microStx)`
+- `formatAddress(address)`
+- `formatTimestamp(timestamp)`
+- `calculateTimeRemaining(endTime)`
+- `validateAddress(address)`
+- `validateAddressResult(address)`
+- `formatAmount(amount, decimals?)`
+- `parseAmount(amount)`
+- `generateId()`
+- `sleep(ms)`
+- `retry(fn, maxRetries?, delay?)`
+- `initializeProtocol(options?)`
+- `getProtocolVersion()`
+- `getProtocolConfig()`
+- `normalizeVault(vault)`
+- `normalizeTransaction(transaction)`
+- `formatNumber(value)`
+- `formatPercent(value)`
+- `formatDate(value)`
+- `formatRelativeTime(value)`
+- `CONTRACT_ADDRESS`
+- `CONTRACT_NAMES`
+- `LOCK_PERIODS`
+
+## License
 
 MIT © [AdekunleBamz](https://github.com/AdekunleBamz)

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+export class TimeFiClient {
+    constructor(networkType?: string);
+    networkType: string;
+    network: StacksMainnet | StacksTestnet;
+    contractAddress: string;
+    callReadOnly(functionName: any, functionArgs: any[], senderAddress: any): Promise<any>;
+    getVault(vaultId: any): Promise<any>;
+    getTimeRemaining(vaultId: any): Promise<any>;
+    canWithdraw(vaultId: any): Promise<any>;
+    getTVL(): Promise<any>;
+    getCreateVaultOptions(amountSTX: any, lockDurationBlocks: any): {
+        contractAddress: string;
+        contractName: string;
+        functionName: string;
+        functionArgs: import("@stacks/transactions").UIntCV[];
+        network: StacksMainnet | StacksTestnet;
+        anchorMode: AnchorMode;
+        postConditionMode: PostConditionMode;
+    };
+    getWithdrawOptions(vaultId: any): {
+        contractAddress: string;
+        contractName: string;
+        functionName: string;
+        functionArgs: import("@stacks/transactions").UIntCV[];
+        network: StacksMainnet | StacksTestnet;
+        anchorMode: AnchorMode;
+        postConditionMode: PostConditionMode;
+    };
+}
+import { StacksMainnet } from '@stacks/network';
+import { StacksTestnet } from '@stacks/network';
+import { AnchorMode } from '@stacks/transactions';
+import { PostConditionMode } from '@stacks/transactions';

package/dist/constants.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Protocol Constants
+ */
+export const CONTRACT_ADDRESS: "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N";
+export namespace CONTRACT_NAMES {
+    let VAULT: string;
+    let REWARDS: string;
+    let GOVERNANCE: string;
+    let EMERGENCY: string;
+}
+export namespace LOCK_PERIODS {
+    namespace MONTH_1 {
+        let label: string;
+        let blocks: number;
+        let apy: number;
+    }
+    namespace MONTH_3 {
+        let label_1: string;
+        export { label_1 as label };
+        let blocks_1: number;
+        export { blocks_1 as blocks };
+        let apy_1: number;
+        export { apy_1 as apy };
+    }
+    namespace MONTH_6 {
+        let label_2: string;
+        export { label_2 as label };
+        let blocks_2: number;
+        export { blocks_2 as blocks };
+        let apy_2: number;
+        export { apy_2 as apy };
+    }
+    namespace MONTH_9 {
+        let label_3: string;
+        export { label_3 as label };
+        let blocks_3: number;
+        export { blocks_3 as blocks };
+        let apy_3: number;
+        export { apy_3 as apy };
+    }
+    namespace YEAR_1 {
+        let label_4: string;
+        export { label_4 as label };
+        let blocks_4: number;
+        export { blocks_4 as blocks };
+        let apy_4: number;
+        export { apy_4 as apy };
+    }
+}
+export const MIN_DEPOSIT: 0.01;
+export const MAX_DEPOSIT: 1000000;

package/dist/format.d.ts

@@ -0,0 +1,6 @@
+export function formatSTX(microStx: any): string;
+export function formatAddress(address: any, prefix?: number, suffix?: number): any;
+export function formatNumber(val: any): string;
+export function formatPercent(val: any, decimals?: number): string;
+export function formatDate(date: any): string;
+export function formatRelativeTime(date: any): string;

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@stacks/transactions"),f=require("@stacks/network"),d="SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N",u={VAULT:"timefi-vault-v-A2",REWARDS:"timefi-rewards-v-A2",GOVERNANCE:"timefi-governance-v-A2",EMERGENCY:"timefi-emergency-v-A2"},p={MONTH_1:{label:"1 Month",blocks:4320,apy:1},MONTH_3:{label:"3 Months",blocks:12960,apy:3},MONTH_6:{label:"6 Months",blocks:25920,apy:6},MONTH_9:{label:"9 Months",blocks:38880,apy:9},YEAR_1:{label:"1 Year",blocks:52560,apy:12}},y=.01,M=1e6,V=e=>{if(e==null)return"0.000000";try{const t=typeof e=="object"&&e!==null&&"value"in e?e.value:e,r=Number(t);return isNaN(r)?"0.000000":(r/1e6).toLocaleString(void 0,{minimumFractionDigits:0,maximumFractionDigits:6})}catch(t){return console.error("Error formatting STX:",t),"0.000000"}},E=(e,t=4,r=4)=>e?e.length<=t+r?e:`${e.slice(0,t+2)}...${e.slice(-r)}`:"",P=e=>{if(e==null)return"0";const t=Number(e);return isNaN(t)?"0":t.toLocaleString()},R=(e,t=2)=>{if(e==null)return"0%";const r=Number(e);return isNaN(r)?"0%":(r*100).toFixed(t)+"%"},m=e=>{if(!e)return"--";const t=new Date(e);return isNaN(t.getTime())?"--":t.toLocaleDateString(void 0,{year:"numeric",month:"short",day:"numeric"})},_=e=>{if(!e)return"--";const t=new Date,r=new Date(e),n=Math.floor((t-r)/1e3);if(n<-1){const i=Math.abs(n);return i<60?"in a few seconds":i<3600?`in ${Math.floor(i/60)}m`:i<86400?`in ${Math.floor(i/3600)}h`:`in ${Math.floor(i/86400)}d`}return n<5?"just now":n<60?`${n}s ago`:n<3600?`${Math.floor(n/60)}m ago`:n<86400?`${Math.floor(n/3600)}h ago`:n<604800?`${Math.floor(n/86400)}d ago`:m(e)},D=/^S[PTMN][A-Z0-9]{38,40}$/i;function v(e){const t=Number(e);return!Number.isInteger(t)||t<0?6:t}function k(e){const t=e instanceof Date?e:new Date(e);return Number.isNaN(t.getTime())?"Invalid Date":t.toLocaleString()}function I(e){const t=e instanceof Date?e.getTime():Number(e),r=Number.isFinite(t)?t-Date.now():0;if(r<=0)return{days:0,hours:0,minutes:0,seconds:0,total:0};const n=Math.floor(r/(1e3*60*60*24)),i=Math.floor(r%(1e3*60*60*24)/(1e3*60*60)),l=Math.floor(r%(1e3*60*60)/(1e3*60)),C=Math.floor(r%(1e3*60)/1e3);return{days:n,hours:i,minutes:l,seconds:C,total:r}}function g(e){if(typeof e!="string")return{valid:!1,error:"Address must be a string."};const t=e.trim().toUpperCase();return t?D.test(t)?{valid:!0,address:t}:{valid:!1,address:t,error:"Address must be a valid Stacks address."}:{valid:!1,error:"Address is required."}}function F(e){return g(e).valid}function L(e,t=6){const r=Number(e),n=v(t);return Number.isFinite(r)?r.toFixed(n):0 .toFixed(n)}function j(e){const t=Number.parseFloat(String(e).replace(/,/g,"").trim());return Number.isFinite(t)?t:0}function U(){return`${Date.now()}-${Math.random().toString(36).slice(2,11)}`}function T(e){const t=Number.isFinite(e)&&e>0?e:0;return new Promise(r=>setTimeout(r,t))}async function z(e,t=3,r=1e3){const n=Number.isInteger(t)&&t>0?t:1;for(let i=0;i<n;i+=1)try{return await e()}catch(l){if(i===n-1)throw l;await T(r)}throw new Error("Retry exhausted without executing the operation.")}const A="1.0.0",h=Object.freeze({timeLock:!0,vaults:!0,governance:!1,rewards:!1}),b=Object.freeze(["active","locked","withdrawn","failed"]),N=Object.freeze(["deposit","withdraw","create","fee"]),S=Object.freeze(["pending","confirmed","failed"]);function s(e,t=0){const r=Number(e);return Number.isFinite(r)?r:t}function $(e){return b.includes(e)?e:"active"}function G(e){return N.includes(e)?e:"deposit"}function X(e){return S.includes(e)?e:"pending"}function O(e={}){const t={...h,...e.features||{}};return{network:e.network||"mainnet",version:e.version||A,features:t,initialized:e.initialized??!0}}let c=O();function H(e={}){return c=O(e),w()}function q(){return c.version}function w(){return{...c,features:{...c.features}}}function Y(e={}){return{id:e.id?String(e.id):"",owner:e.owner?String(e.owner):"",amount:s(e.amount),lockTime:s(e.lockTime),unlockTime:s(e.unlockTime),status:$(e.status),fees:s(e.fees)}}function Z(e={}){return{hash:e.hash?String(e.hash):"",type:G(e.type),amount:s(e.amount),from:e.from?String(e.from):"",to:e.to?String(e.to):"",timestamp:s(e.timestamp),status:X(e.status)}}function a(e,t){if(!Number.isInteger(e)||e<=0)throw new Error(`${t} must be a positive integer.`)}function K(e){if(e==null)throw new Error("amountSTX is required");const t=String(e).trim();if(!/^\d+(\.\d+)?$/.test(t))throw new Error("amountSTX must be a valid positive number.");const[r,n=""]=t.split(".");if(n.length>6)throw new Error("amountSTX supports at most 6 decimal places.");const i=BigInt(r)*1000000n+BigInt((n+"000000").slice(0,6));if(i<=0n)throw new Error("amountSTX must be greater than 0.");return i}class B{constructor(t="mainnet"){if(!["mainnet","testnet"].includes(t))throw new Error(`Invalid networkType "${t}". Use "mainnet" or "testnet".`);this.networkType=t,this.network=t==="mainnet"?new f.StacksMainnet:new f.StacksTestnet,this.contractAddress=d}async callReadOnly(t,r=[],n){const i=await o.callReadOnlyFunction({contractAddress:this.contractAddress,contractName:u.VAULT,functionName:t,functionArgs:r,network:this.network,senderAddress:n||this.contractAddress});return i.type===7||i.type===8?o.cvToValue(i.value):o.cvToValue(i)}async getVault(t){return a(t,"vaultId"),this.callReadOnly("get-vault",[o.uintCV(t)])}async getTimeRemaining(t){return a(t,"vaultId"),this.callReadOnly("get-time-remaining",[o.uintCV(t)])}async canWithdraw(t){return a(t,"vaultId"),this.callReadOnly("can-withdraw",[o.uintCV(t)])}async getTVL(){return this.callReadOnly("get-tvl",[])}getCreateVaultOptions(t,r){return a(r,"lockDurationBlocks"),{contractAddress:this.contractAddress,contractName:u.VAULT,functionName:"create-vault",functionArgs:[o.uintCV(K(t)),o.uintCV(r)],network:this.network,anchorMode:o.AnchorMode.Any,postConditionMode:o.PostConditionMode.Allow}}getWithdrawOptions(t){return a(t,"vaultId"),{contractAddress:this.contractAddress,contractName:u.VAULT,functionName:"request-withdraw",functionArgs:[o.uintCV(t)],network:this.network,anchorMode:o.AnchorMode.Any,postConditionMode:o.PostConditionMode.Allow}}}Object.defineProperty(exports,"AnchorMode",{enumerable:!0,get:()=>o.AnchorMode});Object.defineProperty(exports,"PostConditionMode",{enumerable:!0,get:()=>o.PostConditionMode});Object.defineProperty(exports,"bufferCV",{enumerable:!0,get:()=>o.bufferCV});Object.defineProperty(exports,"noneCV",{enumerable:!0,get:()=>o.noneCV});Object.defineProperty(exports,"principalCV",{enumerable:!0,get:()=>o.principalCV});Object.defineProperty(exports,"responseErrorCV",{enumerable:!0,get:()=>o.responseErrorCV});Object.defineProperty(exports,"responseOkCV",{enumerable:!0,get:()=>o.responseOkCV});Object.defineProperty(exports,"someCV",{enumerable:!0,get:()=>o.someCV});Object.defineProperty(exports,"stringAsciiCV",{enumerable:!0,get:()=>o.stringAsciiCV});Object.defineProperty(exports,"stringUtf8CV",{enumerable:!0,get:()=>o.stringUtf8CV});Object.defineProperty(exports,"uintCV",{enumerable:!0,get:()=>o.uintCV});exports.CONTRACT_ADDRESS=d;exports.CONTRACT_NAMES=u;exports.DEFAULT_PROTOCOL_FEATURES=h;exports.LOCK_PERIODS=p;exports.MAX_DEPOSIT=M;exports.MIN_DEPOSIT=y;exports.PROTOCOL_VERSION=A;exports.TRANSACTION_STATUSES=S;exports.TRANSACTION_TYPES=N;exports.TimeFiClient=B;exports.VAULT_STATUSES=b;exports.calculateTimeRemaining=I;exports.formatAddress=E;exports.formatAmount=L;exports.formatDate=m;exports.formatNumber=P;exports.formatPercent=R;exports.formatRelativeTime=_;exports.formatSTX=V;exports.formatTimestamp=k;exports.generateId=U;exports.getProtocolConfig=w;exports.getProtocolVersion=q;exports.initializeProtocol=H;exports.normalizeTransaction=Z;exports.normalizeVault=Y;exports.parseAmount=j;exports.retry=z;exports.sleep=T;exports.validateAddress=F;exports.validateAddressResult=g;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./constants.js";
+export * from "./format.js";
+export * from "./utils.js";
+export * from "./protocol.js";
+export * from "./client.js";
+export { uintCV, principalCV, bufferCV, stringAsciiCV, stringUtf8CV, noneCV, someCV, responseOkCV, responseErrorCV, AnchorMode, PostConditionMode } from "@stacks/transactions";

package/dist/index.mjs

@@ -0,0 +1,283 @@
+import { callReadOnlyFunction as w, cvToValue as f, uintCV as i, PostConditionMode as d, AnchorMode as m } from "@stacks/transactions";
+import { AnchorMode as it, PostConditionMode as st, bufferCV as at, noneCV as ut, principalCV as ct, responseErrorCV as lt, responseOkCV as ft, someCV as dt, stringAsciiCV as mt, stringUtf8CV as ht, uintCV as gt } from "@stacks/transactions";
+import { StacksMainnet as A, StacksTestnet as N } from "@stacks/network";
+const T = "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N", l = {
+  VAULT: "timefi-vault-v-A2",
+  REWARDS: "timefi-rewards-v-A2",
+  GOVERNANCE: "timefi-governance-v-A2",
+  EMERGENCY: "timefi-emergency-v-A2"
+}, L = {
+  MONTH_1: { label: "1 Month", blocks: 4320, apy: 1 },
+  MONTH_3: { label: "3 Months", blocks: 12960, apy: 3 },
+  MONTH_6: { label: "6 Months", blocks: 25920, apy: 6 },
+  MONTH_9: { label: "9 Months", blocks: 38880, apy: 9 },
+  YEAR_1: { label: "1 Year", blocks: 52560, apy: 12 }
+}, $ = 0.01, z = 1e6, U = (t) => {
+  if (t == null) return "0.000000";
+  try {
+    const e = typeof t == "object" && t !== null && "value" in t ? t.value : t, n = Number(e);
+    return isNaN(n) ? "0.000000" : (n / 1e6).toLocaleString(void 0, {
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 6
+    });
+  } catch (e) {
+    return console.error("Error formatting STX:", e), "0.000000";
+  }
+}, G = (t, e = 4, n = 4) => t ? t.length <= e + n ? t : `${t.slice(0, e + 2)}...${t.slice(-n)}` : "", j = (t) => {
+  if (t == null) return "0";
+  const e = Number(t);
+  return isNaN(e) ? "0" : e.toLocaleString();
+}, H = (t, e = 2) => {
+  if (t == null) return "0%";
+  const n = Number(t);
+  return isNaN(n) ? "0%" : (n * 100).toFixed(e) + "%";
+}, b = (t) => {
+  if (!t) return "--";
+  const e = new Date(t);
+  return isNaN(e.getTime()) ? "--" : e.toLocaleDateString(void 0, {
+    year: "numeric",
+    month: "short",
+    day: "numeric"
+  });
+}, X = (t) => {
+  if (!t) return "--";
+  const e = /* @__PURE__ */ new Date(), n = new Date(t), r = Math.floor((e - n) / 1e3);
+  if (r < -1) {
+    const o = Math.abs(r);
+    return o < 60 ? "in a few seconds" : o < 3600 ? `in ${Math.floor(o / 60)}m` : o < 86400 ? `in ${Math.floor(o / 3600)}h` : `in ${Math.floor(o / 86400)}d`;
+  }
+  return r < 5 ? "just now" : r < 60 ? `${r}s ago` : r < 3600 ? `${Math.floor(r / 60)}m ago` : r < 86400 ? `${Math.floor(r / 3600)}h ago` : r < 604800 ? `${Math.floor(r / 86400)}d ago` : b(t);
+}, S = /^S[PTMN][A-Z0-9]{38,40}$/i;
+function p(t) {
+  const e = Number(t);
+  return !Number.isInteger(e) || e < 0 ? 6 : e;
+}
+function Z(t) {
+  const e = t instanceof Date ? t : new Date(t);
+  return Number.isNaN(e.getTime()) ? "Invalid Date" : e.toLocaleString();
+}
+function Y(t) {
+  const e = t instanceof Date ? t.getTime() : Number(t), n = Number.isFinite(e) ? e - Date.now() : 0;
+  if (n <= 0)
+    return { days: 0, hours: 0, minutes: 0, seconds: 0, total: 0 };
+  const r = Math.floor(n / (1e3 * 60 * 60 * 24)), o = Math.floor(n % (1e3 * 60 * 60 * 24) / (1e3 * 60 * 60)), c = Math.floor(n % (1e3 * 60 * 60) / (1e3 * 60)), g = Math.floor(n % (1e3 * 60) / 1e3);
+  return { days: r, hours: o, minutes: c, seconds: g, total: n };
+}
+function M(t) {
+  if (typeof t != "string")
+    return { valid: !1, error: "Address must be a string." };
+  const e = t.trim().toUpperCase();
+  return e ? S.test(e) ? { valid: !0, address: e } : { valid: !1, address: e, error: "Address must be a valid Stacks address." } : { valid: !1, error: "Address is required." };
+}
+function q(t) {
+  return M(t).valid;
+}
+function B(t, e = 6) {
+  const n = Number(t), r = p(e);
+  return Number.isFinite(n) ? n.toFixed(r) : 0 .toFixed(r);
+}
+function K(t) {
+  const e = Number.parseFloat(String(t).replace(/,/g, "").trim());
+  return Number.isFinite(e) ? e : 0;
+}
+function W() {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function y(t) {
+  const e = Number.isFinite(t) && t > 0 ? t : 0;
+  return new Promise((n) => setTimeout(n, e));
+}
+async function x(t, e = 3, n = 1e3) {
+  const r = Number.isInteger(e) && e > 0 ? e : 1;
+  for (let o = 0; o < r; o += 1)
+    try {
+      return await t();
+    } catch (c) {
+      if (o === r - 1)
+        throw c;
+      await y(n);
+    }
+  throw new Error("Retry exhausted without executing the operation.");
+}
+const C = "1.0.0", O = Object.freeze({
+  timeLock: !0,
+  vaults: !0,
+  governance: !1,
+  rewards: !1
+}), E = Object.freeze(["active", "locked", "withdrawn", "failed"]), R = Object.freeze(["deposit", "withdraw", "create", "fee"]), V = Object.freeze(["pending", "confirmed", "failed"]);
+function s(t, e = 0) {
+  const n = Number(t);
+  return Number.isFinite(n) ? n : e;
+}
+function D(t) {
+  return E.includes(t) ? t : "active";
+}
+function k(t) {
+  return R.includes(t) ? t : "deposit";
+}
+function v(t) {
+  return V.includes(t) ? t : "pending";
+}
+function h(t = {}) {
+  const e = {
+    ...O,
+    ...t.features || {}
+  };
+  return {
+    network: t.network || "mainnet",
+    version: t.version || C,
+    features: e,
+    initialized: t.initialized ?? !0
+  };
+}
+let u = h();
+function J(t = {}) {
+  return u = h(t), _();
+}
+function Q() {
+  return u.version;
+}
+function _() {
+  return {
+    ...u,
+    features: { ...u.features }
+  };
+}
+function tt(t = {}) {
+  return {
+    id: t.id ? String(t.id) : "",
+    owner: t.owner ? String(t.owner) : "",
+    amount: s(t.amount),
+    lockTime: s(t.lockTime),
+    unlockTime: s(t.unlockTime),
+    status: D(t.status),
+    fees: s(t.fees)
+  };
+}
+function et(t = {}) {
+  return {
+    hash: t.hash ? String(t.hash) : "",
+    type: k(t.type),
+    amount: s(t.amount),
+    from: t.from ? String(t.from) : "",
+    to: t.to ? String(t.to) : "",
+    timestamp: s(t.timestamp),
+    status: v(t.status)
+  };
+}
+function a(t, e) {
+  if (!Number.isInteger(t) || t <= 0)
+    throw new Error(`${e} must be a positive integer.`);
+}
+function F(t) {
+  if (t == null)
+    throw new Error("amountSTX is required");
+  const e = String(t).trim();
+  if (!/^\d+(\.\d+)?$/.test(e))
+    throw new Error("amountSTX must be a valid positive number.");
+  const [n, r = ""] = e.split(".");
+  if (r.length > 6)
+    throw new Error("amountSTX supports at most 6 decimal places.");
+  const o = BigInt(n) * 1000000n + BigInt((r + "000000").slice(0, 6));
+  if (o <= 0n)
+    throw new Error("amountSTX must be greater than 0.");
+  return o;
+}
+class nt {
+  constructor(e = "mainnet") {
+    if (!["mainnet", "testnet"].includes(e))
+      throw new Error(`Invalid networkType "${e}". Use "mainnet" or "testnet".`);
+    this.networkType = e, this.network = e === "mainnet" ? new A() : new N(), this.contractAddress = T;
+  }
+  // --- Read-only Methods ---
+  async callReadOnly(e, n = [], r) {
+    const o = await w({
+      contractAddress: this.contractAddress,
+      contractName: l.VAULT,
+      functionName: e,
+      functionArgs: n,
+      network: this.network,
+      senderAddress: r || this.contractAddress
+    });
+    return o.type === 7 || o.type === 8 ? f(o.value) : f(o);
+  }
+  async getVault(e) {
+    return a(e, "vaultId"), this.callReadOnly("get-vault", [i(e)]);
+  }
+  async getTimeRemaining(e) {
+    return a(e, "vaultId"), this.callReadOnly("get-time-remaining", [i(e)]);
+  }
+  async canWithdraw(e) {
+    return a(e, "vaultId"), this.callReadOnly("can-withdraw", [i(e)]);
+  }
+  async getTVL() {
+    return this.callReadOnly("get-tvl", []);
+  }
+  // --- Transaction Signing Options Helpers ---
+  getCreateVaultOptions(e, n) {
+    return a(n, "lockDurationBlocks"), {
+      contractAddress: this.contractAddress,
+      contractName: l.VAULT,
+      functionName: "create-vault",
+      functionArgs: [i(F(e)), i(n)],
+      network: this.network,
+      anchorMode: m.Any,
+      postConditionMode: d.Allow
+    };
+  }
+  getWithdrawOptions(e) {
+    return a(e, "vaultId"), {
+      contractAddress: this.contractAddress,
+      contractName: l.VAULT,
+      functionName: "request-withdraw",
+      functionArgs: [i(e)],
+      network: this.network,
+      anchorMode: m.Any,
+      postConditionMode: d.Allow
+    };
+  }
+}
+export {
+  it as AnchorMode,
+  T as CONTRACT_ADDRESS,
+  l as CONTRACT_NAMES,
+  O as DEFAULT_PROTOCOL_FEATURES,
+  L as LOCK_PERIODS,
+  z as MAX_DEPOSIT,
+  $ as MIN_DEPOSIT,
+  C as PROTOCOL_VERSION,
+  st as PostConditionMode,
+  V as TRANSACTION_STATUSES,
+  R as TRANSACTION_TYPES,
+  nt as TimeFiClient,
+  E as VAULT_STATUSES,
+  at as bufferCV,
+  Y as calculateTimeRemaining,
+  G as formatAddress,
+  B as formatAmount,
+  b as formatDate,
+  j as formatNumber,
+  H as formatPercent,
+  X as formatRelativeTime,
+  U as formatSTX,
+  Z as formatTimestamp,
+  W as generateId,
+  _ as getProtocolConfig,
+  Q as getProtocolVersion,
+  J as initializeProtocol,
+  ut as noneCV,
+  et as normalizeTransaction,
+  tt as normalizeVault,
+  K as parseAmount,
+  ct as principalCV,
+  lt as responseErrorCV,
+  ft as responseOkCV,
+  x as retry,
+  y as sleep,
+  dt as someCV,
+  mt as stringAsciiCV,
+  ht as stringUtf8CV,
+  gt as uintCV,
+  q as validateAddress,
+  M as validateAddressResult
+};

package/dist/protocol.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @param {Partial<ProtocolConfig>} [options={}]
+ * @returns {ProtocolConfig}
+ */
+export function initializeProtocol(options?: Partial<ProtocolConfig>): ProtocolConfig;
+/**
+ * @returns {string}
+ */
+export function getProtocolVersion(): string;
+/**
+ * @returns {ProtocolConfig}
+ */
+export function getProtocolConfig(): ProtocolConfig;
+/**
+ * @param {Partial<Vault>} [vault={}]
+ * @returns {Vault}
+ */
+export function normalizeVault(vault?: Partial<Vault>): Vault;
+/**
+ * @param {Partial<Transaction>} [transaction={}]
+ * @returns {Transaction}
+ */
+export function normalizeTransaction(transaction?: Partial<Transaction>): Transaction;
+/**
+ * Protocol metadata and typed helpers for the TimeFi ecosystem.
+ */
+/** @typedef {{ timeLock: boolean, vaults: boolean, governance: boolean, rewards: boolean }} ProtocolFeatures */
+/** @typedef {{ network: string, version: string, features: ProtocolFeatures, initialized?: boolean }} ProtocolConfig */
+/** @typedef {'active' | 'locked' | 'withdrawn' | 'failed'} VaultStatus */
+/** @typedef {{ id: string, owner: string, amount: number, lockTime: number, unlockTime: number, status: VaultStatus, fees: number }} Vault */
+/** @typedef {'deposit' | 'withdraw' | 'create' | 'fee'} TransactionType */
+/** @typedef {'pending' | 'confirmed' | 'failed'} TransactionStatus */
+/** @typedef {{ hash: string, type: TransactionType, amount: number, from: string, to: string, timestamp: number, status: TransactionStatus }} Transaction */
+export const PROTOCOL_VERSION: "1.0.0";
+/** @type {Readonly<ProtocolFeatures>} */
+export const DEFAULT_PROTOCOL_FEATURES: Readonly<ProtocolFeatures>;
+/** @type {Readonly<VaultStatus[]>} */
+export const VAULT_STATUSES: Readonly<VaultStatus[]>;
+/** @type {Readonly<TransactionType[]>} */
+export const TRANSACTION_TYPES: Readonly<TransactionType[]>;
+/** @type {Readonly<TransactionStatus[]>} */
+export const TRANSACTION_STATUSES: Readonly<TransactionStatus[]>;
+export type ProtocolFeatures = {
+    timeLock: boolean;
+    vaults: boolean;
+    governance: boolean;
+    rewards: boolean;
+};
+export type ProtocolConfig = {
+    network: string;
+    version: string;
+    features: ProtocolFeatures;
+    initialized?: boolean;
+};
+export type VaultStatus = "active" | "locked" | "withdrawn" | "failed";
+export type Vault = {
+    id: string;
+    owner: string;
+    amount: number;
+    lockTime: number;
+    unlockTime: number;
+    status: VaultStatus;
+    fees: number;
+};
+export type TransactionType = "deposit" | "withdraw" | "create" | "fee";
+export type TransactionStatus = "pending" | "confirmed" | "failed";
+export type Transaction = {
+    hash: string;
+    type: TransactionType;
+    amount: number;
+    from: string;
+    to: string;
+    timestamp: number;
+    status: TransactionStatus;
+};

package/dist/utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @param {number | string | Date} timestamp
+ * @returns {string}
+ */
+export function formatTimestamp(timestamp: number | string | Date): string;
+/**
+ * @param {number | string | Date} endTime
+ * @returns {TimeRemaining}
+ */
+export function calculateTimeRemaining(endTime: number | string | Date): TimeRemaining;
+/**
+ * @param {string} address
+ * @returns {ValidationResult}
+ */
+export function validateAddressResult(address: string): ValidationResult;
+/**
+ * @param {string} address
+ * @returns {boolean}
+ */
+export function validateAddress(address: string): boolean;
+/**
+ * @param {number | string} amount
+ * @param {number} [decimals=6]
+ * @returns {string}
+ */
+export function formatAmount(amount: number | string, decimals?: number): string;
+/**
+ * @param {string | number} amountStr
+ * @returns {number}
+ */
+export function parseAmount(amountStr: string | number): number;
+/**
+ * @returns {string}
+ */
+export function generateId(): string;
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms: number): Promise<void>;
+/**
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {number} [maxRetries=3]
+ * @param {number} [delay=1000]
+ * @returns {Promise<T>}
+ */
+export function retry<T>(fn: () => Promise<T>, maxRetries?: number, delay?: number): Promise<T>;
+export type TimeRemaining = {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    total: number;
+};
+export type ValidationResult = {
+    valid: boolean;
+    address?: string;
+    error?: string;
+};

package/package.json

@@ -1,19 +1,28 @@
 {
     "name": "timefi-sdk",
-    "version": "0.1.3",
+    "version": "0.2.0",
     "description": "Official JavaScript SDK for TimeFi Protocol - Time-locked vaults on Stacks blockchain",
-    "main": "dist/index.js",
-    "module": "dist/index.esm.js",
+    "main": "dist/index.cjs",
+    "module": "dist/index.mjs",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.cjs"
+        }
+    },
     "files": [
         "dist",
         "README.md",
         "LICENSE"
     ],
     "scripts": {
-        "build": "vite build",
-        "test": "echo \"Error: no test specified\" && exit 1",
-        "prepublishOnly": "npm run build"
+        "clean": "rimraf dist",
+        "build": "npm run clean && vite build && npm run build:types",
+        "build:types": "tsc -p tsconfig.types.json",
+        "test": "vitest run",
+        "prepublishOnly": "npm run build && npm run test"
     },
     "keywords": [
         "stacks",
@@ -41,12 +50,17 @@
     "publishConfig": {
         "access": "public"
     },
+    "engines": {
+        "node": ">=18"
+    },
     "dependencies": {
         "@stacks/transactions": "^6.0.0",
         "@stacks/network": "^6.0.0"
     },
     "devDependencies": {
-        "vite": "^5.0.0"
+        "rimraf": "^6.1.0",
+        "typescript": "^5.9.2",
+        "vite": "^5.0.0",
+        "vitest": "^4.0.8"
     }
-
-}
+}

package/dist/index.esm.js

@@ -1,131 +0,0 @@
-import { callReadOnlyFunction as l, cvToValue as a, uintCV as i, PostConditionMode as c, AnchorMode as u } from "@stacks/transactions";
-import { AnchorMode as b, PostConditionMode as D, bufferCV as k, noneCV as _, principalCV as S, responseErrorCV as L, responseOkCV as $, someCV as F, stringAsciiCV as v, stringUtf8CV as G, uintCV as P } from "@stacks/transactions";
-import { StacksMainnet as f, StacksTestnet as d } from "@stacks/network";
-const h = "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N", s = {
-  VAULT: "timefi-vault-v-A2",
-  REWARDS: "timefi-rewards-v-A2",
-  GOVERNANCE: "timefi-governance-v-A2",
-  EMERGENCY: "timefi-emergency-v-A2"
-}, N = {
-  MONTH_1: { label: "1 Month", blocks: 4320, apy: 1 },
-  MONTH_3: { label: "3 Months", blocks: 12960, apy: 3 },
-  MONTH_6: { label: "6 Months", blocks: 25920, apy: 6 },
-  MONTH_9: { label: "9 Months", blocks: 38880, apy: 9 },
-  YEAR_1: { label: "1 Year", blocks: 52560, apy: 12 }
-}, M = 0.01, g = 1e6, y = (t) => {
-  if (t == null) return "0.000000";
-  try {
-    const n = typeof t == "object" && t !== null && "value" in t ? t.value : t, e = Number(n);
-    return isNaN(e) ? "0.000000" : (e / 1e6).toLocaleString(void 0, {
-      minimumFractionDigits: 0,
-      maximumFractionDigits: 6
-    });
-  } catch (n) {
-    return console.error("Error formatting STX:", n), "0.000000";
-  }
-}, C = (t, n = 4, e = 4) => t ? t.length <= n + e ? t : `${t.slice(0, n + 2)}...${t.slice(-e)}` : "", T = (t) => {
-  if (t == null) return "0";
-  const n = Number(t);
-  return isNaN(n) ? "0" : n.toLocaleString();
-}, p = (t, n = 2) => {
-  if (t == null) return "0%";
-  const e = Number(t);
-  return isNaN(e) ? "0%" : (e * 100).toFixed(n) + "%";
-}, m = (t) => {
-  if (!t) return "--";
-  const n = new Date(t);
-  return isNaN(n.getTime()) ? "--" : n.toLocaleDateString(void 0, {
-    year: "numeric",
-    month: "short",
-    day: "numeric"
-  });
-}, O = (t) => {
-  if (!t) return "--";
-  const n = /* @__PURE__ */ new Date(), e = new Date(t), r = Math.floor((n - e) / 1e3);
-  if (r < -1) {
-    const o = Math.abs(r);
-    return o < 60 ? "in a few seconds" : o < 3600 ? `in ${Math.floor(o / 60)}m` : o < 86400 ? `in ${Math.floor(o / 3600)}h` : `in ${Math.floor(o / 86400)}d`;
-  }
-  return r < 5 ? "just now" : r < 60 ? `${r}s ago` : r < 3600 ? `${Math.floor(r / 60)}m ago` : r < 86400 ? `${Math.floor(r / 3600)}h ago` : r < 604800 ? `${Math.floor(r / 86400)}d ago` : m(t);
-};
-class R {
-  constructor(n = "mainnet") {
-    this.network = n === "mainnet" ? new f() : new d(), this.contractAddress = h;
-  }
-  // --- Read-only Methods ---
-  async callReadOnly(n, e = [], r) {
-    const o = await l({
-      contractAddress: this.contractAddress,
-      contractName: s.VAULT,
-      functionName: n,
-      functionArgs: e,
-      network: this.network,
-      senderAddress: r || this.contractAddress
-    });
-    return o.type === 7 || o.type === 8 ? a(o.value) : a(o);
-  }
-  async getVault(n) {
-    if (n == null) throw new Error("vaultId is required");
-    return this.callReadOnly("get-vault", [i(n)]);
-  }
-  async getTimeRemaining(n) {
-    if (n == null) throw new Error("vaultId is required");
-    return this.callReadOnly("get-time-remaining", [i(n)]);
-  }
-  async canWithdraw(n) {
-    if (n == null) throw new Error("vaultId is required");
-    return this.callReadOnly("can-withdraw", [i(n)]);
-  }
-  async getTVL() {
-    return this.callReadOnly("get-tvl", []);
-  }
-  // --- Transaction Signing Options Helpers ---
-  getCreateVaultOptions(n, e) {
-    return {
-      contractAddress: this.contractAddress,
-      contractName: s.VAULT,
-      functionName: "create-vault",
-      functionArgs: [i(n * 1e6), i(e)],
-      network: this.network,
-      anchorMode: u.Any,
-      postConditionMode: c.Deny
-    };
-  }
-  getWithdrawOptions(n) {
-    if (n == null) throw new Error("vaultId is required");
-    return {
-      contractAddress: this.contractAddress,
-      contractName: s.VAULT,
-      functionName: "request-withdraw",
-      functionArgs: [i(n)],
-      network: this.network,
-      anchorMode: u.Any,
-      postConditionMode: c.Deny
-    };
-  }
-}
-export {
-  b as AnchorMode,
-  h as CONTRACT_ADDRESS,
-  s as CONTRACT_NAMES,
-  N as LOCK_PERIODS,
-  g as MAX_DEPOSIT,
-  M as MIN_DEPOSIT,
-  D as PostConditionMode,
-  R as TimeFiClient,
-  k as bufferCV,
-  C as formatAddress,
-  m as formatDate,
-  T as formatNumber,
-  p as formatPercent,
-  O as formatRelativeTime,
-  y as formatSTX,
-  _ as noneCV,
-  S as principalCV,
-  L as responseErrorCV,
-  $ as responseOkCV,
-  F as someCV,
-  v as stringAsciiCV,
-  G as stringUtf8CV,
-  P as uintCV
-};

package/dist/index.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("@stacks/transactions"),s=require("@stacks/network"),u="SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N",a={VAULT:"timefi-vault-v-A2",REWARDS:"timefi-rewards-v-A2",GOVERNANCE:"timefi-governance-v-A2",EMERGENCY:"timefi-emergency-v-A2"},l={MONTH_1:{label:"1 Month",blocks:4320,apy:1},MONTH_3:{label:"3 Months",blocks:12960,apy:3},MONTH_6:{label:"6 Months",blocks:25920,apy:6},MONTH_9:{label:"9 Months",blocks:38880,apy:9},YEAR_1:{label:"1 Year",blocks:52560,apy:12}},f=.01,d=1e6,m=t=>{if(t==null)return"0.000000";try{const e=typeof t=="object"&&t!==null&&"value"in t?t.value:t,r=Number(e);return isNaN(r)?"0.000000":(r/1e6).toLocaleString(void 0,{minimumFractionDigits:0,maximumFractionDigits:6})}catch(e){return console.error("Error formatting STX:",e),"0.000000"}},C=(t,e=4,r=4)=>t?t.length<=e+r?t:`${t.slice(0,e+2)}...${t.slice(-r)}`:"",h=t=>{if(t==null)return"0";const e=Number(t);return isNaN(e)?"0":e.toLocaleString()},b=(t,e=2)=>{if(t==null)return"0%";const r=Number(t);return isNaN(r)?"0%":(r*100).toFixed(e)+"%"},c=t=>{if(!t)return"--";const e=new Date(t);return isNaN(e.getTime())?"--":e.toLocaleDateString(void 0,{year:"numeric",month:"short",day:"numeric"})},g=t=>{if(!t)return"--";const e=new Date,r=new Date(t),o=Math.floor((e-r)/1e3);if(o<-1){const i=Math.abs(o);return i<60?"in a few seconds":i<3600?`in ${Math.floor(i/60)}m`:i<86400?`in ${Math.floor(i/3600)}h`:`in ${Math.floor(i/86400)}d`}return o<5?"just now":o<60?`${o}s ago`:o<3600?`${Math.floor(o/60)}m ago`:o<86400?`${Math.floor(o/3600)}h ago`:o<604800?`${Math.floor(o/86400)}d ago`:c(t)};class A{constructor(e="mainnet"){this.network=e==="mainnet"?new s.StacksMainnet:new s.StacksTestnet,this.contractAddress=u}async callReadOnly(e,r=[],o){const i=await n.callReadOnlyFunction({contractAddress:this.contractAddress,contractName:a.VAULT,functionName:e,functionArgs:r,network:this.network,senderAddress:o||this.contractAddress});return i.type===7||i.type===8?n.cvToValue(i.value):n.cvToValue(i)}async getVault(e){if(e==null)throw new Error("vaultId is required");return this.callReadOnly("get-vault",[n.uintCV(e)])}async getTimeRemaining(e){if(e==null)throw new Error("vaultId is required");return this.callReadOnly("get-time-remaining",[n.uintCV(e)])}async canWithdraw(e){if(e==null)throw new Error("vaultId is required");return this.callReadOnly("can-withdraw",[n.uintCV(e)])}async getTVL(){return this.callReadOnly("get-tvl",[])}getCreateVaultOptions(e,r){return{contractAddress:this.contractAddress,contractName:a.VAULT,functionName:"create-vault",functionArgs:[n.uintCV(e*1e6),n.uintCV(r)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Deny}}getWithdrawOptions(e){if(e==null)throw new Error("vaultId is required");return{contractAddress:this.contractAddress,contractName:a.VAULT,functionName:"request-withdraw",functionArgs:[n.uintCV(e)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Deny}}}Object.defineProperty(exports,"AnchorMode",{enumerable:!0,get:()=>n.AnchorMode});Object.defineProperty(exports,"PostConditionMode",{enumerable:!0,get:()=>n.PostConditionMode});Object.defineProperty(exports,"bufferCV",{enumerable:!0,get:()=>n.bufferCV});Object.defineProperty(exports,"noneCV",{enumerable:!0,get:()=>n.noneCV});Object.defineProperty(exports,"principalCV",{enumerable:!0,get:()=>n.principalCV});Object.defineProperty(exports,"responseErrorCV",{enumerable:!0,get:()=>n.responseErrorCV});Object.defineProperty(exports,"responseOkCV",{enumerable:!0,get:()=>n.responseOkCV});Object.defineProperty(exports,"someCV",{enumerable:!0,get:()=>n.someCV});Object.defineProperty(exports,"stringAsciiCV",{enumerable:!0,get:()=>n.stringAsciiCV});Object.defineProperty(exports,"stringUtf8CV",{enumerable:!0,get:()=>n.stringUtf8CV});Object.defineProperty(exports,"uintCV",{enumerable:!0,get:()=>n.uintCV});exports.CONTRACT_ADDRESS=u;exports.CONTRACT_NAMES=a;exports.LOCK_PERIODS=l;exports.MAX_DEPOSIT=d;exports.MIN_DEPOSIT=f;exports.TimeFiClient=A;exports.formatAddress=C;exports.formatDate=c;exports.formatNumber=h;exports.formatPercent=b;exports.formatRelativeTime=g;exports.formatSTX=m;