SDK Integration • Step 1

Quick SDK Integration

Use the NotionAlpha SDK for automatic cost tracking and outcome tracking. Drop-in replacement for OpenAI, Anthropic, and Azure AI Foundry SDKs with built-in transaction ID capture.

Next: Track Business Outcomes

Automatic Transaction ID Capture: SDK automatically captures transaction IDs for outcome tracking - no manual header extraction needed.
Cost Tracking: Every request is automatically tracked with team-level cost attribution and budget enforcement.
Built-in Outcome Tracking: One-line outcome tracking with automatic ROI calculation. Link business value to LLM costs instantly.

SDK Examples

Choose Your SDK

Select an SDK below to see integration examples. All examples use the same pattern: initialize the client and make calls through the proxy.

openai-integration.ts

// Install: npm install @notionalpha/clarity-sdk openai
import { NotionAlphaClient } from '@notionalpha/clarity-sdk';

// Initialize client
const clarity = new NotionAlphaClient({
  orgId: process.env.NOTIONALPHA_ORG_ID!,
  teamId: process.env.NOTIONALPHA_TEAM_ID!,
  environment: 'production',
  provider: {
    type: 'openai',
    providerId: process.env.NOTIONALPHA_PROVIDER_ID!
  }
});

// Make LLM call (FinOps automatic)
const { response, transactionId } = await clarity.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);
// ✅ Cost automatically tracked
// ✅ Transaction ID captured for outcome tracking

Environment Variables

# NotionAlpha Configuration
NOTIONALPHA_PROVIDER_ID=ca2399ae-2dd4-4543-a078-1f009cd09f78
NOTIONALPHA_ORG_ID=e96ff6c3-fcac-40b9-b905-6d49f39bd0e2  # Internal UUID (NOT Clerk org ID)
NOTIONALPHA_TEAM_ID=b3ddb8d1-b2af-414f-bf16-a87beba0042d
NOTIONALPHA_ENVIRONMENT=Production  # Production, Staging, or Development

# Note: Your OpenAI API key is stored securely in Cloudflare KV
# No need to include it in your environment variables

Important: Get your internal Organization ID (UUID format) from the Providers page in the NotionAlpha dashboard.

This is NOT your Clerk organization ID (org_xxxxx format). The internal UUID is required for proper usage tracking.

Security: API keys are stored securely in Cloudflare KV and never exposed in your application code.

Required Headers

Header	Required	Description	Example
X-Org-ID	Yes	Internal organization UUID from dashboard	e96ff6c3-fcac-40b9...
X-Team-ID	Yes	Team UUID for cost attribution	b3ddb8d1-b2af-414f...
X-Environment	Yes	Deployment environment (case-sensitive)	Production, Staging, Development
X-Feature-ID	No	Optional feature identifier for tracking	chat-assistant

Important: Environment values are case-sensitive. Use Production, Staging, or Development (capitalized).

Ready for Step 2?

You've integrated the NotionAlpha proxy to track LLM costs. Now track the business value your AI creates.

Link business outcomes (tickets resolved, code generated, time saved) to LLM transactions for automatic ROI calculation. CFOs and CIOs see value dashboards.

Track Business Outcomes