@jack-kernel/sdk 1.0.0

package/dist/esm/costs.js

@@ -0,0 +1,100 @@
+/**
+ * Cost tracking module for JACK SDK
+ *
+ * Provides methods to query execution costs and budgets.
+ * Validates Requirements 4.1, 4.2
+ */
+/**
+ * CostTracker class for querying execution costs and budgets
+ *
+ * @example
+ * ```typescript
+ * const tracker = new CostTracker(client);
+ * const costs = await tracker.getCosts();
+ * const issueCost = await tracker.getIssueCost('ISSUE-123');
+ * const overBudget = await tracker.getOverBudgetIssues();
+ * ```
+ */
+export class CostTracker {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get all issue costs from the API
+     *
+     * Makes a GET request to /api/costs and returns the complete response
+     * with cost data for all issues.
+     *
+     * @returns Promise resolving to CostsResponse with all issue costs
+     * @throws {APIError} If the API request fails
+     * @throws {NetworkError} If network connection fails
+     *
+     * @example
+     * ```typescript
+     * const costs = await tracker.getCosts();
+     * console.log(`Found ${costs.issueCosts.length} issues`);
+     * ```
+     *
+     * Validates Requirement 4.1
+     */
+    async getCosts() {
+        return this.client.get('/api/costs');
+    }
+    /**
+     * Get costs for a specific issue
+     *
+     * Fetches all costs and filters by the specified issue ID.
+     * Returns null if the issue is not found.
+     *
+     * @param issueId - The issue identifier to filter by
+     * @returns Promise resolving to IssueCost or null if not found
+     * @throws {APIError} If the API request fails
+     * @throws {NetworkError} If network connection fails
+     *
+     * @example
+     * ```typescript
+     * const issueCost = await tracker.getIssueCost('ISSUE-123');
+     * if (issueCost) {
+     *   console.log(`Total cost: ${issueCost.totalCost}`);
+     *   console.log(`Budget: ${issueCost.budget}`);
+     *   console.log(`Over budget: ${issueCost.overBudget}`);
+     * }
+     * ```
+     *
+     * Validates Requirement 4.2
+     */
+    async getIssueCost(issueId) {
+        const response = await this.getCosts();
+        const issueCost = response.issueCosts.find((cost) => cost.issueId === issueId);
+        return issueCost ?? null;
+    }
+    /**
+     * Get all issues that are over budget
+     *
+     * Fetches all costs and filters to only those with overBudget flag set to true.
+     * Returns an empty array if no issues are over budget.
+     *
+     * @returns Promise resolving to array of IssueCost objects that are over budget
+     * @throws {APIError} If the API request fails
+     * @throws {NetworkError} If network connection fails
+     *
+     * @example
+     * ```typescript
+     * const overBudget = await tracker.getOverBudgetIssues();
+     * if (overBudget.length > 0) {
+     *   console.log(`Warning: ${overBudget.length} issues are over budget`);
+     *   overBudget.forEach(issue => {
+     *     console.log(`${issue.issueId}: ${issue.totalCost} / ${issue.budget}`);
+     *   });
+     * }
+     * ```
+     *
+     * Validates Requirement 4.2
+     */
+    async getOverBudgetIssues() {
+        const response = await this.getCosts();
+        return response.issueCosts.filter((cost) => cost.overBudget);
+    }
+}
+//# sourceMappingURL=costs.js.map

package/dist/esm/costs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.js","sourceRoot":"","sources":["../../src/costs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAgB,YAAY,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CACxC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,CACnC,CAAC;QACF,OAAO,SAAS,IAAI,IAAI,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,mBAAmB;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACvC,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/esm/errors.js

