emblem-vault-sdk 2.3.6 → 3.0.0-experimental

package/test/.mocharc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  require: 'ts-node/register',
+  extension: ['.ts'],
+  spec: './test/**/*.spec.ts',
+  timeout: 30000, // 30 seconds, matching the Jest timeout
+  exit: true,
+  recursive: true
+};

package/test/README.md

@@ -0,0 +1,212 @@
+# Emblem Vault SDK Test Suite
+
+This directory contains the tests for the Emblem Vault SDK. We have migrated from Jest to Mocha/Chai while maintaining backward compatibility.
+
+## Directory Structure
+
+```
+/test
+  ├── fixtures/           # Test fixtures (JSON, mock data)
+  ├── unit/               # Unit tests for individual components
+  ├── integration/        # Integration tests that interact with live API
+  ├── utils/              # Test utilities including ResourceMonitor
+  ├── helpers/            # Test helper functions and utilities
+  ├── .mocharc.js         # Mocha configuration
+  └── windsurf-rules.md   # Migration guidelines
+```
+
+## Test Categories
+
+### Unit Tests
+
+Unit tests focus on testing individual components in isolation:
+- Do not make actual API calls
+- Use mock data and override functions
+- Run quickly and reliably
+- Located in `/test/unit/`
+
+### Integration Tests
+
+Integration tests interact with the live Emblem Vault API:
+- Make actual API calls to Emblem Vault services
+- Require valid API keys to execute successfully
+- Take longer to run than unit tests
+- May create or modify real resources
+- Located in `/test/integration/`
+
+#### Integration Test Categories
+
+The integration tests are organized into the following categories:
+
+##### API Operations (`ApiOperations.spec.js`)
+
+Tests for read-only API operations:
+- Fetching curated contracts
+- Retrieving vault information
+- Getting asset metadata
+
+##### Vault Creation (`VaultCreation.spec.js`)
+
+Tests for operations that create or modify vaults:
+- Creating empty vaults
+- Creating vaults with specific assets
+- Validating vault templates
+
+## Running Tests
+
+### Mocha Tests
+
+Run all Mocha tests:
+
+```bash
+npm run test:mocha
+```
+
+Run Mocha tests in watch mode (useful during development):
+
+```bash
+npm run test:mocha:watch
+```
+
+Run Mocha tests with coverage:
+
+```bash
+npm run test:mocha:coverage
+```
+
+### Integration Tests
+
+To run the integration tests, you need a valid API key:
+
+```bash
+# Run with your API key
+API_KEY=your_api_key npx mocha test/integration/**/*.spec.js
+
+# Run a specific integration test file
+API_KEY=your_api_key npx mocha test/integration/ApiOperations.spec.js
+```
+
+Without a valid API key, most integration tests will be skipped.
+
+### Legacy Jest Tests
+
+The legacy Jest tests are still available and can be run with:
+
+```bash
+npm test          # Runs Jest tests after building
+npm run test:node # Runs Jest tests in Node environment
+npm run test:browser # Runs Jest tests in browser environment
+```
+
+### Running All Tests
+
+To run both Jest and Mocha tests:
+
+```bash
+npm run test:all:both
+```
+
+## ResourceMonitor for Memory Leak Detection
+
+The SDK includes a ResourceMonitor utility for detecting memory leaks in tests:
+
+```javascript
+const { ResourceMonitor } = require('../utils/ResourceMonitor');
+
+describe('Memory Usage Tests', function() {
+  let monitor = new ResourceMonitor();
+  
+  beforeEach(() => {
+    monitor.takeSnapshot('test-start');
+  });
+  
+  afterEach(() => {
+    monitor.takeSnapshot('test-end');
+    console.log(monitor.generateReport());
+  });
+  
+  it('should not leak memory during operations', async function() {
+    // Test code here
+    
+    // Check if memory usage exceeds threshold
+    const thresholdCheck = monitor.checkThreshold('test-start');
+    expect(thresholdCheck.exceeded).to.be.false;
+  });
+});
+```
+
+### ResourceMonitor Features
+
+- **Memory Snapshots**: Track memory usage at different points in test execution
+- **Difference Calculation**: Measure memory changes between operations
+- **Threshold Checking**: Set custom thresholds for acceptable memory growth
+- **Detailed Reports**: Generate comprehensive memory usage reports
+- **GC Support**: Trigger garbage collection when available (run with `--expose-gc`)
+
+## Migration Status
+
+We are gradually migrating tests from Jest to Mocha/Chai. The following tests have been migrated:
+
+- [x] EmblemVaultSdk - Core SDK functionality
+- [x] AllowedCounterparty - Counterparty collection tests
+- [x] ResourceMonitor - Memory leak detection utility
+
+Remaining tests to migrate:
+- [ ] AllowedBells
+- [ ] AllowedBitcoinDeGods
+- [ ] AllowedBitcoinOrdinals
+- [ ] AllowedCursedOrdinals
+- [ ] AllowedEmbells
+- [ ] AllowedEmbels
+- [ ] AllowedEmblemOpen
+- [ ] AllowedEthscriptions
+- [ ] AllowedHardcodedNfts
+- [ ] AllowedNamecoin
+- [ ] AllowedOrdi
+- [ ] AllowedOxbt
+- [ ] AllowedProjectlCollection
+- [ ] AllowedProtocolCollection
+- [ ] AllowedStamps
+- [ ] DarkfarmsMetadata
+
+## Best Practices
+
+### For All Tests
+
+1. **Never commit API keys** to the repository
+2. Use environment variables for sensitive information
+3. Use descriptive test names that indicate what's being tested
+4. Follow the project's coding standards
+
+### For Integration Tests
+
+1. Keep integration tests isolated from each other
+2. Add proper cleanup after tests that create resources
+3. Set appropriate timeouts for tests that may take longer to complete
+4. Skip tests when using demo keys or missing required credentials
+
+## Writing New Tests
+
+All new tests should be written using Mocha/Chai and placed in the appropriate directory:
+
+- Unit tests go in `/test/unit/` with the naming convention `*.spec.js`
+- Integration tests go in `/test/integration/` with the naming convention `*.spec.js`
+- Fixtures should be placed in `/test/fixtures/` in an appropriate subdirectory
+
+Example test structure:
+
+```javascript
+const { expect } = require('chai');
+const { EmblemVaultSDK } = require('../../dist');
+
+describe('Feature Name', () => {
+  const sdk = new EmblemVaultSDK('DEMO_KEY');
+  
+  it('should do something specific', async () => {
+    // Test code here
+    expect(result).to.be.true;
+  });
+});
+```
+
+For more detailed migration guidelines, see the [windsurf-rules.md](./windsurf-rules.md) file.

