@almadar/integrations 1.0.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/README.md

@@ -0,0 +1,290 @@
+# @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
+
+```bash
+pnpm add @almadar/integrations
+```
+
+## Usage
+
+### 1. Runtime Integration
+
+Use with `@almadar/runtime`:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```bash
+# 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....
+FROM_EMAIL=noreply@example.com
+
+# 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:
+
+```typescript
+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:
+
+```json
+{
+  "transitions": [{
+    "from": "idle",
+    "to": "processing",
+    "event": "CHECKOUT",
+    "effects": [
+      ["call-service", "stripe", "createPaymentIntent", {
+        "amount": "@payload.amount",
+        "currency": "@payload.currency"
+      }]
+    ]
+  }]
+}
+```
+
+## API
+
+### IntegrationFactory
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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

package/dist/factory-rMujCO3M.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Core types for Almadar integrations
+ */
+/**
+ * Configuration for an integration instance
+ */
+interface IntegrationConfig {
+    /** Integration name (matches registry) */
+    name: string;
+    /** Environment variables (API keys, secrets) */
+    env: Record<string, string>;
+    /** Optional logger */
+    logger?: IntegrationLogger;
+    /** Optional rate limiting config */
+    rateLimit?: {
+        requestsPerSecond: number;
+        burstSize: number;
+    };
+    /** Optional timeout (ms) */
+    timeout?: number;
+    /** Optional retry config */
+    retry?: {
+        maxAttempts: number;
+        backoffMs: number;
+        maxBackoffMs?: number;
+    };
+}
+/**
+ * Result of an integration action call
+ */
+interface IntegrationResult<T = unknown> {
+    /** Success flag */
+    success: boolean;
+    /** Response data (on success) */
+    data?: T;
+    /** Error (on failure) */
+    error?: IntegrationError;
+    /** Metadata (timing, retries, etc.) */
+    metadata: {
+        integration: string;
+        action: string;
+        duration: number;
+        retries: number;
+        timestamp: number;
+    };
+}
+/**
+ * Integration error codes
+ */
+type IntegrationErrorCode = 'VALIDATION_ERROR' | 'AUTH_ERROR' | 'RATE_LIMIT_ERROR' | 'TIMEOUT_ERROR' | 'NETWORK_ERROR' | 'SERVICE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Integration error
+ */
+declare class IntegrationError extends Error {
+    code: IntegrationErrorCode;
+    integration?: string;
+    action?: string;
+    details?: unknown;
+    constructor(message: string, code?: IntegrationErrorCode, details?: unknown);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: IntegrationErrorCode;
+        integration: string | undefined;
+        action: string | undefined;
+        details: unknown;
+    };
+}
+/**
+ * Logger interface
+ */
+interface IntegrationLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validation error
+ */
+interface ValidationError {
+    param: string;
+    message: string;
+}
+
+/**
+ * Validate action params against registry schema
+ */
+declare function validateParams(integration: string, action: string, params: Record<string, unknown>): ValidationResult;
+
+/**
+ * Base class for all integrations
+ */
+declare abstract class BaseIntegration {
+    protected config: IntegrationConfig;
+    protected logger: IntegrationLogger;
+    constructor(config: IntegrationConfig);
+    /**
+     * Execute an action
+     */
+    abstract execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /**
+     * Validate action params against registry
+     */
+    protected validateParams(action: string, params: Record<string, unknown>): ReturnType<typeof validateParams>;
+    /**
+     * Handle errors uniformly
+     */
+    protected handleError(action: string, error: unknown): IntegrationResult;
+    /**
+     * Create metadata for result
+     */
+    protected createMetadata(action: string, duration: number, retries?: number): IntegrationResult['metadata'];
+    /**
+     * Execute with retry logic
+     */
+    protected executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Factory for creating and managing integration instances
+ */
+declare class IntegrationFactory {
+    private instances;
+    private configs;
+    /**
+     * Configure an integration (doesn't instantiate yet)
+     */
+    configure(name: string, config: Omit<IntegrationConfig, 'name'>): void;
+    /**
+     * Get or create an integration instance
+     */
+    get(name: string): BaseIntegration;
+    /**
+     * Execute an action on an integration
+     */
+    execute(integration: string, action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /**
+     * Check if integration is configured
+     */
+    isConfigured(name: string): boolean;
+    /**
+     * Clear all instances (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Clear all instances and configs
+     */
+    reset(): void;
+}
+
+export { BaseIntegration as B, type IntegrationLogger as I, type ValidationError as V, type IntegrationErrorCode as a, type IntegrationConfig as b, type IntegrationResult as c, IntegrationError as d, IntegrationFactory as e, type ValidationResult as f, validateParams as v };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { I as IntegrationLogger, a as IntegrationErrorCode, b as IntegrationConfig, B as BaseIntegration, c as IntegrationResult } from './factory-rMujCO3M.js';
+export { d as IntegrationError, e as IntegrationFactory, V as ValidationError, f as ValidationResult, v as validateParams } from './factory-rMujCO3M.js';
+
+/**
+ * Console-based logger implementation
+ */
+declare class ConsoleLogger implements IntegrationLogger {
+    private level;
+    constructor(level?: 'debug' | 'info' | 'warn' | 'error');
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    private shouldLog;
+}
+
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    maxAttempts: number;
+    backoffMs: number;
+    maxBackoffMs?: number;
+    retryableErrors?: IntegrationErrorCode[];
+}
+/**
+ * Execute a function with retry logic
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
+
+/**
+ * Integration constructor type
+ */
+type IntegrationConstructor = new (config: IntegrationConfig) => BaseIntegration;
+/**
+ * Register an integration
+ */
+declare function registerIntegration(name: string, constructor: IntegrationConstructor): void;
+/**
+ * Get integration constructor by name
+ */
+declare function getIntegration(name: string): IntegrationConstructor | undefined;
+/**
+ * Check if integration is known
+ */
+declare function isKnownIntegration(name: string): boolean;
+/**
+ * Get all registered integration names
+ */
+declare function getRegisteredIntegrations(): string[];
+
+/**
+ * Stripe integration for payment processing
+ */
+declare class StripeIntegration extends BaseIntegration {
+    private client;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private createPaymentIntent;
+    private confirmPayment;
+    private refund;
+}
+
+/**
+ * YouTube Data API integration
+ */
+declare class YouTubeIntegration extends BaseIntegration {
+    private client;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private search;
+    private getVideo;
+    private getChannel;
+}
+
+/**
+ * Twilio messaging integration
+ */
+declare class TwilioIntegration extends BaseIntegration {
+    private client;
+    private phoneNumber;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private sendSMS;
+    private sendWhatsApp;
+}
+
+/**
+ * Email integration (SendGrid/Resend)
+ */
+declare class EmailIntegration extends BaseIntegration {
+    private provider;
+    private fromEmail;
+    private resendClient?;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private send;
+    private sendViaSendGrid;
+    private sendViaResend;
+}
+
+/**
+ * LLM integration using @almadar/llm
+ */
+declare class LLMIntegration extends BaseIntegration {
+    private client;
+    private provider;
+    constructor(config: IntegrationConfig);
+    private createLLMClient;
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private generate;
+    private classify;
+    private extract;
+    private summarize;
+}
+
+/**
+ * DeepAgent integration for AI code generation
+ */
+declare class DeepAgentIntegration extends BaseIntegration {
+    private apiUrl;
+    private apiKey;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private sendMessage;
+    private cancelGeneration;
+    private validateSchema;
+    private compileSchema;
+    private getThreadHistory;
+    private request;
+}
+
+/**
+ * GitHub Integration for Almadar
+ * Provides git operations and GitHub API access for the agent
+ */
+
+/**
+ * GitHub integration class
+ */
+declare class GitHubIntegration extends BaseIntegration {
+    private token;
+    private owner;
+    private repo;
+    private workDir;
+    constructor(config: IntegrationConfig);
+    /**
+     * Execute a GitHub action
+     */
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /**
+     * Clone a repository
+     */
+    private cloneRepo;
+    /**
+     * Create a branch
+     */
+    private createBranch;
+    /**
+     * Commit changes
+     */
+    private commit;
+    /**
+     * Push branch
+     */
+    private push;
+    /**
+     * Create a pull request
+     */
+    private createPR;
+    /**
+     * Get PR comments
+     */
+    private getPRComments;
+    /**
+     * List issues
+     */
+    private listIssues;
+    /**
+     * Get issue details
+     */
+    private getIssue;
+    /**
+     * Get API config for GitHub API calls
+     */
+    private getAPIConfig;
+}
+
+export { BaseIntegration, ConsoleLogger, DeepAgentIntegration, EmailIntegration, GitHubIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationResult, LLMIntegration, type RetryConfig, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };