@almadar/integrations 1.0.15 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/integrations",
-  "version": "1.0.15",
+  "version": "2.0.0",
   "description": "External service integrations for Almadar applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,10 @@
     "./mocks": {
       "import": "./dist/mocks/index.js",
       "types": "./dist/mocks/index.d.ts"
+    },
+    "./github": {
+      "import": "./dist/integrations/github/index.js",
+      "types": "./dist/integrations/github/index.d.ts"
     }
   },
   "files": [
@@ -28,16 +32,16 @@
     "access": "public"
   },
   "dependencies": {
+    "@almadar/core": ">=2.0.0",
+    "@almadar/patterns": ">=2.0.0",
+    "@almadar/llm": ">=2.0.0",
     "stripe": "^17.5.0",
     "twilio": "^5.3.6",
     "@sendgrid/mail": "^8.1.4",
     "resend": "^4.0.1",
     "googleapis": "^144.0.0",
     "dotenv": "^16.4.0",
-    "zod": "^3.23.0",
-    "@almadar/core": "1.0.17",
-    "@almadar/patterns": "1.1.1",
-    "@almadar/llm": "1.0.16"
+    "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -48,7 +52,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/almadar-io/almadar.git",
-    "directory": "packages/almadar-integrations"
+    "directory": "docs/packages/integrations"
   },
   "license": "MIT",
   "keywords": [
@@ -61,6 +65,7 @@
     "llm",
     "api"
   ],
+  "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",

package/dist/factory-rMujCO3M.d.ts

@@ -1,159 +0,0 @@
-/**
- * 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

@@ -1,214 +0,0 @@
-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;
-}
-
-export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, EmailIntegration, GitHubIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationResult, LLMIntegration, type RetryConfig, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };

package/dist/mocks/index.d.ts

@@ -1,50 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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 };