@kquika-inc/trakt 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# Trakt SDK
+
+Client libraries for the Trakt Integrations API: fleet predictions and
+maintenance forecasts, in a few lines of code.
+
+Trakt predicts which components on your fleet need attention, when, and what to
+do about them. This SDK gives you that data directly, with authentication,
+retries, and rate limits handled for you.
+
+## Install
+
+**Python**
+
+```bash
+pip install kquika-trakt              # core
+pip install "kquika-trakt[pandas]"    # with DataFrame support
+```
+
+The distribution is named `kquika-trakt` and the import is `trakt`. That
+difference is normal: the package you install and the module you import do not
+have to share a name.
+
+**Node / TypeScript**
+
+```bash
+npm install @kquika-inc/trakt
+```
+
+Requires Node 18 or newer. TypeScript types are included.
+
+## Quickstart
+
+**Python**
+
+```python
+from trakt import Trakt
+
+trakt = Trakt(token="YOUR_API_KEY")   # or set TRAKT_TOKEN
+
+# What can this token do?
+cfg = trakt.config()
+print(cfg.access_level, cfg.max_predictions, cfg.can_export)
+
+# Per-component predictions, most urgent first
+for c in trakt.components():
+    print(c.name, c.aircraft_tail_number, c.health,
+          c.failure_probability, c.recommended_action)
+
+# The next 90 days of maintenance, soonest first
+for item in trakt.forecast(days=90):
+    if item.is_overdue:
+        print("OVERDUE:", item.tail_number, item.component_name)
+
+# Straight to a DataFrame for planning
+df = trakt.components_dataframe()
+```
+
+**Node / TypeScript**
+
+```typescript
+import { Trakt } from "@kquika/trakt";
+
+const trakt = new Trakt({ token: process.env.TRAKT_TOKEN! });
+
+const cfg = await trakt.config();
+console.log(cfg.access_level, cfg.max_predictions);
+
+// Per-component predictions, most urgent first
+const components = await trakt.components();
+for (const c of components) {
+  console.log(c.name, c.aircraft_tail_number, c.health, c.recommended_action);
+}
+
+// The next 90 days of maintenance, soonest first
+const forecast = await trakt.forecast({ days: 90 });
+for (const item of forecast) {
+  if (item.is_overdue) console.log("OVERDUE:", item.tail_number, item.component_name);
+}
+```
+
+## Handling errors
+
+Both clients raise typed errors, so you can catch the case you care about.
+
+```python
+from trakt import AuthenticationError, PermissionError_, RateLimitError
+
+try:
+    components = trakt.components()
+except AuthenticationError:
+    print("The token was not accepted.")
+except PermissionError_:
+    print("This token's access level does not cover that call.")
+except RateLimitError:
+    print("Quota exhausted. The client already retried with backoff.")
+```
+
+```typescript
+import { AuthenticationError, PermissionError, RateLimitError } from "@kquika-inc/trakt";
+
+try {
+  const components = await trakt.components();
+} catch (e) {
+  if (e instanceof AuthenticationError) console.error("The token was not accepted.");
+  else if (e instanceof PermissionError) console.error("Access level does not cover that call.");
+  else if (e instanceof RateLimitError) console.error("Quota exhausted.");
+  else throw e;
+}
+```
+
+## What the clients do for you
+
+- **Auth.** Set the token once; every request carries the bearer header.
+- **Retries.** A rate limit or a transient server failure is retried with
+  exponential backoff and jitter, honoring `Retry-After` when it is sent. A
+  rejected token or a permission error is not retried, because retrying will not
+  fix it.
+- **Typed errors.** `AuthenticationError`, `PermissionError`, `RateLimitError`,
+  `NotFoundError`, `ServerError`.
+- **Flattened objects.** The nested prediction, survival, and maintenance blocks
+  are lifted onto the component, so `health` and `recommended_action` are one
+  attribute away.
+- **Useful ordering.** Components come back most urgent first; forecast items
+  come back soonest first.
+
+## Reading the fields
+
+| Field | Meaning |
+| --- | --- |
+| `health` | 0 to 100, where higher is healthier. |
+| `health_trend` | stable, declining, or critical. |
+| `predicted_rul_hours` / `predicted_rul_days` | Remaining useful life before attention is due. |
+| `failure_probability` | 0 to 1, the modeled chance of failure in the near term. |
+| `recommended_action` | do_nothing, inspect, repair, or replace. |
+| `priority` | The urgency band for planning. |
+| `task_reference` | The task identifier from your source system, so a row ties back to its task. |
+| `days_until_due` | Negative means the item is already past due. |
+| `is_trained` | False means the prediction is provisional and refines after training. |
+
+## Access levels
+
+Your token is issued at one of three levels, which control both the endpoints it
+can reach and how many records a request returns:
+
+- `read_only` — read predictions and forecasts
+- `read_write` — read, plus the write endpoints
+- `full` — everything, including fleet export
+
+A call outside your token's level raises a permission error. Call `config()` to
+see the level and limits for your token rather than guessing.
+
+## Need a client in another language?
+
+The SDKs are built from an OpenAPI specification, so a client can be generated
+for most languages. Contact us and we will provide the spec.
+
+## Support
+
+Questions, a token, or a raised limit: support@kquika.com
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Trakt Node / TypeScript SDK.
+ *
+ * A thin, typed client for the Trakt Integrations API. It handles
+ * authentication, retries with backoff on rate limits and transient failures,
+ * and gives you typed objects instead of raw JSON.
+ *
+ * Quickstart
+ * ----------
+ *
+ *   import { Trakt } from "@kquika-inc/trakt";
+ *
+ *   const trakt = new Trakt({ token: process.env.TRAKT_TOKEN! });
+ *
+ *   const config = await trakt.config();
+ *   console.log(config.access_level, config.max_predictions);
+ *
+ *   const components = await trakt.components();
+ *   for (const c of components) {
+ *     console.log(c.name, c.aircraft_tail_number, c.health, c.failure_probability);
+ *   }
+ *
+ *   const forecast = await trakt.forecast({ days: 90 });
+ *   for (const item of forecast) {
+ *     console.log(item.days_until_due, item.tail_number, item.component_name);
+ *   }
+ *
+ * Requires Node 18 or newer, which has a built-in fetch.
+ */
+export declare const VERSION = "1.0.0";
+/** Base class for every error this SDK throws. */
+export declare class TraktError extends Error {
+    constructor(message: string);
+}
+/** The token is missing, malformed, revoked, or expired (HTTP 401). */
+export declare class AuthenticationError extends TraktError {
+    constructor(message: string);
+}
+/** The token is valid but its access level does not permit this call (403). */
+export declare class PermissionError extends TraktError {
+    constructor(message: string);
+}
+/** The resource does not exist or is not visible to this token (404). */
+export declare class NotFoundError extends TraktError {
+    constructor(message: string);
+}
+/** A daily or monthly quota for this token is exhausted (429). */
+export declare class RateLimitError extends TraktError {
+    constructor(message: string);
+}
+/** Trakt returned a 5xx. The client retries these before giving up. */
+export declare class ServerError extends TraktError {
+    constructor(message: string);
+}
+export type AccessLevel = "read_only" | "read_write" | "full";
+export type Priority = "critical" | "high" | "medium" | "low";
+export type Urgency = "critical" | "high" | "medium" | "normal";
+/** What the calling token is permitted to do. */
+export interface Config {
+    access_level?: AccessLevel;
+    allowed_endpoints: string[];
+    /** Maximum records a single request may return for this token. */
+    max_predictions?: number;
+    can_export: boolean;
+    raw: Record<string, unknown>;
+}
+/**
+ * A component and the model's view of it. The nested prediction, survival, and
+ * maintenance values are flattened so the fields you want are one property away.
+ */
+export interface Component {
+    id?: number;
+    name?: string;
+    component_type?: string;
+    part_number?: string;
+    serial_number?: string;
+    external_id?: string;
+    /** The task identifier from the source system, so a row ties back to its task. */
+    task_reference?: string;
+    aircraft_id?: number;
+    aircraft_tail_number?: string;
+    manufacturer?: string;
+    unit_cost?: number;
+    lead_time_days?: number;
+    /** 0 to 100, where higher is healthier. */
+    health?: number;
+    health_trend?: string;
+    predicted_rul_hours?: number;
+    predicted_rul_days?: number;
+    /** 0 to 1, the modeled probability of failure in the near term. */
+    failure_probability?: number;
+    prediction_confidence?: number;
+    hazard_rate?: number;
+    /** One of do_nothing, inspect, repair, or replace. */
+    recommended_action?: string;
+    priority?: Priority;
+    /**
+     * True once a trained model has scored this component. When false the
+     * prediction is provisional and refines after the next training run.
+     */
+    is_trained: boolean;
+    raw: Record<string, unknown>;
+}
+/** One item coming due in the forecast window. */
+export interface ForecastItem {
+    kind?: string;
+    urgency?: Urgency;
+    tail_number?: string;
+    aircraft_type?: string;
+    component_name?: string;
+    component_type?: string;
+    part_number?: string;
+    task_reference?: string;
+    failure_probability?: number;
+    predicted_rul_hours?: number;
+    /** Negative when the item is already past due. */
+    days_until_due?: number;
+    suggested_action_date?: string;
+    suggested_duration_hours?: number;
+    /** True when the item is already past its due date. */
+    is_overdue: boolean;
+    raw: Record<string, unknown>;
+}
+export interface Aircraft {
+    id?: number;
+    tail_number?: string;
+    aircraft_type?: string;
+    manufacturer?: string;
+    model?: string;
+    total_flight_hours?: number;
+    total_flight_cycles?: number;
+    raw: Record<string, unknown>;
+}
+export interface TraktOptions {
+    /** Your API token. Falls back to the TRAKT_TOKEN environment variable. */
+    token?: string;
+    /** API base. Falls back to TRAKT_BASE_URL, then production. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** How many times to retry a rate limit or a transient failure. */
+    maxRetries?: number;
+    /** Supply your own fetch (for tests, or a proxied agent). */
+    fetch?: typeof fetch;
+}
+export interface ComponentQuery {
+    aircraft_id?: number;
+    component_type?: string;
+    priority?: Priority;
+    currency?: string;
+}
+export interface ForecastQuery {
+    days?: number;
+    max_items?: number;
+    start_date?: string;
+    fleet_type?: string;
+    station?: string;
+    fp_threshold?: number;
+}
+export declare class Trakt {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options?: TraktOptions);
+    private request;
+    private errorMessage;
+    private sleep;
+    /** What this token is permitted to do. A good first call to check a token. */
+    config(): Promise<Config>;
+    /**
+     * Per-component predictions, ordered with the most urgent first.
+     * The number of records is capped by the token's max_predictions limit.
+     */
+    components(query?: ComponentQuery): Promise<Component[]>;
+    /**
+     * Upcoming maintenance over a window, soonest first.
+     * A negative days_until_due means the item is already past due.
+     */
+    forecast(query?: ForecastQuery): Promise<ForecastItem[]>;
+    /** Aircraft in the fleet. */
+    aircraft(): Promise<Aircraft[]>;
+    /** A full fleet snapshot. Requires a token whose level permits export. */
+    fleetExport(): Promise<Record<string, unknown>>;
+    /** Planning scenarios. */
+    scenarios(): Promise<Array<Record<string, unknown>>>;
+    /** Create a planning scenario. Requires read_write or full. */
+    createScenario(name: string, description?: string): Promise<Record<string, unknown>>;
+}
+export default Trakt;