package/test/fixtures/ethscriptions/balance-with-native-first.json

@@ -0,0 +1,24 @@
+[
+
+  {
+    "coin": "eth",
+    "name": "ETH",
+    "balance": 1
+  },
+  {
+    "coin": "ethscription",
+    "name": "Ethscription #7104",
+    "balance": 1,
+    "type": "nft",
+    "external_url": "https://ethscriptions.com/0x438397AB9350b1B4527cB8397BDF557e5389a456",
+    "image": "https://image-scaler.vercel.app/image2?url=https://eth-script-indexer-eca25c4cf43b.herokuapp.com/api/ethscriptions/7104/data",
+    "id": "0xc7282e29440679a1e283d86dee79e9da483c7d6ae55a37ceee19568a0ebacaf7",
+    "number": 7104,
+    "traits": [
+      {
+        "trait_type": "Ethscriptions",
+        "value": "Sub 10k"
+      }
+    ]
+  }
+]

package/test/fixtures/ethscriptions/balance-with-native.json

@@ -0,0 +1,23 @@
+[
+  {
+    "coin": "ethscription",
+    "name": "Ethscription #7104",
+    "balance": 1,
+    "type": "nft",
+    "external_url": "https://ethscriptions.com/0x438397AB9350b1B4527cB8397BDF557e5389a456",
+    "image": "https://image-scaler.vercel.app/image2?url=https://eth-script-indexer-eca25c4cf43b.herokuapp.com/api/ethscriptions/7104/data",
+    "id": "0xc7282e29440679a1e283d86dee79e9da483c7d6ae55a37ceee19568a0ebacaf7",
+    "number": 7104,
+    "traits": [
+      {
+        "trait_type": "Ethscriptions",
+        "value": "Sub 10k"
+      }
+    ]
+  },
+  {
+    "coin": "eth",
+    "name": "ETH",
+    "balance": 1
+  }
+]

