@jack-kernel/sdk 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,205 @@
+export type { IntentParams, Intent, ExecutionStep, Quote, RouteStep, CostEntry, IssueCost, CostsResponse, ClientConfig, RequestOptions, PollOptions, BatchSubmitResult, DryRunResult, ValidationResult, EIP712Domain, TypedData, Subscription, ExecutionWatcher, Policy } from './types.js';
+export { ExecutionStatus } from './types.js';
+export { JackError, NetworkError, APIError, ValidationError, TimeoutError, RetryError } from './errors.js';
+export { getTypedData, serializeIntentParams, parseIntentParams } from './serialization.js';
+export { validateIntentParams } from './validation.js';
+export { IntentManager } from './intents.js';
+export { ExecutionTracker } from './execution.js';
+export { CostTracker } from './costs.js';
+export { AgentUtils } from './agent.js';
+export { JackClient } from './client.js';
+import { IntentManager } from './intents.js';
+import { ExecutionTracker } from './execution.js';
+import { CostTracker } from './costs.js';
+import { AgentUtils } from './agent.js';
+import { type ClientConfig, type IntentParams, type Intent } from './types.js';
+/**
+ * Main SDK class for JACK cross-chain execution kernel
+ *
+ * Provides a comprehensive, type-safe interface for interacting with the JACK system.
+ * Initializes all managers (intents, execution, costs, agent) and exposes them as
+ * public readonly properties. Also provides convenience methods for common operations.
+ *
+ * @example
+ * ```typescript
+ * // Initialize SDK
+ * const sdk = new JACK_SDK({ baseUrl: 'https://api.jack.example' });
+ *
+ * // Create and submit intent
+ * const typedData = sdk.intents.getTypedData(params);
+ * const signature = await wallet.signTypedData(typedData);
+ * const intentId = await sdk.submitIntent(params, signature);
+ *
+ * // Track execution
+ * const intent = await sdk.waitForSettlement(intentId);
+ * console.log('Settlement tx:', intent.settlementTx);
+ *
+ * // Access managers directly
+ * const costs = await sdk.costs.getCosts();
+ * const results = await sdk.agent.batchSubmit([...]);
+ * ```
+ *
+ * **Validates: Requirements 1.1, 1.2, 1.3, 1.4, 2.5**
+ */
+export declare class JACK_SDK {
+    /**
+     * Intent management - create, submit, query intents
+     */
+    readonly intents: IntentManager;
+    /**
+     * Execution tracking - poll status, wait for completion
+     */
+    readonly execution: ExecutionTracker;
+    /**
+     * Cost tracking - query costs and budgets
+     */
+    readonly costs: CostTracker;
+    /**
+     * Agent utilities - batch operations, subscriptions
+     */
+    readonly agent: AgentUtils;
+    /**
+     * Internal HTTP client (exposed for advanced use cases)
+     */
+    private readonly client;
+    /**
+     * Creates a new JACK_SDK instance
+     *
+     * Initializes all managers with the provided configuration. The configuration
+     * includes the base URL for the API and optional settings for timeout, retries,
+     * caching, and custom headers.
+     *
+     * @param config - Client configuration (baseUrl required, other options optional)
+     * @throws ValidationError if configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const sdk = new JACK_SDK({ baseUrl: 'https://api.jack.example' });
+     *
+     * // With custom configuration
+     * const sdk = new JACK_SDK({
+     *   baseUrl: 'https://api.jack.example',
+     *   timeout: 60000,
+     *   maxRetries: 5,
+     *   enableCache: true,
+     *   cacheTTL: 120000,
+     *   headers: { 'Authorization': 'Bearer token' }
+     * });
+     * ```
+     */
+    constructor(config: ClientConfig);
+    /**
+     * Convenience method: Submit a signed intent
+     *
+     * Delegates to IntentManager.submit(). This is a convenience method
+     * for the most common operation - submitting a signed intent.
+     *
+     * @param params - Intent parameters
+     * @param signature - EIP-712 signature from wallet
+     * @returns Promise resolving to the intent ID
+     * @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 sdk.submitIntent(params, signature);
+     * console.log('Intent submitted:', intentId);
+     * ```
+     *
+     * **Validates: Requirement 1.2**
+     */
+    submitIntent(params: IntentParams, signature: string): Promise<string>;
+    /**
+     * Convenience method: Get a single intent by ID
+     *
+     * Delegates to IntentManager.get(). This is a convenience method
+     * for querying a single intent's current state.
+     *
+     * @param intentId - The intent ID to query
+     * @returns Promise resolving to the complete Intent object
+     * @throws APIError if the intent is not found or other API error
+     * @throws NetworkError if the network request fails
+     *
+     * @example
+     * ```typescript
+     * const intent = await sdk.getIntent('JK-ABC123456');
+     * console.log('Status:', intent.status);
+     * ```
+     *
+     * **Validates: Requirement 1.3**
+     */
+    getIntent(intentId: string): Promise<Intent>;
+    /**
+     * Convenience method: List all intents
+     *
+     * Delegates to IntentManager.list(). This is a convenience method
+     * for retrieving 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 sdk.listIntents();
+     * console.log(`Found ${intents.length} intents`);
+     * ```
+     *
+     * **Validates: Requirement 1.4**
+     */
+    listIntents(): Promise<Intent[]>;
+    /**
+     * Convenience method: Wait for intent to settle
+     *
+     * Polls the intent status until it reaches SETTLED status or the timeout
+     * is exceeded. This is a convenience method that wraps ExecutionTracker.waitForStatus()
+     * with sensible defaults for waiting for settlement.
+     *
+     * @param intentId - The intent ID to wait for
+     * @param timeout - Maximum time to wait in milliseconds (default: 120000 = 2 minutes)
+     * @returns Promise resolving to the Intent when settled
+     * @throws TimeoutError if timeout is exceeded before settlement
+     * @throws APIError if the API returns an error
+     * @throws NetworkError if the network request fails
+     *
+     * @example
+     * ```typescript
+     * // Wait with default timeout (2 minutes)
+     * const intent = await sdk.waitForSettlement('JK-ABC123456');
+     * console.log('Settlement tx:', intent.settlementTx);
+     *
+     * // Wait with custom timeout (5 minutes)
+     * const intent = await sdk.waitForSettlement('JK-ABC123456', 300000);
+     * ```
+     *
+     * **Validates: Requirement 2.5**
+     */
+    waitForSettlement(intentId: string, timeout?: number): Promise<Intent>;
+    /**
+     * Legacy method: Get execution status
+     *
+     * @deprecated Use sdk.getIntent() or sdk.execution.getStatus() instead
+     *
+     * This method is kept for backward compatibility with existing dashboard code.
+     * It delegates to the execution tracker's getStatus method.
+     *
+     * @param intentId - The intent ID to query
+     * @returns Promise resolving to the Intent object
+     */
+    getExecutionStatus(intentId: string): Promise<Intent>;
+    /**
+     * Legacy method: Get intent typed data
+     *
+     * @deprecated Use sdk.intents.getTypedData() instead
+     *
+     * This method is kept for backward compatibility with existing dashboard code.
+     * It delegates to the intent manager's getTypedData method.
+     *
+     * @param params - Intent parameters
+     * @returns EIP-712 TypedData object
+     */
+    getIntentTypedData(params: IntentParams): import("./types.js").TypedData;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAEV,YAAY,EACZ,MAAM,EACN,aAAa,EAEb,KAAK,EACL,SAAS,EAET,SAAS,EACT,SAAS,EACT,aAAa,EAEb,YAAY,EACZ,cAAc,EACd,WAAW,EAEX,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAEhB,YAAY,EACZ,SAAS,EAET,YAAY,EACZ,gBAAgB,EAEhB,MAAM,EACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,UAAU,EACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAmB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAQ;IACnB;;OAEG;IACH,SAAgB,OAAO,EAAE,aAAa,CAAC;IAEvC;;OAEG;IACH,SAAgB,SAAS,EAAE,gBAAgB,CAAC;IAE5C;;OAEG;IACH,SAAgB,KAAK,EAAE,WAAW,CAAC;IAEnC;;OAEG;IACH,SAAgB,KAAK,EAAE,UAAU,CAAC;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;gBACS,MAAM,EAAE,YAAY;IAWhC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5E;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlD;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAQpF;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3D;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,MAAM,EAAE,YAAY;CAGxC"}

package/dist/types/intents.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 type { IntentParams, Intent, TypedData, ValidationResult } from './types.js';
+import type { JackClient } from './client.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 declare class IntentManager {
+    private readonly client;
+    /**
+     * Creates a new IntentManager
+     *
+     * @param client - The JackClient instance to use for API requests
+     */
+    constructor(client: JackClient);
+    /**
+     * 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: IntentParams, chainId?: number, verifyingContract?: `0x${string}`): TypedData;
+    /**
+     * 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: IntentParams): ValidationResult;
+    /**
+     * 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**
+     */
+    submit(params: IntentParams, signature: string): Promise<string>;
+    /**
+     * 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**
+     */
+    get(intentId: string): Promise<Intent>;
+    /**
+     * 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**
+     */
+    list(): Promise<Intent[]>;
+}
+//# sourceMappingURL=intents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../../src/intents.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CACV,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,MAAU,EACnB,iBAAiB,GAAE,KAAK,MAAM,EAAiD,GAC9E,SAAS;IAIZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IAIhD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBtE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAGhC"}

package/dist/types/serialization.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+import type { IntentParams, TypedData } from './types.js';
+/**
+ * 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 declare function getTypedData(params: IntentParams, chainId?: number, verifyingContract?: `0x${string}`): TypedData;
+/**
+ * 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 declare function serializeIntentParams(params: IntentParams): string;
+/**
+ * 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 declare function parseIntentParams(serialized: string): IntentParams;
+//# sourceMappingURL=serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAgB,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,MAAU,EACnB,iBAAiB,GAAE,KAAK,MAAM,EAAiD,GAC9E,SAAS,CA0CX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAclE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CA4BlE"}