@branta-ops/branta 1.0.1 → 2.0.0

package/README.md

@@ -18,6 +18,7 @@ import { V2BrantaClient, BrantaServerBaseUrl } from "@branta-ops/branta";
 
 const client = new V2BrantaClient({
   baseUrl: BrantaServerBaseUrl.Production,
+  privacy: 'loose',
 });
 
 await client.getPayments("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
@@ -31,6 +32,7 @@ import { V2BrantaClient, BrantaServerBaseUrl } from "@branta-ops/branta";
 const client = new V2BrantaClient({
   baseUrl: BrantaServerBaseUrl.Production,
   defaultApiKey: "<default-api-key>",
+  privacy: 'loose',
 });
 
 await client.addPayment({
@@ -54,6 +56,7 @@ const client = new V2BrantaClient({
   baseUrl: BrantaServerBaseUrl.Production,
   defaultApiKey: "<default-api-key>",
   hmacSecret: "<hmac-secret>",
+  privacy: 'loose',
 });
 
 await client.addPayment({
@@ -68,6 +71,11 @@ await client.addPayment({
 });
 ```
 
+## Release
+ - npm login
+ - npm version major|minor|patch
+ - npm publish
+
 ## Feature Support
 
  - [X] Per Environment configuration

package/dist/classes/brantaClientOptions.d.ts

@@ -1,7 +1,22 @@
 import { ServerEnvironment } from "./brantaServerBaseUrl.js";
+/**
+ * Controls the privacy posture for on-chain address lookups.
+ *
+ * - `'strict'` — Only ZK (zero-knowledge / encrypted) on-chain lookups are
+ *   permitted. Calling `getPayments` directly will throw a
+ *   `BrantaPaymentException`; plain-address branches inside
+ *   `getPaymentByQrCode` will silently return `[]`. Lightning invoices and
+ *   all POST operations are unaffected by this setting.
+ *
+ * - `'loose'` — Both plain and ZK on-chain lookups are allowed. No
+ *   restrictions are enforced.
+ */
+export type PrivacyMode = 'strict' | 'loose';
 export default interface BrantaClientOptions {
     baseUrl?: ServerEnvironment | string | null;
     defaultApiKey?: string | null;
     hmacSecret?: string | null;
     timeout?: number;
+    /** @see {@link PrivacyMode} */
+    privacy: PrivacyMode;
 }

package/dist/v2/client.d.ts

@@ -11,7 +11,9 @@ export interface Payment {
     description?: string;
     metadata?: Record<string, string>;
     verifyUrl?: string;
+    platform?: string;
     platformLogoUrl?: string;
+    platformLogoLightUrl?: string;
 }
 interface PaymentResponse extends Payment {
     createdAt: Date;
@@ -28,10 +30,12 @@ export declare class V2BrantaClient {
     private _defaultOptions;
     constructor(brantaClientOptions: BrantaClientOptions);
     getPayments(address: string, options?: BrantaClientOptions | null): Promise<Payment[]>;
+    private _fetchPayments;
     getZKPayment(address: string, secret: string, options?: BrantaClientOptions | null): Promise<Payment[]>;
     addPayment(payment: Payment, options?: BrantaClientOptions | null): Promise<PaymentResult>;
     addZKPayment(payment: Payment, options?: BrantaClientOptions | null): Promise<ZKPaymentResult>;
     getPaymentsByQRCode(qrText: string, options?: BrantaClientOptions | null): Promise<Payment[]>;
+    private _getPlainPayments;
     isApiKeyValid(options?: BrantaClientOptions | null): Promise<boolean>;
     private _buildVerifyUrl;
     private _resolveBaseUrl;

package/dist/v2/client.js

@@ -5,15 +5,23 @@ export class V2BrantaClient {
         this._defaultOptions = brantaClientOptions;
     }
     async getPayments(address, options = null) {
+        const privacy = options?.privacy ?? this._defaultOptions?.privacy;
+        if (privacy === 'strict') {
+            throw new BrantaPaymentException("privacy is set to 'strict': plain on-chain address lookups are not permitted");
+        }
+        return this._fetchPayments(address, options);
+    }
+    async _fetchPayments(address, options = null) {
         const httpClient = this._createClient(options);
         const response = await httpClient.get(`/v2/payments/${encodeURIComponent(address)}`);
         if (!response.ok || response.headers.get("content-length") === "0") {
             return [];
         }
         const raw = await response.json();
-        const data = raw.map(({ platform_logo_url: platformLogoUrl, verify_url: verifyUrl, ...rest }) => ({
+        const data = raw.map(({ platform_logo_url: platformLogoUrl, platform_logo_light_url: platformLogoLightUrl, verify_url: verifyUrl, ...rest }) => ({
             ...rest,
             platformLogoUrl,
+            platformLogoLightUrl,
             verifyUrl,
         }));
         const baseUrl = this._resolveBaseUrl(options);
@@ -29,11 +37,20 @@ export class V2BrantaClient {
                 if (!valid)
                     throw new BrantaPaymentException("platformLogoUrl domain does not match the configured baseUrl domain");
             }
+            if (payment.platformLogoLightUrl) {
+                let valid = false;
+                try {
+                    valid = new URL(payment.platformLogoLightUrl).origin === baseOrigin;
+                }
+                catch { /* invalid URL */ }
+                if (!valid)
+                    throw new BrantaPaymentException("platformLogoLightUrl domain does not match the configured baseUrl domain");
+            }
         }
         return data;
     }
     async getZKPayment(address, secret, options = null) {
-        const payments = await this.getPayments(address, options);
+        const payments = await this._fetchPayments(address, options);
         for (const payment of payments) {
             for (const destination of payment?.destinations || []) {
                 if (destination.zk === false)
@@ -81,38 +98,44 @@ export class V2BrantaClient {
             url = new URL(text);
         }
         catch { /* not a URL */ }
-        if (url) {
-            const rawParams = new URLSearchParams(url.search.replace(/\+/g, '%2B'));
-            const brantaId = rawParams.get('branta_id');
-            const brantaSecret = rawParams.get('branta_secret');
-            if (brantaId && brantaSecret) {
-                return this.getZKPayment(brantaId, brantaSecret, options);
-            }
-            if (url.protocol === 'bitcoin:') {
-                return this.getPayments(this._normalizeAddress(url.pathname), options);
+        if (!url)
+            return this._getPlainPayments(this._normalizeAddress(text), options);
+        const rawParams = new URLSearchParams(url.search.replace(/\+/g, '%2B'));
+        const brantaId = rawParams.get('branta_id');
+        const brantaSecret = rawParams.get('branta_secret');
+        if (brantaId && brantaSecret)
+            return this.getZKPayment(brantaId, brantaSecret, options);
+        if (url.protocol === 'bitcoin:') {
+            return this._getPlainPayments(this._normalizeAddress(url.pathname), options);
+        }
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            const baseUrl = this._resolveBaseUrl(options);
+            if (!baseUrl || new URL(baseUrl).origin !== url.origin) {
+                return this._getPlainPayments(this._normalizeAddress(text), options);
             }
-            if (url.protocol === 'http:' || url.protocol === 'https:') {
-                const baseUrl = this._resolveBaseUrl(options);
-                if (baseUrl && new URL(baseUrl).origin === url.origin) {
-                    const segments = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
-                    const [version, type, id] = segments;
-                    if (version === 'v2' && id) {
-                        if (type === 'verify')
-                            return this.getPayments(id, options);
-                        if (type === 'zk-verify') {
-                            const secret = new URLSearchParams(url.hash.slice(1)).get('secret');
-                            return secret
-                                ? this.getZKPayment(id, secret, options)
-                                : this.getPayments(id, options);
-                        }
-                    }
-                    const lastSegment = segments.at(-1);
-                    if (lastSegment)
-                        return this.getPayments(lastSegment, options);
+            const segments = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+            const [version, type, id] = segments;
+            if (version === 'v2' && id) {
+                if (type === 'verify')
+                    return this._getPlainPayments(id, options);
+                if (type === 'zk-verify') {
+                    const secret = new URLSearchParams(url.hash.slice(1)).get('secret');
+                    if (secret)
+                        return this.getZKPayment(id, secret, options);
+                    return this._getPlainPayments(id, options);
                 }
             }
+            const lastSegment = segments.at(-1);
+            if (lastSegment)
+                return this._getPlainPayments(lastSegment, options);
         }
-        return this.getPayments(this._normalizeAddress(text), options);
+        return this._getPlainPayments(this._normalizeAddress(text), options);
+    }
+    _getPlainPayments(address, options) {
+        const privacy = options?.privacy ?? this._defaultOptions?.privacy;
+        if (privacy === 'strict')
+            return Promise.resolve([]);
+        return this.getPayments(address, options);
     }
     async isApiKeyValid(options = null) {
         const httpClient = this._createClient(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@branta-ops/branta",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "A JavaScript SDK for the Branta API",
   "homepage": "https://github.com/BrantaOps/branta-js#readme",
   "bugs": {

package/dist/classes/brantaBaseServerUrl.d.ts

@@ -1,11 +0,0 @@
-export interface ServerEnvironment {
-    value: number;
-    url: string;
-}
-export interface BrantaServerBaseUrlType {
-    Staging: ServerEnvironment;
-    Production: ServerEnvironment;
-    Localhost: ServerEnvironment;
-}
-declare const BrantaServerBaseUrl: BrantaServerBaseUrlType;
-export default BrantaServerBaseUrl;

package/dist/classes/brantaBaseServerUrl.js

@@ -1,6 +0,0 @@
-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;