@tangle-network/agent-integrations 0.2.0 → 0.3.0

package/README.md

@@ -37,19 +37,49 @@ capability. The sandbox should never receive reusable provider secrets.
 
 ## Core Usage
 
+### Product Flow
+
+For Agent Builder and sandbox apps, the intended flow is:
+
+```txt
+generated app declares required tools
+  -> app searches the integration catalog by intent
+  -> user connects the missing accounts
+  -> runtime issues a short-lived capability to the sandbox
+  -> reads run immediately
+  -> writes pause for policy approval
+  -> every call returns an audit-safe result
+```
+
+The SDK surface for that flow is:
+
+- `buildIntegrationToolCatalog` and `searchIntegrationTools` for discoverable
+  tool catalogs.
+- `toMcpTools` for MCP-compatible tool export.
+- `IntegrationHub.issueCapability` for scoped sandbox handoff.
+- `createDefaultIntegrationPolicyEngine` for allow / approval / deny decisions.
+- `buildIntegrationInvocationEnvelope` for sandbox-safe tool calls.
+- `createConnectorAdapterProvider` to run first-party adapters through the hub.
+
 ```ts
 import {
   InMemoryConnectionStore,
   IntegrationHub,
+  buildIntegrationToolCatalog,
   createMockIntegrationProvider,
+  searchIntegrationTools,
 } from '@tangle-network/agent-integrations'
 
+const provider = createMockIntegrationProvider()
 const hub = new IntegrationHub({
-  providers: [createMockIntegrationProvider()],
+  providers: [provider],
   store: new InMemoryConnectionStore(),
   capabilitySecret: 'dev-secret',
 })
 
+const catalog = buildIntegrationToolCatalog(await hub.listConnectors())
+const tools = searchIntegrationTools(catalog, 'search unread gmail', { maxRisk: 'read' })
+
 const connection = await hub.upsertConnection({
   id: 'conn_1',
   owner: { type: 'user', id: 'user_1' },

package/dist/index.d.ts

@@ -903,6 +903,152 @@ declare const stripeWebhookReceiverConnector: ConnectorAdapter;
 
 declare const slackEventsConnector: ConnectorAdapter;
 
+interface IntegrationToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    providerId: string;
+    connectorId: string;
+    connectorTitle: string;
+    category: IntegrationConnectorCategory;
+    action: IntegrationConnectorAction;
+    risk: IntegrationActionRisk;
+    dataClass: IntegrationDataClass;
+    requiredScopes: string[];
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    tags: string[];
+}
+interface IntegrationToolSearchFilters {
+    providerId?: string;
+    connectorId?: string;
+    category?: IntegrationConnectorCategory;
+    maxRisk?: IntegrationActionRisk;
+    dataClass?: IntegrationDataClass;
+    limit?: number;
+}
+interface IntegrationToolSearchResult {
+    tool: IntegrationToolDefinition;
+    score: number;
+    matched: string[];
+}
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+declare function integrationToolName(providerId: string, connectorId: string, actionId: string): string;
+declare function parseIntegrationToolName(name: string): {
+    providerId: string;
+    connectorId: string;
+    actionId: string;
+};
+declare function buildIntegrationToolCatalog(connectors: IntegrationConnector[]): IntegrationToolDefinition[];
+declare function searchIntegrationTools(catalog: IntegrationToolDefinition[], query: string, filters?: IntegrationToolSearchFilters): IntegrationToolSearchResult[];
+declare function toMcpTools(tools: IntegrationToolDefinition[]): McpToolDefinition[];
+
+type IntegrationPolicyEffect = 'allow' | 'require_approval' | 'deny';
+interface IntegrationPolicyRule {
+    id: string;
+    effect: IntegrationPolicyEffect;
+    reason: string;
+    providerId?: string;
+    connectorId?: string;
+    action?: string;
+    maxRisk?: IntegrationActionRisk;
+    risk?: IntegrationActionRisk;
+    dataClass?: IntegrationDataClass;
+}
+interface StaticIntegrationPolicyOptions {
+    rules?: IntegrationPolicyRule[];
+    defaultReadEffect?: IntegrationPolicyEffect;
+    defaultWriteEffect?: IntegrationPolicyEffect;
+    defaultDestructiveEffect?: IntegrationPolicyEffect;
+    now?: () => Date;
+}
+interface IntegrationApprovalResolution {
+    approvalId: string;
+    approved: boolean;
+    resolvedBy: string;
+    resolvedAt: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class StaticIntegrationPolicyEngine implements IntegrationPolicyEngine {
+    private readonly rules;
+    private readonly defaultReadEffect;
+    private readonly defaultWriteEffect;
+    private readonly defaultDestructiveEffect;
+    private readonly now;
+    constructor(options?: StaticIntegrationPolicyOptions);
+    decide(ctx: IntegrationGuardContext & {
+        subject: {
+            type: string;
+            id: string;
+        };
+    }): IntegrationPolicyDecision;
+    private defaultEffect;
+}
+declare function createDefaultIntegrationPolicyEngine(options?: Omit<StaticIntegrationPolicyOptions, 'rules'>): StaticIntegrationPolicyEngine;
+declare function buildApprovalRequest(ctx: IntegrationGuardContext & {
+    subject: {
+        type: string;
+        id: string;
+    };
+}, reason: string, requestedAt: Date): IntegrationApprovalRequest;
+declare function redactApprovalRequest(request: IntegrationApprovalRequest): IntegrationApprovalRequest;
+
+interface IntegrationInvocationEnvelope {
+    kind: 'integration.invocation';
+    capabilityToken: string;
+    toolName: string;
+    action: string;
+    input?: unknown;
+    idempotencyKey: string;
+    dryRun?: boolean;
+    metadata?: Record<string, unknown>;
+}
+type NormalizedIntegrationResult = {
+    status: 'ok';
+    action: string;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+} | {
+    status: 'approval_required';
+    action: string;
+    approval: IntegrationApprovalRequest;
+    metadata?: Record<string, unknown>;
+} | {
+    status: 'failed';
+    action: string;
+    error: string;
+    metadata?: Record<string, unknown>;
+};
+declare function buildIntegrationInvocationEnvelope(input: {
+    capabilityToken: string;
+    toolName: string;
+    args?: unknown;
+    idempotencyKey: string;
+    dryRun?: boolean;
+    metadata?: Record<string, unknown>;
+}): IntegrationInvocationEnvelope;
+declare function invocationRequestFromEnvelope(envelope: IntegrationInvocationEnvelope): InvokeWithCapabilityRequest;
+declare function redactInvocationEnvelope(envelope: IntegrationInvocationEnvelope): Omit<IntegrationInvocationEnvelope, 'capabilityToken'> & {
+    capabilityToken: '[REDACTED]';
+};
+declare function redactCapability(capability: IntegrationCapability): IntegrationCapability;
+declare function normalizeIntegrationResult(result: IntegrationActionResult): NormalizedIntegrationResult;
+
+interface ConnectorAdapterProviderOptions {
+    id?: string;
+    kind?: IntegrationProviderKind;
+    adapters: ConnectorAdapter[];
+    resolveDataSource: (connection: IntegrationConnection) => Promise<ResolvedDataSource> | ResolvedDataSource;
+    now?: () => Date;
+}
+declare function createConnectorAdapterProvider(options: ConnectorAdapterProviderOptions): IntegrationProvider;
+declare function manifestToConnector(providerId: string, adapter: ConnectorAdapter): 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';
@@ -1100,6 +1246,39 @@ interface IntegrationGuardContext {
     /** The action descriptor from the connector manifest, if discovered. */
     action?: IntegrationConnectorAction;
 }
+type IntegrationPolicyDecision = {
+    decision: 'allow';
+    reason: string;
+    metadata?: Record<string, unknown>;
+} | {
+    decision: 'require_approval';
+    reason: string;
+    approval: IntegrationApprovalRequest;
+    metadata?: Record<string, unknown>;
+} | {
+    decision: 'deny';
+    reason: string;
+    metadata?: Record<string, unknown>;
+};
+interface IntegrationApprovalRequest {
+    id: string;
+    connectionId: string;
+    providerId: string;
+    connectorId: string;
+    action: string;
+    actor: IntegrationActor;
+    risk: IntegrationActionRisk;
+    dataClass: IntegrationDataClass;
+    reason: string;
+    requestedAt: string;
+    inputPreview?: unknown;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationPolicyEngine {
+    decide(ctx: IntegrationGuardContext & {
+        subject: IntegrationActor;
+    }): Promise<IntegrationPolicyDecision> | IntegrationPolicyDecision;
+}
 interface IntegrationHubOptions {
     providers: IntegrationProvider[];
     store: IntegrationConnectionStore;
@@ -1107,6 +1286,10 @@ interface IntegrationHubOptions {
     /** Optional cross-cutting guard. If provided, every invokeAction call
      *  passes through it before reaching the provider. See {@link IntegrationActionGuard}. */
     guard?: IntegrationActionGuard;
+    /** Optional policy engine. Runs after capability/scope checks and before
+     *  provider invocation. Use it to pause writes, deny destructive actions,
+     *  or apply tenant-specific allow rules. */
+    policy?: IntegrationPolicyEngine;
     now?: () => Date;
 }
 interface HttpIntegrationProviderOptions {
@@ -1121,8 +1304,8 @@ interface InvokeWithCapabilityRequest extends Omit<IntegrationActionRequest, 'co
     connectionId?: never;
 }
 declare class IntegrationError extends Error {
-    readonly code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found';
-    constructor(message: string, code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found');
+    readonly code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found' | 'approval_required' | 'policy_denied';
+    constructor(message: string, code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found' | 'approval_required' | 'policy_denied');
 }
 declare class InMemoryConnectionStore implements IntegrationConnectionStore {
     private readonly connections;
@@ -1136,6 +1319,7 @@ declare class IntegrationHub {
     private readonly store;
     private readonly capabilitySecret;
     private readonly guard;
+    private readonly policy;
     private readonly now;
     constructor(options: IntegrationHubOptions);
     listConnectors(): Promise<IntegrationConnector[]>;
@@ -1161,4 +1345,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 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 IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationProvider, type IntegrationProviderKind, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type MicrosoftCalendarOptions, 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, type StripeVerifyOptions, _resetPendingFlowsForTests, assertValidConnectorManifest, consumePendingFlow, createHttpIntegrationProvider, createMockIntegrationProvider, exchangeAuthorizationCode, firstHeader, googleCalendar, googleSheets, hubspot, microsoftCalendar, notionDatabase, parseStripeSignatureHeader, refreshAccessToken, sanitizeConnection, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, 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 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 };