@mastra/connect 0.0.0-aggregate-trace-20261015182851

package/LICENSE-ELv2.txt

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+Generated provider action schemas and implementations in `src/providers/` are adapted from [NangoHQ/integration-templates](https://github.com/NangoHQ/integration-templates), used under the Elastic License 2.0. The source commit is recorded in each provider's `.manifest.json` and generated source headers.
+
+The generated copies have been modified: they run as Mastra tools and route all requests through the Mastra integrations proxy instead of the upstream action runtime.
+
+A verbatim copy of the Elastic License 2.0 is included in [`LICENSE-ELv2.txt`](./LICENSE-ELv2.txt).
+
+The Resend and incident.io providers currently use the contribution fork [rhysbalevicius/integration-templates](https://github.com/rhysbalevicius/integration-templates) while their upstream PRs are reviewed. Their contracts were derived from the official provider OpenAPI specifications; source URLs, revisions, and contract compatibility notes are recorded in each upstream provider directory's `schema-source.json` and README. The fork and these generated adaptations retain Elastic License 2.0 attribution.
+
+The Slack, GitHub, Google Mail, Google Calendar, Fireflies, PostHog, Stripe, Discord, Twitter/X, and HubSpot providers are generated from the head commit of [NangoHQ/integration-templates#677](https://github.com/NangoHQ/integration-templates/pull/677) — upstream main plus that pending contribution — while the PR is reviewed. These generated adaptations retain Elastic License 2.0 attribution.

package/README.md

@@ -0,0 +1,119 @@
+# @mastra/connect
+
+`@mastra/connect` exposes tools backed by connections attached to a Mastra Platform project. Provider credentials stay in the platform connection. Tool traffic passes through Platform so calls can be authorized, audited, and counted without logging arguments or results.
+
+## Installation
+
+```bash
+npm install @mastra/connect
+```
+
+## Usage
+
+Attach connections to your Platform project, configure the project ID and access token, then pass the resolver to your agent's `tools` option:
+
+```ts
+import { tools } from '@mastra/connect';
+
+const connectTools = tools({
+  projectId: process.env.MASTRA_PROJECT_ID,
+  client: { accessToken: process.env.MASTRA_PLATFORM_ACCESS_TOKEN },
+});
+
+const agent = new Agent({
+  // ...
+  tools: connectTools,
+});
+```
+
+The resolver is live: Mastra calls it per generate/stream, so providers connected to (or disconnected from) the project are picked up without a restart.
+
+### Combining with your own tools
+
+Spread the resolver's result alongside your own tools in a dynamic `tools` callback; your tools win on key collision:
+
+```ts
+const agent = new Agent({
+  // ...
+  tools: async ctx => ({ ...(await connectTools(ctx)), weatherTool, searchTool }),
+});
+```
+
+### Choosing providers
+
+The `providers` option accepts two shapes:
+
+```ts
+// Array — an allowlist: only these providers resolve.
+tools({ providers: ['resend', 'incident-io'] });
+
+// Record — per-provider configuration. Every connected provider resolves
+// unless excluded: `true` (or `{}`) enables with defaults, `false` excludes,
+// and an object configures the provider.
+tools({
+  providers: {
+    resend: { allowTools: ['resend_send_email'] },
+    linear: { requireApproval: ['linear_delete_*'] },
+    github: false,
+  },
+});
+```
+
+An id that is neither a checked-in provider nor a platform catalog integration fails with `invalid_options`, so typos never resolve to silence.
+
+### Filtering and approval
+
+- `allowTools` / `disallowTools` (mutually exclusive per provider) restrict a provider's toolset. Entries containing `*` are globs (`'linear_get_*'`). Unknown names and globs that match nothing throw, so access-limiting typos surface immediately.
+- `requireApproval` opts tools into approval. Tools do not require approval by default, matching `@mastra/mcp`'s own default. Pass `true` for every tool on the provider, or an array of keys/globs for a selection — e.g. `neon: { requireApproval: ['neon_delete_project'] }`. Applies to discovered MCP tools and generated HTTP tools alike.
+- All three are also accepted at the top level of `tools()` as defaults for every provider. Per-provider options win wholesale, so `requireApproval: true` globally with `linear: { requireApproval: false }` gates everything except Linear. Top-level entries apply leniently (an entry that matches nothing on one provider simply doesn't apply there) and warn when they matched nothing anywhere.
+
+### Multiple connections
+
+The resolver discovers active project connections. Where multiple connections match a provider, pin one with the provider's `connectionId` option, or leave it unpinned and let the agent route each call: the provider's `<integrationId>__list_connections` tool is added, every other tool takes a required `connection_name`, and the agent uses the display names returned by `list_connections` to pick a connection per call.
+
+### MCP integrations
+
+`tools()` also discovers any attached integration that advertises `capabilities.mcp: true` in the Platform catalog. No provider-specific registration or release of `@mastra/connect` is required. Discovered tools use the same flat dynamic-tool contract and are namespaced as `<integration-id>_<tool-name>`.
+
+Every MCP provider uses `/v2/connections/:connectionId/mcp` for discovery and invocation. The adapter reuses each provider's MCP session across refreshes and closes sessions when the connection changes, is detached, or `disconnect()` is called. If an integration has both checked-in HTTP tools and an MCP capability, the MCP catalog is preferred.
+
+The application sends only its Mastra Platform token. The transport is locked to the selected Platform connection URL. Platform removes caller authentication before Nango injects the provider credential and proxies each protocol request to the MCP server configured for that Nango integration.
+
+MCP tool catalogs can change independently of this package. Use `allowTools` to give an agent the smallest useful subset.
+
+### Generated HTTP providers
+
+Resend, incident.io, Slack, GitHub, Google Mail, Google Calendar, Fireflies, PostHog, Stripe, Discord, Twitter/X, and HubSpot use checked-in tools generated from their provider contracts. Tool inputs preserve provider field names. Mutations put their JSON request payload under `body`. The one exception is `resend_create_contact_import`, whose `body` fields are sent as a multipart form upload with the CSV text in `body.file`.
+
+```json
+{
+  "idempotency_key": "welcome-user-123",
+  "body": {
+    "from": "Team <team@example.com>",
+    "to": ["reader@example.com"],
+    "subject": "Welcome",
+    "text": "Thanks for joining."
+  }
+}
+```
+
+Resend requires a verified sending domain and a key authorized for the operation. A sending-only key cannot list domains or access other account resources. Reuse the idempotency key when retrying the same send. Mastra's proxy runtime does not automatically retry POST requests.
+
+List tools return one provider page and preserve its response envelope. When `next_cursor` is present, pass it as `after` for Resend and incident.io. Preserve filters and sort options between pages.
+
+### Template provenance
+
+Resend and incident.io are generated from integration-template contributions [#667](https://github.com/NangoHQ/integration-templates/pull/667) and [#668](https://github.com/NangoHQ/integration-templates/pull/668). Slack, GitHub, Google Mail, Google Calendar, Fireflies, PostHog, Stripe, Discord, Twitter/X, and HubSpot are generated from contribution [#677](https://github.com/NangoHQ/integration-templates/pull/677), which adds agent-focused actions (PostHog HogQL queries, Stripe balance/dispute/coupon/account reads, GitHub tags and trees, Slack Connect invites, Twitter search and following, HubSpot form submission) on top of upstream main. Until they land upstream, each provider manifest pins the contributing repository and exact commit and records generated file checksums.
+
+## Documentation
+
+- [Mastra Platform](https://mastra.ai/docs/mastra-platform/overview)
+- [Maintainer generation commands](./scripts/README.md) and [third-party notices](./NOTICE.md). Generated-provider tests use OpenAPI examples and synthetic fixtures. MCP tests exercise catalog discovery and the protocol lifecycle with a provider-neutral Platform gateway.
+
+## Changelog
+
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/packages/connect/CHANGELOG.md) for version history and release notes.
+
+## Support
+
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/channels.d.ts

@@ -0,0 +1,153 @@
+import type { ChannelProvider } from '@mastra/core/channels';
+import type { ConnectClientOptions } from './client.js';
+import type { DiscordReservedProviderOption, SlackReservedProviderOption, TeamsReservedProviderOption, TelegramReservedProviderOption } from './providers/channels.js';
+type ApiRoute = ReturnType<ChannelProvider['getRoutes']>[number];
+/**
+ * `providerOptions` fields that `channels()` refuses to forward to a
+ * `ChannelProvider` constructor. Marking them `never` here makes the compiler
+ * reject them at the call site; the resolver also strips them at runtime with
+ * a warning as a defensive layer.
+ *
+ * Two categories, applied per integration:
+ *
+ * - **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. `encryptionKey` is a
+ *   process-wide at-rest secret sourced from `MASTRA_ENCRYPTION_KEY`; letting
+ *   `providerOptions` override it per integration would fragment the
+ *   encryption boundary.
+ */
+type ForbidReservedOptions<Reserved extends string> = {
+    [K in Reserved]?: never;
+};
+/** Per-integration `providerOptions` shapes with reserved fields disallowed. */
+export type SlackChannelsProviderOptions = Record<string, unknown> & ForbidReservedOptions<SlackReservedProviderOption>;
+export type TelegramChannelsProviderOptions = Record<string, unknown> & ForbidReservedOptions<TelegramReservedProviderOption>;
+export type DiscordChannelsProviderOptions = Record<string, unknown> & {
+    applicationId?: string;
+    publicKey?: string;
+} & ForbidReservedOptions<DiscordReservedProviderOption>;
+export type TeamsChannelsProviderOptions = Record<string, unknown> & ForbidReservedOptions<TeamsReservedProviderOption>;
+/** Base shape shared by every integration override; per-id specializations narrow `providerOptions`. */
+export interface ChannelsProviderOptions<ProviderOptions = Record<string, unknown>> {
+    /** Pin a specific connection id (bypasses single-active-connection resolution). */
+    connectionId?: string;
+    /** Provider-specific options merged into the first argument of `ChannelProviderRegistration.create()`. */
+    providerOptions?: ProviderOptions;
+}
+/**
+ * Per-provider configuration map, typed per known channel id. `true` enables
+ * a channel with default options and `false` excludes it, mirroring the
+ * `tools()` shorthand. Unknown ids are allowed with a generic option shape so
+ * future channels don't need a type change here.
+ *
+ * `slack` is accepted as an alias for `slack-channels` (the platform keys the
+ * Slack channel `slack-channels` because `slack` names the Slack tools
+ * provider); setting both keys throws.
+ */
+export interface ChannelsProviders {
+    slack?: boolean | ChannelsProviderOptions<SlackChannelsProviderOptions>;
+    'slack-channels'?: boolean | ChannelsProviderOptions<SlackChannelsProviderOptions>;
+    telegram?: boolean | ChannelsProviderOptions<TelegramChannelsProviderOptions>;
+    discord?: boolean | ChannelsProviderOptions<DiscordChannelsProviderOptions>;
+    'microsoft-teams'?: boolean | ChannelsProviderOptions<TeamsChannelsProviderOptions>;
+    [integrationId: string]: boolean | ChannelsProviderOptions | undefined;
+}
+export interface ChannelsOptions {
+    /** Platform project whose connections to discover. Falls back to MASTRA_PROJECT_ID. */
+    projectId?: string;
+    /**
+     * Which channels to resolve, in one of two shapes:
+     * - `["discord", "telegram"]` — an allowlist: only the listed channels are
+     *   constructed and mounted.
+     * - `{ discord: true, telegram: { connectionId: "..." }, slack: false }` —
+     *   per-channel configuration. Every registered channel still resolves
+     *   unless excluded: `true` (or `{}`) enables with defaults, `false`
+     *   excludes, and an options object pins a connection or passes
+     *   provider-specific options.
+     *
+     * `slack` is an alias for the platform's `slack-channels` key; both spell
+     * the same channel in either shape, and naming it twice throws.
+     *
+     * Omit the option entirely to resolve every registered channel.
+     */
+    providers?: string[] | ChannelsProviders;
+    client?: ConnectClientOptions;
+    /** How long a resolved snapshot stays fresh, in milliseconds. Default 30_000. `0` revalidates every resolution. */
+    ttlMs?: number;
+}
+/**
+ * The result of resolving a project's connections into a
+ * `ChannelProvider` map: providers with an active connection, keyed by
+ * integrationId.
+ */
+export type ResolvedChannels = Record<string, ChannelProvider>;
+/**
+ * Callback context passed to the resolver when invoked with a runtime
+ * context. Mirrors `@mastra/core`'s `ChannelsResolverContext` — Mastra passes
+ * `{ mastra }` from `resolveChannels()`; the resolver currently doesn't vary
+ * output by context.
+ */
+export interface ChannelsResolverContext {
+    requestContext?: unknown;
+    mastra?: unknown;
+}
+/**
+ * The value `channels()` resolves to. Satisfies `@mastra/core`'s
+ * `ChannelsResolver` contract, so it can be handed to
+ * `new Mastra({ channels })` directly:
+ *
+ * - Callable — returns the current `Record<string, ChannelProvider>` of
+ *   providers with an active connection. Mastra invokes it via
+ *   `resolveChannels()`; the TTL cache makes repeat calls cheap.
+ * - `getRoutes()` — the union of routes for every non-disabled channel,
+ *   available synchronously so Mastra can mount them at construction. Routes
+ *   exist before (and after) their integration has an active connection.
+ * - Handles — `refresh()` / `disconnect()` control the resolver's private
+ *   cache; `refresh()` forces a platform fetch now.
+ */
+export interface ChannelsResolver {
+    /** Returns the current provider map for providers with an active connection. */
+    (context?: ChannelsResolverContext): Promise<ResolvedChannels>;
+    /** Union of API routes for every non-disabled channel integration. */
+    getRoutes(): ApiRoute[];
+    /** Fetches connections from the platform now and updates the cache. Rejects if the platform fetch fails. */
+    refresh(): Promise<ResolvedChannels>;
+    /** Clears the cached snapshot. Reserved for symmetry with `tools()`; currently a no-op beyond invalidation. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Returns a live channels resolver over the project's Platform connections,
+ * ready to hand to `new Mastra({ channels: await channels({...}) })`.
+ *
+ * Provider instances for every channel-capable integration (Slack, Telegram,
+ * Discord) are constructed once, up front and credential-less, so their
+ * webhook/OAuth routes can mount at Mastra construction. Each resolution
+ * fetches the project's connections and late-binds credentials into the live
+ * instances: providers with an active connection appear in the resolved
+ * map, others don't — so connecting a new channel on the platform takes
+ * effect without redeploying the app.
+ *
+ * Configuration errors (missing project id, bad ttlMs, malformed integration
+ * id) reject at call time so they surface at startup. Actionable
+ * per-integration problems (provider construction failure, needs re-auth,
+ * ambiguity, credential sync failure) are downgraded to warn-and-skip so one
+ * bad integration never takes down the whole map.
+ *
+ * @example
+ * ```ts
+ * import { Mastra } from '@mastra/core/mastra';
+ * import { channels } from '@mastra/connect';
+ *
+ * export const mastra = new Mastra({
+ *   agents: { pat },
+ *   channels: await channels({ projectId }),
+ * });
+ * ```
+ */
+export declare function channels(options?: ChannelsOptions): Promise<ChannelsResolver>;
+export {};
+//# sourceMappingURL=channels.d.ts.map

package/dist/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+/**
+ * Configuration for talking to the Mastra platform integrations service.
+ * Every field falls back to an environment variable, so a fully env-configured
+ * app can pass nothing at all.
+ */
+export interface ConnectClientOptions {
+    /** Platform access token. Falls back to MASTRA_PLATFORM_ACCESS_TOKEN, then MASTRA_PLATFORM_SECRET_KEY. */
+    accessToken?: string;
+    /** Organization id. Falls back to MASTRA_ORG_ID; the x-organization-id header is omitted when absent. */
+    orgId?: string;
+    /**
+     * Integrations service base URL. Falls back to MASTRA_INTEGRATIONS_API_URL,
+     * then the regional default from MASTRA_PLATFORM_REGION ('us' | 'eu'),
+     * then https://integrations.mastra.ai.
+     */
+    baseUrl?: string;
+    /** Fetch implementation, for testing or custom transports. Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface ResolvedClient {
+    baseUrl: string;
+    headers: Record<string, string>;
+    fetch: typeof globalThis.fetch;
+    accessToken: string;
+}
+export declare function resolveClient(options?: ConnectClientOptions): ResolvedClient;
+/** Builds a locked MCP transport that can only call one Platform connection endpoint. */
+export declare function platformMcpTransport(client: ResolvedClient, connectionId: string): {
+    url: import("url").URL;
+    allowedHosts: string[];
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+};
+export declare const connectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    integrationId: z.ZodString;
+    status: z.ZodString;
+    connectedByUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    connectedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    accountLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ProjectConnection = z.infer<typeof connectionSchema>;
+export declare const integrationCatalogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    capabilities: z.ZodObject<{
+        mcp: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type IntegrationCatalogEntry = z.infer<typeof integrationCatalogEntrySchema>;
+/**
+ * Secondary access token minted by the vendor alongside the primary oauth2
+ * credential (e.g. `devPortalAccessToken` on Microsoft Teams connections).
+ * Keyed by the vendor's connection-config field name. Treat this like any
+ * other bearer credential — it authenticates second-audience API calls
+ * (Teams Dev Portal, etc.) and must not be logged or forwarded to code that
+ * shouldn't hold connection secrets.
+ */
+export declare const secondaryAccessTokenSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SecondaryAccessToken = z.infer<typeof secondaryAccessTokenSchema>;
+export declare const credentialSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"oauth2">;
+    accessToken: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    secondaryAccessTokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        accessToken: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    apiKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"two_step">;
+    token: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type ConnectionCredential = z.infer<typeof credentialSchema>;
+export declare const connectionContextSchema: z.ZodObject<{
+    connection_config: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ConnectionContext = z.infer<typeof connectionContextSchema>;
+export declare function listProjectConnections(client: ResolvedClient, projectId: string): Promise<ProjectConnection[]>;
+export declare function listIntegrations(client: ResolvedClient): Promise<IntegrationCatalogEntry[]>;
+export declare function getConnectionContext(client: ResolvedClient, connectionId: string): Promise<ConnectionContext>;
+export declare function getCredential(client: ResolvedClient, connectionId: string): Promise<ConnectionCredential>;
+type ProxyQueryPrimitive = string | number | boolean;
+export interface ProxyRequestOptions {
+    method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Provider-relative path (no leading slash required; dot segments are rejected client-side, absolute URLs by the platform). */
+    path: string;
+    query?: Record<string, ProxyQueryPrimitive | ProxyQueryPrimitive[] | undefined>;
+    headers?: Record<string, string>;
+    baseUrlOverride?: string;
+    body?: unknown;
+    /**
+     * How to decode the response body. Defaults to JSON parsing (with a raw
+     * text fallback when JSON parsing fails). Set to `'arraybuffer'` for
+     * providers that return binary payloads (file exports, downloaded assets):
+     * the response body is returned as an ArrayBuffer and never parsed.
+     */
+    responseType?: 'arraybuffer';
+}
+export interface ProxyResponse {
+    data: unknown;
+    status: number;
+    headers: Record<string, string>;
+}
+export declare function proxyRequest(client: ResolvedClient, connectionId: string, options: ProxyRequestOptions): Promise<unknown>;
+/** Preserves HTTP metadata for tools with status-dependent provider contracts. */
+export declare function proxyRequestWithResponse(client: ResolvedClient, connectionId: string, options: ProxyRequestOptions): Promise<ProxyResponse>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/credential.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectClientOptions, ConnectionCredential } from './client.js';
+/**
+ * Fetches the raw credential for a connection, for building custom
+ * interactions (own SDKs, MCP servers). Never log the result.
+ */
+export declare function credential(connectionId: string, options?: {
+    client?: ConnectClientOptions;
+}): Promise<ConnectionCredential>;
+//# sourceMappingURL=credential.d.ts.map

package/dist/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG9E;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,oBAAoB,CAAA;CAAE,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CAG/B"}

package/dist/errors.d.ts

@@ -0,0 +1,44 @@
+export type MastraConnectErrorCode = 'missing_access_token' | 'missing_project_id' | 'missing_connection_id' | 'invalid_options' | 'connection_not_found' | 'unauthorized' | 'proxy_error' | 'unsupported_credential_type' | 'no_active_connection' | 'platform_error' | 'unknown_connection';
+export declare class MastraConnectError extends Error {
+    readonly code: MastraConnectErrorCode;
+    readonly status?: number;
+    readonly detail?: string;
+    /**
+     * Axios-compatible alias for {@link status}. Generated provider tools come
+     * from upstream Nango templates whose error handlers check
+     * `error.response.status` (the axios/Nango SDK shape). Exposing the HTTP
+     * status under `response.status` as well lets that generated code work
+     * unchanged against the errors this package throws. Only set when the error
+     * carries an HTTP status.
+     */
+    readonly response?: {
+        status: number;
+    };
+    constructor(code: MastraConnectErrorCode, message: string, options?: {
+        status?: number;
+        detail?: string;
+    });
+}
+/**
+ * A caller configuration mistake (for example an unknown tool name in
+ * `requireApproval`) that must fail resolution instead of being downgraded
+ * to the resolver's warn-and-skip path, which exists for provider-side
+ * failures. Internal to the package: callers observe it as a regular
+ * `MastraConnectError` with code `invalid_options`.
+ *
+ * @internal
+ */
+export declare class MastraConnectConfigError extends MastraConnectError {
+    constructor(message: string);
+}
+/**
+ * Extracts a human-readable detail string from an RFC-7807 problem JSON body
+ * (or a plain `{ error }` body) without echoing anything else from the response.
+ * Returns undefined when the body is not parseable JSON.
+ */
+export declare function extractProblemDetail(response: Response): Promise<{
+    detail?: string;
+    code?: string;
+    isProblemJson: boolean;
+}>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAC9B,sBAAsB,GACtB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,sBAAsB,GACtB,cAAc,GACd,aAAa,GACb,6BAA6B,GAC7B,sBAAsB,GACtB,gBAAgB,GAIhB,oBAAoB,CAAC;AAIzB,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvC,YAAY,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EASxG;CACF;AAED;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,kBAAkB;IAC9D,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAsCD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,CAAC,CA2CrE"}