sdk-triggerx 0.1.17 → 0.1.19

package/README.md

@@ -50,6 +50,17 @@ const client = new TriggerXClient('YOUR_API_KEY');
 - `ArgType.Static`: Hardcoded values
 - `ArgType.Dynamic`: Runtime values fetched from a script
 
+#### Wallet Modes
+
+- `walletMode: 'regular'` (default): Executes jobs from the externally-owned account (EOA) signer.
+- `walletMode: 'safe'`: Executes jobs via a Safe wallet using the TriggerX Safe Module.
+  - Requirements:
+    - Safe threshold must be 1 (single-signer) in this implementation.
+    - The signer must be an owner of the Safe.
+    - Parameters must be dynamic (provided by `dynamicArgumentsScriptUrl`).
+    - The SDK will auto-create a Safe if `safeAddress` is not provided and the chain is configured with a Safe Factory.
+    - The SDK will auto-enable the TriggerX Safe Module on the Safe if not already enabled.
+
 #### Supported Condition Types (for `conditionType`)
 
 - `greater_than`
@@ -97,6 +108,47 @@ console.log(result);
 
 ---
 
+#### 🧷 Example: Time-based Dynamic Job via Safe Wallet (Arbitrum Sepolia)
+
+```ts
+import { createJob, JobType, ArgType } from 'sdk-triggerx';
+
+const jobInput = {
+  jobType: JobType.Time,
+  argType: ArgType.Dynamic,
+
+  jobTitle: 'My Safe Time Job',
+  timeFrame: 3600,
+  scheduleType: 'interval',
+  timeInterval: 300,
+  timezone: 'UTC',
+
+  // Arbitrum Sepolia
+  chainId: '421614',
+
+  // Safe mode (no target required — SDK auto-sets module target/function/ABI)
+  walletMode: 'safe',
+  // Optional: provide an existing Safe; otherwise the SDK will create one for you
+  // safeAddress: '0xYourSafeAddress',
+
+  // Dynamic params must come from an IPFS/URL script
+  dynamicArgumentsScriptUrl: 'https://your-ipfs-gateway/ipfs/your-hash',
+
+  // Optional helper to auto-top up TG if low
+  autotopupTG: true,
+};
+
+const result = await createJob(client, { jobInput, signer });
+console.log(result);
+```
+
+Notes for Safe wallet mode:
+- In Safe mode, you do NOT need to set `targetContractAddress`/`targetFunction`/`abi` — the SDK sets these for the Safe Module and uses `execJobFromHub(address,address,uint256,bytes,uint8)` under the hood.
+- Your action details (action target/value/data/op) must be produced by your IPFS script at execution time.
+- No static arguments are allowed in Safe mode.
+
+---
+
 #### 📟 Example: Event-based Dynamic Job
 
 ```ts
@@ -165,6 +217,49 @@ console.log(result);
 
 ---
 
+### 🛡️ Safe Wallet (Gnosis Safe) Flow
+
+To create jobs that use Safe wallets (`walletMode: 'safe'`), you must first create a Safe and obtain its address. The Safe MUST exist before the job can be created.
+
+#### 1️⃣ Create a Safe wallet for your user
+
+```ts
+import { createSafeWallet } from 'sdk-triggerx/api/safeWallet'; // <--- new dedicated helper!
+const safeAddress = await createSafeWallet(signer /* ethers.Signer */);
+console.log('Your Safe address:', safeAddress);
+```
+
+- Use this new address in safe job creation. All safe wallet creation belongs in this flow.
+- You can use the returned address in any number of jobs for this user.
+- This MUST be done before you attempt to create any job with `walletMode: 'safe'`.
+- All safe wallet creation helpers are now in the dedicated `api/safeWallet` module so your file structure stays clean.
+
+#### 2️⃣ Create a job using the Safe (walletMode: 'safe')
+
+```ts
+const jobInput = {
+  jobType: JobType.Time,
+  argType: ArgType.Dynamic, // required in safe mode
+  jobTitle: 'Safe Job',
+  timeFrame: 3600,
+  scheduleType: 'interval',
+  timeInterval: 300,
+  timezone: 'UTC',
+  chainId: '421614',
+  walletMode: 'safe',
+  safeAddress, // <---- required and must come from step 1
+  dynamicArgumentsScriptUrl: 'https://your-ipfs-gateway/ipfs/your-hash',
+  autotopupTG: true,
+};
+// ...
+await createJob(client, { jobInput, signer }); // as normal
+```
+
+- The `safeAddress` property is now required for jobs using `walletMode: 'safe'`.
+- The SDK will no longer auto-create a Safe wallet for you; you must explicitly create and pass it in your job input.
+
+---
+
 ### 3. Fetch Job Data
 
 #### 🔍 Get All Jobs

package/dist/api/checkTgBalance.d.ts

@@ -1,5 +1,12 @@
 import { ethers } from 'ethers';
 export declare const checkTgBalance: (signer: ethers.Signer) => Promise<{
-    tgBalanceWei: bigint;
-    tgBalance: string;
+    success: boolean;
+    data?: {
+        tgBalanceWei: bigint;
+        tgBalance: string;
+    };
+    error?: string;
+    errorCode?: string;
+    errorType?: string;
+    details?: any;
 }>;

package/dist/api/checkTgBalance.js

@@ -7,33 +7,52 @@ exports.checkTgBalance = void 0;
 const ethers_1 = require("ethers");
 const GasRegistry_json_1 = __importDefault(require("../contracts/abi/GasRegistry.json"));
 const config_1 = require("../config");
+const errors_1 = require("../utils/errors");
 const checkTgBalance = async (signer) => {
-    const network = await signer.provider?.getNetwork();
-    const chainId = network?.chainId ? network.chainId.toString() : undefined;
-    const { gasRegistry } = (0, config_1.getChainAddresses)(chainId);
-    const gasRegistryContractAddress = gasRegistry;
-    if (!gasRegistryContractAddress) {
-        throw new Error('GasRegistry address not configured for this chain. Update config mapping.');
+    // Validate inputs
+    if (!signer) {
+        return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('signer', 'Signer is required'), 'Validation error');
     }
-    const contract = new ethers_1.ethers.Contract(gasRegistryContractAddress, GasRegistry_json_1.default, signer);
-    const address = await signer.getAddress();
-    const balance = await contract.balances(address);
-    // balance is likely an array or object with ethSpent and TGbalance, both in wei
-    // We'll convert TGbalance from wei to ETH
-    // If balance is an array: [ethSpent, TGbalance]
-    // If balance is an object: { ethSpent, TGbalance }
-    let tgBalanceWei;
-    if (Array.isArray(balance)) {
-        tgBalanceWei = balance[1];
+    try {
+        const network = await signer.provider?.getNetwork();
+        const chainId = network?.chainId ? network.chainId.toString() : undefined;
+        const { gasRegistry } = (0, config_1.getChainAddresses)(chainId);
+        const gasRegistryContractAddress = gasRegistry;
+        if (!gasRegistryContractAddress) {
+            return (0, errors_1.createErrorResponse)(new errors_1.ConfigurationError(`GasRegistry address not configured for chain ID: ${chainId}`), 'Configuration error');
+        }
+        const contract = new ethers_1.ethers.Contract(gasRegistryContractAddress, GasRegistry_json_1.default, signer);
+        const address = await signer.getAddress();
+        const balance = await contract.balances(address);
+        // balance is likely an array or object with ethSpent and TGbalance, both in wei
+        // We'll convert TGbalance from wei to ETH
+        // If balance is an array: [ethSpent, TGbalance]
+        // If balance is an object: { ethSpent, TGbalance }
+        let tgBalanceWei;
+        if (Array.isArray(balance)) {
+            tgBalanceWei = balance[1];
+        }
+        else if (balance && balance.TGbalance !== undefined) {
+            tgBalanceWei = balance.TGbalance;
+        }
+        else {
+            return (0, errors_1.createErrorResponse)(new errors_1.ContractError('Unexpected balance format from contract', { balance }), 'Contract error');
+        }
+        const tgBalance = ethers_1.ethers.formatEther(tgBalanceWei);
+        console.log('tgBalanceEth', tgBalance);
+        return { success: true, data: { tgBalanceWei, tgBalance } };
     }
-    else if (balance && balance.TGbalance !== undefined) {
-        tgBalanceWei = balance.TGbalance;
+    catch (error) {
+        console.error('Error checking TG balance:', error);
+        if (error instanceof Error) {
+            if (error.message.includes('network') || error.message.includes('timeout')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.NetworkError('Network error during balance check', { originalError: error }), 'Network error');
+            }
+            else if (error.message.includes('contract') || error.message.includes('transaction')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ContractError('Contract error during balance check', { originalError: error }), 'Contract error');
+            }
+        }
+        return (0, errors_1.createErrorResponse)(error, 'Failed to check TG balance');
     }
-    else {
-        throw new Error('Unexpected balance format');
-    }
-    const tgBalance = ethers_1.ethers.formatEther(tgBalanceWei);
-    console.log('tgBalanceEth', tgBalance);
-    return { tgBalanceWei, tgBalance };
 };
 exports.checkTgBalance = checkTgBalance;

package/dist/api/deleteJob.d.ts

@@ -1,3 +1,9 @@
 import { TriggerXClient } from '../client';
 import { Signer } from 'ethers';
-export declare const deleteJob: (client: TriggerXClient, jobId: string, signer: Signer, chainId: string) => Promise<void>;
+export declare const deleteJob: (client: TriggerXClient, jobId: string, signer: Signer, chainId: string) => Promise<{
+    success: boolean;
+    error?: string;
+    errorCode?: string;
+    errorType?: string;
+    details?: any;
+}>;

package/dist/api/deleteJob.js

@@ -8,11 +8,22 @@ exports.deleteJob = void 0;
 const JobRegistry_json_1 = __importDefault(require("../contracts/abi/JobRegistry.json"));
 const JobRegistry_1 = require("../contracts/JobRegistry");
 const config_1 = require("../config");
+const errors_1 = require("../utils/errors");
 const deleteJob = async (client, jobId, signer, chainId) => {
-    const apiKey = client.getApiKey(); // Assuming you have a method to get the API key
+    // Validate inputs
+    if (!jobId || typeof jobId !== 'string') {
+        return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('jobId', 'Job ID is required and must be a string'), 'Validation error');
+    }
+    if (!chainId || typeof chainId !== 'string') {
+        return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('chainId', 'Chain ID is required and must be a string'), 'Validation error');
+    }
+    const apiKey = client.getApiKey();
+    if (!apiKey) {
+        return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('API key is required but not provided'), 'Authentication error');
+    }
     const { jobRegistry: jobRegistryAddress } = config_1.CONTRACT_ADDRESSES_BY_CHAIN[chainId];
     if (!jobRegistryAddress) {
-        throw new Error(`No contract address found for chain ID: ${chainId}`);
+        return (0, errors_1.createErrorResponse)(new errors_1.ConfigurationError(`No contract address found for chain ID: ${chainId}`), 'Configuration error');
     }
     try {
         console.log(`Deleting job ${jobId} on chain ${chainId}...`);
@@ -33,10 +44,25 @@ const deleteJob = async (client, jobId, signer, chainId) => {
             timeout: 30000, // 30 second timeout
         });
         console.log('API update successful');
+        return { success: true };
     }
     catch (error) {
         console.error('Error deleting job:', error);
-        throw error; // Rethrow the error for handling in the calling function
+        // Determine error type based on the error
+        const httpStatusCode = (0, errors_1.extractHttpStatusCode)(error);
+        const errorCode = (0, errors_1.determineErrorCode)(error, httpStatusCode);
+        if (error instanceof Error) {
+            if (error.message.includes('network') || error.message.includes('timeout')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.NetworkError('Network error during job deletion', { originalError: error, jobId, chainId }, httpStatusCode), 'Network error');
+            }
+            else if (error.message.includes('contract') || error.message.includes('transaction')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ContractError('Contract error during job deletion', { originalError: error, jobId, chainId }, httpStatusCode), 'Contract error');
+            }
+            else if (error.message.includes('API') || error.message.includes('response')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ApiError('API error during job deletion', { originalError: error, jobId, chainId }, httpStatusCode), 'API error');
+            }
+        }
+        return (0, errors_1.createErrorResponse)(error, 'Failed to delete job');
     }
 };
 exports.deleteJob = deleteJob;

package/dist/api/getJobDataById.d.ts

@@ -1,3 +1,10 @@
 import { TriggerXClient } from '../client';
 import { JobDataWithTasks } from '../types';
-export declare const getJobDataById: (client: TriggerXClient, jobId: string) => Promise<JobDataWithTasks>;
+export declare const getJobDataById: (client: TriggerXClient, jobId: string) => Promise<{
+    success: boolean;
+    data?: JobDataWithTasks;
+    error?: string;
+    errorCode?: string;
+    errorType?: string;
+    details?: any;
+}>;

package/dist/api/getJobDataById.js

@@ -2,8 +2,16 @@
 // sdk-triggerx/src/api/getJobDataById.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getJobDataById = void 0;
+const errors_1 = require("../utils/errors");
 const getJobDataById = async (client, jobId) => {
-    const apiKey = client.getApiKey(); // Assuming you have a method to get the API key
+    // Validate inputs
+    if (!jobId || typeof jobId !== 'string') {
+        return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('jobId', 'Job ID is required and must be a string'), 'Validation error');
+    }
+    const apiKey = client.getApiKey();
+    if (!apiKey) {
+        return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('API key is required but not provided'), 'Authentication error');
+    }
     try {
         // First, fetch the job data
         const jobResponse = await client.get(`/api/jobs/${jobId}`, {
@@ -24,11 +32,27 @@ const getJobDataById = async (client, jobId) => {
             jobData: jobResponse,
             taskData: taskResponse
         };
-        return combinedResponse;
+        return { success: true, data: combinedResponse };
     }
     catch (error) {
         console.error('Error fetching job data and task data by ID:', error);
-        throw error; // Rethrow the error for handling in the calling function
+        const httpStatusCode = (0, errors_1.extractHttpStatusCode)(error);
+        const errorCode = (0, errors_1.determineErrorCode)(error, httpStatusCode);
+        if (error instanceof Error) {
+            if (error.message.includes('network') || error.message.includes('timeout')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.NetworkError('Network error while fetching job data', { originalError: error, jobId }, httpStatusCode), 'Network error');
+            }
+            else if (error.message.includes('404') || error.message.includes('not found')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('jobId', 'Job not found', { originalError: error, jobId }, 404), 'Validation error');
+            }
+            else if (error.message.includes('401') || error.message.includes('unauthorized')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('Unauthorized access to job data', { originalError: error, jobId }, 401), 'Authentication error');
+            }
+            else if (error.message.includes('API') || error.message.includes('response')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ApiError('API error while fetching job data', { originalError: error, jobId }, httpStatusCode), 'API error');
+            }
+        }
+        return (0, errors_1.createErrorResponse)(error, 'Failed to fetch job data');
     }
 };
 exports.getJobDataById = getJobDataById;

package/dist/api/getUserData.d.ts

@@ -1,3 +1,10 @@
 import { TriggerXClient } from '../client';
 import { UserData } from '../types';
-export declare const getUserData: (client: TriggerXClient, address: string) => Promise<UserData>;
+export declare const getUserData: (client: TriggerXClient, address: string) => Promise<{
+    success: boolean;
+    data?: UserData;
+    error?: string;
+    errorCode?: string;
+    errorType?: string;
+    details?: any;
+}>;

package/dist/api/getUserData.js

@@ -2,8 +2,16 @@
 // sdk-triggerx/src/api/getUserData.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUserData = void 0;
+const errors_1 = require("../utils/errors");
 const getUserData = async (client, address) => {
-    const apiKey = client.getApiKey(); // Assuming you have a method to get the API key
+    // Validate inputs
+    if (!address || typeof address !== 'string') {
+        return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('address', 'User address is required and must be a string'), 'Validation error');
+    }
+    const apiKey = client.getApiKey();
+    if (!apiKey) {
+        return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('API key is required but not provided'), 'Authentication error');
+    }
     try {
         const response = await client.get(`api/users/${address}`, {
             headers: {
@@ -11,11 +19,27 @@ const getUserData = async (client, address) => {
                 'X-API-KEY': apiKey,
             },
         });
-        return response; // Assuming the response data matches the UserData interface
+        return { success: true, data: response };
     }
     catch (error) {
         console.error('Error fetching user data:', error);
-        throw error; // Rethrow the error for handling in the calling function
+        const httpStatusCode = (0, errors_1.extractHttpStatusCode)(error);
+        const errorCode = (0, errors_1.determineErrorCode)(error, httpStatusCode);
+        if (error instanceof Error) {
+            if (error.message.includes('network') || error.message.includes('timeout')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.NetworkError('Network error while fetching user data', { originalError: error, address }, httpStatusCode), 'Network error');
+            }
+            else if (error.message.includes('404') || error.message.includes('not found')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ValidationError('address', 'User not found', { originalError: error, address }, 404), 'Validation error');
+            }
+            else if (error.message.includes('401') || error.message.includes('unauthorized')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('Unauthorized access to user data', { originalError: error, address }, 401), 'Authentication error');
+            }
+            else if (error.message.includes('API') || error.message.includes('response')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ApiError('API error while fetching user data', { originalError: error, address }, httpStatusCode), 'API error');
+            }
+        }
+        return (0, errors_1.createErrorResponse)(error, 'Failed to fetch user data');
     }
 };
 exports.getUserData = getUserData;

package/dist/api/getjob.js

@@ -1,14 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getJobData = getJobData;
+const errors_1 = require("../utils/errors");
 /**
  * Fetch job data for a given API key by calling the backend endpoint.
  * @param client TriggerXClient instance
  * @returns JobResponse containing job data or error
  */
 async function getJobData(client) {
+    const apiKey = client.getApiKey();
+    if (!apiKey) {
+        return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('API key is required but not provided'), 'Authentication error');
+    }
     try {
-        const apiKey = client.getApiKey(); // Assuming you have a method to get the API key
         const data = await client.get('/api/jobs/by-apikey', {
             headers: {
                 'Content-Type': 'application/json',
@@ -18,6 +22,20 @@ async function getJobData(client) {
         return { success: true, jobs: data.jobs };
     }
     catch (error) {
-        return { success: false, error: error.message, };
+        console.error('Error fetching job data:', error);
+        const httpStatusCode = (0, errors_1.extractHttpStatusCode)(error);
+        const errorCode = (0, errors_1.determineErrorCode)(error, httpStatusCode);
+        if (error instanceof Error) {
+            if (error.message.includes('network') || error.message.includes('timeout')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.NetworkError('Network error while fetching job data', { originalError: error }, httpStatusCode), 'Network error');
+            }
+            else if (error.message.includes('401') || error.message.includes('unauthorized')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.AuthenticationError('Unauthorized access to job data', { originalError: error }, 401), 'Authentication error');
+            }
+            else if (error.message.includes('API') || error.message.includes('response')) {
+                return (0, errors_1.createErrorResponse)(new errors_1.ApiError('API error while fetching job data', { originalError: error }, httpStatusCode), 'API error');
+            }
+        }
+        return (0, errors_1.createErrorResponse)(error, 'Failed to fetch job data');
     }
 }