package/test/fixtures/ethscriptions/balance.json

@@ -0,0 +1,18 @@
+[
+  {
+    "coin": "ethscription",
+    "name": "Ethscription #7104",
+    "balance": 1,
+    "type": "nft",
+    "external_url": "https://ethscriptions.com/0x438397AB9350b1B4527cB8397BDF557e5389a456",
+    "image": "https://image-scaler.vercel.app/image2?url=https://eth-script-indexer-eca25c4cf43b.herokuapp.com/api/ethscriptions/7104/data",
+    "id": "0xc7282e29440679a1e283d86dee79e9da483c7d6ae55a37ceee19568a0ebacaf7",
+    "number": 7104,
+    "traits": [
+      {
+        "trait_type": "Ethscriptions",
+        "value": "Sub 10k"
+      }
+    ]
+  }
+]

package/test/helpers/sdkLoader.js

@@ -0,0 +1,88 @@
+/**
+ * SDK Loader Helper
+ * Provides a singleton pattern for SDK initialization across tests
+ */
+
+const { EmblemVaultSDK } = require('../../dist');
+
+// Default values from environment or fallbacks
+const DEFAULT_API_KEY = process.env.API_KEY || 'DEMO_KEY';
+const DEFAULT_BASE_URL = process.env.BASE_URL;
+const DEFAULT_V3_URL = process.env.V3_URL;
+const DEFAULT_SIG_URL = process.env.SIG_URL;
+
+// Singleton instance
+let sdkInstance = null;
+let currentConfig = null;
+
+/**
+ * Get the SDK instance - creates a new instance if one doesn't exist
+ * or returns the existing instance
+ * 
+ * @param {Object} options - SDK initialization options
+ * @param {string} options.apiKey - API key to use (defaults to env API_KEY or 'DEMO_KEY')
+ * @param {string} options.baseUrl - Base URL to use (defaults to env BASE_URL or SDK default)
+ * @param {string} options.v3Url - V3 URL to use (defaults to env V3_URL or SDK default)
+ * @param {string} options.sigUrl - Signature URL to use (defaults to env SIG_URL or SDK default)
+ * @param {boolean} options.forceNew - Force creation of a new instance
+ * @returns {EmblemVaultSDK} The SDK instance
+ */
+function getSDK(options = {}) {
+  const { 
+    apiKey = DEFAULT_API_KEY, 
+    baseUrl = DEFAULT_BASE_URL, 
+    v3Url = DEFAULT_V3_URL,
+    sigUrl = DEFAULT_SIG_URL,
+    forceNew = false 
+  } = options;
+
+  // Create new configuration object for comparison
+  const newConfig = { apiKey, baseUrl, v3Url, sigUrl };
+  
+  // Create a new instance if:
+  // 1. No instance exists yet
+  // 2. forceNew is true
+  // 3. Configuration has changed
+  const configChanged = currentConfig && (
+    currentConfig.apiKey !== newConfig.apiKey ||
+    currentConfig.baseUrl !== newConfig.baseUrl ||
+    currentConfig.v3Url !== newConfig.v3Url ||
+    currentConfig.sigUrl !== newConfig.sigUrl
+  );
+
+  if (!sdkInstance || forceNew || configChanged) {
+    // Initialize with all possible parameters
+    // Only pass parameters that are defined to avoid overriding SDK defaults
+    const initParams = [apiKey];
+    
+    if (baseUrl) initParams.push(baseUrl);
+    else if (v3Url || sigUrl) initParams.push(undefined); // Add placeholder if later params exist
+    
+    if (v3Url) initParams.push(v3Url);
+    else if (sigUrl) initParams.push(undefined); // Add placeholder if later params exist
+    
+    if (sigUrl) initParams.push(sigUrl);
+    
+    // Create new instance with spread parameters
+    sdkInstance = new EmblemVaultSDK(...initParams);
+    
+    // Store current configuration
+    currentConfig = { ...newConfig };
+  }
+
+  return sdkInstance;
+}
+
+/**
+ * Reset the SDK instance
+ * Useful for tests that need to start with a fresh instance
+ */
+function resetSDK() {
+  sdkInstance = null;
+  currentConfig = null;
+}
+
+module.exports = {
+  getSDK,
+  resetSDK
+};

