@jskit-ai/connectors-catalog 0.1.67 → 0.2.0

package/src/server/n8n.js

@@ -12,7 +12,7 @@ const n8nProvider = Object.freeze({
   oauth: (settings) => {
     const discovery = settings.oauthDiscovery;
     if (!validN8nOAuthDiscovery(discovery) || discovery.resource !== new URL(settings.serverUrl).href) {
-      throw new ConnectorError("connector_discovery_required", "Discover OAuth settings for this exact n8n MCP URL before connecting.");
+      throw new ConnectorError("connector_discovery_required", "Discover OAuth settings for this exact n8n MCP URL before connecting.", { messageCode: "connectors.n8n.discoverOauthSettingsExactMcp" });
     }
     return discovery.oauth;
   },
@@ -51,8 +51,8 @@ async function discoverN8nOAuth({ serverUrl }, { fetchImpl = globalThis.fetch, s
     }
     return discovery;
   } catch {
-    if (requestSignal.aborted) throw new ConnectorError("connector_discovery_interrupted", "n8n OAuth discovery was interrupted.");
-    throw new ConnectorError("connector_discovery_failed", "n8n OAuth discovery failed. Check the MCP URL, advertised authority and supported server version.", { statusCode: 502 });
+    if (requestSignal.aborted) throw new ConnectorError("connector_discovery_interrupted", "n8n OAuth discovery was interrupted.", { messageCode: "connectors.n8n.oauthDiscoveryInterrupted" });
+    throw new ConnectorError("connector_discovery_failed", "n8n OAuth discovery failed. Check the MCP URL, advertised authority and supported server version.", { statusCode: 502, messageCode: "connectors.n8n.oauthDiscoveryFailedCheckMcp" });
   }
 }
 
@@ -69,7 +69,7 @@ async function registerN8nClient(input, options) {
   const values = validateSchemaPayload({ schema: registrationSchema, mode: "replace" }, input, { statusCode: 422 });
   const discovery = await discoverN8nOAuth({ serverUrl: values.serverUrl }, options);
   if (values.scopes.some((scope) => !discovery.scopes.includes(scope))) {
-    throw new ConnectorError("connector_scope_unavailable", "Select only permissions advertised by this n8n MCP server.", { statusCode: 422 });
+    throw new ConnectorError("connector_scope_unavailable", "Select only permissions advertised by this n8n MCP server.", { statusCode: 422, messageCode: "connectors.n8n.selectPermissionsAdvertisedMcpServer" });
   }
   const client = await registerMcpClient("n8n", discovery.oauth, values, options);
   return { ...client, ...discovery, requestedScopes: [...values.scopes] };

package/src/server/oura.js

@@ -19,7 +19,7 @@ function collection(endpoint, scope = "daily", timed = false) {
     const request = operation.request(input, settings);
     const query = new URL(request.url).searchParams;
     if (query.has(start) && query.has(end) && Date.parse(query.get(start)) > Date.parse(query.get(end)))
-      throw new ConnectorError("connector_input_invalid", "Start must be before or equal to end.", { statusCode: 422 });
+      throw new ConnectorError("connector_input_invalid", "Start must be before or equal to end.", { statusCode: 422, messageCode: "connectors.oura.startNotAfterEnd" });
     return request;
   } };
 }

package/src/server/paddle.js

