@almadar/integrations 2.0.0 → 2.0.1

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,368 @@
+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
+ *
+ * Provides 4 actions:
+ * - generate: Generate text content from a prompt
+ * - classify: Classify text into predefined categories
+ * - extract: Extract structured data from text using a schema
+ * - summarize: Summarize long text content
+ */
+declare class LLMIntegration extends BaseIntegration {
+    private client;
+    private provider;
+    constructor(config: IntegrationConfig);
+    /**
+     * Lazily create client — avoids throwing on construction if API key is missing.
+     * The client will throw a clear error when actually used without a key.
+     */
+    private getClient;
+    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;
+}
+
+/**
+ * CLI integration for Almadar CLI commands.
+ *
+ * Wraps `@almadar/cli` commands (validate, compile) as integration actions.
+ * This runs server-side and executes CLI commands as child processes.
+ *
+ * Actions:
+ * - validate: Validate an orbital schema and return structured results
+ */
+declare class CLIIntegration extends BaseIntegration {
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private validate;
+}
+
+/**
+ * Redis / Cache integration with in-memory default backend.
+ *
+ * When `REDIS_URL` is provided in `config.env`, a warning is logged and the
+ * integration falls back to the in-memory store (real Redis client support is
+ * not yet implemented). When `REDIS_URL` is absent the in-memory store is
+ * used silently — this is the expected development mode.
+ */
+declare class RedisIntegration extends BaseIntegration {
+    private store;
+    private locks;
+    private channels;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Remove expired entries on access and return whether a key is alive. */
+    private isAlive;
+    /** Generate a unique lock identifier. */
+    private generateLockId;
+    private getKey;
+    private setKey;
+    private deleteKey;
+    private acquireLock;
+    private releaseLock;
+    private incrementKey;
+    private expireKey;
+    private publishMessage;
+    private subscribeChannel;
+}
+
+/**
+ * Queue integration with in-memory backend.
+ *
+ * Provides job queue semantics: enqueue, dequeue, status tracking,
+ * completion, failure, cancellation, and size queries.
+ */
+declare class QueueIntegration extends BaseIntegration {
+    /** Map from queue name to ordered list of job IDs */
+    private queues;
+    /** Map from job ID to job data */
+    private jobs;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Generate a unique job identifier. */
+    private generateJobId;
+    /** Get or create the queue array for a given queue name. */
+    private getQueue;
+    private enqueue;
+    private dequeue;
+    private status;
+    private complete;
+    private failJob;
+    private cancel;
+    private size;
+}
+
+/**
+ * OpenTelemetry integration with in-memory backend.
+ *
+ * Tracks spans and metrics internally for development and testing purposes.
+ * No actual OpenTelemetry SDK dependency is required.
+ */
+declare class OtelIntegration extends BaseIntegration {
+    private spans;
+    private metrics;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    private startSpan;
+    private endSpan;
+    private addEvent;
+    private recordMetric;
+    private getSpan;
+    private getAllMetrics;
+}
+
+/**
+ * OAuth2/OIDC integration with in-memory mock backend.
+ *
+ * This is a development/mock implementation. No actual OAuth library is used.
+ * State tokens, access tokens, and refresh tokens are generated in-memory and
+ * tracked via Maps. Useful for testing OAuth flows without external providers.
+ */
+declare class OAuthIntegration extends BaseIntegration {
+    /** Maps state token -> provider for pending authorization flows */
+    private states;
+    /** Maps access token -> token set */
+    private tokens;
+    /** Maps refresh token -> access token for refresh lookups */
+    private refreshIndex;
+    /** Maps access token -> mock user session */
+    private sessions;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Generate a random hex token of the given byte length. */
+    private generateToken;
+    /** Generate a mock user profile from a provider and access token. */
+    private generateMockUser;
+    private authorize;
+    private token;
+    private refresh;
+    private revoke;
+    private userinfo;
+}
+
+/**
+ * Storage integration with in-memory backend for development/testing.
+ *
+ * Provides S3-compatible object storage operations (upload, download, list,
+ * delete, getSignedUrl) backed by an in-memory Map. No cloud SDK dependencies
+ * are required.
+ */
+declare class StorageIntegration extends BaseIntegration {
+    private objects;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Build a composite key from bucket and object key. */
+    private compositeKey;
+    /** Generate a deterministic etag from content. */
+    private generateEtag;
+    /** Compute the byte size of content. */
+    private computeSize;
+    private upload;
+    private download;
+    private list;
+    private deleteObject;
+    private getSignedUrl;
+}
+
+/**
+ * Docker/Container integration with in-memory backend for development/testing.
+ *
+ * Provides container lifecycle operations (build, run, stop, remove, logs,
+ * status, list) backed by an in-memory Map. No Docker SDK or daemon connection
+ * is required.
+ */
+declare class DockerIntegration extends BaseIntegration {
+    private containers;
+    private images;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Generate a random hex container/image ID. */
+    private generateId;
+    /** Find a container by ID (prefix match supported). */
+    private findContainer;
+    /** Generate realistic log lines for a container. */
+    private generateLogLines;
+    private build;
+    private run;
+    private stop;
+    private removeContainer;
+    private logs;
+    private status;
+    private list;
+}
+
+export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationResult, LLMIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, type RetryConfig, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };

