@branta-ops/branta 0.0.1

package/README.md

@@ -0,0 +1,54 @@
+# Branta JavaScript SDK
+
+Package contains functionality to assist JavaScript projects with making requests to Branta's server.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install branta
+```
+
+## Quick Start
+```js
+import * as branta from "branta";
+
+const client = new branta.V2BrantaClient(
+  new branta.BrantaClientOptions({
+    baseUrl: branta.BrantaBaseServerUrl.Localhost,
+    defaultApiKey:
+      "<api-key-here>",
+  }),
+);
+
+var payments = await client.getPayments(
+  "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+);
+console.log(payments);
+
+if (payments.length == 0) {
+  console.log("Creating Payment...");
+  await client.addPayment({
+    description: "Testing description",
+    destinations: [
+      {
+        value: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+        zk: false,
+      },
+    ],
+    ttl: "600",
+  });
+}
+```
+
+## Feature Support
+
+ - [X] Per Environment configuration
+ - [X] V2 Get Payment by address
+ - [ ] V2 Get Payment by QR Code
+ - [X] V2 Get decrypted Zero Knowledge by address and secret
+ - [X] V2 Add Payment
+ - [ ] V2 Payment by Parent Platform with HMAC
+ - [X] V2 Add Zero Knowledge Payment with secret
+ - [X] V2 Check API key valid

package/jest.config.js

@@ -0,0 +1,4 @@
+export default {
+  testEnvironment: 'node',
+  transform: {}
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@branta-ops/branta",
+  "version": "0.0.1",
+  "description": "A JavaScript SDK for the Branta API",
+  "homepage": "https://github.com/BrantaOps/branta-js#readme",
+  "bugs": {
+    "url": "https://github.com/BrantaOps/branta-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrantaOps/branta-js.git"
+  },
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --collect-coverage",
+    "script": "npm link branta && node test/script.js"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}

package/src/classes/brantaBaseServerUrl.js

@@ -0,0 +1,7 @@
+const BrantaServerBaseUrl = {
+  Staging: { value: 0, url: "https://staging.guardrail.branta.pro" },
+  Production: { value: 1, url: "https://guardrail.branta.pro" },
+  Localhost: { value: 2, url: "http://localhost:3000" },
+};
+
+export default BrantaServerBaseUrl;

package/src/classes/brantaClientOptions.js

@@ -0,0 +1,10 @@
+class BrantaClientOptions {
+    baseUrl = null;
+    defaultApiKey = null;
+    
+    constructor(options = {}) {
+        Object.assign(this, options);
+    }
+}
+
+export default BrantaClientOptions;

package/src/classes/brantaPaymentException.js

@@ -0,0 +1,8 @@
+class BrantaPaymentException extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BrantaPaymentException";
+  }
+}
+
+export default BrantaPaymentException

package/src/helpers/aes.js

@@ -0,0 +1,83 @@
+class AesEncryption {
+  /**
+   * Encrypts a string value using AES-GCM with a secret key
+   * @param {string} value - The plaintext to encrypt
+   * @param {string} secret - The secret key (will be hashed with SHA-256)
+   * @returns {Promise<string>} Base64-encoded encrypted data (iv + ciphertext + tag)
+   */
+  static async encrypt(value, secret) {
+    const encoder = new TextEncoder();
+    const secretData = encoder.encode(secret);
+    const keyData = await crypto.subtle.digest('SHA-256', secretData);
+
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+
+    const key = await crypto.subtle.importKey(
+      'raw',
+      keyData,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt']
+    );
+
+    const plaintext = encoder.encode(value);
+    const encrypted = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: iv, tagLength: 128 },
+      key,
+      plaintext
+    );
+
+    const encryptedArray = new Uint8Array(encrypted);
+    
+    const ciphertext = encryptedArray.slice(0, -16);
+    const tag = encryptedArray.slice(-16);
+
+    const result = new Uint8Array(iv.length + ciphertext.length + tag.length);
+    result.set(iv, 0);
+    result.set(ciphertext, iv.length);
+    result.set(tag, iv.length + ciphertext.length);
+
+    return btoa(String.fromCharCode(...result));
+  }
+
+  /**
+   * Decrypts an encrypted string using AES-GCM with a secret key
+   * @param {string} encryptedValue - Base64-encoded encrypted data
+   * @param {string} secret - The secret key (will be hashed with SHA-256)
+   * @returns {Promise<string>} The decrypted plaintext
+   */
+  static async decrypt(encryptedValue, secret) {
+    const encryptedData = Uint8Array.from(atob(encryptedValue), c => c.charCodeAt(0));
+
+    const encoder = new TextEncoder();
+    const secretData = encoder.encode(secret);
+    const keyData = await crypto.subtle.digest('SHA-256', secretData);
+
+    const iv = encryptedData.slice(0, 12);
+    const tag = encryptedData.slice(-16);
+    const ciphertext = encryptedData.slice(12, -16);
+
+    const ciphertextWithTag = new Uint8Array(ciphertext.length + tag.length);
+    ciphertextWithTag.set(ciphertext, 0);
+    ciphertextWithTag.set(tag, ciphertext.length);
+
+    const key = await crypto.subtle.importKey(
+      'raw',
+      keyData,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['decrypt']
+    );
+
+    const decrypted = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: iv, tagLength: 128 },
+      key,
+      ciphertextWithTag
+    );
+
+    const decoder = new TextDecoder();
+    return decoder.decode(decrypted);
+  }
+}
+
+export default AesEncryption;

package/src/index.js

@@ -0,0 +1,5 @@
+import V2BrantaClient from "./v2/client.js";
+import BrantaClientOptions from "./classes/brantaClientOptions.js";
+import BrantaBaseServerUrl from "./classes/brantaBaseServerUrl.js";
+
+export { V2BrantaClient, BrantaClientOptions, BrantaBaseServerUrl };

package/src/v2/client.js

@@ -0,0 +1,125 @@
+import AesEncryption from "../helpers/aes.js";
+import BrantaPaymentException from "../classes/brantaPaymentException.js";
+
+export class V2BrantaClient {
+  constructor(brantaClientOptions) {
+    this._defaultOptions = brantaClientOptions;
+  }
+
+  async getPayments(address, options = null) {
+    const httpClient = this._createClient(options);
+    const response = await httpClient.get(`/v2/payments/${address}`);
+
+    if (!response.ok || response.headers.get("content-length") === "0") {
+      return [];
+    }
+
+    const data = await response.json();
+    return data;
+  }
+
+  async getZKPayment(address, secret, options = null) {
+    const payments = await this.getPayments(address, options);
+
+    for (const payment of payments) {
+      for (const destination of payment.destinations) {
+        if (destination.isZk === false) continue;
+        destination.value = await AesEncryption.decrypt(destination.value, secret);
+      }
+    }
+
+    return payments;
+  }
+
+  async addPayment(payment, options = null) {
+    const httpClient = this._createClient(options);
+    this._setApiKey(httpClient, options);
+
+    const response = await httpClient.post("/v2/payments", payment);
+
+    if (!response.ok) {
+      throw new BrantaPaymentException(response.status.toString());
+    }
+
+    const responseBody = await response.text();
+    return JSON.parse(responseBody);
+  }
+
+  async addZKPayment(payment, options = null) {
+    const secret = crypto.randomUUID();
+
+    for (const destination of payment.destinations) {
+      if (destination.isZk === false) continue;
+      destination.value = await AesEncryption.encrypt(destination.value, secret);
+    }
+
+    const responsePayment = await this.addPayment(payment, options);
+    return { payment: responsePayment, secret };
+  }
+
+  async isApiKeyValid(options = null) {
+    const httpClient = this._createClient(options);
+    this._setApiKey(httpClient, options);
+
+    const response = await fetch(
+      `${httpClient.baseURL}/v2/api-keys/health-check`,
+      {
+        headers: httpClient.headers,
+      },
+    );
+
+    return response.ok;
+  }
+
+  _createClient(options) {
+    const baseUrl = options?.baseUrl ?? this._defaultOptions?.baseUrl;
+
+    if (!baseUrl?.url) {
+      throw new Error("Branta: BaseUrl is a required option.");
+    }
+
+    const fullBaseUrl = baseUrl.url;
+
+    return {
+      baseURL: fullBaseUrl,
+      headers: {},
+      async get(url, config = {}) {
+        const response = await fetch(`${this.baseURL}${url}`, {
+          method: "GET",
+          headers: { ...this.headers, ...config?.headers },
+          signal: config?.signal,
+        });
+        return response;
+      },
+      async post(url, data, config = {}) {
+        const response = await fetch(`${this.baseURL}${url}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...this.headers,
+            ...config?.headers,
+          },
+          body: JSON.stringify(data),
+          signal: config?.signal,
+        });
+        return response;
+      },
+    };
+  }
+
+  _setApiKey(httpClient, options) {
+    const apiKey =
+      options?.defaultApiKey ?? this._defaultOptions?.defaultApiKey;
+
+    if (!apiKey) {
+      throw new BrantaPaymentException("Unauthorized");
+    }
+
+    httpClient.headers = {
+      ...httpClient.headers,
+      Authorization: `Bearer ${apiKey}`,
+    };
+  }
+}
+
+export default V2BrantaClient;

