@tangle-network/agent-integrations 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -533,6 +533,25 @@ interface GenericHmacVerifyOptions {
     lowercaseHex?: boolean;
 }
 declare function verifyHmacSignature(rawBody: string, signatureHeader: string, secret: string, options?: GenericHmacVerifyOptions): boolean;
+interface TwilioVerifyOptions {
+    /** Skip verification when the auth token isn't configured. Useful in
+     *  dev where the receiver wants to accept any payload. Default `false`
+     *  — production should always require a configured token. */
+    skipWhenAuthTokenMissing?: boolean;
+    /** When true, sign the raw body instead of the URL-encoded sorted-params
+     *  reduction. Twilio uses raw-body signing for `application/json`
+     *  webhook bodies. Default `false`. */
+    bodyAsRaw?: boolean;
+    /** When `bodyAsRaw` is true, the raw body to sign. Ignored otherwise. */
+    rawBody?: string;
+}
+/** Verify a Twilio webhook signature. */
+declare function verifyTwilioSignature(input: {
+    authToken: string | null | undefined;
+    signatureHeader: string | string[] | undefined;
+    fullUrl: string | null | undefined;
+    params: Record<string, string> | undefined;
+}, options?: TwilioVerifyOptions): boolean;
 declare function firstHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
 
 /**
@@ -1049,6 +1068,60 @@ interface ConnectorAdapterProviderOptions {
 declare function createConnectorAdapterProvider(options: ConnectorAdapterProviderOptions): IntegrationProvider;
 declare function manifestToConnector(providerId: string, adapter: ConnectorAdapter): IntegrationConnector;
 
+interface ImportCatalogOptions {
+    providerId: string;
+    connectorId: string;
+    connectorTitle: string;
+    category?: IntegrationConnectorCategory;
+    auth?: IntegrationConnector['auth'];
+    scopes?: string[];
+    dataClass?: IntegrationDataClass;
+    defaultRisk?: IntegrationActionRisk;
+}
+interface OpenApiDocument {
+    openapi?: string;
+    swagger?: string;
+    info?: {
+        title?: string;
+    };
+    paths?: Record<string, Record<string, OpenApiOperation | unknown>>;
+}
+interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: unknown[];
+    requestBody?: unknown;
+    responses?: unknown;
+    security?: Array<Record<string, string[]>>;
+    tags?: string[];
+}
+interface GraphqlOperationSpec {
+    name: string;
+    kind: 'query' | 'mutation';
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    requiredScopes?: string[];
+}
+interface McpCatalogTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+        title?: string;
+    };
+}
+interface McpCatalog {
+    tools: McpCatalogTool[];
+}
+declare function importOpenApiConnector(document: OpenApiDocument, options: ImportCatalogOptions): IntegrationConnector;
+declare function importGraphqlConnector(operations: GraphqlOperationSpec[], options: ImportCatalogOptions): IntegrationConnector;
+declare function importMcpConnector(catalog: McpCatalog, options: ImportCatalogOptions): IntegrationConnector;
+
 type IntegrationProviderKind = 'first_party' | 'nango' | 'pipedream' | 'zapier' | 'activepieces' | 'executor' | 'custom';
 type IntegrationConnectorCategory = 'email' | 'calendar' | 'chat' | 'crm' | 'storage' | 'docs' | 'database' | 'webhook' | 'workflow' | 'internal' | 'other';
 type IntegrationActionRisk = 'read' | 'write' | 'destructive';
@@ -1345,4 +1418,4 @@ declare function createHttpIntegrationProvider(options: HttpIntegrationProviderO
 declare function signCapability(capability: IntegrationCapability, secret: string): string;
 declare function verifyCapabilityToken(token: string, secret: string): IntegrationCapability;
 
-export { type AuthSpec, type CASStrategy, type Capability, type CapabilityClass, type CapabilityMutation, type CapabilityMutationResult, type CapabilityParameterSchema, type CapabilityRead, type CapabilityReadResult, type CompleteAuthRequest, type ConnectorAdapter, type ConnectorAdapterProviderOptions, type ConnectorCredentials, type ConnectorInvocation, type ConnectorManifest, type ConnectorManifestValidationIssue, type ConnectorManifestValidationResult, type ConsistencyModel, CredentialsExpired, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DataSourceMetadata, type EventHandlerResult, type ExchangeCodeInput, type GenericHmacVerifyOptions, type GoogleCalendarOptions, type GoogleSheetsOptions, type HttpIntegrationProviderOptions, type HubSpotOptions, InMemoryConnectionStore, InMemoryOAuthFlowStore, type InboundEvent, type IntegrationActionGuard, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationApprovalRequest, type IntegrationApprovalResolution, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationPolicyDecision, type IntegrationPolicyEffect, type IntegrationPolicyEngine, type IntegrationPolicyRule, type IntegrationProvider, type IntegrationProviderKind, type IntegrationToolDefinition, type IntegrationToolSearchFilters, type IntegrationToolSearchResult, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type McpToolDefinition, type MicrosoftCalendarOptions, type NormalizedIntegrationResult, type NotionDatabaseOptions, type OAuthFlowStore, type OAuthTokens, type ParsedStripeSignatureHeader, type PendingOAuthFlow, type RateLimitSpec, type RefreshInput, type ResolvedDataSource, ResourceContention, type SecretRef, type SlackOptions, type SlackVerifyOptions, type StartAuthRequest, type StartAuthResult, type StartOAuthInput, type StartOAuthOutput, StaticIntegrationPolicyEngine, type StaticIntegrationPolicyOptions, type StripeVerifyOptions, _resetPendingFlowsForTests, assertValidConnectorManifest, buildApprovalRequest, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, exchangeAuthorizationCode, firstHeader, googleCalendar, googleSheets, hubspot, integrationToolName, invocationRequestFromEnvelope, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, webhookConnector };
+export { type AuthSpec, type CASStrategy, type Capability, type CapabilityClass, type CapabilityMutation, type CapabilityMutationResult, type CapabilityParameterSchema, type CapabilityRead, type CapabilityReadResult, type CompleteAuthRequest, type ConnectorAdapter, type ConnectorAdapterProviderOptions, type ConnectorCredentials, type ConnectorInvocation, type ConnectorManifest, type ConnectorManifestValidationIssue, type ConnectorManifestValidationResult, type ConsistencyModel, CredentialsExpired, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DataSourceMetadata, type EventHandlerResult, type ExchangeCodeInput, type GenericHmacVerifyOptions, type GoogleCalendarOptions, type GoogleSheetsOptions, type GraphqlOperationSpec, type HttpIntegrationProviderOptions, type HubSpotOptions, type ImportCatalogOptions, InMemoryConnectionStore, InMemoryOAuthFlowStore, type InboundEvent, type IntegrationActionGuard, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationApprovalRequest, type IntegrationApprovalResolution, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationPolicyDecision, type IntegrationPolicyEffect, type IntegrationPolicyEngine, type IntegrationPolicyRule, type IntegrationProvider, type IntegrationProviderKind, type IntegrationToolDefinition, type IntegrationToolSearchFilters, type IntegrationToolSearchResult, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type McpCatalog, type McpCatalogTool, type McpToolDefinition, type MicrosoftCalendarOptions, type NormalizedIntegrationResult, type NotionDatabaseOptions, type OAuthFlowStore, type OAuthTokens, type OpenApiDocument, type OpenApiOperation, type ParsedStripeSignatureHeader, type PendingOAuthFlow, type RateLimitSpec, type RefreshInput, type ResolvedDataSource, ResourceContention, type SecretRef, type SlackOptions, type SlackVerifyOptions, type StartAuthRequest, type StartAuthResult, type StartOAuthInput, type StartOAuthOutput, StaticIntegrationPolicyEngine, type StaticIntegrationPolicyOptions, type StripeVerifyOptions, type TwilioVerifyOptions, _resetPendingFlowsForTests, assertValidConnectorManifest, buildApprovalRequest, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, exchangeAuthorizationCode, firstHeader, googleCalendar, googleSheets, hubspot, importGraphqlConnector, importMcpConnector, importOpenApiConnector, integrationToolName, invocationRequestFromEnvelope, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, verifyTwilioSignature, webhookConnector };

package/dist/index.js

@@ -242,6 +242,20 @@ function verifyHmacSignature(rawBody, signatureHeader, secret, options = {}) {
   if (sigBuf.length !== expectedBuf.length) return false;
   return timingSafeEqual(sigBuf, expectedBuf);
 }
+function verifyTwilioSignature(input, options = {}) {
+  if (!input.authToken) {
+    return options.skipWhenAuthTokenMissing === true;
+  }
+  const signature = input.signatureHeader;
+  if (!signature || Array.isArray(signature)) return false;
+  if (!input.fullUrl) return false;
+  const data = options.bodyAsRaw === true ? input.fullUrl + (options.rawBody ?? "") : Object.keys(input.params ?? {}).sort().reduce((acc, key) => acc + key + (input.params[key] ?? ""), input.fullUrl);
+  const expected = createHmac("sha1", input.authToken).update(data).digest("base64");
+  const expectedBuf = Buffer.from(expected);
+  const sigBuf = Buffer.from(signature);
+  if (expectedBuf.length !== sigBuf.length) return false;
+  return timingSafeEqual(expectedBuf, sigBuf);
+}
 function firstHeader(headers, name) {
   const v = headers[name] ?? headers[name.toLowerCase()] ?? Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
   if (Array.isArray(v)) return v[0];
@@ -3068,6 +3082,116 @@ function toRecord(input) {
   return {};
 }
 
+// src/importers.ts
+var HTTP_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete"]);
+function importOpenApiConnector(document, options) {
+  const actions = [];
+  for (const [path, methods] of Object.entries(document.paths ?? {})) {
+    for (const [method, rawOperation] of Object.entries(methods)) {
+      const normalizedMethod = method.toLowerCase();
+      if (!HTTP_METHODS.has(normalizedMethod) || !isObject(rawOperation)) continue;
+      const operation = rawOperation;
+      const operationId = operation.operationId ?? `${normalizedMethod}_${path.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+      actions.push({
+        id: operationId,
+        title: operation.summary ?? titleFromId(operationId),
+        risk: riskFromHttpMethod(normalizedMethod, operation, options.defaultRisk),
+        requiredScopes: scopesFromOpenApiOperation(operation, options.scopes ?? []),
+        dataClass: options.dataClass ?? "private",
+        description: operation.description ?? operation.summary ?? `${normalizedMethod.toUpperCase()} ${path}`,
+        approvalRequired: riskFromHttpMethod(normalizedMethod, operation, options.defaultRisk) !== "read",
+        inputSchema: openApiInputSchema(path, normalizedMethod, operation),
+        outputSchema: operation.responses
+      });
+    }
+  }
+  return connectorFromActions(options, actions);
+}
+function importGraphqlConnector(operations, options) {
+  return connectorFromActions(options, operations.map((operation) => ({
+    id: operation.name,
+    title: titleFromId(operation.name),
+    risk: operation.kind === "query" ? "read" : options.defaultRisk ?? "write",
+    requiredScopes: operation.requiredScopes ?? options.scopes ?? [],
+    dataClass: options.dataClass ?? "private",
+    description: operation.description,
+    approvalRequired: operation.kind === "mutation",
+    inputSchema: operation.inputSchema,
+    outputSchema: operation.outputSchema
+  })));
+}
+function importMcpConnector(catalog, options) {
+  return connectorFromActions(options, catalog.tools.map((tool) => {
+    const risk = riskFromMcpTool(tool, options.defaultRisk);
+    return {
+      id: tool.name,
+      title: tool.annotations?.title ?? titleFromId(tool.name),
+      risk,
+      requiredScopes: options.scopes ?? [],
+      dataClass: options.dataClass ?? "private",
+      description: tool.description,
+      approvalRequired: risk !== "read",
+      inputSchema: tool.inputSchema
+    };
+  }));
+}
+function connectorFromActions(options, actions) {
+  const scopes = unique2([
+    ...options.scopes ?? [],
+    ...actions.flatMap((action) => action.requiredScopes)
+  ]);
+  return {
+    id: options.connectorId,
+    providerId: options.providerId,
+    title: options.connectorTitle,
+    category: options.category ?? "other",
+    auth: options.auth ?? "custom",
+    scopes,
+    actions,
+    metadata: { source: "catalog-importer" }
+  };
+}
+function riskFromHttpMethod(method, operation, fallback) {
+  if (method === "get") return "read";
+  if (method === "delete") return "destructive";
+  const text = `${operation.operationId ?? ""} ${operation.summary ?? ""} ${operation.description ?? ""}`.toLowerCase();
+  if (/\b(delete|remove|destroy|cancel|void|revoke|drop)\b/.test(text)) return "destructive";
+  return fallback && fallback !== "read" ? fallback : "write";
+}
+function riskFromMcpTool(tool, fallback) {
+  if (tool.annotations?.destructiveHint) return "destructive";
+  if (tool.annotations?.readOnlyHint) return "read";
+  const text = `${tool.name} ${tool.description ?? ""}`.toLowerCase();
+  if (/\b(delete|remove|destroy|cancel|void|revoke|drop)\b/.test(text)) return "destructive";
+  if (/\b(get|list|read|search|find|fetch|query)\b/.test(text)) return "read";
+  return fallback ?? "write";
+}
+function scopesFromOpenApiOperation(operation, fallback) {
+  const scopes = (operation.security ?? []).flatMap((entry) => Object.values(entry).flat());
+  return unique2(scopes.length > 0 ? scopes : fallback);
+}
+function openApiInputSchema(path, method, operation) {
+  return {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+      path: { const: path },
+      method: { const: method.toUpperCase() },
+      parameters: { type: "object", additionalProperties: true },
+      body: operation.requestBody ?? { type: "object", additionalProperties: true }
+    }
+  };
+}
+function titleFromId(id) {
+  return id.replace(/([a-z])([A-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/g).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+}
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function unique2(values) {
+  return [...new Set(values)];
+}
+
 // src/index.ts
 var IntegrationError = class extends Error {
   constructor(message, code) {
@@ -3142,8 +3266,8 @@ var IntegrationHub = class {
       id: `cap_${randomUUID2()}`,
       subject: request.subject,
       connectionId: request.connectionId,
-      scopes: unique2(request.scopes),
-      allowedActions: unique2(request.allowedActions),
+      scopes: unique3(request.scopes),
+      allowedActions: unique3(request.allowedActions),
       issuedAt: now.toISOString(),
       expiresAt: new Date(now.getTime() + request.ttlMs).toISOString(),
       metadata: request.metadata
@@ -3389,7 +3513,7 @@ function base64UrlEncode(value) {
 function base64UrlDecode(value) {
   return Buffer.from(value, "base64url").toString("utf8");
 }
-function unique2(values) {
+function unique3(values) {
   return [...new Set(values)];
 }
 export {
@@ -3416,6 +3540,9 @@ export {
   googleCalendar,
   googleSheets,
   hubspot,
+  importGraphqlConnector,
+  importMcpConnector,
+  importOpenApiConnector,
   integrationToolName,
   invocationRequestFromEnvelope,
   manifestToConnector,
@@ -3443,6 +3570,7 @@ export {
   verifyHmacSignature,
   verifySlackSignature,
   verifyStripeSignature,
+  verifyTwilioSignature,
   webhookConnector
 };
 //# sourceMappingURL=index.js.map