package/dist/index.js

@@ -0,0 +1,315 @@
+/**
+ * Trakt Node / TypeScript SDK.
+ *
+ * A thin, typed client for the Trakt Integrations API. It handles
+ * authentication, retries with backoff on rate limits and transient failures,
+ * and gives you typed objects instead of raw JSON.
+ *
+ * Quickstart
+ * ----------
+ *
+ *   import { Trakt } from "@kquika-inc/trakt";
+ *
+ *   const trakt = new Trakt({ token: process.env.TRAKT_TOKEN! });
+ *
+ *   const config = await trakt.config();
+ *   console.log(config.access_level, config.max_predictions);
+ *
+ *   const components = await trakt.components();
+ *   for (const c of components) {
+ *     console.log(c.name, c.aircraft_tail_number, c.health, c.failure_probability);
+ *   }
+ *
+ *   const forecast = await trakt.forecast({ days: 90 });
+ *   for (const item of forecast) {
+ *     console.log(item.days_until_due, item.tail_number, item.component_name);
+ *   }
+ *
+ * Requires Node 18 or newer, which has a built-in fetch.
+ */
+export const VERSION = "1.0.0";
+const DEFAULT_BASE_URL = "https://trakt.tech";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 4;
+/* -------------------------------------------------------------------------- */
+/* Errors                                                                      */
+/* -------------------------------------------------------------------------- */
+/** Base class for every error this SDK throws. */
+export class TraktError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TraktError";
+    }
+}
+/** The token is missing, malformed, revoked, or expired (HTTP 401). */
+export class AuthenticationError extends TraktError {
+    constructor(message) {
+        super(message);
+        this.name = "AuthenticationError";
+    }
+}
+/** The token is valid but its access level does not permit this call (403). */
+export class PermissionError extends TraktError {
+    constructor(message) {
+        super(message);
+        this.name = "PermissionError";
+    }
+}
+/** The resource does not exist or is not visible to this token (404). */
+export class NotFoundError extends TraktError {
+    constructor(message) {
+        super(message);
+        this.name = "NotFoundError";
+    }
+}
+/** A daily or monthly quota for this token is exhausted (429). */
+export class RateLimitError extends TraktError {
+    constructor(message) {
+        super(message);
+        this.name = "RateLimitError";
+    }
+}
+/** Trakt returned a 5xx. The client retries these before giving up. */
+export class ServerError extends TraktError {
+    constructor(message) {
+        super(message);
+        this.name = "ServerError";
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Client                                                                      */
+/* -------------------------------------------------------------------------- */
+export class Trakt {
+    token;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(options = {}) {
+        const token = options.token ?? process.env.TRAKT_TOKEN;
+        if (!token) {
+            throw new TraktError("No API token. Pass { token } or set the TRAKT_TOKEN environment variable.");
+        }
+        this.token = token;
+        this.baseUrl = (options.baseUrl ?? process.env.TRAKT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new TraktError("No fetch available. Use Node 18 or newer, or pass your own fetch in options.");
+        }
+    }
+    /* -- transport ---------------------------------------------------------- */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+            "User-Agent": `trakt-node/${VERSION}`,
+        };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            let resp;
+            try {
+                resp = await this.fetchImpl(url.toString(), {
+                    method,
+                    headers,
+                    body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                lastError = e;
+                if (attempt < this.maxRetries) {
+                    await this.sleep(attempt, null);
+                    continue;
+                }
+                throw new TraktError(`Could not reach Trakt at ${url.toString()}: ${String(e)}`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (resp.status === 200) {
+                try {
+                    return (await resp.json());
+                }
+                catch {
+                    throw new TraktError(`Trakt returned a non-JSON body (HTTP 200) for ${path}.`);
+                }
+            }
+            // Errors that retrying will not fix.
+            if (resp.status === 401) {
+                throw new AuthenticationError(await this.errorMessage(resp, "The token was not accepted."));
+            }
+            if (resp.status === 403) {
+                throw new PermissionError(await this.errorMessage(resp, "This token's access level does not permit that call."));
+            }
+            if (resp.status === 404) {
+                throw new NotFoundError(await this.errorMessage(resp, "Not found."));
+            }
+            // Retryable.
+            if (resp.status === 429) {
+                if (attempt < this.maxRetries) {
+                    await this.sleep(attempt, resp.headers.get("Retry-After"));
+                    continue;
+                }
+                throw new RateLimitError(await this.errorMessage(resp, "Rate limit exceeded for this token."));
+            }
+            if (resp.status >= 500 && resp.status < 600) {
+                if (attempt < this.maxRetries) {
+                    await this.sleep(attempt, null);
+                    continue;
+                }
+                throw new ServerError(await this.errorMessage(resp, `Trakt returned HTTP ${resp.status}.`));
+            }
+            throw new TraktError(await this.errorMessage(resp, `Unexpected response (HTTP ${resp.status}).`));
+        }
+        throw new TraktError(`Request failed: ${String(lastError)}`);
+    }
+    async errorMessage(resp, fallback) {
+        try {
+            const body = (await resp.json());
+            if (body && typeof body.error === "string" && body.error)
+                return body.error;
+        }
+        catch {
+            // fall through
+        }
+        return fallback;
+    }
+    sleep(attempt, retryAfter) {
+        let delayMs;
+        const parsed = retryAfter ? Number(retryAfter) : NaN;
+        if (!Number.isNaN(parsed) && parsed > 0) {
+            delayMs = Math.min(parsed * 1000, 60_000);
+        }
+        else {
+            // Exponential backoff with jitter, capped.
+            delayMs = Math.min(2 ** attempt, 30) * 1000 + Math.random() * 500;
+        }
+        return new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    /* -- endpoints ---------------------------------------------------------- */
+    /** What this token is permitted to do. A good first call to check a token. */
+    async config() {
+        const d = await this.request("GET", "/api/integrations/config");
+        return {
+            access_level: d.access_level,
+            allowed_endpoints: d.allowed_endpoints ?? [],
+            max_predictions: d.max_predictions,
+            can_export: Boolean(d.can_export),
+            raw: d,
+        };
+    }
+    /**
+     * Per-component predictions, ordered with the most urgent first.
+     * The number of records is capped by the token's max_predictions limit.
+     */
+    async components(query = {}) {
+        const d = await this.request("GET", "/api/integrations/components/extended", { query: { currency: "USD", ...query } });
+        const items = (d.components ?? []).map((c) => {
+            const preds = c.predictions ?? {};
+            const surv = c.survival_analysis ?? {};
+            const maint = c.maintenance ?? {};
+            return {
+                id: c.id,
+                name: c.name,
+                component_type: c.component_type,
+                part_number: c.part_number,
+                serial_number: c.serial_number,
+                external_id: c.external_id,
+                task_reference: c.task_reference,
+                aircraft_id: c.aircraft_id,
+                aircraft_tail_number: c.aircraft_tail_number,
+                manufacturer: c.manufacturer,
+                unit_cost: c.unit_cost,
+                lead_time_days: c.lead_time_days,
+                health: preds.current_health_score,
+                health_trend: preds.health_trend,
+                predicted_rul_hours: preds.predicted_rul_hours,
+                predicted_rul_days: preds.predicted_rul_days,
+                failure_probability: preds.failure_probability,
+                prediction_confidence: preds.prediction_confidence,
+                hazard_rate: surv.hazard_rate,
+                recommended_action: c.recommended_action ?? c.optimal_action ?? maint.optimal_action,
+                priority: c.priority ?? maint.priority,
+                is_trained: preds.prediction_confidence !== null && preds.prediction_confidence !== undefined,
+                raw: c,
+            };
+        });
+        items.sort((a, b) => {
+            const fpA = a.failure_probability ?? 0;
+            const fpB = b.failure_probability ?? 0;
+            if (fpA !== fpB)
+                return fpB - fpA;
+            return (a.health ?? 100) - (b.health ?? 100);
+        });
+        return items;
+    }
+    /**
+     * Upcoming maintenance over a window, soonest first.
+     * A negative days_until_due means the item is already past due.
+     */
+    async forecast(query = {}) {
+        const d = await this.request("GET", "/api/integrations/planner/forecast", { query: { days: 30, max_items: 100, ...query } });
+        const items = (d.items ?? []).map((i) => ({
+            kind: i.kind,
+            urgency: i.urgency,
+            tail_number: i.tail_number,
+            aircraft_type: i.aircraft_type,
+            component_name: i.component_name,
+            component_type: i.component_type,
+            part_number: i.part_number,
+            task_reference: i.task_reference,
+            failure_probability: i.failure_probability,
+            predicted_rul_hours: i.predicted_rul_hours,
+            days_until_due: i.days_until_due,
+            suggested_action_date: i.suggested_action_date,
+            suggested_duration_hours: i.suggested_duration_hours,
+            is_overdue: typeof i.days_until_due === "number" && i.days_until_due < 0,
+            raw: i,
+        }));
+        items.sort((a, b) => (a.days_until_due ?? 1_000_000) - (b.days_until_due ?? 1_000_000));
+        return items;
+    }
+    /** Aircraft in the fleet. */
+    async aircraft() {
+        const d = await this.request("GET", "/api/integrations/aircraft/extended");
+        return (d.aircraft ?? []).map((a) => ({
+            id: a.id,
+            tail_number: a.tail_number,
+            aircraft_type: a.aircraft_type,
+            manufacturer: a.manufacturer,
+            model: a.model,
+            total_flight_hours: a.total_flight_hours,
+            total_flight_cycles: a.total_flight_cycles,
+            raw: a,
+        }));
+    }
+    /** A full fleet snapshot. Requires a token whose level permits export. */
+    async fleetExport() {
+        return this.request("GET", "/api/integrations/fleet/export");
+    }
+    /** Planning scenarios. */
+    async scenarios() {
+        const d = await this.request("GET", "/api/integrations/scenarios");
+        return d.scenarios ?? [];
+    }
+    /** Create a planning scenario. Requires read_write or full. */
+    async createScenario(name, description) {
+        const d = await this.request("POST", "/api/integrations/scenarios", {
+            body: description ? { name, description } : { name },
+        });
+        return d.scenario ?? {};
+    }
+}
+export default Trakt;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kquika-inc/trakt",
+  "version": "1.0.0",
+  "description": "Trakt System Integrations API client: fleet predictions and maintenance forecasts.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "keywords": [
+    "trakt",
+    "predictive-maintenance",
+    "aviation",
+    "mro",
+    "api-client"
+  ]
+}