@@ -49,7 +49,7 @@ const paddleProvider = Object.freeze({
       request(input, settings) {
         const { notification_setting_id, ...body } = validateSchemaPayload(
           { schema: webhookUpdateSchema, mode: "replace" }, input, { statusCode: 422 });
-        if (!Object.keys(body).length) throw new ConnectorError("connector_input_invalid", "Choose at least one notification setting to change.", { statusCode: 422 });
+        if (!Object.keys(body).length) throw new ConnectorError("connector_input_invalid", "Choose at least one notification setting to change.", { statusCode: 422, messageCode: "connectors.paddle.chooseLeastNotificationSettingChange" });
         return { method: "PATCH", url: `${origins[settings.environment]}/notification-settings/${notification_setting_id}`, body };
       },
       validateResult: (result) => /^ntfset_[a-z0-9]{26}$/.test(result?.data?.id || "") && typeof result.data.active === "boolean"

package/src/server/pipedrive.js

@@ -6,7 +6,7 @@ import { ConnectorError } from "@jskit-ai/connectors-core/server";
 
 function companyApiDomain(value) {
   if (typeof value !== "string" || !/^https:\/\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.pipedrive\.com$/.test(value)) {
-    throw new ConnectorError("connector_response_invalid", "Pipedrive returned an invalid company API address.", { statusCode: 502 });
+    throw new ConnectorError("connector_response_invalid", "Pipedrive returned an invalid company API address.", { statusCode: 502, messageCode: "connectors.pipedrive.returnedInvalidCompanyApiAddress" });
   }
   return value;
 }
@@ -34,8 +34,8 @@ function crmOperation(collection, action) {
   return { scopes: [], request(input, settings = {}, data) {
     const { id, ...values } = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });
     if (action === "update" && !Object.keys(values).length || lead && action === "create" && !values.person_id && !values.organization_id)
-      throw new ConnectorError("connector_input_invalid", "Supply changed fields; a new lead also needs a person or organization.", { statusCode: 422 });
-    if (!data && !settings.companyDomain) throw new ConnectorError("connector_binding_missing", "Set the Pipedrive Company domain for API-token CRM operations.", { statusCode: 422 });
+      throw new ConnectorError("connector_input_invalid", "Supply changed fields; a new lead also needs a person or organization.", { statusCode: 422, messageCode: "connectors.pipedrive.supplyChangedFieldsNewLead" });
+    if (!data && !settings.companyDomain) throw new ConnectorError("connector_binding_missing", "Set the Pipedrive Company domain for API-token CRM operations.", { statusCode: 422, messageCode: "connectors.pipedrive.setCompanyDomainApiToken" });
     const origin = data ? companyApiDomain(data.apiDomain) : companyApiDomain(`https://${settings.companyDomain}.pipedrive.com`);
     const url = new URL(`${origin}/api/${lead ? "v1" : "v2"}/${collection}${id === undefined ? "" : `/${id}`}`);
     if (!write) for (const [name, value] of Object.entries(values)) url.searchParams.set(name, String(value));
@@ -56,7 +56,7 @@ const pipedriveProvider = Object.freeze({
   dataFromTokenResponse(response, previous) {
     const apiDomain = companyApiDomain(response.api_domain);
     if (previous && apiDomain !== previous.apiDomain) {
-      throw new ConnectorError("connector_reconnect_required", "The Pipedrive company address changed. Connect this account again.", { statusCode: 401 });
+      throw new ConnectorError("connector_reconnect_required", "The Pipedrive company address changed. Connect this account again.", { statusCode: 401, messageCode: "connectors.pipedrive.companyAddressChangedConnectAccount" });
     }
     return { apiDomain };
   },

package/src/server/posthog.js

@@ -9,7 +9,7 @@ const posthogProvider = Object.freeze({
   apiOrigins: (settings) => [origin(settings)],
   apiKey: { bodyParameter: "api_key", headers: (token) => {
     if (!/^phc_[a-zA-Z0-9_-]+$/u.test(token)) {
-      throw new ConnectorError("connector_binding_missing", "Use the public PostHog project token starting with phc_.");
+      throw new ConnectorError("connector_binding_missing", "Use the public PostHog project token starting with phc_.", { messageCode: "connectors.posthog.usePublicProjectTokenStarting" });
     }
     return { "User-Agent": "jskit-connectors/0.1.0 (posthog-node/compatible)" };
   } },
@@ -24,10 +24,10 @@ const posthogProvider = Object.freeze({
         typeof result.errorsWhileComputingFlags !== "boolean" ||
         (result.quotaLimited !== undefined && (!Array.isArray(result.quotaLimited) || !result.quotaLimited.every((item) => typeof item === "string")))) return false;
       if (result.quotaLimited?.includes("feature_flags")) {
-        throw new ConnectorError("connector_quota_limited", "PostHog's feature flag quota has been reached.", { statusCode: 429 });
+        throw new ConnectorError("connector_quota_limited", "PostHog's feature flag quota has been reached.", { statusCode: 429, messageCode: "connectors.posthog.featureFlagQuotaReached" });
       }
       if (result.errorsWhileComputingFlags) {
-        throw new ConnectorError("connector_provider_failed", "PostHog could not evaluate all requested flags.", { statusCode: 502 });
+        throw new ConnectorError("connector_provider_failed", "PostHog could not evaluate all requested flags.", { statusCode: 502, messageCode: "connectors.posthog.couldNotEvaluateAllRequested" });
       }
       return Object.values(result.flags).every((flag) => flag && typeof flag.enabled === "boolean" &&
         (flag.variant === undefined || typeof flag.variant === "string"));

package/src/server/salesforce.js

@@ -28,7 +28,7 @@ const salesforceProvider = Object.freeze({
     let value;
     try { value = await response.clone().json(); } catch { /* reported below */ }
     if (!record(value) || ![origin(settings), origin(settings) + "/"].includes(value.instance_url) || typeof value.scope !== "string" || !value.scope.trim()) {
-      throw new ConnectorError("connector_response_invalid", "Salesforce returned an invalid grant or a different organisation.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "Salesforce returned an invalid grant or a different organisation.", { statusCode: 502, messageCode: "connectors.salesforce.returnedInvalidGrantDifferentOrganisation" });
     }
     // Salesforce can omit expiry. Renew after five minutes of use as a local
     // policy; this is not a claim about the org's actual session lifetime.
@@ -65,17 +65,17 @@ const salesforceProvider = Object.freeze({
     try { value = await response.json(); } catch { /* checked after status */ }
     const code = Array.isArray(value) ? value[0]?.errorCode : null;
     if (!response.ok) {
-      if (code === "REQUEST_LIMIT_EXCEEDED") throw new ConnectorError("connector_rate_limited", "The Salesforce organisation's API request limit was reached.", { statusCode: 429 });
-      if (code === "INVALID_SESSION_ID") throw new ConnectorError("connector_reconnect_required", "Connect this Salesforce account again.", { statusCode: 401 });
-      if (code === "INVALID_QUERY_LOCATOR") throw new ConnectorError("connector_cursor_expired", "Start the Salesforce query again; its result cursor is no longer valid.", { statusCode: 410 });
-      if (response.status === 404) throw new ConnectorError("connector_resource_not_found", "This Salesforce resource is not available.", { statusCode: 404 });
-      if (response.status === 400) throw new ConnectorError("connector_query_invalid", "Salesforce rejected the query or object. Check its API names and the user's permissions.", { statusCode: 422 });
+      if (code === "REQUEST_LIMIT_EXCEEDED") throw new ConnectorError("connector_rate_limited", "The Salesforce organisation's API request limit was reached.", { statusCode: 429, messageCode: "connectors.salesforce.organisationApiRequestLimitReached" });
+      if (code === "INVALID_SESSION_ID") throw new ConnectorError("connector_reconnect_required", "Connect this Salesforce account again.", { statusCode: 401, messageCode: "connectors.shared.reconnectAccount", messageParams: { provider: "Salesforce" } });
+      if (code === "INVALID_QUERY_LOCATOR") throw new ConnectorError("connector_cursor_expired", "Start the Salesforce query again; its result cursor is no longer valid.", { statusCode: 410, messageCode: "connectors.salesforce.startQueryAgainResultCursor" });
+      if (response.status === 404) throw new ConnectorError("connector_resource_not_found", "This Salesforce resource is not available.", { statusCode: 404, messageCode: "connectors.shared.resourceUnavailable", messageParams: { provider: "Salesforce" } });
+      if (response.status === 400) throw new ConnectorError("connector_query_invalid", "Salesforce rejected the query or object. Check its API names and the user's permissions.", { statusCode: 422, messageCode: "connectors.salesforce.rejectedQueryObjectCheckApi" });
       throw Object.assign(new Error("Salesforce request failed."), { status: response.status });
     }
-    if (response.status !== 200 || !record(value)) throw new ConnectorError("connector_response_invalid", "Salesforce returned an unexpected response.", { statusCode: 502 });
+    if (response.status !== 200 || !record(value)) throw new ConnectorError("connector_response_invalid", "Salesforce returned an unexpected response.", { statusCode: 502, messageCode: "connectors.shared.unexpectedResponse", messageParams: { provider: "Salesforce" } });
     const url = new URL(address);
     if (url.pathname.endsWith("/describe") && value.name !== url.pathname.split("/").at(-2)) {
-      throw new ConnectorError("connector_response_invalid", "Salesforce described a different object.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "Salesforce described a different object.", { statusCode: 502, messageCode: "connectors.salesforce.describedDifferentObject" });
     }
     return value;
   }

package/src/server/semrush.js

@@ -44,11 +44,11 @@ function semrushKeywordReport(target, kind) {
   return {
     scopes: [],
     request(input, settings) {
-      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for keyword reports.");
+      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for keyword reports.", { messageCode: "connectors.semrush.configureSeparateV3ApiKey" });
       const result = operation.request(input);
       const url = new URL(result.url);
       const limit = Number(url.searchParams.get("limit")), offset = Number(url.searchParams.get("offset"));
-      if (limit + offset > 4_000_000) throw new ConnectorError("connector_input_invalid", "The requested Semrush page exceeds the provider's result window.", { statusCode: 422 });
+      if (limit + offset > 4_000_000) throw new ConnectorError("connector_input_invalid", "The requested Semrush page exceeds the provider's result window.", { statusCode: 422, messageCode: "connectors.semrush.requestedPageExceedsProviderResult" });
       url.searchParams.delete("limit"); url.searchParams.delete("offset");
       url.searchParams.set("display_limit", String(limit + offset));
       url.searchParams.set("display_offset", String(offset));
@@ -82,13 +82,13 @@ function semrushTrackingReport(type, positions = false) {
         Object.values(value.data).length <= Number(url.searchParams.get("display_limit")) &&
         Object.values(value.data).every((entry) => typeof entry?.Ph === "string" && typeof entry.Pi === "string" && entry.Dt !== null && typeof entry.Dt === "object"));
   }, request(input, settings) {
-    if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for position tracking.");
+    if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for position tracking.", { messageCode: "connectors.semrush.configureV3KeyPositionTracking" });
     const result = operation.request(input);
     const url = new URL(result.url);
     url.pathname = `/reports/v1/projects/${url.searchParams.get("campaignId")}/tracking/`;
     url.searchParams.delete("campaignId");
     if (url.searchParams.has("date_begin") && url.searchParams.has("date_end") && url.searchParams.get("date_begin") > url.searchParams.get("date_end")) {
-      throw new ConnectorError("connector_input_invalid", "The tracking start date must not follow its end date.", { statusCode: 422 });
+      throw new ConnectorError("connector_input_invalid", "The tracking start date must not follow its end date.", { statusCode: 422, messageCode: "connectors.semrush.trackingStartDateMustNot" });
     }
     url.searchParams.set("action", "report"); url.searchParams.set("type", type);
     return { ...result, url: url.href };
@@ -109,11 +109,11 @@ function parseSemrushCsv(text) {
       row.push(field); field = ""; closed = false;
       if (char !== ";") { rows.push(row); row = []; if (char === "\r" && text[i + 1] === "\n") i++; }
     } else {
-      if (closed || char === '"') throw new ConnectorError("connector_response_invalid", "Semrush returned malformed CSV.", { statusCode: 502 });
+      if (closed || char === '"') throw new ConnectorError("connector_response_invalid", "Semrush returned malformed CSV.", { statusCode: 502, messageCode: "connectors.semrush.returnedMalformedCsv" });
       field += char;
     }
   }
-  if (quoted) throw new ConnectorError("connector_response_invalid", "Semrush returned incomplete CSV.", { statusCode: 502 });
+  if (quoted) throw new ConnectorError("connector_response_invalid", "Semrush returned incomplete CSV.", { statusCode: 502, messageCode: "connectors.semrush.returnedIncompleteCsv" });
   if (field !== "" || closed || row.length) { row.push(field); rows.push(row); }
   return rows;
 }
@@ -157,7 +157,7 @@ const semrushProvider = Object.freeze({
   ...semrushDefinition, apiOrigins: ["https://api.semrush.com"],
   apiKey: { headers: (key) => {
     if (/[\s\p{Cc}]/u.test(key)) {
-      throw new ConnectorError("connector_binding_missing", "Use the Semrush V4 API key without spaces or control characters.");
+      throw new ConnectorError("connector_binding_missing", "Use the Semrush V4 API key without spaces or control characters.", { messageCode: "connectors.semrush.useV4ApiKeyWithout" });
     }
     return { Authorization: `Apikey ${key}` };
   } },
@@ -169,7 +169,7 @@ const semrushProvider = Object.freeze({
         typeof campaign.url === "string" && typeof campaign.device === "string" && typeof campaign.isGathering === "boolean"),
     request(input, settings) {
       const { projectId } = validateSchemaPayload({ schema: projectSchema, mode: "replace" }, input, { statusCode: 422 });
-      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for campaign discovery.");
+      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for campaign discovery.", { messageCode: "connectors.semrush.configureV3KeyCampaignDiscovery" });
       return { method: "GET", url: `https://api.semrush.com/management/v1/projects/${projectId}/tracking/campaigns` };
     } },
     "tracking.dates": semrushTrackingReport("tracking_campaign_dates"),
@@ -184,7 +184,7 @@ const semrushProvider = Object.freeze({
     "domains.overview": {
       scopes: [],
       request(input, settings) {
-        if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for domain reports.");
+        if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for domain reports.", { messageCode: "connectors.semrush.configureSeparateV3ApiKeyReferenceDomainReports" });
         const operation = jsonOperation("https://api.semrush.com/", {
           domain: { type: "string", required: true, minLength: 1, maxLength: 253, pattern: /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/iu },
           database: { type: "string", required: true, pattern: /^[a-z]{2}$/u }
@@ -214,7 +214,7 @@ const semrushProvider = Object.freeze({
         const url = new URL(result.url);
         const month = url.searchParams.get("month");
         if (month && (month < "2012-01" || month > new Date().toISOString().slice(0, 7))) {
-          throw new ConnectorError("connector_input_invalid", "Choose a month from 2012-01 through the current month.", { statusCode: 422 });
+          throw new ConnectorError("connector_input_invalid", "Choose a month from 2012-01 through the current month.", { statusCode: 422, messageCode: "connectors.semrush.chooseMonth201201Through" });
         }
         url.searchParams.set("format", "json");
         return { ...result, url: url.href };
@@ -274,10 +274,10 @@ const semrushProvider = Object.freeze({
     if (path === "/" || path.startsWith("/management/v1/projects/") || path.startsWith("/reports/v1/projects/")) {
       let key;
       try { key = await resolveReference(settings.v3ApiKeyRef); } catch {
-        throw new ConnectorError("connector_binding_missing", "Provide the Semrush V3 API key through its private Env reference.");
+        throw new ConnectorError("connector_binding_missing", "Provide the Semrush V3 API key through its private Env reference.", { messageCode: "connectors.semrush.provideV3ApiKeyThrough" });
       }
       if (typeof key !== "string" || !key || key === "MISSING" || /[\s\p{Cc}]/u.test(key)) {
-        throw new ConnectorError("connector_binding_missing", "Provide a valid Semrush V3 API key.");
+        throw new ConnectorError("connector_binding_missing", "Provide a valid Semrush V3 API key.", { messageCode: "connectors.semrush.provideValidV3ApiKey" });
       }
       const url = new URL(address);
       url.searchParams.set("key", key);
@@ -291,12 +291,12 @@ const semrushProvider = Object.freeze({
         options.signal.throwIfAborted();
         const status = response?.status;
         throw new ConnectorError(status === 429 ? "connector_rate_limited" : status === 403 ? "connector_permission_denied" : "connector_provider_failed",
-          "Semrush could not return the V3 report.", { statusCode: status === 429 ? 429 : status === 403 ? 403 : 502 });
+          "Semrush could not return the V3 report.", { statusCode: status === 429 ? 429 : status === 403 ? 403 : 502, messageCode: "connectors.semrush.couldNotReturnV3Report" });
       }
-      if (text.length > 2_000_000) throw new ConnectorError("connector_response_invalid", "Semrush returned an oversized V3 report.", { statusCode: 502 });
+      if (text.length > 2_000_000) throw new ConnectorError("connector_response_invalid", "Semrush returned an oversized V3 report.", { statusCode: 502, messageCode: "connectors.semrush.returnedOversizedV3Report" });
       if (path !== "/") {
         try { return JSON.parse(text); } catch {
-          throw new ConnectorError("connector_response_invalid", "Semrush returned invalid tracking JSON.", { statusCode: 502 });
+          throw new ConnectorError("connector_response_invalid", "Semrush returned invalid tracking JSON.", { statusCode: 502, messageCode: "connectors.semrush.returnedInvalidTrackingJson" });
         }
       }
       const columns = url.searchParams.get("type") === "domain_rank" ? domainColumns : keywordColumns;
@@ -305,15 +305,15 @@ const semrushProvider = Object.freeze({
       if (error) {
         if (error[1] === "50") return { columns, rows: [] };
         const code = Number(error[1]);
-        if ([110, 120].includes(code)) throw new ConnectorError("connector_binding_missing", "Replace the separate Semrush V3 key in Env.");
-        if ([130, 133, 135].includes(code)) throw new ConnectorError("connector_permission_denied", "Check Semrush V3 API, database and report entitlement.", { statusCode: 403 });
-        if ([131, 132, 134].includes(code)) throw new ConnectorError("connector_quota_limited", "Check Semrush V3 API units and report limits.", { statusCode: 429 });
-        throw new ConnectorError("connector_provider_failed", "Semrush rejected the V3 report. Check its inputs and account access.", { statusCode: 502 });
+        if ([110, 120].includes(code)) throw new ConnectorError("connector_binding_missing", "Replace the separate Semrush V3 key in Env.", { messageCode: "connectors.semrush.replaceSeparateV3KeyEnv" });
+        if ([130, 133, 135].includes(code)) throw new ConnectorError("connector_permission_denied", "Check Semrush V3 API, database and report entitlement.", { statusCode: 403, messageCode: "connectors.semrush.checkV3ApiDatabaseReport" });
+        if ([131, 132, 134].includes(code)) throw new ConnectorError("connector_quota_limited", "Check Semrush V3 API units and report limits.", { statusCode: 429, messageCode: "connectors.semrush.checkV3ApiUnitsReport" });
+        throw new ConnectorError("connector_provider_failed", "Semrush rejected the V3 report. Check its inputs and account access.", { statusCode: 502, messageCode: "connectors.semrush.rejectedV3ReportCheckInputs" });
       }
       const rows = parseSemrushCsv(text);
       if (JSON.stringify(rows.shift()) !== JSON.stringify(columns) || rows.length > rowLimit ||
         rows.some((row) => row.length !== columns.length)) {
-        throw new ConnectorError("connector_response_invalid", "Semrush returned unexpected V3 report columns or rows.", { statusCode: 502 });
+        throw new ConnectorError("connector_response_invalid", "Semrush returned unexpected V3 report columns or rows.", { statusCode: 502, messageCode: "connectors.semrush.returnedUnexpectedV3ReportColumns" });
       }
       return { columns, rows };
     }
@@ -321,18 +321,18 @@ const semrushProvider = Object.freeze({
     if (result?.meta?.success === false) {
       const code = result.error?.code;
       if ([70, 120, 121, 122].includes(code)) {
-        throw new ConnectorError("connector_reconnect_required", "Replace the Semrush V4 key and connect again.", { statusCode: 401 });
+        throw new ConnectorError("connector_reconnect_required", "Replace the Semrush V4 key and connect again.", { statusCode: 401, messageCode: "connectors.semrush.replaceV4KeyConnectAgain" });
       }
       if (code === 130) {
-        throw new ConnectorError("connector_permission_denied", "Semrush API access is disabled for this account.", { statusCode: 403 });
+        throw new ConnectorError("connector_permission_denied", "Semrush API access is disabled for this account.", { statusCode: 403, messageCode: "connectors.semrush.apiAccessDisabledAccount" });
       }
       if ([131, 132, 134].includes(code)) {
-        throw new ConnectorError("connector_quota_limited", "Semrush API capacity is exhausted. Check the account's subscription and available units.", { statusCode: 429 });
+        throw new ConnectorError("connector_quota_limited", "Semrush API capacity is exhausted. Check the account's subscription and available units.", { statusCode: 429, messageCode: "connectors.semrush.apiCapacityExhaustedCheckAccount" });
       }
       if (code === 512) {
-        throw new ConnectorError("connector_resource_not_found", "The Semrush project was not found or is not accessible.", { statusCode: 404 });
+        throw new ConnectorError("connector_resource_not_found", "The Semrush project was not found or is not accessible.", { statusCode: 404, messageCode: "connectors.semrush.projectNotFoundNotAccessible" });
       }
-      throw new ConnectorError("connector_provider_failed", "Semrush could not complete this request.", { statusCode: 502 });
+      throw new ConnectorError("connector_provider_failed", "Semrush could not complete this request.", { statusCode: 502, messageCode: "connectors.semrush.couldNotCompleteRequest" });
     }
     return result;
   }

package/src/server/shopify.js

@@ -29,7 +29,7 @@ function productMutation(name, fields) {
   return { ...operation, scopes: ["write_products"], request(input, settings) {
     const request = operation.request(input, settings);
     if (name === "Update" && Object.keys(request.body.variables.product).length === 1) {
-      throw new ConnectorError("connector_input_invalid", "Select at least one product detail to update.", { statusCode: 422 });
+      throw new ConnectorError("connector_input_invalid", "Select at least one product detail to update.", { statusCode: 422, messageCode: "connectors.shopify.selectLeastProductDetailUpdate" });
     }
     return request;
   } };
@@ -48,7 +48,7 @@ const shopifyProvider = Object.freeze({
     if (typeof token?.access_token !== "string" || !token.access_token.trim() ||
       !Number.isSafeInteger(token.expires_in) || token.expires_in <= 0 ||
       typeof token.scope !== "string" || !/^[a-z_]+(?:,[a-z_]+)*$/u.test(token.scope)) {
-      throw new ConnectorError("connector_response_invalid", "Shopify returned an invalid token grant.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "Shopify returned an invalid token grant.", { statusCode: 502, messageCode: "connectors.shared.invalidTokenGrant", messageParams: { provider: "Shopify" } });
     }
     // Shopify's documented client-credentials response omits the standard token_type.
     return Response.json({ ...token, token_type: token.token_type ?? "Bearer" });
@@ -80,17 +80,17 @@ const shopifyProvider = Object.freeze({
     const result = await request(address, { ...options, headers });
     if (Array.isArray(result?.errors) && result.errors.length) {
       const codes = result.errors.map((error) => error?.extensions?.code);
-      if (codes.includes("THROTTLED")) throw new ConnectorError("connector_rate_limited", "Shopify's request limit was reached.", { statusCode: 429 });
-      if (codes.includes("ACCESS_DENIED")) throw new ConnectorError("connector_permission_denied", "Shopify denied this operation.", { statusCode: 403 });
+      if (codes.includes("THROTTLED")) throw new ConnectorError("connector_rate_limited", "Shopify's request limit was reached.", { statusCode: 429, messageCode: "connectors.shared.requestLimitReached", messageParams: { provider: "Shopify" } });
+      if (codes.includes("ACCESS_DENIED")) throw new ConnectorError("connector_permission_denied", "Shopify denied this operation.", { statusCode: 403, messageCode: "connectors.shared.operationDenied", messageParams: { provider: "Shopify" } });
     }
     for (const name of ["productCreate", "productUpdate", "productDelete"]) {
       const payload = result?.data?.[name];
       if (Array.isArray(payload?.userErrors) && payload.userErrors.length) {
-        throw new ConnectorError("connector_operation_rejected", "Shopify rejected the product change. Check the product values and permissions before retrying.", { statusCode: 422 });
+        throw new ConnectorError("connector_operation_rejected", "Shopify rejected the product change. Check the product values and permissions before retrying.", { statusCode: 422, messageCode: "connectors.shopify.rejectedProductChangeCheckProduct" });
       }
     }
     if (result?.data?.products?.nodes?.length > options.body.variables.first) {
-      throw new ConnectorError("connector_response_invalid", "Shopify returned more products than requested.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "Shopify returned more products than requested.", { statusCode: 502, messageCode: "connectors.shopify.returnedMoreProductsRequested" });
     }
     return result;
   }

package/src/server/slack.js

@@ -6,41 +6,41 @@ import { jsonOperation } from "./jsonOperation.js";
 function checkReply(value) {
   if (value?.ok === true) return value;
   if (value?.ok !== false || typeof value.error !== "string") {
-    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid response.", { statusCode: 502 });
+    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid response.", { statusCode: 502, messageCode: "connectors.shared.invalidResponse", messageParams: { provider: "Slack" } });
   }
   if (["invalid_auth", "not_authed", "token_revoked", "token_expired", "account_inactive", "invalid_refresh_token", "invalid_grant"].includes(value.error)) {
-    throw new ConnectorError("connector_reconnect_required", "Connect this Slack account again.", { statusCode: 401 });
+    throw new ConnectorError("connector_reconnect_required", "Connect this Slack account again.", { statusCode: 401, messageCode: "connectors.shared.reconnectAccount", messageParams: { provider: "Slack" } });
   }
   if (["missing_scope", "not_allowed_token_type", "access_denied", "no_permission", "not_in_channel", "restricted_action"].includes(value.error)) {
-    throw new ConnectorError("connector_permission_denied", "Slack denied this operation.", { statusCode: 403 });
+    throw new ConnectorError("connector_permission_denied", "Slack denied this operation.", { statusCode: 403, messageCode: "connectors.shared.operationDenied", messageParams: { provider: "Slack" } });
   }
   if (["ratelimited", "rate_limited"].includes(value.error)) {
-    throw new ConnectorError("connector_rate_limited", "Slack's request limit was reached.", { statusCode: 429 });
+    throw new ConnectorError("connector_rate_limited", "Slack's request limit was reached.", { statusCode: 429, messageCode: "connectors.shared.requestLimitReached", messageParams: { provider: "Slack" } });
   }
   if (["invalid_client_id", "bad_client_secret", "bad_redirect_uri"].includes(value.error)) {
-    throw new ConnectorError("connector_registration_invalid", "Check the Slack client registration and callback.", { statusCode: 422 });
+    throw new ConnectorError("connector_registration_invalid", "Check the Slack client registration and callback.", { statusCode: 422, messageCode: "connectors.slack.checkClientRegistrationCallback" });
   }
-  throw new ConnectorError("connector_provider_failed", "The Slack request failed. Try again.", { statusCode: 502 });
+  throw new ConnectorError("connector_provider_failed", "The Slack request failed. Try again.", { statusCode: 502, messageCode: "connectors.slack.requestFailedTryAgain" });
 }
 
 async function normalizeTokenResponse(response, { settings, grantType }) {
   if ([401, 403, 429].includes(response.status)) {
     throw new ConnectorError(
       { 401: "connector_reconnect_required", 403: "connector_permission_denied", 429: "connector_rate_limited" }[response.status],
-      "Slack could not authorize this request.", { statusCode: response.status }
+      "Slack could not authorize this request.", { statusCode: response.status, messageCode: "connectors.slack.couldNotAuthorizeRequest" }
     );
   }
   let value;
   try { value = await response.clone().json(); } catch {
     if (!response.ok) return response;
-    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid token response.", { statusCode: 502 });
+    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid token response.", { statusCode: 502, messageCode: "connectors.shared.invalidTokenResponse", messageParams: { provider: "Slack" } });
   }
   checkReply(value);
   if (!response.ok) return response;
   const actor = settings.actor || "user";
   const token = grantType === "authorization_code" && actor === "user" ? value.authed_user : value;
   if (token?.token_type !== actor || typeof token.scope !== "string" || !/^[^\s,]+(?:,[^\s,]+)*$/u.test(token.scope)) {
-    throw new ConnectorError("connector_response_invalid", "Slack returned a token for the wrong identity or an invalid permission grant.", { statusCode: 502 });
+    throw new ConnectorError("connector_response_invalid", "Slack returned a token for the wrong identity or an invalid permission grant.", { statusCode: 502, messageCode: "connectors.slack.returnedTokenWrongIdentityInvalid" });
   }
   // Retain exactly one identity; a response may contain both user and bot tokens.
   return Response.json({ access_token: token.access_token, token_type: "Bearer", scope: token.scope,
@@ -109,7 +109,7 @@ const slackProvider = Object.freeze({
 });
 // The app supplies raw bytes before body parsing and binds the expected installation.
 function verifySlackRequest({ rawBody, signature, timestamp, secret, contentType, appId, teamId, now = Date.now() }) {
-  const reject = () => { throw new ConnectorError("connector_webhook_invalid", "Invalid Slack callback.", { statusCode: 401 }); };
+  const reject = () => { throw new ConnectorError("connector_webhook_invalid", "Invalid Slack callback.", { statusCode: 401, messageCode: "connectors.shared.invalidCallback", messageParams: { provider: "Slack" } }); };
   if (!(rawBody instanceof Uint8Array) || rawBody.byteLength > 1048576 ||
     typeof secret !== "string" || !secret || typeof signature !== "string" || !/^v0=[a-f0-9]{64}$/u.test(signature) ||
     typeof timestamp !== "string" || !/^[0-9]{1,12}$/u.test(timestamp) || !Number.isFinite(now) ||

package/src/server/snowflake.js

@@ -78,7 +78,7 @@ const snowflakeProvider = Object.freeze({
       if (!Number.isSafeInteger(value?.expires_in) || value.expires_in <= 0 ||
         (value.scope !== undefined && (typeof value.scope !== "string" || !/^[^\s]+(?: [^\s]+)*$/u.test(value.scope))) ||
         (value.refresh_token !== undefined && (typeof value.refresh_token !== "string" || !value.refresh_token.trim()))) {
-        throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid token grant.", { statusCode: 502 });
+        throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid token grant.", { statusCode: 502, messageCode: "connectors.shared.invalidTokenGrant", messageParams: { provider: "Snowflake" } });
       }
     }
     return response;
@@ -89,7 +89,7 @@ const snowflakeProvider = Object.freeze({
       ...(options.body !== undefined ? { body: JSON.stringify(options.body), headers: { ...options.headers, "Content-Type": "application/json" } } : {}) });
     const url = new URL(address);
     const sql = url.pathname.startsWith("/api/v2/statements");
-    if (sql && response.status === 422) throw new ConnectorError("connector_operation_rejected", "Snowflake rejected the statement. Inspect query history with the authorized role.", { statusCode: 422 });
+    if (sql && response.status === 422) throw new ConnectorError("connector_operation_rejected", "Snowflake rejected the statement. Inspect query history with the authorized role.", { statusCode: 422, messageCode: "connectors.snowflake.rejectedStatementInspectQueryHistory" });
     if (!response.ok) throw Object.assign(new Error("Snowflake request failed."), { status: response.status });
     const reader = response.body?.getReader();
     const chunks = [];
@@ -101,7 +101,7 @@ const snowflakeProvider = Object.freeze({
         size += value.byteLength;
         if (size > 16 * 1024 * 1024) {
           await reader.cancel();
-          throw new ConnectorError("connector_response_too_large", "Snowflake response exceeds 16 MiB. Reduce the query result or use a native streaming client.", { statusCode: 413 });
+          throw new ConnectorError("connector_response_too_large", "Snowflake response exceeds 16 MiB. Reduce the query result or use a native streaming client.", { statusCode: 413, messageCode: "connectors.snowflake.responseExceeds16MibReduce" });
         }
         chunks.push(value);
       }
@@ -109,7 +109,7 @@ const snowflakeProvider = Object.freeze({
     let result;
     try { result = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { /* rejected below */ }
     if (sql) {
-      const reject = () => { throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid statement response.", { statusCode: 502 }); };
+      const reject = () => { throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid statement response.", { statusCode: 502, messageCode: "connectors.snowflake.returnedInvalidStatementResponse" }); };
       if (!object(result)) reject();
       const requestedHandle = url.pathname.split("/")[4];
       const handle = result.statementHandle ?? requestedHandle;
@@ -131,7 +131,7 @@ const snowflakeProvider = Object.freeze({
         ...(url.searchParams.has("partition") ? { partition: Number(url.searchParams.get("partition")) } : {}) };
     }
     if (response.status !== 200 || !Array.isArray(result) || result.length > Number(url.searchParams.get("showLimit"))) {
-      throw new ConnectorError("connector_response_invalid", "Snowflake returned an unexpected database page.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "Snowflake returned an unexpected database page.", { statusCode: 502, messageCode: "connectors.snowflake.returnedUnexpectedDatabasePage" });
     }
     return result;
   }

package/src/server/tally.js

@@ -49,7 +49,7 @@ const tallyProvider = Object.freeze({
       scopes: [],
       request(input) {
         const { formId, ...body } = validateSchemaPayload({ schema: formUpdateSchema, mode: "replace" }, input, { statusCode: 422 });
-        if (!Object.keys(body).length) throw new ConnectorError("connector_input_invalid", "Choose a name, status or block change.", { statusCode: 422 });
+        if (!Object.keys(body).length) throw new ConnectorError("connector_input_invalid", "Choose a name, status or block change.", { statusCode: 422, messageCode: "connectors.tally.chooseNameStatusBlockChange" });
         return { method: "PATCH", url: `https://api.tally.so/forms/${formId}`, body };
       },
       validateResult: formResult

package/src/server/telegram.js

@@ -19,7 +19,7 @@ const telegramProvider = Object.freeze({
   apiOrigins: ["https://api.telegram.org"],
   apiKey: { pathPrefix(key) {
     if (!/^\d+:[A-Za-z0-9_-]+$/.test(key)) {
-      throw new ConnectorError("connector_binding_invalid", "Configure a Telegram bot token in the referenced environment variable.");
+      throw new ConnectorError("connector_binding_invalid", "Configure a Telegram bot token in the referenced environment variable.", { messageCode: "connectors.telegram.configureBotTokenReferencedEnvironment" });
     }
     return `/bot${key}`;
   } },

package/src/server/tiktok.js

@@ -8,13 +8,13 @@ const count = (value) => Number.isSafeInteger(value) && value >= 0;
 function checkReply(value) {
   const code = value?.error?.code ?? value?.code;
   if (code === "ok") return value;
-  if (typeof code !== "string" || !code) throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502 });
-  if (code === "access_token_invalid") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401 });
+  if (typeof code !== "string" || !code) throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502, messageCode: "connectors.shared.invalidResponse", messageParams: { provider: "TikTok" } });
+  if (code === "access_token_invalid") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401, messageCode: "connectors.shared.reconnectAccount", messageParams: { provider: "TikTok" } });
   if (["scope_not_authorized", "scope_permission_missed"].includes(code)) {
-    throw new ConnectorError("connector_scope_missing", "Connect TikTok with the permission required for this operation.", { statusCode: 403 });
+    throw new ConnectorError("connector_scope_missing", "Connect TikTok with the permission required for this operation.", { statusCode: 403, messageCode: "connectors.tiktok.connectPermissionRequiredOperation" });
   }
-  if (code === "rate_limit_exceeded") throw new ConnectorError("connector_rate_limited", "TikTok's request limit was reached.", { statusCode: 429 });
-  throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502 });
+  if (code === "rate_limit_exceeded") throw new ConnectorError("connector_rate_limited", "TikTok's request limit was reached.", { statusCode: 429, messageCode: "connectors.shared.requestLimitReached", messageParams: { provider: "TikTok" } });
+  throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502, messageCode: "connectors.tiktok.couldNotCompleteRequest" });
 }
 
 function profileOperation(fields, scope, validateUser) {
@@ -31,21 +31,21 @@ const tiktokProvider = Object.freeze({
     let value;
     try { value = await response.clone().json(); } catch {
       if (!response.ok) return response;
-      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid token response.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid token response.", { statusCode: 502, messageCode: "connectors.shared.invalidTokenResponse", messageParams: { provider: "TikTok" } });
     }
     if (!response.ok) return response;
     if (value?.error) {
-      if (value.error === "invalid_grant") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401 });
-      throw new ConnectorError("connector_provider_failed", "TikTok could not authorize this connection.", { statusCode: 502 });
+      if (value.error === "invalid_grant") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401, messageCode: "connectors.shared.reconnectAccount", messageParams: { provider: "TikTok" } });
+      throw new ConnectorError("connector_provider_failed", "TikTok could not authorize this connection.", { statusCode: 502, messageCode: "connectors.tiktok.couldNotAuthorizeConnection" });
     }
     if (!textId(value?.open_id) || !Number.isSafeInteger(value.expires_in) || value.expires_in <= 0 ||
       !Number.isSafeInteger(value.refresh_expires_in) || value.refresh_expires_in <= 0 || !textId(value.refresh_token) ||
       typeof value.scope !== "string" || !/^[^\s,]+(?:,[^\s,]+)*$/u.test(value.scope)) {
-      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid permission grant.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid permission grant.", { statusCode: 502, messageCode: "connectors.shared.invalidPermissionGrant", messageParams: { provider: "TikTok" } });
     }
     const scopes = value.scope.split(",");
-    if (new Set(scopes).size !== scopes.length) throw new ConnectorError("connector_response_invalid", "TikTok returned duplicate permissions.", { statusCode: 502 });
-    if (!scopes.includes("user.info.basic")) throw new ConnectorError("connector_scope_missing", "Connect TikTok with basic profile permission.", { statusCode: 403 });
+    if (new Set(scopes).size !== scopes.length) throw new ConnectorError("connector_response_invalid", "TikTok returned duplicate permissions.", { statusCode: 502, messageCode: "connectors.tiktok.returnedDuplicatePermissions" });
+    if (!scopes.includes("user.info.basic")) throw new ConnectorError("connector_scope_missing", "Connect TikTok with basic profile permission.", { statusCode: 403, messageCode: "connectors.tiktok.connectBasicProfilePermission" });
     return response;
   },
   apiOrigins: ["https://open.tiktokapis.com"], checkOperation: "profile.read",
@@ -72,12 +72,12 @@ const tiktokProvider = Object.freeze({
       ...(options.body ? { body: JSON.stringify(options.body) } : {}) });
     let value;
     try { value = await response.json(); } catch {
-      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502, messageCode: "connectors.shared.invalidResponse", messageParams: { provider: "TikTok" } });
     }
     checkReply(value);
-    if (!response.ok) throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502 });
+    if (!response.ok) throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502, messageCode: "connectors.tiktok.couldNotCompleteRequest" });
     if (options.body?.max_count !== undefined && value.data?.videos?.length > options.body.max_count) {
-      throw new ConnectorError("connector_response_invalid", "TikTok returned too many videos.", { statusCode: 502 });
+      throw new ConnectorError("connector_response_invalid", "TikTok returned too many videos.", { statusCode: 502, messageCode: "connectors.tiktok.returnedTooManyVideos" });
     }
     return value;
   }

package/src/server/twilio.js

@@ -39,7 +39,7 @@ const twilioProvider = Object.freeze({
       To: phone, From: { ...phone, required: false }, MessagingServiceSid: { ...sid("MG"), required: false },
       Body: { type: "string", required: true, noTrim: true, minLength: 1, maxLength: 1600 }, StatusCallback: callbackUrl
     }, values => {
-      if (Boolean(values.From) === Boolean(values.MessagingServiceSid)) throw new ConnectorError("connector_input_invalid", "Choose one sender number or Messaging Service SID.", { statusCode: 422 });
+      if (Boolean(values.From) === Boolean(values.MessagingServiceSid)) throw new ConnectorError("connector_input_invalid", "Choose one sender number or Messaging Service SID.", { statusCode: 422, messageCode: "connectors.twilio.chooseSenderNumberMessagingService" });
     }),
     "messages.get": resourceOperation("Messages", "GET", { resourceSid: sid("SM") }),
     "calls.create": resourceOperation("Calls", "POST", {
@@ -47,7 +47,7 @@ const twilioProvider = Object.freeze({
       Twiml: { type: "string", noTrim: true, minLength: 1, maxLength: 4000 },
       StatusCallback: callbackUrl, Timeout: { type: "integer", min: 5, max: 600, defaultTo: 60 }
     }, values => {
-      if (Boolean(values.Url) === Boolean(values.Twiml)) throw new ConnectorError("connector_input_invalid", "Supply either a call-control URL or inline TwiML.", { statusCode: 422 });
+      if (Boolean(values.Url) === Boolean(values.Twiml)) throw new ConnectorError("connector_input_invalid", "Supply either a call-control URL or inline TwiML.", { statusCode: 422, messageCode: "connectors.twilio.supplyEitherCallControlUrl" });
     }),
     "calls.get": resourceOperation("Calls", "GET", { resourceSid: sid("CA") }),
     "calls.list": jsonOperation((settings) => `${origins[settings.region]}/2010-04-01/Accounts/${settings.accountSid}/Calls.json`, {
@@ -65,7 +65,7 @@ const twilioProvider = Object.freeze({
 // POST form callbacks only. The caller supplies the exact public URL configured
 // at Twilio, never a URL reconstructed from untrusted forwarded headers.
 function verifyTwilioRequest({ rawBody, signature, authToken, url, accountSid, contentType }) {
-  const reject = () => { throw new ConnectorError("connector_webhook_invalid", "Invalid Twilio callback.", { statusCode: 401 }); };
+  const reject = () => { throw new ConnectorError("connector_webhook_invalid", "Invalid Twilio callback.", { statusCode: 401, messageCode: "connectors.shared.invalidCallback", messageParams: { provider: "Twilio" } }); };
   if (!(rawBody instanceof Uint8Array) || rawBody.byteLength > 1048576 ||
     typeof signature !== "string" || !/^[A-Za-z0-9+/]{27}=$/u.test(signature) ||
     typeof authToken !== "string" || !authToken ||