@almadar/integrations 2.36.0 → 2.38.0

package/dist/index.js

@@ -54,8 +54,8 @@ var serviceCredentials = {
     { envVar: "TWILIO_PHONE_NUMBER", required: false, description: "Default sender phone number" }
   ],
   email: [
-    { envVar: "SENDGRID_API_KEY", required: false, description: "SendGrid API key (use this OR RESEND_API_KEY)" },
-    { envVar: "RESEND_API_KEY", required: false, description: "Resend API key (use this OR SENDGRID_API_KEY)" },
+    { envVar: "SENDGRID_API_KEY", required: false, oneOf: "provider", description: "SendGrid API key (use this OR RESEND_API_KEY)" },
+    { envVar: "RESEND_API_KEY", required: false, oneOf: "provider", description: "Resend API key (use this OR SENDGRID_API_KEY)" },
     { envVar: "FROM_EMAIL", required: false, description: "Default sender email address" }
   ],
   webhook: [
@@ -74,9 +74,9 @@ var serviceCredentials = {
     { envVar: "GOOGLE_CALENDAR_CHANNEL_TOKEN", required: false, description: "Watch-channel verification token \u2014 required to receive inbound calendar hooks (two-way sync)" }
   ],
   drive: [
-    { envVar: "GOOGLE_DRIVE_SA_KEY", required: false, description: "Google service-account key JSON (raw or base64) with drive scope \u2014 serves reads; store in Secret Manager, bind as env" },
+    { envVar: "GOOGLE_DRIVE_SA_KEY", required: false, oneOf: "auth", description: "Google service-account key JSON (raw or base64) with drive scope \u2014 serves reads; store in Secret Manager, bind as env" },
     { envVar: "GOOGLE_DRIVE_SUBJECT", required: false, description: "Workspace user to impersonate (domain-wide delegation); empty = act as the service account" },
-    { envVar: "GOOGLE_DRIVE_REFRESH_TOKEN", required: false, description: "User OAuth refresh token (drive-consent.mjs) \u2014 serves writes; SA uploads are impossible on personal accounts (no SA storage quota)" },
+    { envVar: "GOOGLE_DRIVE_REFRESH_TOKEN", required: false, oneOf: "auth", description: "User OAuth refresh token (drive-consent.mjs) \u2014 serves writes; SA uploads are impossible on personal accounts (no SA storage quota)" },
     { envVar: "GOOGLE_DRIVE_FOLDER_ID", required: false, description: "Default parent folder for uploads/new folders when the call names none" }
   ],
   metaAds: [
@@ -93,12 +93,13 @@ var serviceCredentials = {
     { envVar: "DOCUSIGN_ACCESS_TOKEN", required: true, description: "DocuSign OAuth access token (JWT grant rotation is the deployment concern)" }
   ],
   llm: [
-    { envVar: "ANTHROPIC_API_KEY", required: false, description: "Anthropic API key (use this OR OPENAI_API_KEY)" },
-    { envVar: "OPENAI_API_KEY", required: false, description: "OpenAI API key (use this OR ANTHROPIC_API_KEY)" }
+    { envVar: "ANTHROPIC_API_KEY", required: false, oneOf: "provider", description: "Anthropic API key (use this OR OPENAI_API_KEY)" },
+    { envVar: "OPENAI_API_KEY", required: false, oneOf: "provider", description: "OpenAI API key (use this OR ANTHROPIC_API_KEY)" },
+    { envVar: "LLM_PROVIDER", required: false, description: "Chat provider when several keys are set: anthropic | openai | deepseek | kimi | openrouter (default: the first key found)" }
   ],
   "llm-integration": [
-    { envVar: "ANTHROPIC_API_KEY", required: false, description: "Anthropic API key" },
-    { envVar: "OPENAI_API_KEY", required: false, description: "OpenAI API key" }
+    { envVar: "ANTHROPIC_API_KEY", required: false, oneOf: "provider", description: "Anthropic API key" },
+    { envVar: "OPENAI_API_KEY", required: false, oneOf: "provider", description: "OpenAI API key" }
   ],
   ml: [
     { envVar: "MASAR_URL", required: true, description: "Base URL of the deployed model-serving orbital" },
@@ -255,13 +256,14 @@ function validateParams(integration, action, params) {
     }
   }
   for (const paramDef of actionDef.params) {
-    if (paramDef.required && !(paramDef.name in params)) {
+    const provided = params[paramDef.name] !== void 0;
+    if (paramDef.required && !provided) {
       errors.push({
         param: paramDef.name,
         message: `Missing required parameter: ${paramDef.name}`
       });
     }
-    if (paramDef.name in params) {
+    if (provided) {
       const value = params[paramDef.name];
       const expectedType = paramDef.type;
       const actualType = typeof value;
@@ -342,6 +344,14 @@ var BaseIntegration = class {
   validateParams(action, params) {
     return validateParams(this.config.name, action, params);
   }
+  /** A rejected call: a real IntegrationError naming every failing param (kept in `details`). */
+  validationFailure(action, errors) {
+    const reasons = errors.map((e) => `${e.param}: ${e.message}`).join("; ");
+    const error = new IntegrationError(`Validation failed for ${this.config.name}.${action}: ${reasons}`, "VALIDATION_ERROR", errors);
+    error.integration = this.config.name;
+    error.action = action;
+    return { success: false, error, metadata: this.createMetadata(action, 0) };
+  }
   /**
    * Handle errors uniformly
    */
@@ -432,13 +442,13 @@ var IntegrationFactory = class {
     }
     const Constructor = getIntegration(name);
     if (!Constructor) {
-      throw new Error(`Unknown integration: ${name}. Make sure it's imported.`);
+      throw new IntegrationError(`Unknown integration: ${name}. Make sure it's imported.`, "UNKNOWN_INTEGRATION");
     }
     const config = this.configs.get(key) ?? this.configs.get(name);
     if (!config) {
-      throw new Error(
-        `Integration not configured: ${name}. Call configure() first.`
-      );
+      const envVars = (serviceCredentials[name] ?? []).map((c) => c.envVar);
+      const needs = envVars.length > 0 ? ` Set ${envVars.join(" / ")}.` : "";
+      throw new IntegrationError(`Integration not configured: ${name}.${needs}`, "NOT_CONFIGURED");
     }
     const instance = new Constructor(config);
     this.instances.set(key, instance);
@@ -995,18 +1005,7 @@ var StripeIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     const retries = 0;
     try {
@@ -1224,18 +1223,7 @@ var YouTubeIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -1329,18 +1317,7 @@ var TwilioIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -1414,18 +1391,7 @@ var EmailIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -1498,8 +1464,11 @@ var EmailIntegration = class extends BaseIntegration {
       ...message.htmlBody ? { text: message.body } : {},
       ...message.replyTo ? { replyTo: message.replyTo } : {}
     });
+    if (response.error || !response.data) {
+      throw new Error(`Resend rejected the email: ${response.error?.message ?? "no message id returned"}`);
+    }
     return {
-      id: response.data?.id,
+      id: response.data.id,
       status: "sent"
     };
   }
@@ -1514,18 +1483,7 @@ var WebhookIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -1605,18 +1563,7 @@ var PushIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -1737,18 +1684,7 @@ var CalendarIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -2010,18 +1946,7 @@ var DriveIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2157,18 +2082,7 @@ var MetaAdsIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2256,18 +2170,7 @@ var AccountingIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2335,18 +2238,7 @@ var BankingIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2459,18 +2351,7 @@ var EsignIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2607,18 +2488,7 @@ var LLMIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2659,16 +2529,14 @@ var LLMIntegration = class extends BaseIntegration {
       maxTokens
     } = params;
     this.logger.debug("Generating content", { model, temperature });
-    const client = model ? new LLMClient({ provider: this.provider, model, temperature: temperature ?? 0.7 }) : this.getClient();
-    const response = await client.callWithMetadata({
+    const client = model !== void 0 || temperature !== void 0 ? new LLMClient({ provider: this.provider, model, temperature: temperature ?? 0.7 }) : this.getClient();
+    const response = await client.callRawWithMetadata({
       systemPrompt: systemPrompt || "You are a helpful assistant.",
       userPrompt,
-      maxTokens: maxTokens ?? 1024,
-      temperature,
-      skipSchemaValidation: true
+      maxTokens: maxTokens ?? 1024
     });
     return {
-      content: response.data,
+      content: response.raw,
       usage: response.usage ? {
         promptTokens: response.usage.promptTokens,
         completionTokens: response.usage.completionTokens,
@@ -2785,18 +2653,7 @@ var MLIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -2905,18 +2762,7 @@ var DeepAgentIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -3350,18 +3196,7 @@ var GitHubIntegration = class extends BaseIntegration {
    */
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     let retries = 0;
     try {
@@ -3652,18 +3487,7 @@ var RedisIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -3866,18 +3690,7 @@ var QueueIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -4076,18 +3889,7 @@ var OtelIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -4279,18 +4081,7 @@ var OAuthIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -4592,18 +4383,7 @@ var CredentialsIntegration = class extends BaseIntegration {
       }
     }
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -4804,18 +4584,7 @@ var StorageIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5094,18 +4863,7 @@ var DockerIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5530,18 +5288,7 @@ var DatabaseIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5609,18 +5356,7 @@ var WikimediaIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5678,18 +5414,7 @@ var IconifyIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5788,18 +5513,7 @@ var ArxivIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
     try {
       let data;
@@ -5871,32 +5585,10 @@ var RiggerIntegration = class extends BaseIntegration {
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          name: "IntegrationError",
-          message: "Validation failed",
-          code: "VALIDATION_ERROR",
-          details: validation.errors
-        },
-        metadata: this.createMetadata(action, 0)
-      };
-    }
+    if (!validation.valid) return this.validationFailure(action, validation.errors);
     if (action === "generate") {
       const invalid = generateParamErrors(params);
-      if (invalid.length > 0) {
-        return {
-          success: false,
-          error: {
-            name: "IntegrationError",
-            message: "Validation failed",
-            code: "VALIDATION_ERROR",
-            details: invalid
-          },
-          metadata: this.createMetadata(action, 0)
-        };
-      }
+      if (invalid.length > 0) return this.validationFailure(action, invalid.map((message) => ({ param: "params", message })));
     }
     const startTime = Date.now();
     try {