@jack-kernel/sdk 1.0.0

package/dist/esm/intents.js

@@ -0,0 +1,181 @@
+/**
+ * Intent management for the JACK SDK
+ *
+ * This module provides the IntentManager class for creating, submitting,
+ * and querying intents through the JACK API.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4
+ */
+import { getTypedData } from './serialization.js';
+import { validateIntentParams } from './validation.js';
+import { ValidationError } from './errors.js';
+/**
+ * Manager for intent operations
+ *
+ * Provides methods to create EIP-712 typed data, validate parameters,
+ * submit signed intents, and query intent status.
+ *
+ * @example
+ * ```typescript
+ * const client = new JackClient({ baseUrl: 'https://api.jack.example' });
+ * const manager = new IntentManager(client);
+ *
+ * // Create typed data for signing
+ * const typedData = manager.getTypedData(params);
+ * const signature = await wallet.signTypedData(typedData);
+ *
+ * // Submit the signed intent
+ * const intentId = await manager.submit(params, signature);
+ *
+ * // Query the intent
+ * const intent = await manager.get(intentId);
+ * ```
+ */
+export class IntentManager {
+    client;
+    /**
+     * Creates a new IntentManager
+     *
+     * @param client - The JackClient instance to use for API requests
+     */
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get EIP-712 typed data for intent signing
+     *
+     * Constructs properly formatted EIP-712 TypedData that can be signed
+     * by a wallet. This method delegates to the serialization module.
+     *
+     * @param params - Intent parameters to serialize
+     * @param chainId - Chain ID for the domain separator (default: 1)
+     * @param verifyingContract - Address of the verifying contract
+     * @returns EIP-712 TypedData object ready for signing
+     *
+     * @example
+     * ```typescript
+     * const typedData = manager.getTypedData({
+     *   sourceChain: 'arbitrum',
+     *   destinationChain: 'base',
+     *   tokenIn: '0xUSDC...',
+     *   tokenOut: '0xWETH...',
+     *   amountIn: '1000000',
+     *   minAmountOut: '42000000000000000',
+     *   deadline: Date.now() + 3600000
+     * });
+     *
+     * const signature = await wallet.signTypedData(typedData);
+     * ```
+     *
+     * **Validates: Requirement 1.1**
+     */
+    getTypedData(params, chainId = 1, verifyingContract = '0x0000000000000000000000000000000000000000') {
+        return getTypedData(params, chainId, verifyingContract);
+    }
+    /**
+     * Validate intent parameters
+     *
+     * Checks that all required fields are present, amounts are positive,
+     * deadline is in the future, and addresses are valid format.
+     * This method delegates to the validation module.
+     *
+     * @param params - Intent parameters to validate
+     * @returns ValidationResult with valid flag and error messages
+     *
+     * @example
+     * ```typescript
+     * const result = manager.validate(params);
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * ```
+     *
+     * **Validates: Requirement 5.4**
+     */
+    validate(params) {
+        return validateIntentParams(params);
+    }
+    /**
+     * Submit a signed intent to the JACK API
+     *
+     * Validates the intent parameters before submission. If validation fails,
+     * throws a ValidationError without making any network request. On success,
+     * returns the intent ID.
+     *
+     * @param params - Intent parameters
+     * @param signature - EIP-712 signature from the user's wallet
+     * @returns Promise resolving to the intent ID (format: JK-[A-Z0-9]{9})
+     * @throws ValidationError if parameters are invalid
+     * @throws APIError if the API returns an error
+     * @throws NetworkError if the network request fails
+     *
+     * @example
+     * ```typescript
+     * const intentId = await manager.submit(params, signature);
+     * console.log('Intent submitted:', intentId); // "JK-ABC123456"
+     * ```
+     *
+     * **Validates: Requirement 1.2**
+     */
+    async submit(params, signature) {
+        // Validate parameters before making network request
+        const validation = this.validate(params);
+        if (!validation.valid) {
+            throw new ValidationError('Invalid intent parameters', validation.errors);
+        }
+        // Submit to API
+        const response = await this.client.post('/api/intents', {
+            params,
+            signature
+        });
+        return response.intentId;
+    }
+    /**
+     * Get a single intent by ID
+     *
+     * Queries the JACK API for the complete intent object including
+     * current status, execution steps, and settlement transaction (if settled).
+     *
+     * @param intentId - The intent ID to query (format: JK-[A-Z0-9]{9})
+     * @returns Promise resolving to the complete Intent object
+     * @throws APIError if the intent is not found (404) or other API error
+     * @throws NetworkError if the network request fails
+     *
+     * @example
+     * ```typescript
+     * const intent = await manager.get('JK-ABC123456');
+     * console.log('Status:', intent.status);
+     * console.log('Settlement tx:', intent.settlementTx);
+     * ```
+     *
+     * **Validates: Requirement 1.3**
+     */
+    async get(intentId) {
+        return this.client.get(`/api/intents/${intentId}`);
+    }
+    /**
+     * List all intents
+     *
+     * Queries the JACK API for all intents. The API may implement pagination
+     * or filtering in the future, but currently returns all intents.
+     *
+     * @returns Promise resolving to an array of Intent objects
+     * @throws APIError if the API returns an error
+     * @throws NetworkError if the network request fails
+     *
+     * @example
+     * ```typescript
+     * const intents = await manager.list();
+     * console.log(`Found ${intents.length} intents`);
+     * intents.forEach(intent => {
+     *   console.log(`${intent.id}: ${intent.status}`);
+     * });
+     * ```
+     *
+     * **Validates: Requirement 1.4**
+     */
+    async list() {
+        return this.client.get('/api/intents');
+    }
+}
+//# sourceMappingURL=intents.js.map

