@almadar/integrations 2.3.0 → 2.5.0

package/dist/{BaseIntegration-DNSuiUnG.d.ts → BaseIntegration-B9X5vK3f.d.ts}

@@ -66,14 +66,26 @@ declare class IntegrationError extends Error {
         details: unknown;
     };
 }
+/** Metadata attached to log entries */
+interface LogMeta {
+    [key: string]: string | number | boolean | null | undefined | Error | string[] | LogMeta;
+}
 /**
  * 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;
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
+}
+/**
+ * Integration action parameters.
+ * Each integration's execute() method receives params as this type.
+ * Individual methods cast to specific param shapes from their contracts.
+ */
+interface IntegrationParams {
+    [key: string]: string | number | boolean | null | undefined | string[] | IntegrationParams;
 }
 /**
  * Validation result
@@ -93,7 +105,7 @@ interface ValidationError {
 /**
  * Validate action params against registry schema
  */
-declare function validateParams(integration: string, action: string, params: Record<string, unknown>): ValidationResult;
+declare function validateParams(integration: string, action: string, params: IntegrationParams): ValidationResult;
 
 /**
  * Base class for all integrations
@@ -105,11 +117,11 @@ declare abstract class BaseIntegration {
     /**
      * Execute an action
      */
-    abstract execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    abstract execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /**
      * Validate action params against registry
      */
-    protected validateParams(action: string, params: Record<string, unknown>): ReturnType<typeof validateParams>;
+    protected validateParams(action: string, params: IntegrationParams): ReturnType<typeof validateParams>;
     /**
      * Handle errors uniformly
      */
@@ -124,4 +136,4 @@ declare abstract class BaseIntegration {
     protected executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
 }
 
-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, type ValidationResult as e, validateParams as v };
+export { BaseIntegration as B, type IntegrationParams as I, type LogMeta as L, type ValidationError as V, type IntegrationLogger as a, type IntegrationErrorCode as b, type IntegrationConfig as c, type IntegrationResult as d, IntegrationError as e, type ValidationResult as f, validateParams as v };

package/dist/{factory-B1QtCI_c.d.ts → factory-CSJzotsJ.d.ts}

@@ -1,4 +1,4 @@
-import { b as IntegrationConfig, B as BaseIntegration, c as IntegrationResult } from './BaseIntegration-DNSuiUnG.js';
+import { c as IntegrationConfig, B as BaseIntegration, I as IntegrationParams, d as IntegrationResult } from './BaseIntegration-B9X5vK3f.js';
 
 /**
  * Factory for creating and managing integration instances
@@ -17,7 +17,7 @@ declare class IntegrationFactory {
     /**
      * Execute an action on an integration
      */
