@almadar/integrations 2.0.3 → 2.0.5

package/dist/index.d.ts

@@ -3,6 +3,834 @@ export { d as IntegrationError, V as ValidationError, e as ValidationResult, v a
 export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-B1QtCI_c.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
+/**
+ * ServiceContract type definitions for all @almadar/integrations.
+ *
+ * Each integration defines its own action map as a Record<string, ServiceAction>,
+ * suitable for use with ServiceContract<T> from @almadar/core.
+ *
+ * Types are simplified representations of the actual params/results. They capture
+ * the contract shape without pulling in third-party SDK types (Stripe, Twilio, etc.).
+ *
+ * @packageDocumentation
+ */
+
+type GitHubActions = {
+    cloneRepo: {
+        params: {
+            repoUrl: string;
+            targetDir: string;
+            branch?: string;
+        };
+        result: {
+            message: string;
+        };
+    };
+    createBranch: {
+        params: {
+            branchName: string;
+            baseBranch?: string;
+        };
+        result: {
+            message: string;
+        };
+    };
+    commit: {
+        params: {
+            message: string;
+            files?: string[];
+        };
+        result: {
+            message: string;
+        };
+    };
+    push: {
+        params: {
+            branchName: string;
+            force?: boolean;
+        };
+        result: {
+            message: string;
+        };
+    };
+    createPR: {
+        params: {
+            title: string;
+            body: string;
+            head: string;
+            base: string;
+        };
+        result: {
+            number: number;
+            url: string;
+            title: string;
+        };
+    };
+    getPRComments: {
+        params: {
+            prNumber: number;
+        };
+        result: {
+            comments: Array<{
+                id: number;
+                body: string;
+                user: string;
+            }>;
+        };
+    };
+    listIssues: {
+        params: {
+            state?: string;
+            labels?: string[];
+            per_page?: number;
+        };
+        result: {
+            issues: Array<{
+                number: number;
+                title: string;
+                state: string;
+            }>;
+        };
+    };
+    getIssue: {
+        params: {
+            issueNumber: number;
+        };
+        result: {
+            number: number;
+            title: string;
+            body: string;
+            state: string;
+        };
+    };
+};
+type StripeActions = {
+    createPaymentIntent: {
+        params: {
+            amount: number;
+            currency: string;
+            metadata?: Record<string, string>;
+        };
+        result: {
+            id: string;
+            clientSecret: string;
+            status: string;
+            amount: number;
+            currency: string;
+        };
+    };
+    confirmPayment: {
+        params: {
+            paymentIntentId: string;
+        };
+        result: {
+            id: string;
+            status: string;
+        };
+    };
+    refund: {
+        params: {
+            paymentIntentId: string;
+            amount?: number;
+        };
+        result: {
+            id: string;
+            status: string;
+            amount: number;
+        };
+    };
+};
+type LLMIntegrationActions = {
+    generate: {
+        params: {
+            userPrompt: string;
+            systemPrompt?: string;
+            model?: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        result: {
+            content: string;
+            usage: {
+                promptTokens?: number;
+                completionTokens?: number;
+                totalTokens?: number;
+                tokens?: number;
+            };
+        };
+    };
+    classify: {
+        params: {
+            text: string;
+            categories: string[];
+            model?: string;
+        };
+        result: {
+            category: string;
+            confidence: number;
+            reasoning: string;
+        };
+    };
+    extract: {
+        params: {
+            text: string;
+            schema: Record<string, unknown>;
+            model?: string;
+        };
+        result: Record<string, unknown>;
+    };
+    summarize: {
+        params: {
+            text: string;
+            maxLength?: number;
+            style?: string;
+            model?: string;
+        };
+        result: {
+            summary: string;
+            keyPoints: string[];
+        };
+    };
+};
+type YouTubeActions = {
+    search: {
+        params: {
+            query: string;
+            maxResults?: number;
+            type?: string;
+        };
+        result: Array<{
+            videoId: string;
+            title: string;
+            thumbnail: string;
+            description: string;
+        }>;
+    };
+    getVideo: {
+        params: {
+            videoId: string;
+        };
+        result: {
+            title: string;
+            description: string;
+            viewCount: string;
+            likeCount: string;
+        };
+    };
+    getChannel: {
+        params: {
+            channelId: string;
+        };
+        result: {
+            name: string;
+            description: string;
+            subscriberCount: string;
+        };
+    };
+};
+type TwilioActions = {
+    sendSMS: {
+        params: {
+            to: string;
+            body: string;
+        };
+        result: {
+            sid: string;
+            status: string;
+        };
+    };
+    sendWhatsApp: {
+        params: {
+            to: string;
+            body: string;
+        };
+        result: {
+            sid: string;
+            status: string;
+        };
+    };
+};
+type EmailActions = {
+    send: {
+        params: {
+            to: string;
+            subject: string;
+            body: string;
+            from?: string;
+        };
+        result: {
+            id: string;
+            status: string;
+        };
+    };
+};
+type DockerActions = {
+    build: {
+        params: {
+            tag: string;
+            dockerfile?: string;
+            context?: string;
+            buildArgs?: Record<string, string>;
+        };
+        result: {
+            imageId: string;
+            tag: string;
+            size: number;
+            buildTime: number;
+        };
+    };
+    run: {
+        params: {
+            image: string;
+            name?: string;
+            ports?: Array<{
+                host: number;
+                container: number;
+                protocol?: string;
+            }>;
+            env?: Record<string, string>;
+            volumes?: Array<{
+                host: string;
+                container: string;
+            }>;
+            command?: string;
+        };
+        result: {
+            containerId: string;
+            name: string;
+            status: string;
+            ports: Array<{
+                host: number;
+                container: number;
+                protocol: string;
+            }>;
+        };
+    };
+    stop: {
+        params: {
+            containerId: string;
+        };
+        result: {
+            containerId: string;
+            status: string;
+            stoppedAt: number;
+        };
+    };
+    remove: {
+        params: {
+            containerId: string;
+            force?: boolean;
+        };
+        result: {
+            containerId: string;
+            removed: boolean;
+        };
+    };
+    logs: {
+        params: {
+            containerId: string;
+            tail?: number;
+            since?: string;
+        };
+        result: {
+            containerId: string;
+            logs: string[];
+            lineCount: number;
+        };
+    };
+    status: {
+        params: {
+            containerId: string;
+        };
+        result: {
+            containerId: string;
+            name: string;
+            image: string;
+            status: string;
+            ports: Array<{
+                host: number;
+                container: number;
+                protocol: string;
+            }>;
+            createdAt: number;
+            startedAt: number | null;
+            stoppedAt: number | null;
+        };
+    };
+    list: {
+        params: {
+            all?: boolean;
+            filterByLabel?: string;
+        };
+        result: {
+            containers: Array<{
+                id: string;
+                name: string;
+                image: string;
+                status: string;
+                ports: Array<{
+                    host: number;
+                    container: number;
+                    protocol: string;
+                }>;
+                createdAt: number;
+            }>;
+            total: number;
+        };
+    };
+};
+type StorageActions = {
+    upload: {
+        params: {
+            bucket: string;
+            key: string;
+            content: unknown;
+            contentType?: string;
+            metadata?: Record<string, unknown>;
+        };
+        result: {
+            key: string;
+            bucket: string;
+            size: number;
+            etag: string;
+        };
+    };
+    download: {
+        params: {
+            bucket: string;
+            key: string;
+        };
+        result: {
+            content: unknown;
+            contentType: string;
+            size: number;
+            metadata: Record<string, unknown>;
+        };
+    };
+    list: {
+        params: {
+            bucket: string;
+            prefix?: string;
+            maxKeys?: number;
+        };
+        result: {
+            keys: Array<{
+                key: string;
+                size: number;
+                lastModified: number;
+            }>;
+            truncated: boolean;
+        };
+    };
+    delete: {
+        params: {
+            bucket: string;
+            key: string;
+        };
+        result: {
+            deleted: boolean;
+        };
+    };
+    getSignedUrl: {
+        params: {
+            bucket: string;
+            key: string;
+            expiresIn?: number;
+            operation?: 'get' | 'put';
+        };
+        result: {
+            url: string;
+            expiresAt: number;
+        };
+    };
+};
+type QueueActions = {
+    enqueue: {
+        params: {
+            queue: string;
+            payload: unknown;
+            delay?: number;
+            priority?: number;
+        };
+        result: {
+            jobId: string;
+            position: number;
+        };
+    };
+    dequeue: {
+        params: {
+            queue: string;
+        };
+        result: {
+            job: {
+                id: string;
+                payload: unknown;
+                enqueuedAt: number;
+                priority: number;
+            } | null;
+        };
+    };
+    status: {
+        params: {
+            jobId: string;
+        };
+        result: {
+            status: 'pending' | 'processing' | 'completed' | 'failed';
+            job: {
+                id: string;
+                payload: unknown;
+                enqueuedAt: number;
+                priority: number;
+            } | null;
+        };
+    };
+    complete: {
+        params: {
+            jobId: string;
+            result?: unknown;
+        };
+        result: {
+            completed: boolean;
+        };
+    };
+    fail: {
+        params: {
+            jobId: string;
+            error?: string;
+        };
+        result: {
+            failed: boolean;
+        };
+    };
+    cancel: {
+        params: {
+            jobId: string;
+        };
+        result: {
+            cancelled: boolean;
+        };
+    };
+    size: {
+        params: {
+            queue: string;
+        };
+        result: {
+            size: number;
+            pending: number;
+            processing: number;
+        };
+    };
+};
+type RedisActions = {
+    get: {
+        params: {
+            key: string;
+        };
+        result: {
+            value: unknown;
+        };
+    };
+    set: {
+        params: {
+            key: string;
+            value: unknown;
+            ttl?: number;
+        };
+        result: {
+            ok: boolean;
+        };
+    };
+    delete: {
+        params: {
+            key: string;
+        };
+        result: {
+            deleted: boolean;
+        };
+    };
+    lock: {
+        params: {
+            key: string;
+            ttl?: number;
+        };
+        result: {
+            acquired: boolean;
+            lockId: string;
+        };
+    };
+    unlock: {
+        params: {
+            key: string;
+            lockId: string;
+        };
+        result: {
+            released: boolean;
+        };
+    };
+    increment: {
+        params: {
+            key: string;
+            by?: number;
+        };
+        result: {
+            value: number;
+        };
+    };
+    expire: {
+        params: {
+            key: string;
+            ttl: number;
+        };
+        result: {
+            set: boolean;
+        };
+    };
+    publish: {
+        params: {
+            channel: string;
+            message: unknown;
+        };
+        result: {
+            receivers: number;
+        };
+    };
+    subscribe: {
+        params: {
+            channel: string;
+        };
+        result: {
+            subscribed: boolean;
+        };
+    };
+};
+type OAuthActions = {
+    authorize: {
+        params: {
+            provider: 'google' | 'github' | 'auth0';
+            scopes: string[];
+            redirectUri: string;
+        };
+        result: {
+            authUrl: string;
+            state: string;
+        };
+    };
+    token: {
+        params: {
+            code: string;
+            state: string;
+        };
+        result: {
+            accessToken: string;
+            refreshToken: string;
+            expiresIn: number;
+            tokenType: 'bearer';
+        };
+    };
+    refresh: {
+        params: {
+            refreshToken: string;
+        };
+        result: {
+            accessToken: string;
+            expiresIn: number;
+        };
+    };
+    revoke: {
+        params: {
+            token: string;
+        };
+        result: {
+            revoked: boolean;
+        };
+    };
+    userinfo: {
+        params: {
+            accessToken: string;
+        };
+        result: {
+            sub: string;
+            email: string;
+            name: string;
+            picture: string;
+        };
+    };
+};
+type OtelActions = {
+    startSpan: {
+        params: {
+            name: string;
+            attributes?: Record<string, unknown>;
+            traceId?: string;
+        };
+        result: {
+            spanId: string;
+            traceId: string;
+        };
+    };
+    endSpan: {
+        params: {
+            spanId: string;
+            status?: 'ok' | 'error';
+        };
+        result: {
+            ended: boolean;
+        };
+    };
+    addEvent: {
+        params: {
+            spanId: string;
+            name: string;
+            attributes?: Record<string, unknown>;
+        };
+        result: {
+            added: boolean;
+        };
+    };
+    recordMetric: {
+        params: {
+            name: string;
+            value: number;
+            type?: 'counter' | 'gauge' | 'histogram';
+            labels?: Record<string, unknown>;
+        };
+        result: {
+            recorded: boolean;
+        };
+    };
+    getSpan: {
+        params: {
+            spanId: string;
+        };
+        result: {
+            spanId: string;
+            traceId: string;
+            name: string;
+            startTime: number;
+            endTime?: number;
+            status?: 'ok' | 'error';
+            attributes: Record<string, unknown>;
+        } | null;
+    };
+    getMetrics: {
+        params: Record<string, never>;
+        result: Record<string, {
+            name: string;
+            type: string;
+            value: number;
+            values: number[];
+            labels: Record<string, unknown>;
+        }>;
+    };
+};
+type CLIActions = {
+    validate: {
+        params: {
+            schema: string;
+        };
+        result: {
+            valid: boolean;
+            errors: string[];
+            warnings: string[];
+            summary: string;
+        };
+    };
+};
+type DeepAgentActions = {
+    sendMessage: {
+        params: {
+            message: string;
+            threadId?: string;
+            skill?: string;
+            context?: Record<string, unknown>;
+        };
+        result: {
+            response: string;
+            threadId: string;
+        };
+    };
+    cancelGeneration: {
+        params: {
+            threadId: string;
+        };
+        result: {
+            cancelled: boolean;
+        };
+    };
+    validateSchema: {
+        params: {
+            schema: string;
+        };
+        result: {
+            valid: boolean;
+            errors: string[];
+        };
+    };
+    compileSchema: {
+        params: {
+            schema: string;
+            shell?: string;
+        };
+        result: {
+            output: string;
+            files: string[];
+        };
+    };
+    getThreadHistory: {
+        params: {
+            threadId: string;
+        };
+        result: {
+            messages: Array<{
+                role: string;
+                content: string;
+                timestamp: number;
+            }>;
+        };
+    };
+};
+/**
+ * Maps each integration name (as used in `registerIntegration`) to its action
+ * map type. Use with `ServiceContract<IntegrationContracts[K]>` to get a fully
+ * typed service interface for a specific integration.
+ *
+ * @example
+ * ```typescript
+ * import type { ServiceContract } from '@almadar/core';
+ * import type { IntegrationContracts } from '@almadar/integrations';
+ *
+ * type TypedStripe = ServiceContract<IntegrationContracts['stripe']>;
+ * ```
+ */
+type IntegrationContracts = {
+    github: GitHubActions;
+    stripe: StripeActions;
+    llm: LLMIntegrationActions;
+    youtube: YouTubeActions;
+    twilio: TwilioActions;
+    email: EmailActions;
+    docker: DockerActions;
+    storage: StorageActions;
+    queue: QueueActions;
+    redis: RedisActions;
+    oauth: OAuthActions;
+    otel: OtelActions;
+    cli: CLIActions;
+    deepagent: DeepAgentActions;
+};
+/** Integration name literal union. */
+type IntegrationName = keyof IntegrationContracts;
+/**
+ * Helper: extract the action names for a given integration.
+ *
+ * @example
+ * ```typescript
+ * type StripeAction = IntegrationActionName<'stripe'>;
+ * // => 'createPaymentIntent' | 'confirmPayment' | 'refund'
+ * ```
+ */
+type IntegrationActionName<K extends IntegrationName> = keyof IntegrationContracts[K] & string;
+
 /**
  * Console-based logger implementation
  */
@@ -311,4 +1139,4 @@ declare class DockerIntegration extends BaseIntegration {
     private list;
 }
 
-export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, DockerIntegration, EmailIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationResult, LLMIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, type RetryConfig, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };
+export { BaseIntegration, type CLIActions, CLIIntegration, ConsoleLogger, type DeepAgentActions, DeepAgentIntegration, type DockerActions, DockerIntegration, type EmailActions, EmailIntegration, type GitHubActions, type IntegrationActionName, IntegrationConfig, type IntegrationConstructor, type IntegrationContracts, IntegrationErrorCode, IntegrationLogger, type IntegrationName, IntegrationResult, LLMIntegration, type LLMIntegrationActions, type OAuthActions, OAuthIntegration, type OtelActions, OtelIntegration, type QueueActions, QueueIntegration, type RedisActions, RedisIntegration, type RetryConfig, type StorageActions, StorageIntegration, type StripeActions, StripeIntegration, type TwilioActions, TwilioIntegration, type YouTubeActions, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };