SDK v1.2.0

Structured Payload Reference

Send rich, structured data through the Proven SDK and it renders automatically — tables, charts, timelines, metrics, and more. No more flattened text strings.

Install / Update

npm install @foxruv/[email protected]
# or
pnpm add @foxruv/[email protected]

How It Works

Each report section has a content field. In v1.1.0, this was always a string. In v1.2.0, it can be:

stringPlain text (backward compatible)

objectStructured content with a type field

arrayMultiple content blocks in sequence

nullSection exists but no data yet

The Proven platform auto-detects the content type and renders it appropriately — sortable tables, SVG charts, formatted key-value cards, status badge lists, and more.

Structured Content Types

Extended Report Fields

Beyond sections, the report payload supports top-level fields that are preserved in metadata. These are stored alongside the structured columns and rendered on the report page.

Field	Type	Description
patient	object	Patient demographics, diagnoses, medications, allergies
clinicalTrial	object	Trial name, phase, dates, baseline metrics
epistemicData	object	Confidence level, evidence grade, limitations
metrics	array	Key metric cards (label, value, unit, icon)
keyFindings	string[]	Bullet-point key findings
methodology	string	Methodology description
dataSources	string[]	Data sources used in analysis
[any key]	any	All extra fields preserved in rawPayload

Full Example — Clinical Discovery Report

This is a complete example showing how FoxFlow's Levi report should be structured for rich rendering on the Proven platform. Every section uses structured content types.

import { Proven } from '@foxruv/proven-sdk';

const proven = new Proven({ apiKey: 'sq_your_api_key' });
await proven.init();

const result = await proven.certify({
  title: 'Ulcerative Colitis & Iron Deficiency Anemia — Epistemic Discovery Report',
  reportType: 'clinical_discovery',
  institution: 'FoxFlow Research',
  creatorName: 'FoxFlow AI (Levi)',
  dataSources: ['Knowledge Graph', 'PubMed', 'Clinical Trials DB'],
  tags: ['ulcerative-colitis', 'iron-deficiency', 'epistemic-discovery'],
  methodology: 'Multi-tier epistemic analysis with graph-based inference',

  // Extended fields — preserved in rawPayload + metadata
  patient: {
    age: 30,
    sex: 'Male',
    diagnoses: ['Ulcerative Colitis', 'Iron Deficiency Anemia'],
    medications: ['Mesalamine 4.8g/day', 'Iron IV (Ferinject)'],
  },
  epistemicData: {
    confidenceLevel: 0.87,
    evidenceGrade: 'B',
    limitations: ['Limited longitudinal data', 'Single-center cohort'],
  },

  keyFindings: [
    'Severe iron deficiency secondary to chronic GI blood loss',
    'Elevated inflammatory markers suggest active disease',
    'Current treatment suboptimal — consider biologic escalation',
  ],

  metrics: [
    { label: 'Conditions', value: 2, icon: 'activity' },
    { label: 'Drug Safety Flags', value: 3, icon: 'shield' },
    { label: 'Evidence Sources', value: 47, icon: 'database' },
  ],

  sections: [
    // ─── Structured table ─────────────────────────────────
    {
      title: 'Lab Results (Tier 1)',
      content: {
        type: 'table',
        headers: ['Test', 'Value', 'Unit', 'Reference Range', 'Status'],
        rows: [
          ['Hemoglobin', 10.2, 'g/dL', '12.0-16.0', 'Low'],
          ['Ferritin', 8, 'ng/mL', '12-150', 'Low'],
          ['CRP', 45, 'mg/L', '<5', 'High'],
          ['ESR', 38, 'mm/hr', '0-20', 'High'],
          ['Calprotectin', 890, 'μg/g', '<50', 'High'],
        ],
      },
    },

    // ─── Chart ────────────────────────────────────────────
    {
      title: 'Condition Graph (Tier 2)',
      content: {
        type: 'bar',
        labels: ['UC Severity', 'Iron Deficiency', 'Inflammation', 'Fatigue Risk'],
        datasets: [{ label: 'Risk Score (0-10)', data: [8.5, 7.2, 9.1, 6.8] }],
        title: 'Clinical Risk Assessment',
      },
    },

    // ─── Key-value patient summary ────────────────────────
    {
      title: 'Patient Summary',
      content: {
        type: 'key_value',
        data: {
          'Age': 30,
          'Sex': 'Male',
          'Primary Diagnosis': 'Ulcerative Colitis',
          'Secondary': 'Iron Deficiency Anemia',
          'Disease Duration': '3 years',
          'Current Medications': ['Mesalamine 4.8g/day', 'Iron IV infusion'],
        },
      },
    },

    // ─── Status list ──────────────────────────────────────
    {
      title: 'Drug Safety Flags',
      content: {
        type: 'list',
        items: [
          { label: 'Mesalamine', status: 'pass', description: 'No contraindications' },
          { label: 'Iron IV (Ferinject)', status: 'warning', description: 'Monitor phosphate' },
          { label: 'Corticosteroids', status: 'critical', description: 'Avoid long-term' },
        ],
      },
    },

    // ─── Metrics row ──────────────────────────────────────
    {
      title: 'Key Indicators',
      content: {
        type: 'metrics_row',
        metrics: [
          { type: 'metric', label: 'Mayo Score', value: 8, unit: '/12', status: 'high' },
          { type: 'metric', label: 'Fatigue', value: 9, unit: '/10', status: 'critical' },
          { type: 'metric', label: 'Pain', value: 8, unit: '/10', status: 'high' },
          { type: 'metric', label: 'Wellbeing', value: 2, unit: '/10', status: 'low' },
        ],
      },
    },

    // ─── Timeline ─────────────────────────────────────────
    {
      title: 'Treatment Timeline',
      content: {
        type: 'timeline',
        events: [
          { date: '2023-03', title: 'UC Diagnosis', description: 'Colonoscopy confirmed' },
          { date: '2024-01', title: 'Iron Deficiency', description: 'Ferritin 8 ng/mL' },
          { date: '2026-02', title: 'AI Analysis', description: 'Epistemic discovery report' },
        ],
      },
    },

    // ─── Plain text (backward compatible) ─────────────────
    {
      title: 'Safety Disclaimer',
      type: 'text',
      content: 'This report is AI-generated and should not replace clinical judgment.',
    },
  ],
});

console.log(result.report.url);        // /r/Xk9mQ2?ref=doc
console.log(result.report.trustLevel); // "sdk_verified"

Migrating from v1.1.0

v1.2.0 is fully backward compatible. Your existing string-based sections continue to work. To upgrade rendering quality, replace string content with structured objects:

Before (v1.1.0)

{
  title: "Lab Results",
  content: "Hemoglobin: 10.2 g/dL (Low)\nCRP: 45 mg/L (High)"
}

After (v1.2.0)

{
  title: "Lab Results",
  content: {
    type: "table",
    headers: ["Test", "Value", "Unit", "Status"],
    rows: [
      ["Hemoglobin", 10.2, "g/dL", "Low"],
      ["CRP", 45, "mg/L", "High"]
    ]
  }
}

@foxruv/proven-sdk v1.2.0 — Published on npm

npm install @foxruv/[email protected]