@almadar/integrations

External service integrations for Almadar applications

Production-ready implementations of external service integrations that work seamlessly in both interpreted runtime and compiled applications.

Features

• ✅ Type-Safe - Full TypeScript types from registry to implementation
• ✅ Environment-Agnostic - Works in runtime AND compiled apps
• ✅ Testable - Mock implementations for testing
• ✅ Extensible - Easy to add new integrations
• ✅ Secure - API keys via environment variables
• ✅ Observable - Logging and error tracking
• ✅ Validated - Input validation against registry schema

Supported Integrations

| Integration | Actions | Use Case | |-------------|---------|----------| | Stripe | createPaymentIntent, confirmPayment, refund | Payment processing | | YouTube | search, getVideo, getChannel | Video data and search | | Twilio | sendSMS, sendWhatsApp | Messaging | | Email | send | Transactional email (SendGrid/Resend) | | LLM | generate, classify, extract, summarize | AI content generation | | DeepAgent | sendMessage, validateSchema, compileSchema | AI code generation |

Installation

pnpm add @almadar/integrations

Usage

1. Runtime Integration

Use with @almadar/runtime:

import { RuntimeIntegrationManager } from '@almadar/integrations/runtime';
import '@almadar/integrations'; // Auto-register integrations

const integrationManager = new RuntimeIntegrationManager();
integrationManager.configureFromEnv();

const runtime = new OrbitalServerRuntime({
  schema,
  effectHandlers: {
    callService: integrationManager.getCallServiceHandler(),
    // ... other handlers
  },
});

2. Compiled App

Use in generated code:

import { IntegrationFactory } from '@almadar/integrations';
import '@almadar/integrations'; // Auto-register integrations

const integrations = new IntegrationFactory();

// Configure integrations
integrations.configure('stripe', {
  env: {
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
  },
});

// Use in effect handler
async function handleCallService(service, action, params) {
  const result = await integrations.execute(service, action, params);
  
  if (!result.success) {
    throw result.error;
  }
  
  return result.data;
}

3. Direct Usage

Use integrations directly:

import { StripeIntegration } from '@almadar/integrations';

const stripe = new StripeIntegration({
  name: 'stripe',
  env: {
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
  },
});

const result = await stripe.execute('createPaymentIntent', {
  amount: 2000,
  currency: 'usd',
});

if (result.success) {
  console.log('Payment intent:', result.data);
}

Configuration

Set environment variables:

# Stripe
STRIPE_SECRET_KEY=sk_test_...

# YouTube
YOUTUBE_API_KEY=AIza...

# Twilio
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1...

# Email (SendGrid)
SENDGRID_API_KEY=SG....
[email protected]

# Email (Resend)
RESEND_API_KEY=re_...

# LLM (Anthropic)
ANTHROPIC_API_KEY=sk-ant-...

# LLM (OpenAI)
OPENAI_API_KEY=sk-...

# DeepAgent
DEEPAGENT_API_URL=http://localhost:3000
DEEPAGENT_API_KEY=...

Testing

Use mock implementations:

import { MockIntegrationFactory } from '@almadar/integrations/mocks';

const mockFactory = new MockIntegrationFactory();

// Set mock response
mockFactory.setMockResponse('stripe', 'createPaymentIntent', {
  id: 'pi_test_123',
  clientSecret: 'secret_test_123',
  status: 'succeeded',
});

// Execute
const result = await mockFactory.execute('stripe', 'createPaymentIntent', {
  amount: 2000,
  currency: 'usd',
});

// Assert
expect(result.success).toBe(true);
expect(result.data).toHaveProperty('id');

// Check calls
const calls = mockFactory.getMockCalls('stripe');
expect(calls).toHaveLength(1);
expect(calls[0].action).toBe('createPaymentIntent');

Schema Usage

In .orb files, use call-service effect:

{
  "transitions": [{
    "from": "idle",
    "to": "processing",
    "event": "CHECKOUT",
    "effects": [
      ["call-service", "stripe", "createPaymentIntent", {
        "amount": "@payload.amount",
        "currency": "@payload.currency"
      }]
    ]
  }]
}

API

IntegrationFactory

const factory = new IntegrationFactory();

// Configure an integration
factory.configure('stripe', {
  env: { STRIPE_SECRET_KEY: '...' },
  timeout: 30000,
  retry: { maxAttempts: 3, backoffMs: 1000 }
});

// Execute an action
const result = await factory.execute('stripe', 'createPaymentIntent', params);

// Get integration instance
const stripe = factory.get('stripe');

RuntimeIntegrationManager

const manager = new RuntimeIntegrationManager();

// Auto-configure from environment
manager.configureFromEnv();

// Get effect handler
const callServiceHandler = manager.getCallServiceHandler();

// Get factory
const factory = manager.getFactory();

BaseIntegration

Extend for custom integrations:

import { BaseIntegration } from '@almadar/integrations';

class MyIntegration extends BaseIntegration {
  async execute(action, params) {
    const validation = this.validateParams(action, params);
    if (!validation.valid) {
      return { success: false, error: ... };
    }
    
    // Implement your logic
    const data = await this.myApiCall(params);
    
    return {
      success: true,
      data,
      metadata: this.createMetadata(action, duration)
    };
  }
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     .orb Schema File                         │
│  ["call-service", "stripe", "createPaymentIntent", {...}]    │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│           @almadar/patterns (Registry)                       │
│  integrators-registry.json - Defines actions & params        │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│         @almadar/integrations (THIS PACKAGE)                 │
│  - SDK wrappers                                              │
│  - Auth handling                                             │
│  - Error handling                                            │
│  - Type-safe implementations                                 │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│              Runtime / Compiled App                          │
│  - @almadar/runtime (interpreted)                            │
│  - Generated TypeScript/Python code (compiled)               │
└─────────────────────────────────────────────────────────────┘

License

MIT