package/dist/mocks/index.d.ts

@@ -0,0 +1,50 @@
+import { B as BaseIntegration, b as IntegrationConfig, c as IntegrationResult, e as IntegrationFactory } from '../factory-rMujCO3M.js';
+
+/**
+ * Mock integration for testing
+ */
+declare class MockIntegration extends BaseIntegration {
+    private responses;
+    private calls;
+    constructor(config: IntegrationConfig);
+    /**
+     * Set mock response for an action
+     */
+    setResponse(action: string, data: unknown): void;
+    /**
+     * Get all calls made to this integration
+     */
+    getCalls(): Array<{
+        action: string;
+        params: Record<string, unknown>;
+    }>;
+    /**
+     * Clear all calls
+     */
+    clearCalls(): void;
+    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+}
+
+/**
+ * Mock integration factory for testing
+ */
+declare class MockIntegrationFactory extends IntegrationFactory {
+    constructor();
+    /**
+     * Set mock response for an integration action
+     */
+    setMockResponse(integration: string, action: string, data: unknown): void;
+    /**
+     * Get calls made to an integration
+     */
+    getMockCalls(integration: string): Array<{
+        action: string;
+        params: Record<string, unknown>;
+    }>;
+    /**
+     * Clear calls for an integration
+     */
+    clearMockCalls(integration: string): void;
+}
+
+export { MockIntegration, MockIntegrationFactory };

package/dist/runtime/index.d.ts

@@ -0,0 +1,29 @@
+import { e as IntegrationFactory } from '../factory-rMujCO3M.js';
+
+/**
+ * Runtime integration manager
+ * Auto-configures integrations from environment variables
+ */
+declare class RuntimeIntegrationManager {
+    private factory;
+    constructor();
+    /**
+     * Configure from environment variables
+     */
+    configureFromEnv(): void;
+    /**
+     * Get effect handler for runtime
+     */
+    getCallServiceHandler(): (service: string, action: string, params: Record<string, unknown> | undefined) => Promise<unknown>;
+    /**
+     * Get factory (for advanced usage)
+     */
+    getFactory(): IntegrationFactory;
+}
+
+/**
+ * Create a callService effect handler for @almadar/runtime
+ */
+declare function createCallServiceHandler(factory: IntegrationFactory): (service: string, action: string, params: Record<string, unknown> | undefined) => Promise<unknown>;
+
+export { RuntimeIntegrationManager, createCallServiceHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/integrations",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "External service integrations for Almadar applications",
   "type": "module",
   "main": "./dist/index.js",