package/test/helpers/aes.test.js

@@ -0,0 +1,35 @@
+import { describe, test, expect } from "@jest/globals";
+import AesEncryption from "./../../src/helpers/aes";
+
+describe("AesEncryption", () => {
+  test("should encrypt and decrypt a bitcoin address", async () => {
+    const plaintext = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
+    const secret = "mySecret123";
+
+    const encrypted = await AesEncryption.encrypt(plaintext, secret);
+    const decrypted = await AesEncryption.decrypt(encrypted, secret);
+
+    expect(decrypted).toBe(plaintext);
+  });
+
+  test("should produce different ciphertext with different secrets", async () => {
+    const plaintext = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
+    const secret1 = "secret1";
+    const secret2 = "secret2";
+
+    const encrypted1 = await AesEncryption.encrypt(plaintext, secret1);
+    const encrypted2 = await AesEncryption.encrypt(plaintext, secret2);
+
+    expect(encrypted1).not.toBe(encrypted2);
+  });
+
+  test("should decrypt text", async () => {
+    const encrypted =
+      "pQerSFV+fievHP+guYoGJjx1CzFFrYWHAgWrLhn5473Z19M6+WMScLd1hsk808AEF/x+GpZKmNacFBf5BbQ=";
+    const secret1 = "1234";
+
+    const decrypted = await AesEncryption.decrypt(encrypted, secret1);
+
+    expect(decrypted).toBe("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
+  });
+});

package/test/script.js

@@ -0,0 +1,28 @@
+import * as branta from "branta";
+
+const client = new branta.V2BrantaClient(
+  new branta.BrantaClientOptions({
+    baseUrl: branta.BrantaBaseServerUrl.Localhost,
+    defaultApiKey:
+      "<api-key-here>",
+  }),
+);
+
+var payments = await client.getPayments(
+  "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+);
+console.log(payments);
+
+if (payments.length == 0) {
+  console.log("Creating Payment...");
+  await client.addPayment({
+    description: "Testing description",
+    destinations: [
+      {
+        value: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+        zk: false,
+      },
+    ],
+    ttl: "600",
+  });
+}

package/test/v2/client.test.js

@@ -0,0 +1,310 @@
+import { describe, test, expect, jest, beforeEach } from "@jest/globals";
+import V2BrantaClient from "../../src/v2/client.js";
+import BrantaPaymentException from "../../src/classes/brantaPaymentException.js";
+import AesEncryption from "../../src/helpers/aes.js";
+
+describe("V2BrantaClient", () => {
+  let client;
+  let mockFetch;
+  const defaultOptions = {
+    baseUrl: { url: "http://localhost:3000" },
+    defaultApiKey: "test-api-key",
+  };
+
+  const testPayments = [
+    {
+      destinations: [
+        {
+          value: "123",
+          isZk: false,
+        },
+      ],
+    },
+    {
+      destinations: [
+        {
+          value: "456",
+          isZk: false,
+        },
+      ],
+    },
+  ];
+
+  beforeEach(() => {
+    client = new V2BrantaClient(defaultOptions);
+    mockFetch = jest.fn();
+    global.fetch = mockFetch;
+    jest.clearAllMocks();
+  });
+
+  describe("getPayments", () => {
+    test("should return payments", async () => {
+      const address = "test-address";
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: () => "100",
+        },
+        json: async () => testPayments,
+      });
+
+      const result = await client.getPayments(address);
+
+      expect(result).not.toBeNull();
+      expect(result).toHaveLength(2);
+      expect(result[0].destinations[0].value).toBe("123");
+      expect(result[1].destinations[0].value).toBe("456");
+    });
+
+    test("should return empty list on non-success status code", async () => {
+      const address = "test-address";
+      mockFetch.mockResolvedValue({
+        ok: false,
+        headers: {
+          get: () => "0",
+        },
+      });
+
+      const result = await client.getPayments(address);
+
+      expect(result).not.toBeNull();
+      expect(result).toHaveLength(0);
+    });
+
+    test("should return empty list on null content", async () => {
+      const address = "test-address";
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: () => "0",
+        },
+      });
+
+      const result = await client.getPayments(address);
+
+      expect(result).not.toBeNull();
+      expect(result).toHaveLength(0);
+    });
+
+    test("should use custom options", async () => {
+      const address = "test-address";
+      const customOptions = {
+        baseUrl: { url: "https://production.example.com" },
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: () => "2",
+        },
+        json: async () => [],
+      });
+
+      await client.getPayments(address, customOptions);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://production.example.com/v2/payments/test-address",
+        expect.any(Object),
+      );
+    });
+
+    test("should throw exception if baseUrl not set", async () => {
+      client = new V2BrantaClient({});
+
+      await expect(client.getPayments("test-address")).rejects.toThrow(
+        "Branta: BaseUrl is a required option.",
+      );
+    });
+  });
+
+  describe("getZKPayment", () => {
+    test("should decrypt ZK destination values", async () => {
+      const encryptedValue =
+        "pQerSFV+fievHP+guYoGJjx1CzFFrYWHAgWrLhn5473Z19M6+WMScLd1hsk808AEF/x+GpZKmNacFBf5BbQ=";
+      const payments = [
+        {
+          destinations: [
+            { isZk: true, value: encryptedValue },
+            { isZk: false, value: "plain-value" },
+          ],
+        },
+      ];
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: () => "100",
+        },
+        json: async () => JSON.parse(JSON.stringify(payments)),
+      });
+
+      const result = await client.getZKPayment(encryptedValue, "1234");
+
+      expect(result).not.toBeNull();
+      expect(result).toHaveLength(1);
+      expect(result[0].destinations[0].value).toBe(
+        "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+      );
+    });
+
+    test("should return unmodified payments with no ZK destinations", async () => {
+      const payments = [
+        {
+          destinations: [{ isZk: false, value: "plain-value" }],
+        },
+      ];
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: () => "100",
+        },
+        json: async () => JSON.parse(JSON.stringify(payments)),
+      });
+
+      const result = await client.getZKPayment("plain-value", "test-secret");
+
+      expect(result).not.toBeNull();
+      expect(result).toHaveLength(1);
+      expect(result[0].destinations[0].value).toBe("plain-value");
+    });
+  });
+
+  describe("addPayment", () => {
+    test("should throw exception when no API key is provided", async () => {
+      const payment = testPayments[0];
+      const clientWithoutApiKey = new V2BrantaClient({
+        baseUrl: { url: "https://production.example.com" },
+        defaultApiKey: null,
+      });
+
+      await expect(clientWithoutApiKey.addPayment(payment)).rejects.toThrow(
+        BrantaPaymentException,
+      );
+    });
+
+    test("should use custom API key", async () => {
+      const payment = testPayments[0];
+      const customOptions = {
+        baseUrl: { url: "https://production.example.com" },
+        defaultApiKey: "custom-api-key",
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        text: async () => JSON.stringify(testPayments[0]),
+      });
+
+      await client.addPayment(payment, customOptions);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://production.example.com/v2/payments",
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: "Bearer custom-api-key",
+          }),
+        }),
+      );
+    });
+
+    test("should throw exception on failed response", async () => {
+      const payment = testPayments[0];
+
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 400,
+      });
+
+      await expect(client.addPayment(payment)).rejects.toThrow(
+        BrantaPaymentException,
+      );
+    });
+
+    test("should return parsed response on success", async () => {
+      const payment = testPayments[0];
+      const expectedResponse = { ...payment, id: "12345" };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        text: async () => JSON.stringify(expectedResponse),
+      });
+
+      const result = await client.addPayment(payment);
+
+      expect(result).toEqual(expectedResponse);
+    });
+  });
+
+  describe("addZKPayment", () => {
+    test("should encrypt ZK destinations and return payment with secret", async () => {
+      const plainText = "plain-value";
+      const payment = {
+        destinations: [
+          { isZk: true, value: plainText },
+          { isZk: false, value: "other-value" },
+        ],
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        text: async () => JSON.stringify(payment),
+      });
+
+      const result = await client.addZKPayment(payment);
+
+      const zkPayment = result.payment.destinations.find(
+        (d) => d.isZk == true,
+      ).value;
+
+      expect(await AesEncryption.decrypt(zkPayment, result.secret)).toBe(
+        plainText,
+      );
+
+      expect(result.payment).toBeDefined();
+    });
+  });
+
+  describe("isApiKeyValid", () => {
+    test("should return true for valid API key", async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+      });
+
+      const result = await client.isApiKeyValid();
+
+      expect(result).toBe(true);
+    });
+
+    test("should return false for invalid API key", async () => {
+      mockFetch.mockResolvedValue({
+        ok: false,
+      });
+
+      const result = await client.isApiKeyValid();
+
+      expect(result).toBe(false);
+    });
+
+    test("should use custom options", async () => {
+      const customOptions = {
+        baseUrl: { url: "https://production.example.com" },
+        defaultApiKey: "custom-key",
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+      });
+
+      await client.isApiKeyValid(customOptions);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://production.example.com/v2/api-keys/health-check",
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: "Bearer custom-key",
+          }),
+        }),
+      );
+    });
+  });
+});