@tangle-network/agent-integrations 0.7.1 → 0.8.0

package/README.md

@@ -35,6 +35,8 @@ agent-facing tool contract.
 - A declarative REST adapter factory for promoting REST APIs from reviewed specs.
 - A broad coverage catalog for planning hundreds of integrations without
   pretending every catalog item is executable.
+- A generated `IntegrationSpec` registry used for setup docs, admin UI steps,
+  normalized permissions, healthcheck plans, and tool descriptions.
 
 ## Architecture
 
@@ -78,6 +80,9 @@ pnpm add @tangle-network/agent-integrations
 | `createHttpIntegrationProvider` | Adapter for hosted integration gateways. |
 | `createConnectorAdapterProvider` | Runs first-party `ConnectorAdapter`s through the same provider contract. |
 | `declarativeRestConnector` | Builds REST-backed first-party adapters from compact specs. |
+| `listIntegrationSpecs` | Generates setup/execution specs from the coverage catalog and family defaults. |
+| `renderRunbookMarkdown` / `renderConsoleSteps` | Render operator docs or admin UI steps from the same spec source. |
+| `validateCredentialSet` / `buildHealthcheckPlan` | Validate setup input and describe the correct healthcheck path. |
 
 ## Provider Strategy
 

package/dist/index.d.ts

@@ -1205,6 +1205,189 @@ declare function buildIntegrationCoverageConnectors(options?: {
 }): IntegrationConnector[];
 declare function integrationCoverageChecklistMarkdown(): string;
 
