@insightgenius/sdk

TypeScript SDK for InsightGenius — deterministic survey data analysis with significance testing.

Install

npm install @insightgenius/sdk

Quick Start

import { InsightGenius } from "@insightgenius/sdk";
import { readFileSync, writeFileSync } from "fs";

const ig = new InsightGenius("sk_test_your_key_here");

// 1. Upload a .sav file
const file = new Blob([readFileSync("survey.sav")]);
const { file_id } = await ig.upload(file, "survey.sav");

// 2. See what's in it
const meta = await ig.getMetadata(file_id);
console.log(`${meta.n_cases} respondents, ${meta.n_variables} variables`);
console.log("Suggested banners:", meta.suggested_banners);

// 3. Run a crosstab with significance testing
const ct = await ig.crosstab(file_id, {
  row: "Q1_Satisfaction",
  col: "Gender",
  significance_level: 0.95,
});
console.log("Significance letters:", ct.significance_letters);
// { "5": { "A": "B" } } means column A is significantly higher than B

// 4. Generate a full Excel report
const excel = await ig.tabulate(file_id, {
  banners: ["Gender", "AgeGroup"],
  stubs: ["_all_"],
  significance_level: 0.95,
  include_means: true,
  nets: {
    Q1_Satisfaction: { "Top 2 Box": [4, 5], "Bottom 2 Box": [1, 2] },
  },
});
writeFileSync("report.xlsx", Buffer.from(excel));

API Reference

Constructor

// Simple
const ig = new InsightGenius("sk_test_...");

// With options
const ig = new InsightGenius({
  apiKey: "sk_live_...",
  baseUrl: "https://spss.insightgenius.io",  // default
  timeout: 120_000,                           // 2 min default
  maxRetries: 2,                              // default
});

Methods

| Method | Description | Returns | |--------|-------------|---------| | upload(file, filename) | Upload .sav/.csv/.xlsx | UploadResult | | getMetadata(fileId) | Variables, types, detected groups | Metadata | | frequency(fileId, variable) | Frequency table with stats | FrequencyResult | | crosstab(fileId, spec) | Crosstab with sig letters (A/B/C) | CrosstabResult | | anova(fileId, spec) | One-way ANOVA + Tukey HSD | AnovaResult | | correlation(fileId, spec) | Correlation matrix | CorrelationResult | | satisfactionSummary(fileId, spec) | T2B/B2B/Mean summary | SatisfactionItem[] | | gapAnalysis(fileId, spec) | Importance-Performance gaps | GapAnalysisItem[] | | waveCompare(fileId1, fileId2) | Compare two survey waves | WaveComparisonItem[] | | tabulate(fileId, spec) | Full Excel with sig testing | ArrayBuffer | | autoAnalyze(fileId) | Zero-config Excel report | ArrayBuffer | | convert(fileId, format) | Convert to xlsx/csv/dta/parquet | ArrayBuffer |

Error Handling

import {
  InsightGenius,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "@insightgenius/sdk";

try {
  const meta = await ig.getMetadata(fileId);
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid API key
  } else if (err instanceof RateLimitError) {
    // Wait and retry
    await new Promise((r) => setTimeout(r, err.retryAfterMs));
  } else if (err instanceof ValidationError) {
    // Bad input
    console.error(err.message);
  }
}

Get an API Key

1. Go to spss.insightgenius.io/app/keys
2. Create a key
3. Use it: new InsightGenius("sk_live_...")

Build Your Own Displayr

See the Next.js template for a complete example of building a survey analysis platform using this SDK.

License

MIT