@contractspec/integration.providers-impls 3.0.0 → 3.2.0

package/README.md

@@ -37,7 +37,7 @@ Secret payload example (`secretRef` target value):
 Factory usage:
 
 ```ts
-import { IntegrationProviderFactory } from "@contractspec/integration.providers-impls/impls/provider-factory";
+import { IntegrationProviderFactory } from '@contractspec/integration.providers-impls/impls/provider-factory';
 
 const factory = new IntegrationProviderFactory();
 const analytics = await factory.createAnalyticsProvider(context); // key: analytics.posthog
@@ -54,7 +54,7 @@ This package ships health/wearables providers routed by a transport strategy:
 Factory usage:
 
 ```ts
-import { IntegrationProviderFactory } from "@contractspec/integration.providers-impls/impls/provider-factory";
+import { IntegrationProviderFactory } from '@contractspec/integration.providers-impls/impls/provider-factory';
 
 const factory = new IntegrationProviderFactory();
 const healthProvider = await factory.createHealthProvider(context); // key: health.*
@@ -158,7 +158,7 @@ Secret payload example (`secretRef` target value):
 ### 2) Factory usage
 
 ```ts
-import { IntegrationProviderFactory } from "@contractspec/integration.providers-impls/impls/provider-factory";
+import { IntegrationProviderFactory } from '@contractspec/integration.providers-impls/impls/provider-factory';
 
 const factory = new IntegrationProviderFactory();
 
@@ -169,20 +169,20 @@ const dbProvider = await factory.createDatabaseProvider(databaseContext); // key
 ### 3) Direct provider usage
 
 ```ts
-import { SupabaseVectorProvider } from "@contractspec/integration.providers-impls/impls/supabase-vector";
-import { SupabasePostgresProvider } from "@contractspec/integration.providers-impls/impls/supabase-psql";
+import { SupabaseVectorProvider } from '@contractspec/integration.providers-impls/impls/supabase-vector';
+import { SupabasePostgresProvider } from '@contractspec/integration.providers-impls/impls/supabase-psql';
 
 const vector = new SupabaseVectorProvider({
   connectionString: process.env.SUPABASE_DATABASE_URL,
-  schema: "public",
-  table: "contractspec_vectors",
-  distanceMetric: "cosine",
+  schema: 'public',
+  table: 'contractspec_vectors',
+  distanceMetric: 'cosine',
 });
 
 const database = new SupabasePostgresProvider({
   connectionString: process.env.SUPABASE_DATABASE_URL,
   maxConnections: 10,
-  sslMode: "require",
+  sslMode: 'require',
 });
 ```
 
@@ -191,3 +191,53 @@ const database = new SupabasePostgresProvider({
 - `SupabaseVectorProvider` creates `vector` extension/table/indexes automatically when `createTableIfMissing=true`.
 - `SupabaseVectorProvider` maps scores from pgvector distances (`cosine`, `l2`, `inner_product`) to `VectorSearchResult.score`.
 - `SupabasePostgresProvider` supports `$1`, `$2`, ... placeholders, transactions, and clean connection shutdown through `close()`.
+
+## Composio universal fallback
+
+When an integration key has no native implementation, the factory can delegate to [Composio](https://composio.dev/) -- a platform providing 850+ toolkits (Slack, GitHub, Gmail, Jira, Salesforce, etc.) via MCP or native SDK.
+
+### Enabling the fallback
+
+Pass a `ComposioFallbackResolver` when constructing the factory:
+
+```ts
+import { IntegrationProviderFactory } from '@contractspec/integration.providers-impls/impls/provider-factory';
+import { ComposioFallbackResolver } from '@contractspec/integration.providers-impls/impls/composio-fallback-resolver';
+
+const resolver = new ComposioFallbackResolver({
+  apiKey: process.env.COMPOSIO_API_KEY!,
+  preferredTransport: 'mcp', // "mcp" (default) or "sdk"
+});
+
+const factory = new IntegrationProviderFactory({ composioFallback: resolver });
+
+// Now any unsupported key falls through to Composio:
+const messaging = await factory.createMessagingProvider(discordContext);
+```
+
+### Transport modes
+
+| Mode              | When to use        | How it works                                                    |
+| ----------------- | ------------------ | --------------------------------------------------------------- |
+| **MCP** (default) | Standard fallback  | Creates a Composio session, connects via MCP protocol           |
+| **SDK**           | Advanced use cases | Uses `@composio/core` directly for tool search, auth management |
+
+### Domain proxy adapters
+
+For typed domains (messaging, email, payments, project management, calendar), the resolver returns proxy adapters that implement the ContractSpec interface and translate method calls to Composio tool executions. For untyped domains, a `ComposioGenericProxy` provides raw `executeTool()` access.
+
+### Runtime configuration
+
+Add `composio` to your `IntegrationRuntimeConfig`:
+
+```ts
+const runtimeConfig: IntegrationRuntimeConfig = {
+  secretProvider: mySecretProvider,
+  composio: {
+    apiKey: process.env.COMPOSIO_API_KEY!,
+    preferredTransport: 'mcp',
+  },
+};
+```
+
+See `docs/tech/integrations/composio-fallback.md` for the full architecture.

package/dist/impls/async-event-queue.js

@@ -1,4 +1,6 @@
 // @bun
+var __require = import.meta.require;
+
 // src/impls/async-event-queue.ts
 class AsyncEventQueue {
   values = [];

package/dist/impls/composio-fallback-resolver.d.ts

@@ -0,0 +1,34 @@
+import type { IntegrationContext } from '@contractspec/integration.runtime/runtime';
+import type { ComposioConfig } from './composio-types';
+import { ComposioGenericProxy } from './composio-proxies';
+import type { MessagingProvider } from '../messaging';
+import type { EmailOutboundProvider } from '../email';
+import type { PaymentsProvider } from '../payments';
+import type { ProjectManagementProvider } from '../project-management';
+import type { CalendarProvider } from '../calendar';
+/**
+ * Resolves unsupported integration keys to Composio-backed proxy providers.
+ *
+ * When IntegrationProviderFactory encounters an unknown key, it delegates
+ * to this resolver. The resolver maps the key to a Composio toolkit and
+ * returns a domain-typed proxy that translates method calls into Composio
+ * tool executions.
+ */
+export declare class ComposioFallbackResolver {
+    private readonly mcpProvider;
+    private readonly sdkProvider;
+    private readonly preferredTransport;
+    constructor(config: ComposioConfig);
+    /**
+     * Returns true for any integration key -- Composio is a universal fallback.
+     * The actual availability of the toolkit is checked at execution time.
+     */
+    canHandle(_integrationKey: string): boolean;
+    createMessagingProxy(context: IntegrationContext): MessagingProvider;
+    createEmailProxy(context: IntegrationContext): EmailOutboundProvider;
+    createPaymentsProxy(context: IntegrationContext): PaymentsProvider;
+    createProjectManagementProxy(context: IntegrationContext): ProjectManagementProvider;
+    createCalendarProxy(context: IntegrationContext): CalendarProvider;
+    createGenericProxy(context: IntegrationContext): ComposioGenericProxy;
+    private getProxy;
+}