glucoguard 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# glucoguard — TypeScript/JavaScript SDK
+
+Typed client for the GlucoGuard REST API. Works in Node 18+ and modern
+browsers. Zero runtime dependencies.
+
+## Install
+
+```bash
+npm install glucoguard
+# or
+pnpm add glucoguard
+# or
+yarn add glucoguard
+```
+
+## Quick start
+
+```ts
+import { GlucoGuard } from 'glucoguard';
+
+const gg = new GlucoGuard({ apiKey: 'sk_live_...' });
+
+const result = await gg.predictDiabetes({
+  age: 55,
+  gender: 0,
+  bmi: 30,
+  systolic_bp: 140,
+  diastolic_bp: 88,
+  hba1c: 6.5,
+});
+
+console.log(`Risk: ${result.risk_score}% (${result.risk_category})`);
+for (const factor of result.top_factors.slice(0, 3)) {
+  console.log(`  ${factor.feature}: ${factor.direction} (${factor.shap_value.toFixed(3)})`);
+}
+```
+
+## Batch predictions
+
+```ts
+const patients = [
+  { age: 55, gender: 0, bmi: 30, systolic_bp: 140, diastolic_bp: 88 },
+  { age: 35, gender: 1, bmi: 22, systolic_bp: 118, diastolic_bp: 72 },
+];
+
+const result = await gg.predictBatch(patients);
+
+if (GlucoGuard.isInlineResult(result)) {
+  console.log(`Processed ${result.total} patients in ${result.processing_time_ms}ms`);
+  for (const item of result.results) {
+    console.log(`Patient ${item.index}: diabetes ${item.diabetes.risk_score}%`);
+  }
+}
+```
+
+## Webhook batch jobs
+
+For long-running batches, pass a `webhookUrl` and GlucoGuard will POST the
+result to your endpoint when complete. The response includes the signed
+HMAC-SHA256 signature in `X-GlucoGuard-Signature`.
+
+```ts
+const ack = await gg.predictBatch(patients, {
+  webhookUrl: 'https://your-server.com/glucoguard-hook',
+});
+
+if (GlucoGuard.isWebhookResult(ack)) {
+  console.log(`Job queued: ${ack.job_id}`);
+}
+```
+
+## Error handling
+
+Every failure is a typed error. Check with `instanceof`:
+
+```ts
+import {
+  GlucoGuard,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  GlucoGuardError,
+} from 'glucoguard';
+
+try {
+  await gg.predictDiabetes(patient);
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    console.error('Bad API key');
+  } else if (err instanceof RateLimitError) {
+    console.error('Slow down and retry');
+  } else if (err instanceof ValidationError) {
+    console.error('Bad request:', err.message);
+  } else if (err instanceof GlucoGuardError) {
+    console.error(`API error ${err.statusCode}: ${err.message}`);
+    console.error(`request_id: ${err.requestId}`);  // useful for support
+  }
+}
+```
+
+## Ops endpoints
+
+```ts
+await gg.health();                    // public liveness probe
+await gg.status();                    // detailed status + model versions
+await gg.usage(7);                    // your key's usage over 7 days
+await gg.modelInfo('diabetes');       // model metrics + feature importance
+await gg.samplePatients();            // pre-configured demo patients
+```
+
+## PDF reports
+
+```ts
+import { writeFile } from 'node:fs/promises';
+
+const bytes = await gg.generatePDFReport({
+  patient,
+  diabetes_result: diabetesResult,
+  cvd_result: cvdResult,
+  patient_name: 'Jane Smith',
+});
+await writeFile('report.pdf', Buffer.from(bytes));
+```
+
+## Browser usage
+
+The client uses the built-in `fetch` API, so it works in modern browsers
+with zero config. **Do not expose your API key in client-side code** —
+always call the API from a trusted backend and proxy requests.
+
+```ts
+// browser-only — proxy through your own backend
+const gg = new GlucoGuard({
+  apiKey: 'sk_live_server_proxy_token',
+  baseUrl: '/proxy/glucoguard',  // your backend forwards to the real API
+});
+```
+
+## Node 16 or older
+
+The SDK requires a `fetch` implementation. Node 18+ has it built in.
+For older versions:
+
+```bash
+npm install undici
+```
+
+```ts
+import { fetch } from 'undici';
+import { GlucoGuard } from 'glucoguard';
+
+const gg = new GlucoGuard({
+  apiKey: 'sk_live_...',
+  fetch: fetch as unknown as typeof globalThis.fetch,
+});
+```
+
+## TypeScript
+
+Every method is fully typed. The package ships with `.d.ts` files, so
+IDE autocompletion works out of the box.
+
+```ts
+import type { PatientInput, PredictionResult } from 'glucoguard';
+
+function makePatient(): PatientInput {
+  return { age: 55, gender: 0, bmi: 30, systolic_bp: 140, diastolic_bp: 88 };
+}
+```
+
+## Links
+
+- API docs: https://glucoguard.analyticadss.com/docs
+- Web app:  https://glucoguard.analyticadss.com
+- Status:   https://glucoguard.analyticadss.com/status.html
+- Issues:   mailto:api@analyticadss.com
+
+Built by [Analytica Data Science Solutions](https://analyticadss.com).

package/dist/index.cjs

@@ -0,0 +1,228 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  GlucoGuard: () => GlucoGuard,
+  GlucoGuardError: () => GlucoGuardError,
+  RateLimitError: () => RateLimitError,
+  ValidationError: () => ValidationError,
+  default: () => GlucoGuard
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var GlucoGuardError = class extends Error {
+  statusCode;
+  body;
+  requestId;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "GlucoGuardError";
+    this.statusCode = opts.statusCode;
+    this.body = opts.body;
+    this.requestId = opts.requestId;
+  }
+};
+var AuthenticationError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ValidationError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://glucoguard.analyticadss.com/api";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_USER_AGENT = "glucoguard-js/0.1.0";
+var GlucoGuard = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  fetchImpl;
+  userAgent;
+  constructor(options) {
+    if (!options.apiKey || !options.apiKey.startsWith("sk_")) {
+      throw new Error('apiKey must start with "sk_" (e.g. sk_live_...)');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (!resolvedFetch) {
+      throw new Error(
+        "No fetch implementation available. Upgrade to Node 18+ or pass a fetch option."
+      );
+    }
+    this.fetchImpl = resolvedFetch;
+  }
+  // ---------------------------------------------------------------------
+  // Core request helper
+  // ---------------------------------------------------------------------
+  async request(method, path, body, returnBinary = false) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": this.userAgent
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err.name === "AbortError") {
+        throw new GlucoGuardError(`Request timed out after ${this.timeout}ms`);
+      }
+      throw new GlucoGuardError(`Network error: ${err.message}`);
+    }
+    clearTimeout(timer);
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    if (!response.ok) {
+      let errorBody = null;
+      let detail = `HTTP ${response.status}`;
+      try {
+        errorBody = await response.json();
+        const body2 = errorBody;
+        if (typeof body2.detail === "string") {
+          detail = body2.detail;
+        } else if (Array.isArray(body2.detail)) {
+          detail = body2.detail.map((d) => JSON.stringify(d)).join("; ");
+        }
+      } catch {
+        try {
+          detail = await response.text();
+        } catch {
+        }
+      }
+      const opts = { statusCode: response.status, body: errorBody, requestId };
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthenticationError(detail, opts);
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(detail, opts);
+      }
+      if (response.status === 422 || response.status === 400) {
+        throw new ValidationError(detail, opts);
+      }
+      throw new GlucoGuardError(`${method} ${path} failed: ${detail}`, opts);
+    }
+    if (returnBinary) {
+      return await response.arrayBuffer();
+    }
+    return await response.json();
+  }
+  // ---------------------------------------------------------------------
+  // Predictions
+  // ---------------------------------------------------------------------
+  /** Predict diabetes risk for a single patient. */
+  async predictDiabetes(patient) {
+    return this.request("POST", "/predict/diabetes", patient);
+  }
+  /** Predict cardiovascular disease risk for a single patient. */
+  async predictCVD(patient) {
+    return this.request("POST", "/predict/cvd", patient);
+  }
+  /** Generic disease predictor — use the specific methods above for stronger typing. */
+  async predict(disease, patient) {
+    return this.request("POST", `/predict/${disease}`, patient);
+  }
+  /**
+   * Run batch predictions.
+   *
+   * - Without `webhookUrl`: runs synchronously and returns inline results.
+   * - With `webhookUrl`: returns `{ job_id, status: 'queued', ... }` immediately
+   *   and POSTs the final result to your URL when complete.
+   */
+  async predictBatch(patients, options = {}) {
+    const body = { patients };
+    if (options.webhookUrl) {
+      body.webhook_url = options.webhookUrl;
+    }
+    return this.request("POST", "/predict/batch", body);
+  }
+  /** Type guard to narrow a BatchResult to the webhook-mode shape. */
+  static isWebhookResult(result) {
+    return result.job_id !== void 0;
+  }
+  /** Type guard to narrow a BatchResult to the inline-mode shape. */
+  static isInlineResult(result) {
+    return result.results !== void 0;
+  }
+  // ---------------------------------------------------------------------
+  // Ops endpoints
+  // ---------------------------------------------------------------------
+  /** Simple liveness probe — public endpoint, works without a key. */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  /** Detailed service status — uptime, model versions, AUC scores. Public. */
+  async status() {
+    return this.request("GET", "/status");
+  }
+  /** Usage statistics for the authenticated key. Accepts an optional time window in days (1-90). */
+  async usage(days = 7) {
+    return this.request("GET", `/usage?days=${days}`);
+  }
+  // ---------------------------------------------------------------------
+  // Metadata
+  // ---------------------------------------------------------------------
+  async modelInfo(disease) {
+    return this.request("GET", `/model/info/${disease}`);
+  }
+  async samplePatients() {
+    return this.request("GET", "/patients/samples");
+  }
+  // ---------------------------------------------------------------------
+  // PDF report
+  // ---------------------------------------------------------------------
+  /** Generate a PDF report. Returns the raw bytes as an ArrayBuffer. */
+  async generatePDFReport(request) {
+    return this.request("POST", "/report/pdf", request, true);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  GlucoGuard,
+  GlucoGuardError,
+  RateLimitError,
+  ValidationError
+});

