@tangle-network/agent-integrations 0.5.0 → 0.7.0

package/README.md

@@ -55,6 +55,8 @@ The SDK surface for that flow is:
 
 - `buildIntegrationToolCatalog` and `searchIntegrationTools` for discoverable
   tool catalogs.
+- `buildIntegrationCoverageConnectors` for broad planning coverage across
+  100+ high-value integrations before each one has a first-party executor.
 - `toMcpTools` for MCP-compatible tool export.
 - `IntegrationHub.issueCapability` for scoped sandbox handoff.
 - `createDefaultIntegrationPolicyEngine` for allow / approval / deny decisions.
@@ -63,6 +65,8 @@ The SDK surface for that flow is:
   action/tool consistency, idempotency-key, metadata-shape, known-tool, and
   input-size checks.
 - `createConnectorAdapterProvider` to run first-party adapters through the hub.
+- `declarativeRestConnector` to promote REST-shaped providers from compact,
+  reviewed specs instead of hand-writing one brittle adapter per API.
 
 ```ts
 import {
@@ -134,6 +138,21 @@ const provider = createHttpIntegrationProvider({
 The HTTP adapter keeps product code stable while the backing provider can be
 Nango, Pipedream, Activepieces, a Zapier-style service, or an internal gateway.
 
+For first-party REST APIs, use the declarative adapter factory:
+
+```ts
+import { createConnectorAdapterProvider, githubConnector } from '@tangle-network/agent-integrations'
+
+const provider = createConnectorAdapterProvider({
+  adapters: [githubConnector],
+  resolveDataSource: async (connection) => loadSourceAndCredentials(connection),
+})
+```
+
+Current first-party adapters include Google Calendar, Microsoft Calendar,
+Google Sheets, Slack, HubSpot, Notion database, Stripe, Twilio, webhooks,
+GitHub, GitLab, Airtable, Asana, and Salesforce.
+
 See [Provider Decision Matrix](./docs/provider-decision-matrix.md) for the
 build-vs-buy policy. The short version: use a vendor gateway only to compress
 time-to-coverage, but keep all product and sandbox code on this package's

package/dist/index.d.ts

@@ -789,6 +789,51 @@ interface NotionDatabaseOptions {
 }
 declare function notionDatabase(opts: NotionDatabaseOptions): ConnectorAdapter;
 
+type RestCredentialPlacement = {
+    kind: 'bearer';
+} | {
+    kind: 'header';
+    header: string;
+    prefix?: string;
+} | {
+    kind: 'query';
+    parameter: string;
+};
+interface RestConnectorSpec {
+    kind: string;
+    displayName: string;
+    description: string;
+    auth: ConnectorAdapter['manifest']['auth'];
+    category: ConnectorAdapter['manifest']['category'];
+    defaultConsistencyModel: ConnectorAdapter['manifest']['defaultConsistencyModel'];
+    baseUrl: string | {
+        metadataKey: string;
+        fallback?: string;
+    };
+    credentialPlacement?: RestCredentialPlacement;
+    defaultHeaders?: Record<string, string>;
+    capabilities: RestOperationSpec[];
+    test?: RestRequestSpec;
+}
+interface RestOperationSpec {
+    name: string;
+    class: 'read' | 'mutation';
+    description: string;
+    parameters: Record<string, unknown>;
+    requiredScopes?: string[];
+    request: RestRequestSpec;
+    cas?: 'etag-if-match' | 'native-idempotency' | 'optimistic-read-verify' | 'none';
+    externalEffect?: boolean;
+}
+interface RestRequestSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    body?: 'args' | string | Record<string, unknown>;
+}
+declare function declarativeRestConnector(spec: RestConnectorSpec): ConnectorAdapter;
+
 /**
  * Twilio SMS connector — outbound texts + recent-message lookup. The
  * agent's "send the caller a confirmation link" surface.
@@ -922,6 +967,16 @@ declare const stripeWebhookReceiverConnector: ConnectorAdapter;
 
 declare const slackEventsConnector: ConnectorAdapter;
 
+declare const githubConnector: ConnectorAdapter;
+
+declare const gitlabConnector: ConnectorAdapter;
+
+declare const airtableConnector: ConnectorAdapter;
+
+declare const asanaConnector: ConnectorAdapter;
+
+declare const salesforceConnector: ConnectorAdapter;
+
 interface IntegrationToolDefinition {
     name: string;
     title: string;
@@ -1128,6 +1183,28 @@ declare function importOpenApiConnector(document: OpenApiDocument, options: Impo
 declare function importGraphqlConnector(operations: GraphqlOperationSpec[], options: ImportCatalogOptions): IntegrationConnector;
 declare function importMcpConnector(catalog: McpCatalog, options: ImportCatalogOptions): IntegrationConnector;
 
+type IntegrationCoveragePriority = 'tier_0' | 'tier_1' | 'tier_2' | 'long_tail';
+interface IntegrationCoverageSpec {
+    id: string;
+    title: string;
+    category: IntegrationConnectorCategory;
+    auth: IntegrationConnector['auth'];
+    priority: IntegrationCoveragePriority;
+    providerKinds: IntegrationProviderKind[];
+    domains: string[];
+    actionPack: IntegrationActionPack;
+    scopes?: string[];
+}
+type IntegrationActionPack = 'email' | 'calendar' | 'chat' | 'crm' | 'storage' | 'docs' | 'database' | 'project' | 'support' | 'marketing' | 'sales' | 'commerce' | 'finance' | 'hr' | 'dev' | 'ai' | 'analytics' | 'workflow' | 'webhook';
+declare function listIntegrationCoverageSpecs(): IntegrationCoverageSpec[];
+declare function buildIntegrationCoverageConnectors(options?: {
+    providerId?: string;
+    priorities?: IntegrationCoveragePriority[];
+    categories?: IntegrationConnectorCategory[];
+    actionPacks?: IntegrationActionPack[];
+}): IntegrationConnector[];
+declare function integrationCoverageChecklistMarkdown(): string;
+
 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';
@@ -1424,4 +1501,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 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 IntegrationInvocationEnvelopeValidationOptions, 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, validateIntegrationInvocationEnvelope, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, verifyTwilioSignature, 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 IntegrationActionPack, 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 IntegrationCoveragePriority, type IntegrationCoverageSpec, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationInvocationEnvelopeValidationOptions, 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 RestConnectorSpec, type RestCredentialPlacement, type RestOperationSpec, type RestRequestSpec, type SecretRef, type SlackOptions, type SlackVerifyOptions, type StartAuthRequest, type StartAuthResult, type StartOAuthInput, type StartOAuthOutput, StaticIntegrationPolicyEngine, type StaticIntegrationPolicyOptions, type StripeVerifyOptions, type TwilioVerifyOptions, _resetPendingFlowsForTests, airtableConnector, asanaConnector, assertValidConnectorManifest, buildApprovalRequest, buildIntegrationCoverageConnectors, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, declarativeRestConnector, exchangeAuthorizationCode, firstHeader, githubConnector, gitlabConnector, googleCalendar, googleSheets, hubspot, importGraphqlConnector, importMcpConnector, importOpenApiConnector, integrationCoverageChecklistMarkdown, integrationToolName, invocationRequestFromEnvelope, listIntegrationCoverageSpecs, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, salesforceConnector, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, validateIntegrationInvocationEnvelope, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, verifyTwilioSignature, webhookConnector };