+type IntegrationAuthMode = 'oauth2' | 'api_key' | 'hmac' | 'none' | 'custom';
+type IntegrationSpecStatus = 'catalog' | 'executable' | 'deprecated';
+type IntegrationFamilyId = 'google' | 'microsoft-graph' | 'atlassian' | 'salesforce' | 'hubspot' | 'slack' | 'notion' | 'standard-oauth2' | 'api-key' | 'hmac' | 'none';
+type NormalizedPermission = `${string}.read` | `${string}.write` | `${string}.delete` | `${string}.admin`;
+interface IntegrationSpec {
+    kind: string;
+    title: string;
+    category: IntegrationConnectorCategory;
+    status: IntegrationSpecStatus;
+    family: IntegrationFamilyId;
+    auth: IntegrationAuthSpec;
+    permissions: PermissionDescriptor[];
+    actions: IntegrationConnectorAction[];
+    triggers?: IntegrationConnectorTrigger[];
+    setup: IntegrationSetupSpec;
+    lifecycle?: IntegrationLifecycleSpec;
+    plannerHints?: IntegrationPlannerHints;
+    metadata?: Record<string, unknown>;
+}
+type IntegrationAuthSpec = OAuth2AuthSpec | ApiKeyAuthSpec | HmacAuthSpec | NoneAuthSpec | CustomAuthSpec;
+interface OAuth2AuthSpec {
+    mode: 'oauth2';
+    authorizationUrl: string;
+    tokenUrl: string;
+    clientIdEnv?: string;
+    clientSecretEnv?: string;
+    scopes: ScopeDescriptor[];
+    extraAuthParams?: Record<string, string>;
+    redirectUriTemplate: string;
+    pkce?: 'required' | 'supported' | 'unsupported';
+}
+interface ApiKeyAuthSpec {
+    mode: 'api_key';
+    credential: CredentialFieldSpec;
+    placement?: 'bearer' | 'header' | 'query' | 'basic';
+}
+interface HmacAuthSpec {
+    mode: 'hmac';
+    credential: CredentialFieldSpec;
+    signatureHeader?: string;
+}
+interface NoneAuthSpec {
+    mode: 'none';
+}
+interface CustomAuthSpec {
+    mode: 'custom';
+    description: string;
+}
+interface ScopeDescriptor {
+    normalized: NormalizedPermission;
+    providerScope: string;
+    title: string;
+    reason: string;
+    risk: IntegrationActionRisk;
+    dataClass: IntegrationDataClass;
+}
+interface PermissionDescriptor {
+    normalized: NormalizedPermission;
+    providerScopes: string[];
+    title: string;
+    risk: IntegrationActionRisk;
+    dataClass: IntegrationDataClass;
+    reason: string;
+}
+interface CredentialFieldSpec {
+    label: string;
+    description: string;
+    env?: string;
+    example?: string;
+    regex?: string;
+    secret: boolean;
+}
+interface ConsoleStep {
+    id: string;
+    title: string;
+    detail: string;
+    copyValue?: string;
+}
+interface Quirk {
+    id: string;
+    severity: 'info' | 'warning' | 'critical';
+    message: string;
+}
+interface PostSetupCheck {
+    id: string;
+    title: string;
+    detail: string;
+}
+interface HealthcheckSpec {
+    id: string;
+    level: 'client_config' | 'connection' | 'webhook' | 'static';
+    method?: 'GET' | 'POST';
+    url?: string;
+    expectedStatus?: number[];
+    description: string;
+}
+interface IntegrationSetupSpec {
+    consoleUrl?: string;
+    consoleSteps: ConsoleStep[];
+    credentialFields: CredentialFieldSpec[];
+    redirectUriTemplate?: string;
+    knownQuirks?: Quirk[];
+    postSetup?: PostSetupCheck[];
+    healthcheck?: HealthcheckSpec;
+}
+interface IntegrationLifecycleSpec {
+    supportsRefresh: boolean;
+    supportsRevoke: boolean;
+    supportsIncrementalAuth: boolean;
+    recommendedHealthcheckIntervalHours?: number;
+    freshnessSloMinutes?: number;
+}
+interface IntegrationPlannerHints {
+    useFor: string[];
+    avoidFor?: string[];
+    dataFreshness: 'realtime' | 'near_realtime' | 'eventual' | 'manual';
+    writeRisk: 'low' | 'medium' | 'high';
+}
+interface IntegrationFamilySpec {
+    id: IntegrationFamilyId;
+    title: string;
+    authMode: IntegrationAuthMode;
+    consoleUrl?: string;
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    redirectUriTemplate?: string;
+    credentialFields: CredentialFieldSpec[];
+    consoleSteps: ConsoleStep[];
+    knownQuirks?: Quirk[];
+    lifecycle: IntegrationLifecycleSpec;
+}
+interface IntegrationSpecValidationIssue {
+    path: string;
+    message: string;
+}
+interface IntegrationSpecValidationResult {
+    ok: boolean;
+    issues: IntegrationSpecValidationIssue[];
+}
+interface RenderSpecOptions {
+    host: string;
+    callbackPath?: string;
+}
+interface RenderedConsoleStep extends ConsoleStep {
+    detail: string;
+    copyValue?: string;
+}
+interface CredentialValidationInput {
+    field: CredentialFieldSpec;
+    value: string;
+}
+interface CredentialValidationResult {
+    ok: boolean;
+    field: string;
+    message?: string;
+}
+interface HealthcheckPlan {
+    kind: string;
+    healthcheck: HealthcheckSpec;
+    requires: Array<'client_id' | 'client_secret' | 'api_key' | 'hmac_secret' | 'connection_credentials'>;
+    message: string;
+}
+declare function specAuthToConnectorAuth(auth: IntegrationAuthSpec): IntegrationConnector['auth'];
+
+declare const INTEGRATION_FAMILIES: Record<IntegrationFamilyId, IntegrationFamilySpec>;
+declare function getIntegrationFamily(id: IntegrationFamilyId): IntegrationFamilySpec;
+
+declare function listIntegrationSpecs(): IntegrationSpec[];
+declare function getIntegrationSpec(kind: string): IntegrationSpec | undefined;
+declare function listExecutableIntegrationSpecs(): IntegrationSpec[];
+declare function integrationSpecToConnector(spec: IntegrationSpec, providerId?: string): IntegrationConnector;
+
+declare function renderConsoleSteps(spec: IntegrationSpec, options: RenderSpecOptions): RenderedConsoleStep[];
+declare function renderRunbookMarkdown(spec: IntegrationSpec, options: RenderSpecOptions): string;
+declare function renderAgentToolDescription(spec: IntegrationSpec): string;
+declare function buildHealthcheckPlan(spec: IntegrationSpec): HealthcheckPlan;
+declare function consoleStepsToText(steps: ConsoleStep[]): string;
+
+declare function validateIntegrationSpec(spec: IntegrationSpec): IntegrationSpecValidationResult;
+declare function assertValidIntegrationSpec(spec: IntegrationSpec): void;
+declare function validateCredentialFormat(field: CredentialFieldSpec, value: string): CredentialValidationResult;
+declare function validateCredentialSet(spec: IntegrationSpec, values: Record<string, string>): CredentialValidationResult[];
+
 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';