package/dist/index.d.cts

@@ -0,0 +1,216 @@
+/**
+ * Type definitions for the GlucoGuard API.
+ */
+type Disease = 'diabetes' | 'cvd';
+type RiskCategory = 'low' | 'moderate' | 'high';
+type Tier = 'free' | 'pro' | 'enterprise';
+interface PatientInput {
+    /** Age in years, 20-120 */
+    age: number;
+    /** 0 = Female, 1 = Male */
+    gender: 0 | 1;
+    /** BMI in kg/m² */
+    bmi: number;
+    /** Systolic blood pressure in mmHg */
+    systolic_bp: number;
+    /** Diastolic blood pressure in mmHg */
+    diastolic_bp: number;
+    /** HbA1c / Glycohemoglobin percentage */
+    hba1c?: number | null;
+    /** HDL cholesterol in mg/dL */
+    hdl_cholesterol?: number | null;
+    /** Total cholesterol in mg/dL */
+    total_cholesterol?: number | null;
+    /** Waist circumference in cm */
+    waist?: number | null;
+    /** Weight in kg */
+    weight?: number | null;
+    /** Height in cm */
+    height?: number | null;
+}
+interface TopFactor {
+    feature: string;
+    shap_value: number;
+    direction: 'increases' | 'decreases';
+    input_value: number;
+}
+interface PredictionResult {
+    /** Risk score 0-100 */
+    risk_score: number;
+    risk_category: RiskCategory;
+    recommendation: string;
+    shap_values: Record<string, number>;
+    top_factors: TopFactor[];
+}
+interface BatchResultItem {
+    index: number;
+    patient: PatientInput;
+    diabetes: PredictionResult;
+    cvd: PredictionResult;
+}
+interface BatchInlineResult {
+    results: BatchResultItem[];
+    total: number;
+    processing_time_ms: number;
+}
+interface BatchWebhookResult {
+    job_id: string;
+    status: 'queued';
+    patient_count: number;
+    webhook_url: string;
+    message: string;
+}
+type BatchResult = BatchInlineResult | BatchWebhookResult;
+interface HealthResponse {
+    status: 'ok' | 'degraded';
+    service: string;
+    version: string;
+}
+interface StatusResponse {
+    status: 'ok' | 'degraded';
+    service: string;
+    version: string;
+    uptime_seconds: number;
+    uptime_human: string;
+    started_at: string;
+    current_time: string;
+    models: {
+        diabetes?: ModelSummary;
+        cvd?: ModelSummary;
+        error?: string;
+    };
+    built_by: string;
+    docs: {
+        swagger: string;
+        redoc: string;
+        openapi: string;
+    };
+}
+interface ModelSummary {
+    type: string;
+    auc_roc: number;
+    n_samples: number;
+    n_features: number;
+}
+interface ModelInfoResponse {
+    metrics: Record<string, number>;
+    feature_importance: Record<string, number>;
+    n_samples: number;
+    n_features: number;
+    feature_names: string[];
+    model_type?: string;
+    all_results?: Array<Record<string, unknown>>;
+}
+interface UsageResponse {
+    key: {
+        id: string;
+        name: string;
+        tier: Tier;
+        prefix: string;
+    };
+    usage: {
+        days: number;
+        total_requests: number;
+        avg_duration_ms: number;
+        errors_4xx: number;
+        errors_5xx: number;
+        by_endpoint: Record<string, number>;
+        error?: string;
+    };
+    global?: Record<string, unknown>;
+}
+interface SamplePatient {
+    name: string;
+    description: string;
+    data: PatientInput;
+}
+interface ClientOptions {
+    /** API key, must start with "sk_live_..." */
+    apiKey: string;
+    /** Base URL — defaults to production */
+    baseUrl?: string;
+    /** Request timeout in milliseconds — default 30000 */
+    timeout?: number;
+    /** Custom fetch implementation (for Node 16, tests, etc.) */
+    fetch?: typeof fetch;
+    /** Custom user agent */
+    userAgent?: string;
+}
+interface PDFReportRequest {
+    patient: PatientInput;
+    diabetes_result: Partial<PredictionResult>;
+    cvd_result: Partial<PredictionResult>;
+    patient_name?: string;
+}
+
+/**
+ * GlucoGuard API client.
+ *
+ * A thin, typed wrapper around the REST API. Works in Node 18+ and any
+ * modern browser thanks to the built-in fetch API. Zero runtime dependencies.
+ */
+
+declare class GlucoGuard {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    constructor(options: ClientOptions);
+    private request;
+    /** Predict diabetes risk for a single patient. */
+    predictDiabetes(patient: PatientInput): Promise<PredictionResult>;
+    /** Predict cardiovascular disease risk for a single patient. */
+    predictCVD(patient: PatientInput): Promise<PredictionResult>;
+    /** Generic disease predictor — use the specific methods above for stronger typing. */
+    predict(disease: Disease, patient: PatientInput): Promise<PredictionResult>;
+    /**
+     * Run batch predictions.
+     *
+     * - Without `webhookUrl`: runs synchronously and returns inline results.
+     * - With `webhookUrl`: returns `{ job_id, status: 'queued', ... }` immediately
+     *   and POSTs the final result to your URL when complete.
+     */
+    predictBatch(patients: PatientInput[], options?: {
+        webhookUrl?: string;
+    }): Promise<BatchResult>;
+    /** Type guard to narrow a BatchResult to the webhook-mode shape. */
+    static isWebhookResult(result: BatchResult): result is BatchWebhookResult;
+    /** Type guard to narrow a BatchResult to the inline-mode shape. */
+    static isInlineResult(result: BatchResult): result is BatchInlineResult;
+    /** Simple liveness probe — public endpoint, works without a key. */
+    health(): Promise<HealthResponse>;
+    /** Detailed service status — uptime, model versions, AUC scores. Public. */
+    status(): Promise<StatusResponse>;
+    /** Usage statistics for the authenticated key. Accepts an optional time window in days (1-90). */
+    usage(days?: number): Promise<UsageResponse>;
+    modelInfo(disease: Disease): Promise<ModelInfoResponse>;
+    samplePatients(): Promise<SamplePatient[]>;
+    /** Generate a PDF report. Returns the raw bytes as an ArrayBuffer. */
+    generatePDFReport(request: PDFReportRequest): Promise<ArrayBuffer>;
+}
+
+/**
+ * Typed errors surfaced by the GlucoGuard client.
+ */
+declare class GlucoGuardError extends Error {
+    readonly statusCode?: number;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+    });
+}
+declare class AuthenticationError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+declare class RateLimitError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+declare class ValidationError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+
+export { AuthenticationError, type BatchInlineResult, type BatchResult, type BatchResultItem, type BatchWebhookResult, type ClientOptions, type Disease, GlucoGuard, GlucoGuardError, type HealthResponse, type ModelInfoResponse, type ModelSummary, type PDFReportRequest, type PatientInput, type PredictionResult, RateLimitError, type RiskCategory, type SamplePatient, type StatusResponse, type Tier, type TopFactor, type UsageResponse, ValidationError, GlucoGuard as default };

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Type definitions for the GlucoGuard API.
+ */
+type Disease = 'diabetes' | 'cvd';
+type RiskCategory = 'low' | 'moderate' | 'high';
+type Tier = 'free' | 'pro' | 'enterprise';
+interface PatientInput {
+    /** Age in years, 20-120 */
+    age: number;
+    /** 0 = Female, 1 = Male */
+    gender: 0 | 1;
+    /** BMI in kg/m² */
+    bmi: number;
+    /** Systolic blood pressure in mmHg */
+    systolic_bp: number;
+    /** Diastolic blood pressure in mmHg */
+    diastolic_bp: number;
+    /** HbA1c / Glycohemoglobin percentage */
+    hba1c?: number | null;
+    /** HDL cholesterol in mg/dL */
+    hdl_cholesterol?: number | null;
+    /** Total cholesterol in mg/dL */
+    total_cholesterol?: number | null;
+    /** Waist circumference in cm */
+    waist?: number | null;
+    /** Weight in kg */
+    weight?: number | null;
+    /** Height in cm */
+    height?: number | null;
+}
+interface TopFactor {
+    feature: string;
+    shap_value: number;
+    direction: 'increases' | 'decreases';
+    input_value: number;
+}
+interface PredictionResult {
+    /** Risk score 0-100 */
+    risk_score: number;
+    risk_category: RiskCategory;
+    recommendation: string;
+    shap_values: Record<string, number>;
+    top_factors: TopFactor[];
+}
+interface BatchResultItem {
+    index: number;
+    patient: PatientInput;
+    diabetes: PredictionResult;
+    cvd: PredictionResult;
+}
+interface BatchInlineResult {
+    results: BatchResultItem[];
+    total: number;
+    processing_time_ms: number;
+}
+interface BatchWebhookResult {
+    job_id: string;
+    status: 'queued';
+    patient_count: number;
+    webhook_url: string;
+    message: string;
+}
+type BatchResult = BatchInlineResult | BatchWebhookResult;
+interface HealthResponse {
+    status: 'ok' | 'degraded';
+    service: string;
+    version: string;
+}
+interface StatusResponse {
+    status: 'ok' | 'degraded';
+    service: string;
+    version: string;
+    uptime_seconds: number;
+    uptime_human: string;
+    started_at: string;
+    current_time: string;
+    models: {
+        diabetes?: ModelSummary;
+        cvd?: ModelSummary;
+        error?: string;
+    };
+    built_by: string;
+    docs: {
+        swagger: string;
+        redoc: string;
+        openapi: string;
+    };
+}
+interface ModelSummary {
+    type: string;
+    auc_roc: number;
+    n_samples: number;
+    n_features: number;
+}
+interface ModelInfoResponse {
+    metrics: Record<string, number>;
+    feature_importance: Record<string, number>;
+    n_samples: number;
+    n_features: number;
+    feature_names: string[];
+    model_type?: string;
+    all_results?: Array<Record<string, unknown>>;
+}
+interface UsageResponse {
+    key: {
+        id: string;
+        name: string;
+        tier: Tier;
+        prefix: string;
+    };
+    usage: {
+        days: number;
+        total_requests: number;
+        avg_duration_ms: number;
+        errors_4xx: number;
+        errors_5xx: number;
+        by_endpoint: Record<string, number>;
+        error?: string;
+    };
+    global?: Record<string, unknown>;
+}
+interface SamplePatient {
+    name: string;
+    description: string;
+    data: PatientInput;
+}
+interface ClientOptions {
+    /** API key, must start with "sk_live_..." */
+    apiKey: string;
+    /** Base URL — defaults to production */
+    baseUrl?: string;
+    /** Request timeout in milliseconds — default 30000 */
+    timeout?: number;
+    /** Custom fetch implementation (for Node 16, tests, etc.) */
+    fetch?: typeof fetch;
+    /** Custom user agent */
+    userAgent?: string;
+}
+interface PDFReportRequest {
+    patient: PatientInput;
+    diabetes_result: Partial<PredictionResult>;
+    cvd_result: Partial<PredictionResult>;
+    patient_name?: string;
+}
+
+/**
+ * GlucoGuard API client.
+ *
+ * A thin, typed wrapper around the REST API. Works in Node 18+ and any
+ * modern browser thanks to the built-in fetch API. Zero runtime dependencies.
+ */
+
+declare class GlucoGuard {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    constructor(options: ClientOptions);
+    private request;
+    /** Predict diabetes risk for a single patient. */
+    predictDiabetes(patient: PatientInput): Promise<PredictionResult>;
+    /** Predict cardiovascular disease risk for a single patient. */
+    predictCVD(patient: PatientInput): Promise<PredictionResult>;
+    /** Generic disease predictor — use the specific methods above for stronger typing. */
+    predict(disease: Disease, patient: PatientInput): Promise<PredictionResult>;
+    /**
+     * Run batch predictions.
+     *
+     * - Without `webhookUrl`: runs synchronously and returns inline results.
+     * - With `webhookUrl`: returns `{ job_id, status: 'queued', ... }` immediately
+     *   and POSTs the final result to your URL when complete.
+     */
+    predictBatch(patients: PatientInput[], options?: {
+        webhookUrl?: string;
+    }): Promise<BatchResult>;
+    /** Type guard to narrow a BatchResult to the webhook-mode shape. */
+    static isWebhookResult(result: BatchResult): result is BatchWebhookResult;
+    /** Type guard to narrow a BatchResult to the inline-mode shape. */
+    static isInlineResult(result: BatchResult): result is BatchInlineResult;
+    /** Simple liveness probe — public endpoint, works without a key. */
+    health(): Promise<HealthResponse>;
+    /** Detailed service status — uptime, model versions, AUC scores. Public. */
+    status(): Promise<StatusResponse>;
+    /** Usage statistics for the authenticated key. Accepts an optional time window in days (1-90). */
+    usage(days?: number): Promise<UsageResponse>;
+    modelInfo(disease: Disease): Promise<ModelInfoResponse>;
+    samplePatients(): Promise<SamplePatient[]>;
+    /** Generate a PDF report. Returns the raw bytes as an ArrayBuffer. */
+    generatePDFReport(request: PDFReportRequest): Promise<ArrayBuffer>;
+}
+
+/**
+ * Typed errors surfaced by the GlucoGuard client.
+ */
+declare class GlucoGuardError extends Error {
+    readonly statusCode?: number;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+    });
+}
+declare class AuthenticationError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+declare class RateLimitError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+declare class ValidationError extends GlucoGuardError {
+    constructor(message: string, opts?: ConstructorParameters<typeof GlucoGuardError>[1]);
+}
+
+export { AuthenticationError, type BatchInlineResult, type BatchResult, type BatchResultItem, type BatchWebhookResult, type ClientOptions, type Disease, GlucoGuard, GlucoGuardError, type HealthResponse, type ModelInfoResponse, type ModelSummary, type PDFReportRequest, type PatientInput, type PredictionResult, RateLimitError, type RiskCategory, type SamplePatient, type StatusResponse, type Tier, type TopFactor, type UsageResponse, ValidationError, GlucoGuard as default };

