Type Reference

Complete type definitions for the Graphy AI SDK.

GraphConfig

The chart configuration object. See Graph Config Schema for the complete reference.

import type { GraphConfig } from '@graphysdk/core';

GenerateGraphParams

Request parameters for the Chart Maker Agent.

interface GenerateGraphParams {
  config: GraphConfig;
  userPrompt: string;
  metadata?: Metadata;
  storytellingOptions?: StorytellingOptions;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The current chart configuration
`userPrompt`	`string`	Yes	Natural language instruction
`metadata`	`Metadata`	No	Request tracking information
`storytellingOptions`	`StorytellingOptions`	No	Prune storytelling from config content client-side (SDK only).

GenerateGraphResponse

Response from the Chart Maker Agent.

interface GenerateGraphResponse {
  config: GraphConfig;
  response: {
    message: string;
    steps?: string[];
  };
}

Field	Type	Description
`config`	`GraphConfig`	Updated chart configuration. Narrative (title, subtitle, caption) is embedded in `config.content` as TipTap JSON documents.
`response.message`	`string`	Explanation of changes made
`response.steps`	`string[]`	Optional breakdown of modifications

GenerateGraphSuggestionsParams

Request parameters for the Suggestions Agent.

interface GenerateGraphSuggestionsParams {
  config: GraphConfig;
  userPrompt: string;
  metadata?: Metadata;
  maxSuggestionCount?: 1 | 2 | 3 | 4;
}

Field	Type	Required	Description
`config`	`GraphConfig`	Yes	The chart configuration containing the dataset
`userPrompt`	`string`	Yes	Natural language description of what to visualize
`metadata`	`Metadata`	No	Request tracking information
`maxSuggestionCount`	`1` \| `2` \| `3` \| `4`	No	Optional cap (1–4) passed to the model for how many suggestions to aim for. Omitted uses the default (4). Responses are not truncated if longer.

GenerateGraphSuggestionsResponse

Response from the Suggestions Agent.

interface GenerateGraphSuggestionsResponse {
  suggestions: Suggestion[];
}

Field	Type	Description
`suggestions`	`Suggestion[]`	List of chart type suggestions

Suggestion

A single chart suggestion returned by the Suggestions Agent.

interface Suggestion {
  dataPrepPrompt: string;
  chartType: AiChartType;
  summary: string;
}

Field	Type	Description
`dataPrepPrompt`	`string`	Prompt describing how to prepare the data for this chart
`chartType`	`AiChartType`	Suggested chart type
`summary`	`string`	Short description of what the chart would show

StorytellingOptions

SDK-only options to prune storytelling fields from the config content after the API returns. For each option set to true, the SDK removes that field from config.content before returning.

interface StorytellingOptions {
  excludeTitle?: boolean;
  excludeSubtitle?: boolean;
  excludeCaption?: boolean;
}

Field	Type	Description
`excludeTitle`	`boolean`	If true, the SDK removes `config.content.title`.
`excludeSubtitle`	`boolean`	If true, the SDK removes `config.content.subtitle`.
`excludeCaption`	`boolean`	If true, the SDK removes `config.content.caption`.

Metadata

Optional tracking information for requests.

interface Metadata {
  callId?: string;
  locale?: string;
  storytellingEffort?: 'none' | 'low' | 'medium' | 'high';
}

Field	Type	Description
`callId`	`string`	Required when `metadata` is provided. Unique identifier for tracking and debugging.
`locale`	`string`	Locale for responses (e.g., `en-US`, `fr-FR`).
`storytellingEffort`	`'none' \| 'low' \| 'medium' \| 'high'`	Which narrative fields the agent embeds in `config.content`: none → no narrative; low → title only; medium → title + caption; high → title + subtitle + caption. Default is `'low'`.

SSE Events

ProgressEvent

interface ProgressEvent {
  type: 'progress';
  percentage: number;
  message?: string;
  metadata?: Record<string, unknown>;
}

CompleteEvent

interface CompleteEvent<T> {
  type: 'complete';
  data: T;
}

ErrorEvent

interface ErrorEvent {
  type: 'error';
  error: string;
  code?: string;
  retryable?: boolean;
}

SSEEvent Union

type SSEEvent<T> = ProgressEvent | CompleteEvent<T> | ErrorEvent;

Error Types

GraphyApiError

Error thrown by the SDK when an API request fails. Covers HTTP errors, SSE stream errors, and network failures.

import { GraphyApiError } from '@graphysdk/agents-sdk';

class GraphyApiError extends Error {
  readonly status: number | undefined;
  readonly code: string | undefined;
  readonly retryable: boolean;