package/test/helpers/setup.js

@@ -0,0 +1,55 @@
+/**
+ * Global Mocha/Chai test setup file
+ * Provides common utilities and configurations for tests
+ */
+
+const { expect } = require('chai');
+
+// Export chai expect for use in tests
+module.exports = {
+  expect,
+  
+  // Test constants
+  TEST_ADDRESS: "0xb0573e14D92755DE30281f7b10d0F3a5DD3e747B",
+  API_KEY: 'DEMO_KEY',
+
+  // Common mocks used across tests
+  mocks: {
+    emblemopen_create_template: {
+      "fromAddress": { "type": "user-provided" },
+      "toAddress": { "type": "user-provided" },
+      "chainId": { "type": "user-provided" },
+      "experimental": true,
+      "targetContract": {
+        "1": "0x184ddb67E2EF517f6754F055b56905f2A9b29b6A",
+        "900": "5rxENZEa3rhDk2hcuG6RNFbCGGQwU9APm4CMmaW4s4xy",
+        "name": "EmblemOpen",
+        "description": "The vaults within this collection feature deposit addresses spanning two or more blockchains. Vault images, titles, and descriptions are generated by users. Prior to making a purchase, it is advisable to authenticate the legitimacy of the assets within the vault. Supported blockchains encompass, but are not restricted to: Bitcoin, Litecoin, Bitcoin Cash, Ethereum, Dogecoin, Solana, Tezos, Namecoin, and any EVM-compatible protocol.",
+        "fusion": false
+      },
+      "targetAsset": {
+        "name": { "type": "user-provided" },
+        "image": { "type": "user-provided" },
+        "description": { "type": "user-provided" }
+      }
+    },
+    empty_create_template: { 
+      "fromAddress": { "type": "user-provided" }, 
+      "toAddress": { "type": "user-provided" }, 
+      "chainId": { "type": "user-provided" }, 
+      "experimental": true, 
+      "targetContract": { 
+        "1": "0xEAD67175CDb9CBDeA5bDDC36015e52f4A954E3fD", 
+        "name": "BitcoinOrdinals", 
+        "description": "Ordinal Theory is a method for assigning unique identifiers to individual satoshis on the Bitcoin blockchain. This is done by assigning each satoshi a unique identifier based on the order in which it was mined. This identifier can be used to track the satoshi's history and ownership, and to transfer it to another party. Ordinal Theory can also be used to inscribe additional data to satoshis, such as a message, image, serial number, audio file, or document.",
+        "fusion": false
+      }, 
+      "targetAsset": { 
+        "name": "Loading...", 
+        "image": "https://emblem.finance/ordinals.png"
+      }
+    }
+  }
+};
+
+// Helper functions can be added here

package/test/integration/ApiOperations.spec.js