@@ -0,0 +1,278 @@
+/**
+ * Error hierarchy for the JACK SDK
+ *
+ * This module defines custom error classes for different failure scenarios.
+ * All errors extend the base JackError class and include context for debugging.
+ * Requirements: 5.2, 5.3
+ */
+/**
+ * Base error class for all JACK SDK errors
+ *
+ * Extends the native Error class and adds optional context for debugging.
+ * All SDK-specific errors inherit from this class.
+ *
+ * @example
+ * ```typescript
+ * throw new JackError('Something went wrong', { requestId: '123', timestamp: Date.now() });
+ * ```
+ *
+ * Requirement 5.2
+ */
+export class JackError extends Error {
+    /**
+     * Additional context information for debugging
+     * Can include request details, timestamps, or any relevant metadata
+     */
+    context;
+    /**
+     * Creates a new JackError
+     *
+     * @param message - Human-readable error message
+     * @param context - Optional context object with debugging information
+     */
+    constructor(message, context) {
+        super(message);
+        this.name = 'JackError';
+        this.context = context;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when network-level failures occur
+ *
+ * This includes connection failures, DNS resolution errors, timeouts at the
+ * network layer, and other transport-level issues. The original error is
+ * preserved for detailed debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch('https://api.jack.example');
+ * } catch (err) {
+ *   throw new NetworkError('Failed to connect to API', err as Error);
+ * }
+ * ```
+ *
+ * Requirement 5.3
+ */
+export class NetworkError extends JackError {
+    /**
+     * The original error that caused the network failure
+     * Preserved for detailed debugging and error analysis
+     */
+    originalError;
+    /**
+     * Creates a new NetworkError
+     *
+     * @param message - Human-readable error message
+     * @param originalError - The underlying error that caused the network failure
+     * @param context - Optional additional context
+     */
+    constructor(message, originalError, context) {
+        super(message, context);
+        this.name = 'NetworkError';
+        this.originalError = originalError;
+    }
+}
+/**
+ * Error thrown when the API returns an error response
+ *
+ * This includes 4xx client errors (bad request, not found, unauthorized) and
+ * 5xx server errors (internal server error, service unavailable). The HTTP
+ * status code and response body are included for debugging.
+ *
+ * @example
+ * ```typescript
+ * if (response.status >= 400) {
+ *   throw new APIError(
+ *     'Intent not found',
+ *     404,
+ *     { error: 'Intent with ID JK-ABC123456 does not exist' }
+ *   );
+ * }
+ * ```
+ *
+ * Requirement 5.3
+ */
+export class APIError extends JackError {
+    /**
+     * HTTP status code from the API response
+     * Used to distinguish between client errors (4xx) and server errors (5xx)
+     */
+    statusCode;
+    /**
+     * The parsed response body from the API
+     * May contain error details, validation messages, or other diagnostic information
+     */
+    response;
+    /**
+     * Creates a new APIError
+     *
+     * @param message - Human-readable error message
+     * @param statusCode - HTTP status code from the response
+     * @param response - Optional parsed response body
+     * @param context - Optional additional context
+     */
+    constructor(message, statusCode, response, context) {
+        super(message, context);
+        this.name = 'APIError';
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+    /**
+     * Check if this is a client error (4xx status code)
+     * @returns true if status code is in the 400-499 range
+     */
+    isClientError() {
+        return this.statusCode >= 400 && this.statusCode < 500;
+    }
+    /**
+     * Check if this is a server error (5xx status code)
+     * @returns true if status code is in the 500-599 range
+     */
+    isServerError() {
+        return this.statusCode >= 500 && this.statusCode < 600;
+    }
+    /**
+     * Check if this error is retryable
+     * Server errors (5xx) are typically retryable, client errors (4xx) are not
+     * @returns true if the error should be retried
+     */
+    isRetryable() {
+        return this.isServerError();
+    }
+}
+/**
+ * Error thrown when client-side validation fails
+ *
+ * This error is thrown before making any network requests when input parameters
+ * fail validation checks. It includes an array of specific validation errors
+ * to help developers identify and fix issues.
+ *
+ * @example
+ * ```typescript
+ * const errors = [];
+ * if (params.amountIn <= 0) errors.push('amountIn must be positive');
+ * if (params.deadline < Date.now()) errors.push('deadline must be in the future');
+ * if (errors.length > 0) {
+ *   throw new ValidationError('Invalid intent parameters', errors);
+ * }
+ * ```
+ *
+ * Requirement 5.3
+ */
+export class ValidationError extends JackError {
+    /**
+     * Array of specific validation error messages
+     * Each message describes a single validation failure
+     */
+    errors;
+    /**
+     * Creates a new ValidationError
+     *
+     * @param message - Human-readable error message
+     * @param errors - Array of specific validation error messages
+     * @param context - Optional additional context
+     */
+    constructor(message, errors, context) {
+        super(message, context);
+        this.name = 'ValidationError';
+        this.errors = errors;
+    }
+}
+/**
+ * Error thrown when an operation exceeds its timeout
+ *
+ * This includes request timeouts, polling timeouts, and any other time-bound
+ * operations. The timeout duration is included for debugging.
+ *
+ * @example
+ * ```typescript
+ * const timeout = 30000; // 30 seconds
+ * const timeoutPromise = new Promise((_, reject) => {
+ *   setTimeout(() => {
+ *     reject(new TimeoutError('Request timed out', timeout));
+ *   }, timeout);
+ * });
+ * await Promise.race([fetchPromise, timeoutPromise]);
+ * ```
+ *
+ * Requirement 5.3
+ */
+export class TimeoutError extends JackError {
+    /**
+     * The timeout duration in milliseconds
+     * Indicates how long the operation was allowed to run before timing out
+     */
+    timeoutMs;
+    /**
+     * Creates a new TimeoutError
+     *
+     * @param message - Human-readable error message
+     * @param timeoutMs - The timeout duration in milliseconds
+     * @param context - Optional additional context
+     */
+    constructor(message, timeoutMs, context) {
+        super(message, context);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Error thrown when retry attempts are exhausted
+ *
+ * This error is thrown after all retry attempts have failed. It includes the
+ * number of attempts made and the final error that caused the failure.
+ *
+ * @example
+ * ```typescript
+ * let lastError: Error;
+ * for (let attempt = 1; attempt <= maxRetries; attempt++) {
+ *   try {
+ *     return await makeRequest();
+ *   } catch (err) {
+ *     lastError = err as Error;
+ *     if (attempt === maxRetries) {
+ *       throw new RetryError(
+ *         'All retry attempts exhausted',
+ *         attempt,
+ *         lastError
+ *       );
+ *     }
+ *     await delay(retryDelay * Math.pow(retryBackoff, attempt - 1));
+ *   }
+ * }
+ * ```
+ *
+ * Requirement 5.3
+ */
+export class RetryError extends JackError {
+    /**
+     * The number of retry attempts that were made
+     * Includes the initial attempt plus all retries
+     */
+    attempts;
+    /**
+     * The final error that caused the retry loop to fail
+     * This is the error from the last retry attempt
+     */
+    lastError;
+    /**
+     * Creates a new RetryError
+     *
+     * @param message - Human-readable error message
+     * @param attempts - The number of attempts that were made
+     * @param lastError - The final error from the last attempt
+     * @param context - Optional additional context
+     */
+    constructor(message, attempts, lastError, context) {
+        super(message, context);
+        this.name = 'RetryError';
+        this.attempts = attempts;
+        this.lastError = lastError;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

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