@mastra/connect 0.3.1 → 0.4.0

package/dist/providers/channel-provider.d.ts

@@ -0,0 +1,32 @@
+import type { ChannelProvider } from '@mastra/core/channels';
+import type { ConnectionCredential, ConnectionContext, ResolvedClient } from '../client.js';
+/**
+ * Extra inputs a channel contributor may need beyond the raw credential:
+ * durable non-secret metadata that lives on the platform connection (e.g.
+ * Discord's `applicationId` + `publicKey`), and a resolved client for
+ * follow-up lookups when necessary.
+ */
+export interface ChannelBuildContext {
+    connectionId: string;
+    context?: ConnectionContext;
+    client: ResolvedClient;
+}
+/**
+ * Registers one channel-capable provider with `channels()`. An `integrationId`
+ * matches the project connection and `build()` materializes a Mastra
+ * `ChannelProvider` from the credential (plus per-integration
+ * `providerOptions`). Ambiguity is handled at the resolver level (`channels()`
+ * warns and picks the first active connection when more than one is present)
+ * so registrations stay minimal.
+ */
+export interface ChannelProviderRegistration<Options = Record<string, unknown>> {
+    /** Platform catalog id used to match project connections (e.g. 'slack', 'telegram', 'discord'). */
+    integrationId: string;
+    /**
+     * Build a Mastra `ChannelProvider` from a resolved credential. Peer packages
+     * are imported inside `build()` with `await import()` so they stay optional
+     * at install time.
+     */
+    build(credential: ConnectionCredential, options?: Options, context?: ChannelBuildContext): Promise<ChannelProvider>;
+}
+//# sourceMappingURL=channel-provider.d.ts.map

package/dist/providers/channel-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-provider.d.ts","sourceRoot":"","sources":["../../src/providers/channel-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5F;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5E,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,UAAU,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACrH"}

package/dist/providers/channels.d.ts

@@ -0,0 +1,30 @@
+import type { ChannelProviderRegistration } from './channel-provider.js';
+/**
+ * Fields on `providerOptions` that `channels()` refuses to forward to a
+ * `ChannelProvider` constructor. Two categories:
+ *
+ * - **Credentials.** The whole point of `channels()` is that the credential
+ *   comes from the platform connection. Passing another `refreshToken` /
+ *   `botToken` via `providerOptions` would silently override the connection
+ *   (and thereby bypass rotation, revocation, and auditing).
+ * - **Framework-managed.** `baseUrl` is derived from the Mastra server config
+ *   so webhook URLs match the actually-bound host. Overriding it from user code
+ *   is a foot-gun (mismatched OAuth redirect URIs, dropped webhook deliveries).
+ *   `encryptionKey` is a process-wide at-rest secret sourced from
+ *   `MASTRA_ENCRYPTION_KEY`; letting `providerOptions` override it per
+ *   integration would fragment the encryption boundary.
+ *
+ * Anything on this list is stripped with a warning; the rest of
+ * `providerOptions` (handlers, streaming, commands, handlers, threadContext,
+ * inlineMedia, etc.) is forwarded to the provider constructor unchanged.
+ */
+declare const SLACK_RESERVED_KEYS: readonly ['baseUrl', 'refreshToken', 'token', 'encryptionKey'];
+declare const TELEGRAM_RESERVED_KEYS: readonly ['baseUrl', 'apiBaseUrl', 'botToken', 'encryptionKey'];
+declare const DISCORD_RESERVED_KEYS: readonly ['baseUrl', 'encryptionKey'];
+/** Reserved (credential + framework-managed) `providerOptions` keys per integration. */
+export type SlackReservedProviderOption = (typeof SLACK_RESERVED_KEYS)[number];
+export type TelegramReservedProviderOption = (typeof TELEGRAM_RESERVED_KEYS)[number];
+export type DiscordReservedProviderOption = (typeof DISCORD_RESERVED_KEYS)[number];
+export declare const CHANNELS: readonly ChannelProviderRegistration[];
+export {};
+//# sourceMappingURL=channels.d.ts.map

package/dist/providers/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/providers/channels.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAczE;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,mBAAmB,YAAI,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,CAAU,CAAC;AAC3F,QAAA,MAAM,sBAAsB,YAAI,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,CAAU,CAAC;AAC/F,QAAA,MAAM,qBAAqB,YAAI,SAAS,EAAE,eAAe,CAAU,CAAC;AAEpE,wFAAwF;AACxF,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AACrF,MAAM,MAAM,6BAA6B,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAuKnF,eAAO,MAAM,QAAQ,EAAE,SAAS,2BAA2B,EAAoD,CAAC"}