@@ -0,0 +1,102 @@
+const { expect } = require('chai');
+const { getSDK } = require('../helpers/sdkLoader');
+// const dotenv = require('dotenv');
+// const path = require('path');
+const mocks = require('../mocks');
+
+// Load environment variables
+// dotenv.config({ path: path.resolve(__dirname, '../../.env') });
+
+// Test constants
+const API_KEY = 'DEMO_KEY';
+const TEST_ADDRESS = "0xb0573e14D92755DE30281f7b10d0F3a5DD3e747B";
+
+describe('API Operations Integration Tests', function() {
+  // Get SDK instance using the loader
+  const sdk = getSDK();
+
+  // Increase timeout for these tests as they make API calls
+  this.timeout(15000);
+  
+  describe('Curated Contracts', function() {
+    it('should fetch curated contracts from the API', async function() {
+      const contracts = await sdk.fetchCuratedContracts();
+      expect(contracts).to.be.an('array');
+      expect(contracts.length).to.be.greaterThan(0);
+      
+      // Verify contract structure
+      const firstContract = contracts[0];
+      expect(firstContract).to.have.property('name');
+      expect(firstContract).to.have.property('mintable');
+    });
+    
+    it('should fetch a specific curated contract by name', async function() {
+      // Use override function with mock data when using demo key
+      const contractName = 'Ethscription';
+      // First get all contracts
+      const contracts = await sdk.fetchCuratedContracts();
+      // Then find the specific one by name
+      const contract = await sdk.fetchCuratedContractByName(
+        contractName, 
+        contracts
+      );
+      
+      expect(contract).to.be.an('object');
+      expect(contract).to.have.property('name');
+      expect(contract.name).to.equal('Ethscription');
+    });
+  });
+  
+  describe('Vault Operations', function() {
+    it('should fetch vaults of a specific type', async function() {
+      const vaults = await sdk.fetchVaultsOfType(
+        "created", 
+        TEST_ADDRESS,
+        API_KEY === 'DEMO_KEY' ? () => mocks.sample_vaults : null
+      );
+      
+      expect(vaults).to.be.an('array');
+      
+      // If vaults exist, check their structure
+      if (vaults.length > 0) {
+        const firstVault = vaults[0];
+        expect(firstVault).to.have.property('tokenId');
+      }
+    });
+    
+    it('should fetch vaults for an address', async function() {
+      // Using fetchVaultsOfType with "all" type to get all vaults for an address
+      const vaults = await sdk.fetchVaultsOfType(
+        "all", 
+        TEST_ADDRESS,
+        API_KEY === 'DEMO_KEY' ? () => mocks.sample_vaults : null
+      );
+      
+      expect(vaults).to.be.an('array');
+    });
+  });
+  
+  describe('Asset Metadata', function() {
+    it('should fetch asset metadata from the API', async function() {
+      const metadata = await sdk.getAssetMetadata(
+        'Bitcoin Ordinals',
+        API_KEY === 'DEMO_KEY' ? () => mocks.bitcoin_ordinals_metadata : null
+      );
+      
+      expect(metadata).to.be.an('array');
+      
+      if (metadata.length > 0) {
+        expect(metadata[0]).to.have.property('projectName');
+        expect(metadata[0].projectName.toLowerCase()).to.include('bitcoin ordinals');
+      }
+    });
+    
+    it('should fetch remote asset metadata project list', async function() {
+      const projects = await sdk.getRemoteAssetMetadataProjectList(
+        API_KEY === 'DEMO_KEY' ? () => mocks.project_list : null
+      );
+      
+      expect(projects).to.be.an('array');
+    });
+  });
+});

package/test/integration/VaultAI.spec.js

@@ -0,0 +1,57 @@
+const { expect } = require('chai');
+const { EmblemVaultSDK } = require('../../dist/index');
+
+// API key for testing
+const API_KEY = 'demo';
+const AI_API_KEY = 'demo-ai-key';
+
+describe.skip('Vault AI Integration Tests', () => {
+  let sdk;
+  
+  before(() => {
+    // Create a new SDK instance with the demo AI API key
+    sdk = new EmblemVaultSDK(API_KEY, undefined, undefined, undefined, undefined, AI_API_KEY);
+  });
+  
+  it('should fetch NOT vault info using the demo AI API key', async function() {
+    this.timeout(10000); // Increase timeout for API call
+    
+    // Call the method with the demo AI API key
+    const result = await sdk.vaultInfoFromApiKey();
+    
+    // Verify the response structure
+    expect(result).to.be.an('object');
+    expect(result).to.have.property('data');
+    
+    // Log the response for debugging
+    console.log('Vault info response:', JSON.stringify(result, null, 2));
+    
+    // If the API returns an error with the demo key, this test will still pass
+    // as long as we get a proper response object
+    if (result.success === true) {
+      expect(result.data).to.be.an('object');
+      // Add more specific assertions based on the expected response structure
+    } else {
+      console.log('Note: API returned an error, but the test is verifying the call was made correctly');
+    }
+  });
+  
+  it('should handle API errors gracefully', async function() {
+    this.timeout(10000); // Increase timeout for API call
+    
+    // Call the method with an invalid API key
+    try {
+      const result = await sdk.vaultInfoFromApiKey('invalid-key');
+      
+      // If we get here, the API might return an error object rather than throwing
+      expect(result).to.be.an('object');
+      
+      // Log the response for debugging
+      console.log('Error response with invalid key:', JSON.stringify(result, null, 2));
+    } catch (error) {
+      // If the API throws an error, that's also acceptable
+      console.log('API threw an error with invalid key (expected):', error.message);
+      expect(error).to.exist;
+    }
+  });
+});

