@jack-kernel/sdk 1.0.0

package/dist/types/types.d.ts

@@ -0,0 +1,302 @@
+/**
+ * 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
+ */
+/**
+ * Parameters required to create an intent
+ * Requirement 1.5
+ */
+export interface IntentParams {
+    /** Source blockchain identifier (e.g., 'arbitrum', 'ethereum') */
+    sourceChain: string;
+    /** Destination blockchain identifier (e.g., 'base', 'optimism') */
+    destinationChain: string;
+    /** Address of the input token on the source chain */
+    tokenIn: string;
+    /** Address of the output token on the destination chain */
+    tokenOut: string;
+    /** Amount of input token (in smallest unit, e.g., wei) */
+    amountIn: string;
+    /** Minimum acceptable amount of output token */
+    minAmountOut: string;
+    /** Unix timestamp (milliseconds) after which the intent expires */
+    deadline: number;
+    /** Allow additional properties for extensibility */
+    [key: string]: string | number;
+}
+/**
+ * Execution status of an intent
+ * Requirement 1.5
+ */
+export declare enum ExecutionStatus {
+    /** Intent created but not yet quoted */
+    CREATED = "CREATED",
+    /** Solver quotes received */
+    QUOTED = "QUOTED",
+    /** Intent is being executed */
+    EXECUTING = "EXECUTING",
+    /** Settlement transaction is being processed */
+    SETTLING = "SETTLING",
+    /** Intent successfully settled on-chain */
+    SETTLED = "SETTLED",
+    /** Intent execution was aborted */
+    ABORTED = "ABORTED",
+    /** Intent expired before completion */
+    EXPIRED = "EXPIRED"
+}
+/**
+ * A discrete step in the intent execution lifecycle
+ * Requirement 1.5
+ */
+export interface ExecutionStep {
+    /** Name of the execution step (e.g., 'signing', 'quoting', 'routing') */
+    step: string;
+    /** Current status of this step */
+    status: 'COMPLETED' | 'IN_PROGRESS' | 'PENDING' | 'FAILED';
+    /** Unix timestamp (milliseconds) when this step was updated */
+    timestamp: number;
+    /** Optional additional details about the step */
+    details?: string;
+}
+/**
+ * Complete intent object with execution state
+ * Requirement 1.5
+ */
+export interface Intent {
+    /** Unique intent identifier (format: JK-[A-Z0-9]{9}) */
+    id: string;
+    /** Intent parameters */
+    params: IntentParams;
+    /** EIP-712 signature (if signed) */
+    signature?: string;
+    /** Current execution status */
+    status: ExecutionStatus;
+    /** Unix timestamp (milliseconds) when intent was created */
+    createdAt: number;
+    /** Array of execution steps with their statuses */
+    executionSteps: ExecutionStep[];
+    /** Settlement transaction hash (if settled) */
+    settlementTx?: string;
+}
+/**
+ * A step in the execution route
+ * Requirement 3.4
+ */
+export interface RouteStep {
+    /** Blockchain where this step executes */
+    chain: string;
+    /** Protocol used for this step (e.g., 'uniswap', 'stargate') */
+    protocol: string;
+    /** Action performed (e.g., 'swap', 'bridge') */
+    action: string;
+}
+/**
+ * A solver's quote for executing an intent
+ * Requirement 3.4
+ */
+export interface Quote {
+    /** Unique identifier of the solver */
+    solverId: string;
+    /** Human-readable name of the solver */
+    solverName: string;
+    /** Total fee charged by the solver (in output token units) */
+    totalFee: string;
+    /** Estimated execution time in seconds */
+    estimatedTime: number;
+    /** Detailed execution route */
+    route: RouteStep[];
+}
+/**
+ * A single cost entry
+ * Requirement 4.3
+ */
+export interface CostEntry {
+    /** Cost amount */
+    cost: number;
+}
+/**
+ * Cost tracking for a specific issue
+ * Requirement 4.3
+ */
+export interface IssueCost {
+    /** Issue identifier */
+    issueId: string;
+    /** Total cost accumulated for this issue */
+    totalCost: number;
+    /** Budget allocated for this issue */
+    budget: number;
+    /** Whether the issue has exceeded its budget */
+    overBudget: boolean;
+}
+/**
+ * Response from the costs API endpoint
+ * Requirement 4.3
+ */
+export interface CostsResponse {
+    /** Array of cost data per issue */
+    issueCosts: IssueCost[];
+}
+/**
+ * Configuration options for the JACK SDK client
+ * Requirement 5.1
+ */
+export interface ClientConfig {
+    /** Base URL for the JACK API (e.g., 'https://api.jack.example') */
+    baseUrl: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Backoff multiplier for exponential retry delay (default: 2) */
+    retryBackoff?: number;
+    /** Enable response caching for GET requests (default: false) */
+    enableCache?: boolean;
+    /** Cache time-to-live in milliseconds (default: 60000) */
+    cacheTTL?: number;
+    /** Custom HTTP headers to include in all requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for individual HTTP requests
+ * Requirement 5.1
+ */
+export interface RequestOptions {
+    /** Override the default timeout for this request */
+    timeout?: number;
+    /** Disable retries for this request */
+    noRetry?: boolean;
+    /** Disable caching for this request */
+    noCache?: boolean;
+    /** Skip cache for this request (alias for noCache) */
+    skipCache?: boolean;
+    /** Query parameters for the request */
+    params?: Record<string, unknown>;
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for polling operations
+ * Requirement 5.1
+ */
+export interface PollOptions {
+    /** Polling interval in milliseconds (default: 2000) */
+    interval?: number;
+    /** Maximum time to poll in milliseconds (default: 60000) */
+    timeout?: number;
+    /** Stop polling when any of these statuses are reached */
+    stopStatuses?: ExecutionStatus[];
+}
+/**
+ * Result of a single intent submission in a batch operation
+ * Requirement 5.1
+ */
+export interface BatchSubmitResult {
+    /** Intent ID if submission succeeded */
+    intentId: string;
+    /** Whether the submission was successful */
+    success: boolean;
+    /** Error object if submission failed */
+    error?: Error;
+}
+/**
+ * Result of a dry-run validation
+ * Requirement 5.1
+ */
+export interface DryRunResult {
+    /** Whether the intent parameters are valid */
+    valid: boolean;
+    /** Estimated cost if validation succeeded */
+    estimatedCost?: string;
+    /** Array of validation error messages */
+    errors?: string[];
+}
+/**
+ * Result of intent parameter validation
+ * Requirement 5.1
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+}
+/**
+ * EIP-712 domain separator
+ * Requirement 5.1
+ */
+export interface EIP712Domain {
+    /** Protocol name */
+    name: string;
+    /** Protocol version */
+    version: string;
+    /** Chain ID where the contract is deployed */
+    chainId: number;
+    /** Address of the verifying contract */
+    verifyingContract: `0x${string}`;
+}
+/**
+ * Complete EIP-712 typed data structure
+ * Requirement 5.1
+ */
+export interface TypedData {
+    /** Domain separator */
+    domain: EIP712Domain;
+    /** Type definitions */
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    /** Message data to be signed */
+    message: Record<string, unknown>;
+    /** Primary type being signed */
+    primaryType: string;
+}
+/**
+ * Subscription handle for event-based updates
+ * Requirement 5.1
+ */
+export interface Subscription {
+    /** Unsubscribe from updates and stop polling */
+    unsubscribe(): void;
+}
+/**
+ * Watcher for continuous intent status updates
+ * Requirement 5.1
+ */
+export interface ExecutionWatcher extends Subscription {
+    /** Intent ID being watched */
+    intentId: string;
+    /** Register callback for status updates */
+    onUpdate(callback: (intent: Intent) => void): void;
+    /** Register callback for errors */
+    onError(callback: (error: Error) => void): void;
+    /** Register callback for completion (SETTLED, ABORTED, or EXPIRED) */
+    onComplete(callback: (intent: Intent) => void): void;
+    /** Stop watching and clean up resources */
+    stop(): void;
+}
+/**
+ * Policy rules for intent validation
+ * Requirement 5.1
+ */
+export interface Policy {
+    /** Maximum allowed amount in (in smallest unit) */
+    maxAmountIn?: string;
+    /** Minimum allowed amount out (in smallest unit) */
+    minAmountOut?: string;
+    /** Allowed source chains */
+    allowedSourceChains?: string[];
+    /** Allowed destination chains */
+    allowedDestinationChains?: string[];
+    /** Allowed input tokens */
+    allowedTokensIn?: string[];
+    /** Allowed output tokens */
+    allowedTokensOut?: string[];
+    /** Maximum deadline offset in milliseconds */
+    maxDeadlineOffset?: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/types/validation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Input validation helpers for the JACK SDK
+ *
+ * This module provides validation functions for intent parameters and other inputs.
+ * Requirements: 5.4, 8.5
+ */
+import type { IntentParams, ValidationResult } from './types.js';
+/**
+ * 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 declare function validateIntentParams(params: IntentParams): ValidationResult;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA0BjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CA8D3E"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@jack-kernel/sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for JACK cross-chain execution kernel",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "jack",
+    "cross-chain",
+    "intent",
+    "blockchain",
+    "sdk"
+  ],
+  "author": "JACK Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/jack.git",
+    "directory": "packages/sdk"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@fast-check/vitest": "^0.2.4",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "fast-check": "^3.23.2",
+    "msw": "^2.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:esm && pnpm run build:cjs && pnpm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/**/*.ts"
+  }
+}