package/dist/esm/intents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intents.js","sourceRoot":"","sources":["../../src/intents.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,CAAa;IAEpC;;;;OAIG;IACH,YAAY,MAAkB;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CACV,MAAoB,EACpB,UAAkB,CAAC,EACnB,oBAAmC,4CAA4C;QAE/E,OAAO,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,MAAoB;QAC3B,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,MAAM,CAAC,MAAoB,EAAE,SAAiB;QAClD,oDAAoD;QACpD,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,IAAI,eAAe,CACvB,2BAA2B,EAC3B,UAAU,CAAC,MAAM,CAClB,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,cAAc,EACd;YACE,MAAM;YACN,SAAS;SACV,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAS,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAW,cAAc,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/esm/serialization.js

@@ -0,0 +1,159 @@
+/**
+ * EIP-712 serialization for JACK intents
+ *
+ * This module provides functions to construct EIP-712 typed data for intent signing.
+ * The typed data follows the EIP-712 standard for structured data hashing and signing.
+ *
+ * Requirements: 1.1, 14.1
+ */
+/**
+ * Get EIP-712 typed data for an intent
+ *
+ * Constructs a properly formatted EIP-712 TypedData object that can be used
+ * with wallet signing methods (e.g., eth_signTypedData_v4). The typed data
+ * includes the domain separator, type definitions, and the intent message.
+ *
+ * @param params - Intent parameters to serialize
+ * @param chainId - Chain ID for the domain separator (default: 1 for Ethereum mainnet)
+ * @param verifyingContract - Address of the verifying contract
+ * @returns EIP-712 TypedData object ready for signing
+ *
+ * @example
+ * ```typescript
+ * const params = {
+ *   sourceChain: 'arbitrum',
+ *   destinationChain: 'base',
+ *   tokenIn: '0xUSDC...',
+ *   tokenOut: '0xWETH...',
+ *   amountIn: '1000000',
+ *   minAmountOut: '42000000000000000',
+ *   deadline: Date.now() + 3600000
+ * };
+ *
+ * const typedData = getTypedData(
+ *   params,
+ *   1,
+ *   '0x1234567890123456789012345678901234567890'
+ * );
+ *
+ * // Sign with wallet
+ * const signature = await wallet.signTypedData(typedData);
+ * ```
+ *
+ * Validates: Requirements 1.1, 14.1
+ */
+export function getTypedData(params, chainId = 1, verifyingContract = '0x0000000000000000000000000000000000000000') {
+    // Define the EIP-712 domain
+    const domain = {
+        name: 'JACK',
+        version: '1',
+        chainId,
+        verifyingContract,
+    };
+    // Define the Intent type structure
+    // This must match the on-chain struct definition
+    const types = {
+        Intent: [
+            { name: 'sourceChain', type: 'string' },
+            { name: 'destinationChain', type: 'string' },
+            { name: 'tokenIn', type: 'string' },
+            { name: 'tokenOut', type: 'string' },
+            { name: 'amountIn', type: 'string' },
+            { name: 'minAmountOut', type: 'string' },
+            { name: 'deadline', type: 'uint256' },
+        ],
+    };
+    // Construct the message from intent parameters
+    // Only include the fields defined in the Intent type
+    const message = {
+        sourceChain: params.sourceChain,
+        destinationChain: params.destinationChain,
+        tokenIn: params.tokenIn,
+        tokenOut: params.tokenOut,
+        amountIn: params.amountIn,
+        minAmountOut: params.minAmountOut,
+        deadline: params.deadline,
+    };
+    // Return the complete TypedData structure
+    return {
+        domain,
+        types,
+        message,
+        primaryType: 'Intent',
+    };
+}
+/**
+ * Serialize intent parameters to a consistent string representation
+ *
+ * This function is useful for generating cache keys, logging, or debugging.
+ * It produces a deterministic string representation of the intent parameters.
+ *
+ * @param params - Intent parameters to serialize
+ * @returns JSON string representation of the parameters
+ *
+ * @example
+ * ```typescript
+ * const params = { sourceChain: 'arbitrum', ... };
+ * const serialized = serializeIntentParams(params);
+ * console.log(serialized); // {"sourceChain":"arbitrum",...}
+ * ```
+ */
+export function serializeIntentParams(params) {
+    // Create a clean object with only the core intent fields
+    const cleanParams = {
+        sourceChain: params.sourceChain,
+        destinationChain: params.destinationChain,
+        tokenIn: params.tokenIn,
+        tokenOut: params.tokenOut,
+        amountIn: params.amountIn,
+        minAmountOut: params.minAmountOut,
+        deadline: params.deadline,
+    };
+    // Return deterministic JSON string (sorted keys)
+    return JSON.stringify(cleanParams, Object.keys(cleanParams).sort());
+}
+/**
+ * Parse a serialized intent parameters string back to IntentParams
+ *
+ * This is the inverse of serializeIntentParams(). It parses a JSON string
+ * back into an IntentParams object.
+ *
+ * @param serialized - JSON string representation of intent parameters
+ * @returns Parsed IntentParams object
+ * @throws Error if the string cannot be parsed or is missing required fields
+ *
+ * @example
+ * ```typescript
+ * const serialized = '{"sourceChain":"arbitrum",...}';
+ * const params = parseIntentParams(serialized);
+ * console.log(params.sourceChain); // 'arbitrum'
+ * ```
+ */
+export function parseIntentParams(serialized) {
+    try {
+        const parsed = JSON.parse(serialized);
+        // Validate required fields are present
+        const requiredFields = [
+            'sourceChain',
+            'destinationChain',
+            'tokenIn',
+            'tokenOut',
+            'amountIn',
+            'minAmountOut',
+            'deadline',
+        ];
+        for (const field of requiredFields) {
+            if (!(field in parsed)) {
+                throw new Error(`Missing required field: ${field}`);
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to parse intent parameters: ${error.message}`);
+        }
+        throw new Error('Failed to parse intent parameters: Unknown error');
+    }
+}
+//# sourceMappingURL=serialization.js.map

package/dist/esm/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../../src/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAoB,EACpB,UAAkB,CAAC,EACnB,oBAAmC,4CAA4C;IAE/E,4BAA4B;IAC5B,MAAM,MAAM,GAAiB;QAC3B,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,GAAG;QACZ,OAAO;QACP,iBAAiB;KAClB,CAAC;IAEF,mCAAmC;IACnC,iDAAiD;IACjD,MAAM,KAAK,GAAG;QACZ,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;YACvC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC5C,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;YACnC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;YACpC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;YACpC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;SACtC;KACF,CAAC;IAEF,+CAA+C;IAC/C,qDAAqD;IACrD,MAAM,OAAO,GAAG;QACd,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IAEF,0CAA0C;IAC1C,OAAO;QACL,MAAM;QACN,KAAK;QACL,OAAO;QACP,WAAW,EAAE,QAAQ;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAoB;IACxD,yDAAyD;IACzD,MAAM,WAAW,GAAG;QAClB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IAEF,iDAAiD;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAEtC,uCAAuC;QACvC,MAAM,cAAc,GAAG;YACrB,aAAa;YACb,kBAAkB;YAClB,SAAS;YACT,UAAU;YACV,UAAU;YACV,cAAc;YACd,UAAU;SACX,CAAC;QAEF,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QAED,OAAO,MAAsB,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,sCAAsC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/dist/esm/types.js

@@ -0,0 +1,28 @@
+/**
+ * Core TypeScript types for the JACK SDK
+ *
+ * This module exports all interfaces, types, and enums used in the public API.
+ * Requirements: 1.5, 3.4, 4.3, 5.1
+ */
+/**
+ * Execution status of an intent
+ * Requirement 1.5
+ */
+export var ExecutionStatus;
+(function (ExecutionStatus) {
+    /** Intent created but not yet quoted */
+    ExecutionStatus["CREATED"] = "CREATED";
+    /** Solver quotes received */
+    ExecutionStatus["QUOTED"] = "QUOTED";
+    /** Intent is being executed */
+    ExecutionStatus["EXECUTING"] = "EXECUTING";
+    /** Settlement transaction is being processed */
+    ExecutionStatus["SETTLING"] = "SETTLING";
+    /** Intent successfully settled on-chain */
+    ExecutionStatus["SETTLED"] = "SETTLED";
+    /** Intent execution was aborted */
+    ExecutionStatus["ABORTED"] = "ABORTED";
+    /** Intent expired before completion */
+    ExecutionStatus["EXPIRED"] = "EXPIRED";
+})(ExecutionStatus || (ExecutionStatus = {}));
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH;;;GAGG;AACH,MAAM,CAAN,IAAY,eAeX;AAfD,WAAY,eAAe;IACzB,wCAAwC;IACxC,sCAAmB,CAAA;IACnB,6BAA6B;IAC7B,oCAAiB,CAAA;IACjB,+BAA+B;IAC/B,0CAAuB,CAAA;IACvB,gDAAgD;IAChD,wCAAqB,CAAA;IACrB,2CAA2C;IAC3C,sCAAmB,CAAA;IACnB,mCAAmC;IACnC,sCAAmB,CAAA;IACnB,uCAAuC;IACvC,sCAAmB,CAAA;AACrB,CAAC,EAfW,eAAe,KAAf,eAAe,QAe1B"}

package/dist/esm/validation.js

@@ -0,0 +1,111 @@
+/**
+ * Input validation helpers for the JACK SDK
+ *
+ * This module provides validation functions for intent parameters and other inputs.
+ * Requirements: 5.4, 8.5
+ */
+/**
+ * Validates that a string is a valid Ethereum address format
+ * @param address - The address string to validate
+ * @returns true if the address is valid, false otherwise
+ */
+function isValidAddress(address) {
+    // Check if it's a valid hex string starting with 0x and has 40 hex characters
+    return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+/**
+ * Validates that a string represents a positive number
+ * @param value - The string value to validate
+ * @returns true if the value is a positive number, false otherwise
+ */
+function isPositiveAmount(value) {
+    try {
+        const num = BigInt(value);
+        return num > 0n;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates intent parameters before submission
+ *
+ * This function checks:
+ * - All required fields are present and non-empty
+ * - Amounts (amountIn, minAmountOut) are positive numbers
+ * - Deadline is in the future
+ * - Token addresses are valid Ethereum address format
+ *
+ * @param params - The intent parameters to validate
+ * @returns ValidationResult with valid flag and array of error messages
+ *
+ * @example
+ * ```typescript
+ * const result = validateIntentParams({
+ *   sourceChain: 'arbitrum',
+ *   destinationChain: 'base',
+ *   tokenIn: '0x...',
+ *   tokenOut: '0x...',
+ *   amountIn: '1000000',
+ *   minAmountOut: '950000',
+ *   deadline: Date.now() + 3600000
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ *
+ * **Validates: Requirements 5.4, 8.5**
+ */
+export function validateIntentParams(params) {
+    const errors = [];
+    // Validate required fields are present and non-empty
+    if (!params.sourceChain || params.sourceChain.trim() === '') {
+        errors.push('sourceChain is required and must not be empty');
+    }
+    if (!params.destinationChain || params.destinationChain.trim() === '') {
+        errors.push('destinationChain is required and must not be empty');
+    }
+    if (!params.tokenIn || params.tokenIn.trim() === '') {
+        errors.push('tokenIn is required and must not be empty');
+    }
+    if (!params.tokenOut || params.tokenOut.trim() === '') {
+        errors.push('tokenOut is required and must not be empty');
+    }
+    if (!params.amountIn || params.amountIn.trim() === '') {
+        errors.push('amountIn is required and must not be empty');
+    }
+    if (!params.minAmountOut || params.minAmountOut.trim() === '') {
+        errors.push('minAmountOut is required and must not be empty');
+    }
+    if (params.deadline === undefined || params.deadline === null) {
+        errors.push('deadline is required');
+    }
+    // Validate amounts are positive
+    if (params.amountIn && !isPositiveAmount(params.amountIn)) {
+        errors.push('amountIn must be a positive number');
+    }
+    if (params.minAmountOut && !isPositiveAmount(params.minAmountOut)) {
+        errors.push('minAmountOut must be a positive number');
+    }
+    // Validate deadline is in the future
+    if (typeof params.deadline === 'number') {
+        const now = Date.now();
+        if (params.deadline <= now) {
+            errors.push('deadline must be in the future');
+        }
+    }
+    // Validate addresses are valid format
+    if (params.tokenIn && !isValidAddress(params.tokenIn)) {
+        errors.push('tokenIn must be a valid Ethereum address (0x followed by 40 hex characters)');
+    }
+    if (params.tokenOut && !isValidAddress(params.tokenOut)) {
+        errors.push('tokenOut must be a valid Ethereum address (0x followed by 40 hex characters)');
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/esm/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/types/agent.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Agent utilities for the JACK SDK
+ *
+ * This module provides the AgentUtils class with high-level abstractions
+ * for batch operations, dry-run validation, policy enforcement, and
+ * event subscriptions for automated agent systems.
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
+ */
+import type { IntentParams, Intent, BatchSubmitResult, DryRunResult, ValidationResult, Policy, Subscription, PollOptions } from './types.js';
+import type { JackClient } from './client.js';
+/**
+ * Utilities for agent-based intent orchestration
+ *
+ * Provides batch operations, dry-run validation, policy enforcement,
+ * and multi-intent subscriptions for automated systems.
+ *
+ * @example
+ * ```typescript
+ * const client = new JackClient({ baseUrl: 'https://api.jack.example' });
+ * const agent = new AgentUtils(client);
+ *
+ * // Batch submit multiple intents
+ * const results = await agent.batchSubmit([
+ *   { params: intent1, signature: sig1 },
+ *   { params: intent2, signature: sig2 }
+ * ]);
+ *
+ * results.forEach(result => {
+ *   if (result.success) {
+ *     console.log('Submitted:', result.intentId);
+ *   } else {
+ *     console.error('Failed:', result.error);
+ *   }
+ * });
+ * ```
+ */
+export declare class AgentUtils {
+    private readonly client;
+    private readonly intentManager;
+    private readonly executionTracker;
+    /**
+     * Creates a new AgentUtils instance
+     *
+     * @param client - The JackClient instance to use for API requests
+     */
+    constructor(client: JackClient);
+    /**
+     * Submit multiple intents in parallel
+     *
+     * Uses Promise.allSettled() to submit all intents concurrently,
+     * ensuring that failures in individual submissions don't affect others.
+     * The result array length always matches the input array length,
+     * with each result corresponding to the same index in the input.
+     *
+     * @param intents - Array of intent parameters and signatures to submit
+     * @returns Promise resolving to array of BatchSubmitResult objects
+     *
+     * @example
+     * ```typescript
+     * const results = await agent.batchSubmit([
+     *   { params: intent1, signature: sig1 },
+     *   { params: intent2, signature: sig2 },
+     *   { params: intent3, signature: sig3 }
+     * ]);
+     *
+     * // Results array has same length as input
+     * console.log(results.length); // 3
+     *
+     * // Check individual results
+     * results.forEach((result, index) => {
+     *   if (result.success) {
+     *     console.log(`Intent ${index} submitted: ${result.intentId}`);
+     *   } else {
+     *     console.error(`Intent ${index} failed:`, result.error?.message);
+     *   }
+     * });
+     *
+     * // Count successes and failures
+     * const successes = results.filter(r => r.success).length;
+     * const failures = results.filter(r => !r.success).length;
+     * console.log(`${successes} succeeded, ${failures} failed`);
+     * ```
+     *
+     * **Validates: Requirements 8.1, 8.2**
+     */
+    batchSubmit(intents: Array<{
+        params: IntentParams;
+        signature: string;
+    }>): Promise<BatchSubmitResult[]>;
+    /**
+     * Simulate intent execution without submission
+     *
+     * Validates intent parameters and estimates costs without actually
+     * submitting the intent to the API. Useful for testing and validation.
+     *
+     * @param params - Intent parameters to validate
+     * @returns Promise resolving to DryRunResult with validation status
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.dryRun(params);
+     * if (result.valid) {
+     *   console.log('Estimated cost:', result.estimatedCost);
+     * } else {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * ```
+     *
+     * **Validates: Requirement 8.4**
+     */
+    dryRun(params: IntentParams): Promise<DryRunResult>;
+    /**
+     * Validate intent parameters against policy rules
+     *
+     * Checks that intent parameters comply with the specified policy,
+     * including amount limits, allowed chains, tokens, and deadline constraints.
+     *
+     * @param params - Intent parameters to validate
+     * @param policy - Policy rules to enforce
+     * @returns ValidationResult with valid flag and error messages
+     *
+     * @example
+     * ```typescript
+     * const policy: Policy = {
+     *   maxAmountIn: '1000000000',
+     *   allowedSourceChains: ['arbitrum', 'optimism'],
+     *   allowedDestinationChains: ['base', 'ethereum'],
+     *   maxDeadlineOffset: 3600000 // 1 hour
+     * };
+     *
+     * const result = agent.validatePolicy(params, policy);
+     * if (!result.valid) {
+     *   console.error('Policy violations:', result.errors);
+     * }
+     * ```
+     *
+     * **Validates: Requirement 8.5**
+     */
+    validatePolicy(params: IntentParams, policy: Policy): ValidationResult;
+    /**
+     * Subscribe to status changes for multiple intents
+     *
+     * Polls multiple intents in parallel and invokes the callback whenever
+     * any intent's status changes. Returns a Subscription object that can
+     * be used to unsubscribe and stop polling.
+     *
+     * @param intentIds - Array of intent IDs to monitor
+     * @param callback - Function to call when any intent status changes
+     * @param options - Polling options (interval, timeout)
+     * @returns Subscription object with unsubscribe() method
+     *
+     * @example
+     * ```typescript
+     * const subscription = agent.subscribeToUpdates(
+     *   ['JK-ABC123456', 'JK-DEF789012'],
+     *   (intentId, intent) => {
+     *     console.log(`${intentId} status changed to ${intent.status}`);
+     *   },
+     *   { interval: 5000 }
+     * );
+     *
+     * // Later, stop polling
+     * subscription.unsubscribe();
+     * ```
+     *
+     * **Validates: Requirement 8.3**
+     */
+    subscribeToUpdates(intentIds: string[], callback: (intentId: string, intent: Intent) => void, options?: PollOptions): Subscription;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,WAAW,CACf,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1D,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA2B/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBzD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAgEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,EACpD,OAAO,CAAC,EAAE,WAAW,GACpB,YAAY;CA2DhB"}