package/test/integration/VaultCreation.spec.js

@@ -0,0 +1,95 @@
+const { expect } = require('chai');
+const { getSDK } = require('../helpers/sdkLoader');
+
+// Test constants
+const TEST_ADDRESS = "0xb0573e14D92755DE30281f7b10d0F3a5DD3e747B";
+const CONTRACT_NAME = "EmblemOpen";
+
+describe.skip('Vault Creation Integration Tests', function() {
+  // Get SDK instance using the loader
+  const sdk = getSDK();
+  
+  // Increase timeout for these tests as they make API calls
+  this.timeout(155000);
+  
+  it('should create vault using contract template', async () => {
+    // Get all contracts
+    const contracts = await sdk.fetchCuratedContracts();
+    expect(contracts).to.be.an('array');
+    expect(contracts.length).to.be.greaterThan(0);
+    
+    // Find the Emblem Open contract
+    const contract = contracts.find(contract => contract.name === CONTRACT_NAME);
+    expect(contract).to.be.an('object');
+    
+    // Generate a template using the contract's generateCreateTemplate function
+    const template = contract.generateCreateTemplate(contract);
+    expect(template).to.be.an('object');
+    
+    // Populate the template with test data
+    template.fromAddress = TEST_ADDRESS
+    template.toAddress = TEST_ADDRESS
+    template.chainId = "1" // Add Ethereum mainnet chainId
+    template.targetAsset.name = "Test Asset"
+    template.targetAsset.image = "https://emblem.finance/stamps.png"
+    template.targetAsset.description = "Test Asset Description"
+    template.targetAsset.ownedImage = "https://emblem.finance/stamps.png" // Add required ownedImage field
+    
+    // Create the vault using the populated template
+    const vault = await sdk.createCuratedVault(template);
+    
+    // Verify the created vault
+    expect(vault).to.be.an('object');
+    expect(vault).to.have.property('tokenId');
+  });
+  
+  it('should create vault with asset details', async () => {
+    // Get all contracts
+    const contracts = await sdk.fetchCuratedContracts();
+    expect(contracts).to.be.an('array');
+    
+    // Find the Emblem Open contract
+    const contract = contracts.find(contract => contract.name === CONTRACT_NAME);
+    expect(contract).to.be.an('object');
+    
+    // Generate a template using the contract's generateCreateTemplate function
+    const template = contract.generateCreateTemplate(contract);
+    expect(template).to.be.an('object');
+    
+    // Populate the template with test data
+    template.name = `Test Vault with Asset ${Date.now()}`;
+    template.description = 'Test vault with asset created by integration tests';
+    template.fromAddress = TEST_ADDRESS;
+    template.toAddress = TEST_ADDRESS;
+    template.chainId = "1"; // Ethereum mainnet
+    
+    // Add asset details
+    template.targetAsset = {
+      name: "Test Asset",
+      image: "https://emblem.finance/stamps.png",
+      description: "Test Asset Description",
+      ownedImage: "https://emblem.finance/stamps.png"
+    };
+    
+    // Create the vault using the populated template
+    const vault = await sdk.createCuratedVault(template);
+    
+    // Verify the created vault
+    expect(vault).to.be.an('object');
+    expect(vault).to.have.property('tokenId');
+    expect(vault.targetAsset.name).to.equal("Test Asset");
+    expect(vault.targetAsset.image).to.equal("https://emblem.finance/stamps.png");
+    expect(vault.targetAsset.description).to.equal("Test Asset Description");
+  });
+  
+  it('should fetch vault details after creation', async () => {
+    // Fetch vaults for the test address
+    const vaults = await sdk.fetchVaultsOfType("created", TEST_ADDRESS);
+    expect(vaults).to.be.an('array');
+    
+    if (vaults.length > 0) {
+      const firstVault = vaults[0];
+      expect(firstVault).to.have.property('tokenId');
+    }
+  });
+});