@velumx/sdk 2.1.0 → 2.2.0

package/dist/VelumXClient.d.ts

@@ -1,10 +1,10 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 export declare class VelumXClient {
     private config;
     private relayerUrl;
     constructor(config: NetworkConfig);
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     estimateFee(intent: any): Promise<{
         maxFeeUSDCx: string;
@@ -17,10 +17,19 @@ export declare class VelumXClient {
         txid: string;
         status: string;
     }>;
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    sponsor(txHex: string, options?: SponsorshipOptions): Promise<{
+        txid: string;
+        status: string;
+    }>;
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    submitRawTransaction(txHex: string): Promise<{
+    submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{
         txid: string;
         status: string;
     }>;

package/dist/VelumXClient.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VelumXClient = void 0;
 class VelumXClient {
     constructor(config) {
-        if (!config.apiKey) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
             throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
         }
         this.config = config;
@@ -11,12 +11,12 @@ class VelumXClient {
         this.relayerUrl = config.paymasterUrl || 'https://relayer.velumx.com/api/v1';
     }
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     async estimateFee(intent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/estimate`, {
@@ -41,7 +41,7 @@ class VelumXClient {
     async submitIntent(signedIntent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/sponsor`, {
@@ -60,19 +60,31 @@ class VelumXClient {
             throw error;
         }
     }
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    async sponsor(txHex, options) {
+        return this.submitRawTransaction(txHex, options);
+    }
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    async submitRawTransaction(txHex) {
+    async submitRawTransaction(txHex, options) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
             if (!response.ok) {
                 const errData = await response.json().catch(() => ({ error: 'Unknown error' }));

package/dist/types.d.ts

@@ -14,3 +14,7 @@ export interface NetworkConfig {
     paymasterUrl?: string;
     apiKey?: string;
 }
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velumx/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "VelumX Gas Abstraction Layer SDK for dApps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/VelumXClient.ts

@@ -1,11 +1,11 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 
 export class VelumXClient {
     private config: NetworkConfig;
     private relayerUrl: string;
 
     constructor(config: NetworkConfig) {
-        if (!config.apiKey) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
             throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
         }
         this.config = config;
@@ -14,12 +14,12 @@ export class VelumXClient {
     }
 
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     public async estimateFee(intent: any): Promise<{ maxFeeUSDCx: string, estimatedGas: number }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -47,7 +47,7 @@ export class VelumXClient {
     public async submitIntent(signedIntent: SignedIntent): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -69,20 +69,33 @@ export class VelumXClient {
         }
     }
 
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    public async sponsor(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
+        return this.submitRawTransaction(txHex, options);
+    }
+
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    public async submitRawTransaction(txHex: string): Promise<{ txid: string, status: string }> {
+    public async submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({ 
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
 
             if (!response.ok) {

package/src/types.ts

@@ -15,6 +15,11 @@ export interface SignedIntent extends WalletIntent {
 export interface NetworkConfig {
     coreApiUrl: string;
     network: 'mainnet' | 'testnet' | 'devnet';
-    paymasterUrl?: string; // URL for the SGAL relayer service
-    apiKey?: string; // SGAL API Key
+    paymasterUrl?: string; // URL for the VelumX relayer service
+    apiKey?: string; // VelumX API Key
+}
+
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
 }