package/dist/index.js

@@ -0,0 +1,197 @@
+// src/errors.ts
+var GlucoGuardError = class extends Error {
+  statusCode;
+  body;
+  requestId;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "GlucoGuardError";
+    this.statusCode = opts.statusCode;
+    this.body = opts.body;
+    this.requestId = opts.requestId;
+  }
+};
+var AuthenticationError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends GlucoGuardError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ValidationError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://glucoguard.analyticadss.com/api";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_USER_AGENT = "glucoguard-js/0.1.0";
+var GlucoGuard = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  fetchImpl;
+  userAgent;
+  constructor(options) {
+    if (!options.apiKey || !options.apiKey.startsWith("sk_")) {
+      throw new Error('apiKey must start with "sk_" (e.g. sk_live_...)');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (!resolvedFetch) {
+      throw new Error(
+        "No fetch implementation available. Upgrade to Node 18+ or pass a fetch option."
+      );
+    }
+    this.fetchImpl = resolvedFetch;
+  }
+  // ---------------------------------------------------------------------
+  // Core request helper
+  // ---------------------------------------------------------------------
+  async request(method, path, body, returnBinary = false) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": this.userAgent
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err.name === "AbortError") {
+        throw new GlucoGuardError(`Request timed out after ${this.timeout}ms`);
+      }
+      throw new GlucoGuardError(`Network error: ${err.message}`);
+    }
+    clearTimeout(timer);
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    if (!response.ok) {
+      let errorBody = null;
+      let detail = `HTTP ${response.status}`;
+      try {
+        errorBody = await response.json();
+        const body2 = errorBody;
+        if (typeof body2.detail === "string") {
+          detail = body2.detail;
+        } else if (Array.isArray(body2.detail)) {
+          detail = body2.detail.map((d) => JSON.stringify(d)).join("; ");
+        }
+      } catch {
+        try {
+          detail = await response.text();
+        } catch {
+        }
+      }
+      const opts = { statusCode: response.status, body: errorBody, requestId };
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthenticationError(detail, opts);
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(detail, opts);
+      }
+      if (response.status === 422 || response.status === 400) {
+        throw new ValidationError(detail, opts);
+      }
+      throw new GlucoGuardError(`${method} ${path} failed: ${detail}`, opts);
+    }
+    if (returnBinary) {
+      return await response.arrayBuffer();
+    }
+    return await response.json();
+  }
+  // ---------------------------------------------------------------------
+  // Predictions
+  // ---------------------------------------------------------------------
+  /** Predict diabetes risk for a single patient. */
+  async predictDiabetes(patient) {
+    return this.request("POST", "/predict/diabetes", patient);
+  }
+  /** Predict cardiovascular disease risk for a single patient. */
+  async predictCVD(patient) {
+    return this.request("POST", "/predict/cvd", patient);
+  }
+  /** Generic disease predictor — use the specific methods above for stronger typing. */
+  async predict(disease, patient) {
+    return this.request("POST", `/predict/${disease}`, patient);
+  }
+  /**
+   * Run batch predictions.
+   *
+   * - Without `webhookUrl`: runs synchronously and returns inline results.
+   * - With `webhookUrl`: returns `{ job_id, status: 'queued', ... }` immediately
+   *   and POSTs the final result to your URL when complete.
+   */
+  async predictBatch(patients, options = {}) {
+    const body = { patients };
+    if (options.webhookUrl) {
+      body.webhook_url = options.webhookUrl;
+    }
+    return this.request("POST", "/predict/batch", body);
+  }
+  /** Type guard to narrow a BatchResult to the webhook-mode shape. */
+  static isWebhookResult(result) {
+    return result.job_id !== void 0;
+  }
+  /** Type guard to narrow a BatchResult to the inline-mode shape. */
+  static isInlineResult(result) {
+    return result.results !== void 0;
+  }
+  // ---------------------------------------------------------------------
+  // Ops endpoints
+  // ---------------------------------------------------------------------
+  /** Simple liveness probe — public endpoint, works without a key. */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  /** Detailed service status — uptime, model versions, AUC scores. Public. */
+  async status() {
+    return this.request("GET", "/status");
+  }
+  /** Usage statistics for the authenticated key. Accepts an optional time window in days (1-90). */
+  async usage(days = 7) {
+    return this.request("GET", `/usage?days=${days}`);
+  }
+  // ---------------------------------------------------------------------
+  // Metadata
+  // ---------------------------------------------------------------------
+  async modelInfo(disease) {
+    return this.request("GET", `/model/info/${disease}`);
+  }
+  async samplePatients() {
+    return this.request("GET", "/patients/samples");
+  }
+  // ---------------------------------------------------------------------
+  // PDF report
+  // ---------------------------------------------------------------------
+  /** Generate a PDF report. Returns the raw bytes as an ArrayBuffer. */
+  async generatePDFReport(request) {
+    return this.request("POST", "/report/pdf", request, true);
+  }
+};
+export {
+  AuthenticationError,
+  GlucoGuard,
+  GlucoGuardError,
+  RateLimitError,
+  ValidationError,
+  GlucoGuard as default
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "glucoguard",
+  "version": "0.1.0",
+  "description": "TypeScript client for the GlucoGuard diabetes and cardiovascular risk prediction API",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "keywords": [
+    "glucoguard",
+    "health",
+    "diabetes",
+    "cvd",
+    "cardiovascular",
+    "machine-learning",
+    "ml",
+    "risk-prediction",
+    "healthcare",
+    "api-client",
+    "sdk"
+  ],
+  "author": "Analytica Data Science Solutions <api@analyticadss.com>",
+  "license": "MIT",
+  "homepage": "https://glucoguard.analyticadss.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aousabdo/glucoguard.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "email": "api@analyticadss.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.4"
+  }
+}