@@ -1501,4 +1684,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 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 };
+export { type ApiKeyAuthSpec, 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, type ConsoleStep, type CredentialFieldSpec, type CredentialValidationInput, type CredentialValidationResult, CredentialsExpired, type CustomAuthSpec, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DataSourceMetadata, type EventHandlerResult, type ExchangeCodeInput, type GenericHmacVerifyOptions, type GoogleCalendarOptions, type GoogleSheetsOptions, type GraphqlOperationSpec, type HealthcheckPlan, type HealthcheckSpec, type HmacAuthSpec, type HttpIntegrationProviderOptions, type HubSpotOptions, INTEGRATION_FAMILIES, type ImportCatalogOptions, InMemoryConnectionStore, InMemoryOAuthFlowStore, type InboundEvent, type IntegrationActionGuard, type IntegrationActionPack, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationApprovalRequest, type IntegrationApprovalResolution, type IntegrationAuthMode, type IntegrationAuthSpec, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationCoveragePriority, type IntegrationCoverageSpec, type IntegrationDataClass, IntegrationError, type IntegrationFamilyId, type IntegrationFamilySpec, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationInvocationEnvelopeValidationOptions, type IntegrationLifecycleSpec, type IntegrationPlannerHints, type IntegrationPolicyDecision, type IntegrationPolicyEffect, type IntegrationPolicyEngine, type IntegrationPolicyRule, type IntegrationProvider, type IntegrationProviderKind, type IntegrationSetupSpec, type IntegrationSpec, type IntegrationSpecStatus, type IntegrationSpecValidationIssue, type IntegrationSpecValidationResult, 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 NoneAuthSpec, type NormalizedIntegrationResult, type NormalizedPermission, type NotionDatabaseOptions, type OAuth2AuthSpec, type OAuthFlowStore, type OAuthTokens, type OpenApiDocument, type OpenApiOperation, type ParsedStripeSignatureHeader, type PendingOAuthFlow, type PermissionDescriptor, type PostSetupCheck, type Quirk, type RateLimitSpec, type RefreshInput, type RenderSpecOptions, type RenderedConsoleStep, type ResolvedDataSource, ResourceContention, type RestConnectorSpec, type RestCredentialPlacement, type RestOperationSpec, type RestRequestSpec, type ScopeDescriptor, 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, assertValidIntegrationSpec, buildApprovalRequest, buildHealthcheckPlan, buildIntegrationCoverageConnectors, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consoleStepsToText, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, declarativeRestConnector, exchangeAuthorizationCode, firstHeader, getIntegrationFamily, getIntegrationSpec, githubConnector, gitlabConnector, googleCalendar, googleSheets, hubspot, importGraphqlConnector, importMcpConnector, importOpenApiConnector, integrationCoverageChecklistMarkdown, integrationSpecToConnector, integrationToolName, invocationRequestFromEnvelope, listExecutableIntegrationSpecs, listIntegrationCoverageSpecs, listIntegrationSpecs, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, renderAgentToolDescription, renderConsoleSteps, renderRunbookMarkdown, salesforceConnector, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, specAuthToConnectorAuth, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, validateCredentialFormat, validateCredentialSet, validateIntegrationInvocationEnvelope, validateIntegrationSpec, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, verifyTwilioSignature, webhookConnector };