The SDK ships full TypeScript definitions for everything it accepts and everything it returns. This page explains where those types come from and which ones you are expected to touch. It does not list them — the definitions themselves are the reference, and your editor will show you them on hover.

The shapes of the served project configuration — experiences, variations, features, goals, audiences, locations, segments — are auto-generated from Convert's serving API specification. They are not hand-maintained in this repo: a generator (@hey-api/openapi-ts) turns the OpenAPI spec into TypeScript, and Convert's API tooling opens a pull request against this repo whenever the spec moves.

They live in @convertcom/js-sdk-types, under packages/types/src/config/, and cover types such as ConfigExperience, ConfigFeature, ConfigGoal, ConfigAudience, ConfigLocation and ConfigResponseData.

Two consequences worth knowing:

• The spec is the source of truth, not this wiki. For what a field means, read the Data Model for the relationships, and the Convert Serving API docs for the authoritative field-level reference.
• Don't edit them. Any change is overwritten the next time the spec is regenerated.

You rarely construct these yourself. You receive them — from getConfigEntity(), from getConfigEntityById(), or as the data you pass when initializing from a static configuration.

Everything describing how you talk to the SDK is hand-written and stable:

• Config — the options object you pass to new ConvertSDK(...). Exported as ConvertConfig. See Configuration for the full field reference.
• BucketingAttributes — the optional attributes accepted by every runExperience / runExperiences / runFeature / runFeatures call. See Initialization → Attributes Object.
• LocationAttributes, SegmentsAttributes, ConversionAttributes — attribute objects for the location, segment, and conversion calls.
• BucketedVariation / BucketedFeature — what the run methods hand back. See Data Model.

The enums (EntityType, RuleError, BucketingError, GoalDataKey, LogLevel, SystemEvents, VariationChangeType) come from @convertcom/js-sdk-enums and are re-exported from the main package.

The types you need day to day are re-exported from the main package, so a single import is usually enough:

import ConvertSDK, {EntityType, LogLevel, SystemEvents} from '@convertcom/js-sdk';
import type {
  ConvertConfig,
  ConvertInterface,
  ContextInterface,
  BucketedVariation,
  BucketedFeature,
  BucketingAttributes,
  ConfigExperience
} from '@convertcom/js-sdk';

Anything not re-exported is available from the package that owns it — @convertcom/js-sdk-types, @convertcom/js-sdk-enums, @convertcom/js-sdk-bucketing, and so on. Build & Custom Bundling lists the packages.

You only pass the options you want to change. At construction the SDK deep-merges your object over its defaults, so every setting always has a value:

const convertSDK = new ConvertSDK({
  sdkKey: 'xxx',
  logger: {logLevel: LogLevel.ERROR}   // everything else stays at its default
} as ConvertConfig);

Later sources win, and the merge is recursive — passing logger.logLevel alone does not wipe logger.customLoggers.

sdkKey and data are mutually exclusive at the type level: supply an SDK key or a static configuration object, never both. Configuration documents every field and its default, including debugToken for QA builds — see QA & Preview.

The generated config types are what lets each manager trust the data it is handed: DataManager parses the served configuration as ConfigResponseData, experience selection reads a ConfigExperience, feature resolution reads a ConfigFeature, and rule evaluation reads the audience and location rule shapes — all from the same generated definitions. Architecture Overview shows how those pieces fit together.

• Configuration — every config field, its type and its default
• Code Examples — typed examples for every SDK method
• Data Model — what the config entities mean and how they relate