-    execute(integration: string, action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(integration: string, action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /**
      * Check if integration is configured
      */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { I as IntegrationLogger, a as IntegrationErrorCode, b as IntegrationConfig, B as BaseIntegration, c as IntegrationResult } from './BaseIntegration-DNSuiUnG.js';
-export { d as IntegrationError, V as ValidationError, e as ValidationResult, v as validateParams } from './BaseIntegration-DNSuiUnG.js';
-export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-B1QtCI_c.js';
+import { I as IntegrationParams, a as IntegrationLogger, L as LogMeta, b as IntegrationErrorCode, c as IntegrationConfig, B as BaseIntegration, d as IntegrationResult } from './BaseIntegration-B9X5vK3f.js';
+export { e as IntegrationError, V as ValidationError, f as ValidationResult, v as validateParams } from './BaseIntegration-B9X5vK3f.js';
+export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-CSJzotsJ.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -174,10 +174,10 @@ type LLMIntegrationActions = {
     extract: {
         params: {
             text: string;
-            schema: Record<string, unknown>;
+            schema: IntegrationParams;
             model?: string;
         };
-        result: Record<string, unknown>;
+        result: IntegrationParams;
     };
     summarize: {
         params: {
@@ -386,7 +386,7 @@ type StorageActions = {
             key: string;
             content: unknown;
             contentType?: string;
-            metadata?: Record<string, unknown>;
+            metadata?: IntegrationParams;
         };
         result: {
             key: string;
@@ -404,7 +404,7 @@ type StorageActions = {
             content: unknown;
             contentType: string;
             size: number;
-            metadata: Record<string, unknown>;
+            metadata: IntegrationParams;
         };
     };
     list: {
@@ -660,7 +660,7 @@ type OtelActions = {
     startSpan: {
         params: {
             name: string;
-            attributes?: Record<string, unknown>;
+            attributes?: IntegrationParams;
             traceId?: string;
         };
         result: {
@@ -681,7 +681,7 @@ type OtelActions = {
         params: {
             spanId: string;
             name: string;
-            attributes?: Record<string, unknown>;
+            attributes?: IntegrationParams;
         };
         result: {
             added: boolean;
@@ -692,7 +692,7 @@ type OtelActions = {
             name: string;
             value: number;
             type?: 'counter' | 'gauge' | 'histogram';
-            labels?: Record<string, unknown>;
+            labels?: IntegrationParams;
         };
         result: {
             recorded: boolean;
@@ -709,7 +709,7 @@ type OtelActions = {
             startTime: number;
             endTime?: number;
             status?: 'ok' | 'error';
-            attributes: Record<string, unknown>;
+            attributes: IntegrationParams;
         } | null;
     };
     getMetrics: {
@@ -719,7 +719,7 @@ type OtelActions = {
             type: string;
             value: number;
             values: number[];
-            labels: Record<string, unknown>;
+            labels: IntegrationParams;
         }>;
     };
 };
@@ -742,7 +742,7 @@ type DeepAgentActions = {
             message: string;
             threadId?: string;
             skill?: string;
-            context?: Record<string, unknown>;
+            context?: IntegrationParams;
         };
         result: {
             response: string;
@@ -837,10 +837,10 @@ type IntegrationActionName<K extends IntegrationName> = keyof IntegrationContrac
 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;
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
     private shouldLog;
 }
 
@@ -885,7 +885,7 @@ declare function getRegisteredIntegrations(): string[];
 declare class StripeIntegration extends BaseIntegration {
     private client;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private createPaymentIntent;
     private confirmPayment;
     private refund;
@@ -897,7 +897,7 @@ declare class StripeIntegration extends BaseIntegration {
 declare class YouTubeIntegration extends BaseIntegration {
     private client;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private search;
     private getVideo;
     private getChannel;
@@ -910,7 +910,7 @@ declare class TwilioIntegration extends BaseIntegration {
     private client;
     private phoneNumber;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private sendSMS;
     private sendWhatsApp;
 }
@@ -923,7 +923,7 @@ declare class EmailIntegration extends BaseIntegration {
     private fromEmail;
     private resendClient?;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private send;
     private sendViaSendGrid;
     private sendViaResend;
@@ -947,7 +947,7 @@ declare class LLMIntegration extends BaseIntegration {
      * The client will throw a clear error when actually used without a key.
      */
     private getClient;
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private generate;
     private classify;
     private extract;
@@ -961,7 +961,7 @@ declare class DeepAgentIntegration extends BaseIntegration {
     private apiUrl;
     private apiKey;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private sendMessage;
     private cancelGeneration;
     private validateSchema;
@@ -981,7 +981,7 @@ declare class DeepAgentIntegration extends BaseIntegration {
  */
 declare class CLIIntegration extends BaseIntegration {
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private validate;
 }
 
@@ -998,7 +998,7 @@ declare class RedisIntegration extends BaseIntegration {
     private locks;
     private channels;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /** Remove expired entries on access and return whether a key is alive. */
     private isAlive;
     /** Generate a unique lock identifier. */
@@ -1026,7 +1026,7 @@ declare class QueueIntegration extends BaseIntegration {
     /** Map from job ID to job data */
     private jobs;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /** Generate a unique job identifier. */
     private generateJobId;
     /** Get or create the queue array for a given queue name. */
@@ -1050,7 +1050,7 @@ declare class OtelIntegration extends BaseIntegration {
     private spans;
     private metrics;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private startSpan;
     private endSpan;
     private addEvent;
@@ -1076,7 +1076,7 @@ declare class OAuthIntegration extends BaseIntegration {
     /** Maps access token -> mock user session */
     private sessions;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): 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. */
@@ -1098,7 +1098,7 @@ declare class OAuthIntegration extends BaseIntegration {
 declare class StorageIntegration extends BaseIntegration {
     private objects;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /** Build a composite key from bucket and object key. */
     private compositeKey;
     /** Generate a deterministic etag from content. */
@@ -1123,7 +1123,7 @@ declare class DockerIntegration extends BaseIntegration {
     private containers;
     private images;
     constructor(config: IntegrationConfig);
-    execute(action: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     /** Generate a random hex container/image ID. */
     private generateId;
     /** Find a container by ID (prefix match supported). */

package/dist/index.js

@@ -156,7 +156,7 @@ var BaseIntegration = class {
    */
   handleError(action, error) {
     this.logger.error(`Integration error in ${this.config.name}.${action}`, {
-      error
+      error: error instanceof Error ? error : new Error(String(error))
     });
     const integrationError = error instanceof Error ? error : new Error(String(error));
     return {
@@ -600,7 +600,7 @@ var EmailIntegration = class extends BaseIntegration {
   }
   async send(params) {
     const { to, subject, body, from } = params;
-    this.logger.debug("Sending email", { to, subject, provider: this.provider });
+    this.logger.debug("Sending email", { to: String(to), subject: String(subject), provider: this.provider });
     if (this.provider === "sendgrid") {
       return await this.sendViaSendGrid(
         to,
@@ -2547,7 +2547,7 @@ var DockerIntegration = class extends BaseIntegration {
     const env = params.env ?? {};
     const rawVolumes = params.volumes ?? [];
     const command = params.command ?? "";
-    this.logger.debug("Docker RUN", { image, name, ports: rawPorts, env, volumes: rawVolumes, command });
+    this.logger.debug("Docker RUN", { image, name, ports: rawPorts.map((p) => `${p.host}:${p.container}`), volumes: rawVolumes.map((v) => `${v.host}:${v.container}`), command });
     const containerId = this.generateId();
     const ports = rawPorts.map((p) => ({
       host: p.host,