@contractspec/integration.providers-impls 2.10.0 → 3.1.1

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.*
@@ -75,7 +75,8 @@ Connection config example:
   "allowUnofficial": false,
   "unofficialAllowList": ["health.peloton"],
   "apiBaseUrl": "https://api.provider.example",
-  "mcpUrl": "https://mcp.provider.example"
+  "mcpUrl": "https://mcp.provider.example",
+  "oauthTokenUrl": "https://api.provider.example/oauth/token"
 }
 ```
 
@@ -85,6 +86,10 @@ Secret payload example (`secretRef` target value):
 {
   "apiKey": "provider-api-key",
   "accessToken": "oauth-access-token",
+  "refreshToken": "oauth-refresh-token",
+  "clientId": "oauth-client-id",
+  "clientSecret": "oauth-client-secret",
+  "tokenExpiresAt": "2026-02-01T00:00:00.000Z",
   "mcpAccessToken": "mcp-access-token",
   "webhookSecret": "webhook-signature-secret"
 }
@@ -94,6 +99,7 @@ Notes:
 
 - Unofficial routing is disabled unless `allowUnofficial: true`.
 - When `unofficialAllowList` is provided, only listed `health.*` keys can use unofficial routing.
+- Unofficial routing expects MCP transport (`mcpUrl`) plus either `mcpAccessToken` or automation credentials.
 - If a selected strategy is unavailable, the resolver falls through `strategyOrder`.
 
 ## Supabase integrations
@@ -152,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();
 
@@ -163,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',
 });
 ```
 
@@ -185,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.d.ts

@@ -0,0 +1,8 @@
+export declare class AsyncEventQueue<T> implements AsyncIterable<T> {
+    private readonly values;
+    private readonly waiters;
+    private done;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

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

@@ -0,0 +1,49 @@
+// @bun
+var __require = import.meta.require;
+
+// src/impls/async-event-queue.ts
+class AsyncEventQueue {
+  values = [];
+  waiters = [];
+  done = false;
+  push(value) {
+    if (this.done) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    for (const waiter of this.waiters) {
+      waiter({ value: undefined, done: true });
+    }
+    this.waiters.length = 0;
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = this.values.shift();
+        if (value != null) {
+          return { value, done: false };
+        }
+        if (this.done) {
+          return { value: undefined, done: true };
+        }
+        return new Promise((resolve) => {
+          this.waiters.push(resolve);
+        });
+      }
+    };
+  }
+}
+export {
+  AsyncEventQueue
+};

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;
+}