  constructor(message: string, options?: GraphyApiErrorOptions);
}

Property	Type	Description
`status`	`number \| undefined`	HTTP status code, if from an HTTP response
`code`	`string \| undefined`	Machine-readable error code from the API
`retryable`	`boolean`	Whether the SDK considers this error retryable

GraphyApiErrorOptions

interface GraphyApiErrorOptions {
  status?: number;
  code?: string;
  retryable?: boolean;
}

isGraphyApiError

Type guard for narrowing unknown errors to GraphyApiError:

import { isGraphyApiError } from '@graphysdk/agents-sdk';

if (isGraphyApiError(error)) {
  console.error(error.status, error.code, error.retryable);
}

Configuration Types

ClientConfig

interface ClientConfig {
  apiKey: string;
  baseUrl: string;
  timeout?: number;
  retryConfig?: RetryConfig;
  logger?: Logger;
}

RetryConfig

interface RetryConfig {
  attempts: number;
  delay: number;
  backoff: number;
}

Defaults:

{
  attempts: 3,
  delay: 1000,
  backoff: 2
}

Logger

interface Logger {
  log: (...args: unknown[]) => void;
  warn: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
  debug: (...args: unknown[]) => void;
}

AiChartType

Supported chart types for AI operations.

type AiChartType =
  | 'line'
  | 'bar'
  | 'groupedBar'
  | 'stackedBar'
  | '100StackedBar'
  | 'column'
  | 'groupedColumn'
  | 'stackedColumn'
  | '100StackedColumn'
  | 'combo'
  | 'pie'
  | 'donut'
  | 'funnel'
  | 'heatmap'
  | 'scatter'
  | 'waterfall'
  | 'table';

Type	Description
`line`	Line chart
`bar`	Horizontal bar chart
`groupedBar`	Grouped horizontal bars
`stackedBar`	Stacked horizontal bars
`100StackedBar`	100% stacked horizontal bars
`column`	Vertical column chart
`groupedColumn`	Grouped vertical columns
`stackedColumn`	Stacked vertical columns
`100StackedColumn`	100% stacked vertical columns
`combo`	Combined line and column
`pie`	Pie chart
`donut`	Donut chart
`funnel`	Funnel chart
`heatmap`	Heatmap
`scatter`	Scatter plot
`waterfall`	Waterfall chart
`table`	Data table

Zod Schemas

The SDK exports Zod schemas for runtime validation:

import { AiChartTypeEnum, GenerateGraphResponseSchema } from '@graphysdk/agents-sdk';

// Validate a response
const validated = GenerateGraphResponseSchema.parse(response);

Get Started

TypeScript SDK

REST API

Reference

GraphConfig

GenerateGraphParams

GenerateGraphResponse

GenerateGraphSuggestionsParams

GenerateGraphSuggestionsResponse

Suggestion

StorytellingOptions

Metadata

SSE Events

ProgressEvent

CompleteEvent

ErrorEvent

SSEEvent Union

Error Types

GraphyApiError

GraphyApiErrorOptions

isGraphyApiError

Configuration Types

ClientConfig

RetryConfig

Logger

AiChartType

Zod Schemas

Get Started

TypeScript SDK

REST API

Reference

​GraphConfig

​GenerateGraphParams

​GenerateGraphResponse

​GenerateGraphSuggestionsParams

​GenerateGraphSuggestionsResponse

​Suggestion

​StorytellingOptions

​Metadata

​SSE Events

​ProgressEvent

​CompleteEvent

​ErrorEvent

​SSEEvent Union

​Error Types

​GraphyApiError

​GraphyApiErrorOptions

​isGraphyApiError

​Configuration Types

​ClientConfig

​RetryConfig

​Logger

​AiChartType

​Zod Schemas

GraphConfig

GenerateGraphParams

GenerateGraphResponse

GenerateGraphSuggestionsParams

GenerateGraphSuggestionsResponse

Suggestion

StorytellingOptions

Metadata

SSE Events

ProgressEvent

CompleteEvent

ErrorEvent

SSEEvent Union

Error Types

GraphyApiError

GraphyApiErrorOptions

isGraphyApiError

Configuration Types

ClientConfig

RetryConfig

Logger

AiChartType

Zod Schemas