Client Setup — Cognest.ai Docs

Basic Initialization#

index.ts

import { Cognest } from '@cognest/sdk'

// Reads from COGNEST_API_KEY env var automatically
const cognest = new Cognest()

// Or provide explicit configuration
const cognest = new Cognest({
  apiKey: process.env.COGNEST_API_KEY,
  orgId: process.env.COGNEST_ORG_ID,
})

Configuration Options#

new Cognest(options?)(apiKey?: string, orgId?: string, configPath?: string, logLevel?: 'debug' | 'info' | 'warn' | 'error', baseUrl?: string): Cognest

Create a new Cognest client instance.

Parameters

apiKey?stringAPI key. Defaults to COGNEST_API_KEY env var.

orgId?stringOrganization ID. Defaults to COGNEST_ORG_ID.

configPath?stringPath to cognest.config.yaml. Defaults to ./cognest.config.yaml.

logLevel?'debug' | 'info' | 'warn' | 'error'Log verbosity. Defaults to 'info'.

baseUrl?stringCustom API base URL for self-hosted deployments.

With Config File#

When a cognest.config.yaml file exists in your project root, the SDK automatically loads integrations and settings from it:

index.ts

import { Cognest } from '@cognest/sdk'

// Automatically loads ./cognest.config.yaml
const cognest = new Cognest()

// All integrations from config are pre-initialized
const whatsapp = cognest.integration('whatsapp')
const slack = cognest.integration('slack')

// Start listening for events
await cognest.start()

Programmatic Configuration#

You can also configure integrations entirely in code, without a YAML file:

index.ts

import { Cognest } from '@cognest/sdk'
import { WhatsApp } from '@cognest/integration-whatsapp'
import { Slack } from '@cognest/integration-slack'

const cognest = new Cognest({ configPath: false }) // Skip config file

// Register integrations manually
cognest.use(WhatsApp, {
  phoneNumberId: process.env.WHATSAPP_PHONE_ID!,
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
})

cognest.use(Slack, {
  botToken: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
})

// Configure engine
cognest.engine({
  provider: 'openai',
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.',
})

await cognest.start()

Singleton Pattern#

For web frameworks, create a singleton instance to avoid re-initialization:

lib/cognest.ts

// lib/cognest.ts
import { Cognest } from '@cognest/sdk'

let instance: Cognest | null = null

export function getCognest(): Cognest {
  if (!instance) {
    instance = new Cognest()
  }
  return instance
}

// Usage in API routes or handlers
import { getCognest } from './lib/cognest'
const cognest = getCognest()

Shutdown#

Gracefully shut down the client to close all integration connections and flush pending events:

index.ts

// Graceful shutdown
process.on('SIGTERM', async () => {
  await cognest.shutdown()
  process.exit(0)
})