cNode API (Preview): Forecasts & scenarios via API — test now, go production later

/**
 * CNode API — Preview / Coming Soon (copy–paste)
 * -----------------------------------------------------------------------------
 * STATUS: The public API is under active development. Endpoints and fields may
 *         change before GA. This snippet uses a MOCK URL so you can demo today.
 *
 * PROD BASE URL (when live):
 *   https://api.cnode.ai/v1/scenarios:run
 *
 * CLUSTERS (preview):
 *   "finance", "product", "hr", "marketing", "compliance", "supply_chain"
 *
 * COMMON GOALS by cluster (preview examples):
 *   finance:      "revenue_forecast", "cashflow_forecast", "break_even",
 *                 "profitability", "roi_forecast", "valuation_dcf",
 *                 "price_elasticity", "anomaly_detection"
 *   product:      "demand_forecast", "inventory_coverage", "return_rate_forecast"
 *   hr:           "headcount_forecast", "attrition_forecast"
 *   marketing:    "mql_forecast", "cac_ltv_projection"
 *   compliance:   "esg_risk_score", "anomaly_detection"
 *
 * REQUEST SCHEMA (preview):
 *   {
 *     project_id: string,                      // required
 *     cluster: string,                          // required (see CLUSTERS)
 *     goal: string,                             // required (see GOALS)
 *     horizon: "3M"|"6M"|"12M"|string,          // required
 *     inputs: object,                           // required, domain-specific
 *     explainability?: boolean,                 // default: true
 *     options?: {
 *       confidence?: number,                    // 0.5..0.99; default: 0.8
 *       include_intervals?: boolean,            // return prediction bands
 *       sensitivity?: { top_k?: number },       // top drivers count
 *       backtest?: { from: string, to: string, metric?: "WAPE"|"MAE"|"RMSE" },
 *       retrain?: "auto"|"never",               // retraining hint
 *       tags?: string[],                        // free-form labels
 *       metadata?: Record<string, unknown>      // passthrough user metadata
 *     }
 *   }
 *
 * RESPONSE SCHEMA (preview):
 *   {
 *     run_id: string,
 *     forecast: Array<{ date: "YYYY-MM-DD", value: number }>,
 *     intervals?: Array<{ date: string, lower: number, upper: number, confidence: number }>,
 *     explanations?: {
 *       global_top_features: Array<{ feature: string, weight: number }>,
 *       local?: Array<{ date: string, contributions: Array<{ feature: string, weight: number }> }>
 *     },
 *     diagnostics?: {
 *       metrics?: { WAPE?: number, MAE?: number, RMSE?: number },
 *       retrain?: boolean,
 *       warnings?: string[]
 *     }
 *   }
 *
 * SECURITY NOTE:
 *   Keep API keys server-side. Use Node 18+ (built-in fetch) or a serverless runtime.
 */

import crypto from "node:crypto";

async function runCNodeAPIDemo() {
  // Optional: quick reference you can print in your demo UI
  // const CLUSTERS = ["finance","product","hr","marketing","compliance","supply_chain"];
  // const GOALS = {
  //   finance: ["revenue_forecast","cashflow_forecast","break_even","profitability","roi_forecast","valuation_dcf","price_elasticity","anomaly_detection"]
  // };

  const body = {
    project_id: "demo-finance",
    cluster: "finance",
    goal: "revenue_forecast", // try: "cashflow_forecast", "valuation_dcf", "price_elasticity"
    horizon: "12M",

    // Domain inputs (preview): supply your time series + attributes
    inputs: {
      currency: "EUR",
      revenue_history: [
        { date: "2024-09-01", value: 42000 },
        { date: "2025-08-01", value: 86500 }
      ],
      cost_history: [
        { date: "2024-09-01", value: -28000 },
        { date: "2025-08-01", value: -52500 }
      ],
      // Optional contextual features (examples):
      calendar: [{ date: "2025-05-01", holiday: true }],
      promo_index: [{ date: "2025-06-01", value: 0.6 }],
      assumptions: { seasonality: true, growth_hint: 0.08 }
    },

    explainability: true,

    // Tuning & utilities (preview)
    options: {
      confidence: 0.8,             // 80% PI
      include_intervals: true,     // lower/upper bands
      sensitivity: { top_k: 5 },   // top drivers
      backtest: {
        from: "2025-01-01",
        to: "2025-08-01",
        metric: "WAPE"
      },
      retrain: "auto",
      tags: ["homepage-demo"],
      metadata: { source: "marketing-site" }
    },

    // DEV marker so readers know this is a mock/demo request
    _note: "coming-soon: replace mock URL with production once live"
  };

  const res = await fetch("https://yourdomain.com/api/mock/cnode/scenarios:run", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.CNODE_API_KEY_PLACEHOLDER}`, // server-side only
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
      "X-API-Version": "2025-09-01",
      "X-Demo-Mode": "true"
    },
    body: JSON.stringify(body)
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`Mock API ${res.status}: ${err.message ?? res.statusText}`);
  }

  const { run_id, forecast, intervals, explanations, diagnostics } = await res.json();

  console.log("Run:", run_id);
  console.table(forecast.slice(0, 6));                // preview first 6 points
  if (intervals) console.table(intervals.slice(0, 3)); // preview bands
  console.log("Top drivers:", explanations?.global_top_features?.slice(0, 5));
  console.log("Metrics (if backtest):", diagnostics?.metrics);
}

runCNodeAPIDemo().catch(err => {
  console.error(err);
  process.exit(1);
});