package/dist/registry.d.ts

@@ -1,4 +1,5 @@
 import type { ToolsInput } from '@mastra/core/agent';
+import type { ChannelProviderRegistration } from './providers/channel-provider.js';
 import type { ProviderToolsOptions } from './toolset.js';
 interface ProviderRegistrationBase {
     /** Platform catalog id used to match project connections. */
@@ -20,7 +21,19 @@ export type ProviderRegistration = ProxyProviderRegistration | McpProviderRegist
  * Providers with checked-in HTTP toolsets. MCP-backed providers are discovered
  * from the Platform integration catalog at runtime.
  */
+export declare const TOOLS: readonly ProviderRegistration[];
+/**
+ * @deprecated Use `TOOLS`. This alias is retained for one release cycle so
+ * downstream consumers keep working; it will be removed in the next minor.
+ */
 export declare const PROVIDERS: readonly ProviderRegistration[];
 export declare function findRegistration(integrationId: string): ProviderRegistration | undefined;
+/**
+ * Channel-capable providers with a hand-maintained `channels()` registration.
+ * The launch ships three (Slack, Telegram, Discord); the provider generator
+ * grows to cover new entries when a fourth lands.
+ */
+export declare const CHANNELS: readonly ChannelProviderRegistration[];
+export declare function findChannelRegistration(integrationId: string): ChannelProviderRegistration | undefined;
 export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,UAAU,wBAAwB;IAChC,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,UAAU,CAAC;CAC7D;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,SAAS,EAAE,KAAK,CAAC;CAClB;AAED,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,oBAAoB,EAAwB,CAAC;AAE9E,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAExF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAGnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,UAAU,wBAAwB;IAChC,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,UAAU,CAAC;CAC7D;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,SAAS,EAAE,KAAK,CAAC;CAClB;AAED,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,oBAAoB,EAAwB,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,oBAAoB,EAAU,CAAC;AAEhE,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAExF;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,2BAA2B,EAAkB,CAAC;AAE9E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,2BAA2B,GAAG,SAAS,CAEtG"}

package/dist/resolution.d.ts

@@ -0,0 +1,21 @@
+import type { ProjectConnection } from './client.js';
+/** Identifies one provider's connection-resolution inputs. */
+export interface ConnectionRequest {
+    integrationId: string;
+    /** Fallback connection-id environment variable when more than one active connection exists. */
+    envVar: string;
+    /** Pinned connection id from per-integration options. */
+    connectionId?: string;
+}
+export declare function validateIntegrationOverrides(integrations: Record<string, unknown> | undefined): void;
+export declare function connectionIdEnvVar(integrationId: string): string;
+export declare function groupByIntegrationId(connections: ProjectConnection[]): Map<string, ProjectConnection[]>;
+/**
+ * Resolves the connection to use for one provider, per the contract:
+ * option/env var wins; else a single active connection; anything else
+ * (ambiguity, needs_reauth, no usable candidate) warns and skips so one bad
+ * integration never takes down the whole resolution. A needs_reauth
+ * connection is never silently mapped.
+ */
+export declare function resolveConnection(request: ConnectionRequest, candidates: ProjectConnection[]): string | undefined;
+//# sourceMappingURL=resolution.d.ts.map

package/dist/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","sourceRoot":"","sources":["../src/resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CASpG;AAED,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAQvG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,SAAS,CAoCjH"}

package/dist/tools.d.ts

@@ -0,0 +1,66 @@
+import type { ConnectClientOptions } from './client.js';
+export interface ToolsIntegrationOptions {
+    /** Pin a specific connection id (bypasses env-var fallback and single-active-connection resolution). */
+    connectionId?: string;
+    /** Restrict the returned toolset to these tool keys. Unknown names throw at build time. */
+    allowTools?: string[];
+    /**
+     * MCP tool keys that may run without tool approval. Every other discovered
+     * MCP tool requires approval, whatever the server's annotations claim, since
+     * a remote catalog cannot be trusted to classify its own tools. An unknown
+     * name skips the provider with a warning, so a typo never widens access.
+     */
+    autoApproveTools?: string[];
+    /** Exclude this provider entirely, even if a connection exists. */
+    disabled?: boolean;
+}
+export interface ToolsOptions {
+    /** Platform project whose connections to discover. Falls back to MASTRA_PROJECT_ID. */
+    projectId?: string;
+    /** Optional per-provider overrides keyed by integrationId. */
+    integrations?: Record<string, ToolsIntegrationOptions>;
+    client?: ConnectClientOptions;
+    /** How long a resolved snapshot stays fresh, in milliseconds. Default 30_000. `0` revalidates every resolution. */
+    ttlMs?: number;
+}
+type ResolvedToolsRecord = Record<string, {
+    id: string;
+}>;
+/**
+ * Live tool resolver returned by `tools()`. Pass it straight to an agent's
+ * dynamic `tools` argument: Mastra calls it per generate/stream, so project
+ * integrations attached or detached on the platform are reflected without
+ * restarting the server. Call it directly (`await tools()`) when you need the
+ * current flat tool record.
+ */
+export interface ToolsResolver {
+    (ctx?: {
+        requestContext?: unknown;
+        mastra?: unknown;
+    }): Promise<ResolvedToolsRecord>;
+    /** Drops the cached snapshot; the next resolution fetches fresh from the platform. */
+    invalidate(): void;
+    /** Fetches tools from the platform now and updates the cache. Rejects if the platform fetch fails. */
+    refresh(): Promise<ResolvedToolsRecord>;
+    /** Closes MCP transports owned by this resolver and clears its cached snapshot. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Returns a live toolset resolver over the project's Platform connections.
+ * HTTP providers are loaded from the shipped `TOOLS` registry. MCP providers
+ * are discovered from the Platform integration catalog. Tools from every supported
+ * provider with a matching project connection are merged into one flat record
+ * (matched by `integrationId`). The resolver serves a cached snapshot,
+ * revalidating from the platform every `ttlMs`, so integrations attached
+ * to (or detached from) the project are picked up (or dropped) without a
+ * restart.
+ *
+ * Configuration errors (missing project id, bad ttlMs, malformed integration id)
+ * throw here — at call time — so they surface at startup.
+ * Expected provider absence is silently skipped. Actionable per-integration
+ * problems during resolution (needs re-auth or ambiguity) are downgraded to
+ * warn-and-skip so one bad integration never takes down the whole toolset.
+ */
+export declare function tools(options?: ToolsOptions): ToolsResolver;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAA8D,MAAM,aAAa,CAAC;AAapH,MAAM,WAAW,uBAAuB;IACtC,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACvD,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,KAAK,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrF,sFAAsF;IACtF,UAAU,IAAI,IAAI,CAAC;IACnB,sGAAsG;IACtG,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACxC,mFAAmF;IACnF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,aAAa,CAkI/D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/connect",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Use Mastra platform integration connections as agent toolsets",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,8 +45,22 @@
   },
   "peerDependencies": {
     "@mastra/core": ">=1.68.0-0 <2.0.0-0",
+    "@mastra/discord": ">=1.0.0-0 <2.0.0-0",
+    "@mastra/slack": ">=1.0.0-0 <2.0.0-0",
+    "@mastra/telegram": ">=0.1.0-0 <1.0.0-0",
     "zod": ">=3.0.0 || >=4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@mastra/discord": {
+      "optional": true
+    },
+    "@mastra/slack": {
+      "optional": true
+    },
+    "@mastra/telegram": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "prettier": "3.9.5",
     "ts-morph": "^27.0.2",
@@ -55,9 +69,12 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "zod": "^4.6.4",
-    "@internal/lint": "0.0.136",
-    "@internal/types-builder": "0.0.111",
-    "@mastra/core": "1.70.0"
+    "@internal/lint": "0.0.137",
+    "@mastra/discord": "1.1.0",
+    "@mastra/slack": "1.6.4",
+    "@mastra/telegram": "0.1.3",
+    "@mastra/core": "1.71.0",
+    "@internal/types-builder": "0.0.112"
   },
   "dependencies": {
     "@mastra/mcp": "^2.1.0"
@@ -72,6 +89,6 @@
     "list-providers": "tsx scripts/list-providers.ts",
     "remove-provider": "tsx scripts/remove-provider.ts",
     "sync-templates": "tsx scripts/sync-templates.ts",
-    "test": "vitest run"
+    "test": "vitest run && tsc --noEmit"
   }
 }

package/dist/connect.test-d.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=connect.test-d.d.ts.map

package/dist/connect.test-d.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"connect.test-d.d.ts","sourceRoot":"","sources":["../src/connect.test-d.ts"],"names":[],"mappings":""}