Sixpack SDK

@sixpack-dev/sdk is the TypeScript entry point for defining suppliers, generators, and orchestrators for Sixpack.

If you are adapting reusable Playwright flows into generators, read this together with:

• Playwright flows to Sixpack
• the @sixpack-dev/playwright-flows package README
• the @sixpack-dev/playwright-sixpack-adapter package README

Installation

npm install @sixpack-dev/sdk

Minimal supplier bootstrap

import { Supplier } from '@sixpack-dev/sdk'
import { defineGeneratorItem, s } from '@sixpack-dev/sdk/item'

const createInvoice = defineGeneratorItem({
	generate(input: { country: string }) {
		return {
			invoiceId: `invoice-${Date.now()}`,
			country: input.country,
		}
	},
	metadata: {
		name: 'Invoice',
		inputSchema: {
			country: s.string(),
		},
		outputSchema: {
			invoiceId: s.string(),
			country: s.string(),
		},
	},
})

const supplier = new Supplier({
	name: 'Billing',
	reportIssueUrl: 'https://example.test/support',
})
	.withGenerators(createInvoice)
	.withSixpackUrl('gen.sixpack.dev:443')
	.withAccount('my-account')
	.withEnvironment('TEST')
	.withAuthToken(process.env.SIXPACK_AUTH_TOKEN ?? '')
	.withClientCertificatePath('./config/generator.cert.pem')
	.withClientKeyPath('./config/generator.pkey.pem')

supplier.validate()
await supplier.bootstrap()

Quickstart checklist:

• supplier name
• supplier reportIssueUrl or reportIssueEmail
• generator metadata.name
• generator inputSchema
• generator outputSchema
• generator outputKind when the output is not the default FLAT
• Sixpack URL, account, environment, auth token, and cert/key paths before bootstrap()

SIXPACK_AUTH_TOKEN is required even when you also configure client certificate and key paths. The token and mTLS credentials are used together, not as alternatives.

Next common step: repo-local config

Teams often keep supplier config in a small local module or .env.local-driven loader instead of exporting many shell variables manually.

Use fluent setters for values loaded after process startup so the effective supplier config is explicit:

import { Supplier, type RunMode } from '@sixpack-dev/sdk'

type LocalSixpackConfig = {
	supplierName: string
	sixpackUrl: string
	account: string
	environment: string
	runMode: RunMode
	authToken: string
	clientCertificatePath: string
	clientKeyPath: string
}

export function createSupplier(config: LocalSixpackConfig) {
	return new Supplier({
		name: config.supplierName,
		reportIssueUrl: 'https://example.test/support',
	})
		.withSixpackUrl(config.sixpackUrl)
		.withAccount(config.account)
		.withEnvironment(config.environment)
		.withRunMode(config.runMode)
		.withAuthToken(config.authToken)
		.withClientCertificatePath(config.clientCertificatePath)
		.withClientKeyPath(config.clientKeyPath)
}

This matters most for runtime-sensitive fields such as runMode, and for repo-local cert/key paths that should resolve from the supplier process working directory.

When you use client certificates, make sure SIXPACK_ACCOUNT, the certificate, and the token all belong to the same account shown in the Sixpack account configuration UI.

.env-first starter shape

For local suppliers, prefer a small repo-local loader instead of ad-hoc shell exports:

import 'dotenv/config'

import { Supplier } from '@sixpack-dev/sdk'

function required(name: string): string {
	const value = process.env[name]
	if (!value) {
		throw new Error(`Missing required environment variable ${name}`)
	}
	return value
}

export function createSupplier() {
	return new Supplier({
		name: required('SIXPACK_SUPPLIER_NAME'),
		reportIssueUrl: required('SIXPACK_REPORT_ISSUE_URL'),
	})
		.withSixpackUrl(required('SIXPACK_URL'))
		.withAccount(required('SIXPACK_ACCOUNT'))
		.withEnvironment(required('SIXPACK_ENVIRONMENT'))
		.withAuthToken(required('SIXPACK_AUTH_TOKEN'))
		.withRunMode((process.env.SIXPACK_RUN_MODE as 'DEV' | 'DEPLOYMENT') ?? 'DEV')
		.withClientCertificatePath(required('SIXPACK_CLIENT_CERT_PATH'))
		.withClientKeyPath(required('SIXPACK_CLIENT_KEY_PATH'))
}

Playwright-backed suppliers

When a generator is backed by Playwright flows:

• validate the flow in direct test execution, standalone sixpack-playwright generate, and live supplier execution
• keep generator inputs and outputs flat
• use flow-level deriveFlowInput(...) for unique default identities
• expect supplier execution to reveal retry, timeout, and stale-page issues that ordinary test execution may not

Today the SDK does not derive adapter schemas automatically from flow contracts. Treat sixpack-playwright inspect --strict, sixpack-playwright-adapter validate, and supplier.validate() as the minimum CI guard against contract drift.

The detailed TypeScript reference lives at docs.sixpack.dev/reference/typescript.