04 · Documentation

API reference

The SDK exposes a single class, X2YSdk, with four public methods and two optional configuration objects. All types ship with the package for full TypeScript IntelliSense.

new X2YSdk(apiConfig?, refactorConfig?)constructor

Creates an SDK instance. Both arguments are optional; omitted values fall back to documented defaults. The constructor performs no I/O and makes no network calls. Exposes sdk.version and sdk.config for diagnostics.

Constructor parameters
Parameter	Type	Default	Description
apiConfig.rateLimitThreshold	number	80	Percentage of quota consumed before an endpoint is flagged rateLimitApproaching.
apiConfig.predictionWindow	number	60000	Time window (ms) of recorded traffic considered by the prediction engine.
apiConfig.apiUrl	string	—	Base URL used to scope traffic records and predictions.
refactorConfig.targetLanguage	string	'typescript'	Language assumed when parsing refactoring input.
refactorConfig.rules	string[]	['performance','idiom','async']	Enabled rule sets: performance, idiom, async.

sdk.recordAPITraffic(record: TrafficRecord): voidmonitor

Records a single API interaction into the append-only in-memory index. Synchronous and allocation-light; safe to call on every request. Capable of ingesting thousands of records per second without blocking the event loop.

TrafficRecord fields
Field	Type	Description
endpoint	string	Request path or URL, e.g. '/api/users'.
method	string	HTTP method, e.g. 'GET', 'POST'.
timestamp	number	Epoch milliseconds, typically Date.now().
responseTime	number	Observed latency in milliseconds.
statusCode	number	HTTP status code returned.
headers	Record<string,string>	Raw response headers; rate-limit headers parsed when present.

sdk.predictAPIIssues(endpoint: string): Promise<Prediction>predict

Analyses recorded traffic for the given endpoint using standard deviation and coefficient-of-variation statistics over response times, and returns a Prediction object.

Prediction fields
Field	Type	Description
endpoint	string	The queried endpoint.
riskLevel	'low' \| 'medium' \| 'high'	Composite risk classification from CV analysis.
predictedFailure	boolean	Whether a failure is anticipated within the prediction window.
rateLimitApproaching	boolean	True when usage% exceeds rateLimitThreshold.
suggestedAlternatives	string[]	Fallback strategies, e.g. cached endpoints.
confidence	number	Dynamic confidence score, 50–98, penalized by CV.

Returns — Promise resolving to the Prediction object; see the playground release-gate sample for an exact payload.

sdk.refactorCode(code: string): Promise<RefactorSuggestion[]>refactor

Parses a raw code string with stateful, line-by-line traversal and brace-matching scope heuristics. Returns line-level suggestions carrying the exact corrected snippet, the offending line and a severity of low | medium | high | critical.

Returns — Array of { type, description, originalCode, suggestedCode, line, severity } . Rule categories: performance (N+1, DOM thrashing, repeated allocations), idiom, async.

sdk.refactorFile(path: string): Promise<RefactorSuggestion[]>refactor

Reads a local JavaScript or TypeScript file from disk and runs the full refactoring engine over it. The file is read locally and never transmitted; results are identical in shape to refactorCode.

const fileSuggestions = await sdk.refactorFile('./src/example.js');
console.log(`${fileSuggestions.length} suggestions found`);

type RefactorSuggestiontypes

RefactorSuggestion fields
Field	Type	Description
type	'performance' \| 'idiom' \| 'async'	Rule category that produced the suggestion.
description	string	Human-readable explanation of the issue and fix.
originalCode	string	The offending code fragment.
suggestedCode	string	The exact corrected snippet.
line	number	1-based line number of the finding.
severity	'low' \| 'medium' \| 'high' \| 'critical'	Severity classification; N+1 queries are critical.

env X2Y_AUTO_REFACTORenvironment

Set X2Y_AUTO_REFACTOR=true to automatically apply high-severity refactoring suggestions during build steps. Disabled by default. Review diffs first in production pipelines.

history Changelogreleases

Changelog
Version	Date	Notes
v1.0.4	2026	Current stable. Statistical predictive analytics (μ, σ, CV) with dynamic confidence scoring; heuristic static analysis with scoped context tracking; N+1, DOM-thrashing and repeated-allocation detection; async modernization; rate-limit heuristics with fallback routing; append-only in-memory telemetry. Release gate validated via the unified playground suite.
v0.9.x	2026	Public beta. Refactoring engine hardening, severity calibration, X2Y_AUTO_REFACTOR flag.
v0.5.x	2025	Internal alpha. Core monitor and refactor prototypes developed within the x2y suite.

API reference

Ship safer API integrations and cleaner code reviews.