npm - @tangle-network/agent-integrations - Versions diffs - 0.1.0 → 0.1.1 - Mend

@tangle-network/agent-integrations 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +9 -0
package/dist/index.d.ts +42 -1
package/dist/index.js +8 -1
package/dist/index.js.map +1 -1
package/docs/provider-decision-matrix.md +164 -0
package/package.json +11 -9

package/README.md CHANGED Viewed

@@ -101,6 +101,12 @@ const provider = createHttpIntegrationProvider({
 The HTTP adapter keeps product code stable while the backing provider can be
 Nango, Pipedream, Activepieces, a Zapier-style service, or an internal gateway.
+See [Provider Decision Matrix](./docs/provider-decision-matrix.md) for the
+build-vs-buy policy. The short version: use a vendor gateway only to compress
+time-to-coverage, but keep all product and sandbox code on this package's
+contracts so high-volume or strategic connectors can be moved first-party
+without changing agent code.
 ## Security Defaults
 - Capabilities expire.
@@ -109,3 +115,6 @@ Nango, Pipedream, Activepieces, a Zapier-style service, or an internal gateway.
 - Write/destructive actions can be policy-gated.
 - Action invocation checks connection ownership, status, scopes, allowed
   actions, and expiration.
+- Optional `IntegrationActionGuard` wraps every action invocation for
+  idempotency, audit logging, conflict detection, rate limits, and
+  approval gates.

package/dist/index.d.ts CHANGED Viewed

@@ -158,10 +158,50 @@ interface IssuedIntegrationCapability {
     capability: IntegrationCapability;
     token: string;
 }
+/**
+ * Wraps every action invocation with cross-cutting discipline (idempotency,
+ * conflict detection, rate-limiting, audit logging). Optional. When set on
+ * the hub, runs BEFORE provider.invokeAction; can short-circuit (return a
+ * result directly) or pass through (call `proceed()` to invoke the provider).
+ *
+ * Why this hook exists: production deployments need conflict-resolution
+ * guarantees that span every provider — first-party, Nango, Composio,
+ * webhook receivers — and providers shouldn't re-implement them. The
+ * canonical implementation is a "MutationGuard" that:
+ *   1. Short-circuits on a known idempotency key (returns recorded response).
+ *   2. Refuses same-key-different-args (drift detection).
+ *   3. Wraps `proceed()` and audit-logs the outcome.
+ *   4. Translates upstream conflict signals into a structured result with
+ *      alternatives the agent can act on.
+ *
+ * Implementations live in consumers (every product has different
+ * persistence + telemetry needs); this interface is the contract.
+ */
+interface IntegrationActionGuard {
+    /** Wrap an invokeAction call. Implementations MUST call `proceed()` to
+     *  invoke the underlying provider unless they're returning a cached or
+     *  short-circuited result.
+     *
+     *  @param ctx connection + request the hub is about to dispatch
+     *  @param proceed call to invoke the wrapped provider; returns the
+     *                 underlying IntegrationActionResult
+     *  @returns the result the hub should return to the caller
+     */
+    invokeAction(ctx: IntegrationGuardContext, proceed: () => Promise<IntegrationActionResult>): Promise<IntegrationActionResult>;
+}
+interface IntegrationGuardContext {
+    connection: IntegrationConnection;
+    request: IntegrationActionRequest;
+    /** The action descriptor from the connector manifest, if discovered. */
+    action?: IntegrationConnectorAction;
+}
 interface IntegrationHubOptions {
     providers: IntegrationProvider[];
     store: IntegrationConnectionStore;
     capabilitySecret: string;
+    /** Optional cross-cutting guard. If provided, every invokeAction call
+     *  passes through it before reaching the provider. See {@link IntegrationActionGuard}. */
+    guard?: IntegrationActionGuard;
     now?: () => Date;
 }
 interface HttpIntegrationProviderOptions {
@@ -190,6 +230,7 @@ declare class IntegrationHub {
     private readonly providers;
     private readonly store;
     private readonly capabilitySecret;
+    private readonly guard;
     private readonly now;
     constructor(options: IntegrationHubOptions);
     listConnectors(): Promise<IntegrationConnector[]>;
@@ -215,4 +256,4 @@ declare function createHttpIntegrationProvider(options: HttpIntegrationProviderO
 declare function signCapability(capability: IntegrationCapability, secret: string): string;
 declare function verifyCapabilityToken(token: string, secret: string): IntegrationCapability;
-export { type CompleteAuthRequest, type HttpIntegrationProviderOptions, InMemoryConnectionStore, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, IntegrationHub, type IntegrationHubOptions, type IntegrationProvider, type IntegrationProviderKind, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type SecretRef, type StartAuthRequest, type StartAuthResult, createHttpIntegrationProvider, createMockIntegrationProvider, sanitizeConnection, signCapability, verifyCapabilityToken };
+export { type CompleteAuthRequest, type HttpIntegrationProviderOptions, InMemoryConnectionStore, type IntegrationActionGuard, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationProvider, type IntegrationProviderKind, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type SecretRef, type StartAuthRequest, type StartAuthResult, createHttpIntegrationProvider, createMockIntegrationProvider, sanitizeConnection, signCapability, verifyCapabilityToken };

package/dist/index.js CHANGED Viewed

@@ -29,6 +29,7 @@ var IntegrationHub = class {
   providers = /* @__PURE__ */ new Map();
   store;
   capabilitySecret;
+  guard;
   now;
   constructor(options) {
     if (!options.capabilitySecret) {
@@ -37,6 +38,7 @@ var IntegrationHub = class {
     for (const provider of options.providers) this.providers.set(provider.id, provider);
     this.store = options.store;
     this.capabilitySecret = options.capabilitySecret;
+    this.guard = options.guard;
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
   }
   async listConnectors() {
@@ -97,7 +99,12 @@ var IntegrationHub = class {
     if (!action) throw new IntegrationError(`Action ${request.action} is not defined by connector ${connector.id}.`, "action_not_found");
     assertScopes(connection, action.requiredScopes);
     assertScopes({ ...connection, grantedScopes: capability.scopes }, action.requiredScopes);
-    return provider.invokeAction(connection, { ...request, connectionId: connection.id });
+    const fullRequest = { ...request, connectionId: connection.id };
+    const proceed = () => Promise.resolve(provider.invokeAction(connection, fullRequest));
+    if (this.guard) {
+      return this.guard.invokeAction({ connection, request: fullRequest, action }, proceed);
+    }
+    return proceed();
   }
   async subscribeTrigger(connectionId, trigger, targetUrl) {
     const connection = await this.requireConnection(connectionId);

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'\n\nexport type IntegrationProviderKind =\n \| 'first_party'\n \| 'nango'\n \| 'pipedream'\n \| 'zapier'\n \| 'activepieces'\n \| 'executor'\n \| 'custom'\n\nexport type IntegrationConnectorCategory =\n \| 'email'\n \| 'calendar'\n \| 'chat'\n \| 'crm'\n \| 'storage'\n \| 'docs'\n \| 'database'\n \| 'webhook'\n \| 'workflow'\n \| 'internal'\n \| 'other'\n\nexport type IntegrationActionRisk = 'read' \| 'write' \| 'destructive'\nexport type IntegrationDataClass = 'public' \| 'internal' \| 'private' \| 'sensitive' \| 'secret'\n\nexport interface IntegrationActor {\n type: 'user' \| 'team' \| 'agent' \| 'sandbox' \| 'system'\n id: string\n}\n\nexport interface IntegrationConnectorAction {\n id: string\n title: string\n risk: IntegrationActionRisk\n requiredScopes: string[]\n dataClass: IntegrationDataClass\n description?: string\n approvalRequired?: boolean\n inputSchema?: unknown\n outputSchema?: unknown\n}\n\nexport interface IntegrationConnectorTrigger {\n id: string\n title: string\n requiredScopes: string[]\n dataClass: IntegrationDataClass\n description?: string\n payloadSchema?: unknown\n}\n\nexport interface IntegrationConnector {\n id: string\n providerId: string\n title: string\n category: IntegrationConnectorCategory\n auth: 'oauth2' \| 'api_key' \| 'none' \| 'custom'\n scopes: string[]\n actions: IntegrationConnectorAction[]\n triggers?: IntegrationConnectorTrigger[]\n metadata?: Record<string, unknown>\n}\n\nexport interface SecretRef {\n provider: string\n id: string\n label?: string\n}\n\nexport interface IntegrationConnection {\n id: string\n owner: IntegrationActor\n providerId: string\n connectorId: string\n status: 'pending' \| 'active' \| 'expired' \| 'revoked' \| 'error'\n grantedScopes: string[]\n account?: {\n id?: string\n email?: string\n displayName?: string\n }\n secretRef?: SecretRef\n createdAt: string\n updatedAt: string\n expiresAt?: string\n lastUsedAt?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface StartAuthRequest {\n connectorId: string\n owner: IntegrationActor\n requestedScopes: string[]\n redirectUri: string\n state?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface StartAuthResult {\n providerId: string\n connectorId: string\n authUrl: string\n state: string\n expiresAt?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface CompleteAuthRequest {\n connectorId: string\n owner: IntegrationActor\n code?: string\n state: string\n redirectUri: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationActionRequest {\n connectionId: string\n action: string\n input?: unknown\n idempotencyKey?: string\n dryRun?: boolean\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationActionResult<T = unknown> {\n ok: boolean\n action: string\n output?: T\n externalId?: string\n warnings?: string[]\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationTriggerSubscription {\n id: string\n connectionId: string\n trigger: string\n targetUrl?: string\n status: 'active' \| 'paused' \| 'error'\n createdAt: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationTriggerEvent<T = unknown> {\n id: string\n providerId: string\n connectorId: string\n connectionId: string\n trigger: string\n occurredAt: string\n payload: T\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationProvider {\n id: string\n kind: IntegrationProviderKind\n listConnectors(): Promise<IntegrationConnector[]> \| IntegrationConnector[]\n startAuth?(request: StartAuthRequest): Promise<StartAuthResult> \| StartAuthResult\n completeAuth?(request: CompleteAuthRequest): Promise<IntegrationConnection> \| IntegrationConnection\n invokeAction(connection: IntegrationConnection, request: IntegrationActionRequest): Promise<IntegrationActionResult> \| IntegrationActionResult\n subscribeTrigger?(connection: IntegrationConnection, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription> \| IntegrationTriggerSubscription\n unsubscribeTrigger?(subscriptionId: string): Promise<void> \| void\n normalizeTriggerEvent?(raw: unknown): Promise<IntegrationTriggerEvent> \| IntegrationTriggerEvent\n}\n\nexport interface IntegrationConnectionStore {\n get(connectionId: string): Promise<IntegrationConnection \| undefined> \| IntegrationConnection \| undefined\n put(connection: IntegrationConnection): Promise<void> \| void\n listByOwner(owner: IntegrationActor): Promise<IntegrationConnection[]> \| IntegrationConnection[]\n delete?(connectionId: string): Promise<void> \| void\n}\n\nexport interface IssueCapabilityRequest {\n subject: IntegrationActor\n connectionId: string\n scopes: string[]\n allowedActions: string[]\n ttlMs: number\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationCapability {\n id: string\n subject: IntegrationActor\n connectionId: string\n scopes: string[]\n allowedActions: string[]\n issuedAt: string\n expiresAt: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IssuedIntegrationCapability {\n capability: IntegrationCapability\n token: string\n}\n\nexport interface IntegrationHubOptions {\n providers: IntegrationProvider[]\n store: IntegrationConnectionStore\n capabilitySecret: string\n now?: () => Date\n}\n\nexport interface HttpIntegrationProviderOptions {\n id: string\n kind?: IntegrationProviderKind\n connectors: IntegrationConnector[]\n baseUrl: string\n bearer?: string\n fetchImpl?: typeof fetch\n}\n\nexport interface InvokeWithCapabilityRequest extends Omit<IntegrationActionRequest, 'connectionId'> {\n connectionId?: never\n}\n\nexport class IntegrationError extends Error {\n constructor(\n message: string,\n readonly code:\n \| 'provider_not_found'\n \| 'connector_not_found'\n \| 'connection_not_found'\n \| 'connection_not_active'\n \| 'auth_not_supported'\n \| 'capability_invalid'\n \| 'capability_expired'\n \| 'scope_denied'\n \| 'action_denied'\n \| 'action_not_found',\n ) {\n super(message)\n this.name = 'IntegrationError'\n }\n}\n\nexport class InMemoryConnectionStore implements IntegrationConnectionStore {\n private readonly connections = new Map<string, IntegrationConnection>()\n\n get(connectionId: string): IntegrationConnection \| undefined {\n return this.connections.get(connectionId)\n }\n\n put(connection: IntegrationConnection): void {\n this.connections.set(connection.id, connection)\n }\n\n listByOwner(owner: IntegrationActor): IntegrationConnection[] {\n return [...this.connections.values()].filter((connection) =>\n connection.owner.type === owner.type && connection.owner.id === owner.id,\n )\n }\n\n delete(connectionId: string): void {\n this.connections.delete(connectionId)\n }\n}\n\nexport class IntegrationHub {\n private readonly providers = new Map<string, IntegrationProvider>()\n private readonly store: IntegrationConnectionStore\n private readonly capabilitySecret: string\n private readonly now: () => Date\n\n constructor(options: IntegrationHubOptions) {\n if (!options.capabilitySecret) {\n throw new IntegrationError('capabilitySecret is required.', 'capability_invalid')\n }\n for (const provider of options.providers) this.providers.set(provider.id, provider)\n this.store = options.store\n this.capabilitySecret = options.capabilitySecret\n this.now = options.now ?? (() => new Date())\n }\n\n async listConnectors(): Promise<IntegrationConnector[]> {\n const catalogs = await Promise.all([...this.providers.values()].map((provider) => provider.listConnectors()))\n return catalogs.flat()\n }\n\n async startAuth(providerId: string, request: StartAuthRequest): Promise<StartAuthResult> {\n const provider = this.requireProvider(providerId)\n if (!provider.startAuth) throw new IntegrationError(`Provider ${providerId} does not support auth start.`, 'auth_not_supported')\n await this.requireConnector(provider, request.connectorId)\n return provider.startAuth(request)\n }\n\n async completeAuth(providerId: string, request: CompleteAuthRequest): Promise<IntegrationConnection> {\n const provider = this.requireProvider(providerId)\n if (!provider.completeAuth) throw new IntegrationError(`Provider ${providerId} does not support auth completion.`, 'auth_not_supported')\n const connection = await provider.completeAuth(request)\n await this.store.put(connection)\n return connection\n }\n\n async upsertConnection(connection: IntegrationConnection): Promise<IntegrationConnection> {\n await this.store.put(connection)\n return connection\n }\n\n async issueCapability(request: IssueCapabilityRequest): Promise<IssuedIntegrationCapability> {\n const connection = await this.requireConnection(request.connectionId)\n this.assertConnectionActive(connection)\n assertScopes(connection, request.scopes)\n const now = this.now()\n const capability: IntegrationCapability = {\n id: `cap_${randomUUID()}`,\n subject: request.subject,\n connectionId: request.connectionId,\n scopes: unique(request.scopes),\n allowedActions: unique(request.allowedActions),\n issuedAt: now.toISOString(),\n expiresAt: new Date(now.getTime() + request.ttlMs).toISOString(),\n metadata: request.metadata,\n }\n return { capability, token: signCapability(capability, this.capabilitySecret) }\n }\n\n verifyCapability(token: string): IntegrationCapability {\n const capability = verifyCapabilityToken(token, this.capabilitySecret)\n if (Date.parse(capability.expiresAt) <= this.now().getTime()) {\n throw new IntegrationError('Integration capability expired.', 'capability_expired')\n }\n return capability\n }\n\n async invokeWithCapability(token: string, request: InvokeWithCapabilityRequest): Promise<IntegrationActionResult> {\n const capability = this.verifyCapability(token)\n if (!capability.allowedActions.includes(request.action)) {\n throw new IntegrationError(`Capability does not allow action ${request.action}.`, 'action_denied')\n }\n const connection = await this.requireConnection(capability.connectionId)\n this.assertConnectionActive(connection)\n const provider = this.requireProvider(connection.providerId)\n const connector = await this.requireConnector(provider, connection.connectorId)\n const action = connector.actions.find((candidate) => candidate.id === request.action)\n if (!action) throw new IntegrationError(`Action ${request.action} is not defined by connector ${connector.id}.`, 'action_not_found')\n assertScopes(connection, action.requiredScopes)\n assertScopes({ ...connection, grantedScopes: capability.scopes }, action.requiredScopes)\n return provider.invokeAction(connection, { ...request, connectionId: connection.id })\n }\n\n async subscribeTrigger(connectionId: string, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription> {\n const connection = await this.requireConnection(connectionId)\n this.assertConnectionActive(connection)\n const provider = this.requireProvider(connection.providerId)\n const connector = await this.requireConnector(provider, connection.connectorId)\n const spec = connector.triggers?.find((candidate) => candidate.id === trigger)\n if (!spec) throw new IntegrationError(`Trigger ${trigger} is not defined by connector ${connector.id}.`, 'action_not_found')\n assertScopes(connection, spec.requiredScopes)\n if (!provider.subscribeTrigger) {\n throw new IntegrationError(`Provider ${provider.id} does not support triggers.`, 'auth_not_supported')\n }\n return provider.subscribeTrigger(connection, trigger, targetUrl)\n }\n\n private requireProvider(providerId: string): IntegrationProvider {\n const provider = this.providers.get(providerId)\n if (!provider) throw new IntegrationError(`Provider ${providerId} not found.`, 'provider_not_found')\n return provider\n }\n\n private async requireConnector(provider: IntegrationProvider, connectorId: string): Promise<IntegrationConnector> {\n const connector = (await provider.listConnectors()).find((candidate) => candidate.id === connectorId)\n if (!connector) throw new IntegrationError(`Connector ${connectorId} not found.`, 'connector_not_found')\n return connector\n }\n\n private async requireConnection(connectionId: string): Promise<IntegrationConnection> {\n const connection = await this.store.get(connectionId)\n if (!connection) throw new IntegrationError(`Connection ${connectionId} not found.`, 'connection_not_found')\n return connection\n }\n\n private assertConnectionActive(connection: IntegrationConnection): void {\n if (connection.status !== 'active') {\n throw new IntegrationError(`Connection ${connection.id} is ${connection.status}.`, 'connection_not_active')\n }\n if (connection.expiresAt && Date.parse(connection.expiresAt) <= this.now().getTime()) {\n throw new IntegrationError(`Connection ${connection.id} is expired.`, 'connection_not_active')\n }\n }\n}\n\nexport function sanitizeConnection(connection: IntegrationConnection): Record<string, unknown> {\n return {\n id: connection.id,\n owner: connection.owner,\n providerId: connection.providerId,\n connectorId: connection.connectorId,\n status: connection.status,\n grantedScopes: connection.grantedScopes,\n account: connection.account,\n hasSecretRef: Boolean(connection.secretRef),\n createdAt: connection.createdAt,\n updatedAt: connection.updatedAt,\n expiresAt: connection.expiresAt,\n lastUsedAt: connection.lastUsedAt,\n }\n}\n\nexport function createMockIntegrationProvider(options: {\n id?: string\n connectors?: IntegrationConnector[]\n onInvoke?: (connection: IntegrationConnection, request: IntegrationActionRequest) => IntegrationActionResult \| Promise<IntegrationActionResult>\n} = {}): IntegrationProvider {\n const providerId = options.id ?? 'mock'\n const connectors = options.connectors ?? [{\n id: 'gmail',\n providerId,\n title: 'Gmail',\n category: 'email',\n auth: 'oauth2',\n scopes: ['email.read', 'email.write'],\n actions: [\n { id: 'messages.search', title: 'Search messages', risk: 'read', requiredScopes: ['email.read'], dataClass: 'private' },\n { id: 'drafts.create', title: 'Create draft', risk: 'write', requiredScopes: ['email.write'], dataClass: 'private', approvalRequired: true },\n ],\n triggers: [\n { id: 'message.received', title: 'Message received', requiredScopes: ['email.read'], dataClass: 'private' },\n ],\n }]\n return {\n id: providerId,\n kind: 'custom',\n listConnectors: () => connectors,\n startAuth: (request) => ({\n providerId,\n connectorId: request.connectorId,\n authUrl: `https://auth.example.test/${request.connectorId}?state=${encodeURIComponent(request.state ?? 'state')}`,\n state: request.state ?? 'state',\n }),\n completeAuth: (request) => ({\n id: `conn_${request.connectorId}_${request.owner.id}`,\n owner: request.owner,\n providerId,\n connectorId: request.connectorId,\n status: 'active',\n grantedScopes: connectors.find((connector) => connector.id === request.connectorId)?.scopes ?? [],\n secretRef: { provider: providerId, id: `secret_${request.owner.id}` },\n createdAt: new Date(0).toISOString(),\n updatedAt: new Date(0).toISOString(),\n }),\n invokeAction: async (connection, request) => options.onInvoke?.(connection, request) ?? ({\n ok: true,\n action: request.action,\n output: { echo: request.input ?? null },\n }),\n subscribeTrigger: (connection, trigger, targetUrl) => ({\n id: `sub_${connection.id}_${trigger}`,\n connectionId: connection.id,\n trigger,\n targetUrl,\n status: 'active',\n createdAt: new Date(0).toISOString(),\n }),\n }\n}\n\nexport function createHttpIntegrationProvider(options: HttpIntegrationProviderOptions): IntegrationProvider {\n const fetcher = options.fetchImpl ?? fetch\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n return {\n id: options.id,\n kind: options.kind ?? 'custom',\n listConnectors: () => options.connectors,\n async startAuth(request) {\n const response = await postJson<StartAuthResult>(fetcher, `${baseUrl}/auth/start`, request, options.bearer)\n return response\n },\n async completeAuth(request) {\n const response = await postJson<IntegrationConnection>(fetcher, `${baseUrl}/auth/complete`, request, options.bearer)\n return response\n },\n async invokeAction(connection, request) {\n return postJson<IntegrationActionResult>(fetcher, `${baseUrl}/actions/invoke`, {\n connection,\n request,\n }, options.bearer)\n },\n async subscribeTrigger(connection, trigger, targetUrl) {\n return postJson<IntegrationTriggerSubscription>(fetcher, `${baseUrl}/triggers/subscribe`, {\n connection,\n trigger,\n targetUrl,\n }, options.bearer)\n },\n async unsubscribeTrigger(subscriptionId) {\n await postJson(fetcher, `${baseUrl}/triggers/unsubscribe`, { subscriptionId }, options.bearer)\n },\n async normalizeTriggerEvent(raw) {\n return postJson<IntegrationTriggerEvent>(fetcher, `${baseUrl}/triggers/normalize`, { raw }, options.bearer)\n },\n }\n}\n\nexport function signCapability(capability: IntegrationCapability, secret: string): string {\n const payload = base64UrlEncode(JSON.stringify(capability))\n const signature = hmac(payload, secret)\n return `${payload}.${signature}`\n}\n\nexport function verifyCapabilityToken(token: string, secret: string): IntegrationCapability {\n const [payload, signature] = token.split('.')\n if (!payload \|\| !signature) throw new IntegrationError('Malformed integration capability.', 'capability_invalid')\n const expected = hmac(payload, secret)\n if (!constantTimeEqual(signature, expected)) throw new IntegrationError('Invalid integration capability signature.', 'capability_invalid')\n let parsed: IntegrationCapability\n try {\n parsed = JSON.parse(base64UrlDecode(payload)) as IntegrationCapability\n } catch {\n throw new IntegrationError('Invalid integration capability payload.', 'capability_invalid')\n }\n if (!parsed.id \|\| !parsed.connectionId \|\| !Array.isArray(parsed.scopes) \|\| !Array.isArray(parsed.allowedActions)) {\n throw new IntegrationError('Invalid integration capability payload.', 'capability_invalid')\n }\n return parsed\n}\n\nasync function postJson<T = unknown>(\n fetcher: typeof fetch,\n url: string,\n body: unknown,\n bearer?: string,\n): Promise<T> {\n const response = await fetcher(url, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),\n },\n body: JSON.stringify(body),\n })\n if (!response.ok) throw new IntegrationError(`Integration provider returned HTTP ${response.status}.`, 'provider_not_found')\n return response.json() as Promise<T>\n}\n\nfunction assertScopes(connection: Pick<IntegrationConnection, 'grantedScopes'>, requiredScopes: string[]): void {\n const missing = requiredScopes.filter((scope) => !connection.grantedScopes.includes(scope))\n if (missing.length > 0) throw new IntegrationError(`Missing integration scopes: ${missing.join(', ')}`, 'scope_denied')\n}\n\nfunction hmac(payload: string, secret: string): string {\n return createHmac('sha256', secret).update(payload).digest('base64url')\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n const left = Buffer.from(a)\n const right = Buffer.from(b)\n return left.length === right.length && timingSafeEqual(left, right)\n}\n\nfunction base64UrlEncode(value: string): string {\n return Buffer.from(value, 'utf8').toString('base64url')\n}\n\nfunction base64UrlDecode(value: string): string {\n return Buffer.from(value, 'base64url').toString('utf8')\n}\n\nfunction unique<T>(values: T[]): T[] {\n return [...new Set(values)]\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'\n\nexport type IntegrationProviderKind =\n \| 'first_party'\n \| 'nango'\n \| 'pipedream'\n \| 'zapier'\n \| 'activepieces'\n \| 'executor'\n \| 'custom'\n\nexport type IntegrationConnectorCategory =\n \| 'email'\n \| 'calendar'\n \| 'chat'\n \| 'crm'\n \| 'storage'\n \| 'docs'\n \| 'database'\n \| 'webhook'\n \| 'workflow'\n \| 'internal'\n \| 'other'\n\nexport type IntegrationActionRisk = 'read' \| 'write' \| 'destructive'\nexport type IntegrationDataClass = 'public' \| 'internal' \| 'private' \| 'sensitive' \| 'secret'\n\nexport interface IntegrationActor {\n type: 'user' \| 'team' \| 'agent' \| 'sandbox' \| 'system'\n id: string\n}\n\nexport interface IntegrationConnectorAction {\n id: string\n title: string\n risk: IntegrationActionRisk\n requiredScopes: string[]\n dataClass: IntegrationDataClass\n description?: string\n approvalRequired?: boolean\n inputSchema?: unknown\n outputSchema?: unknown\n}\n\nexport interface IntegrationConnectorTrigger {\n id: string\n title: string\n requiredScopes: string[]\n dataClass: IntegrationDataClass\n description?: string\n payloadSchema?: unknown\n}\n\nexport interface IntegrationConnector {\n id: string\n providerId: string\n title: string\n category: IntegrationConnectorCategory\n auth: 'oauth2' \| 'api_key' \| 'none' \| 'custom'\n scopes: string[]\n actions: IntegrationConnectorAction[]\n triggers?: IntegrationConnectorTrigger[]\n metadata?: Record<string, unknown>\n}\n\nexport interface SecretRef {\n provider: string\n id: string\n label?: string\n}\n\nexport interface IntegrationConnection {\n id: string\n owner: IntegrationActor\n providerId: string\n connectorId: string\n status: 'pending' \| 'active' \| 'expired' \| 'revoked' \| 'error'\n grantedScopes: string[]\n account?: {\n id?: string\n email?: string\n displayName?: string\n }\n secretRef?: SecretRef\n createdAt: string\n updatedAt: string\n expiresAt?: string\n lastUsedAt?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface StartAuthRequest {\n connectorId: string\n owner: IntegrationActor\n requestedScopes: string[]\n redirectUri: string\n state?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface StartAuthResult {\n providerId: string\n connectorId: string\n authUrl: string\n state: string\n expiresAt?: string\n metadata?: Record<string, unknown>\n}\n\nexport interface CompleteAuthRequest {\n connectorId: string\n owner: IntegrationActor\n code?: string\n state: string\n redirectUri: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationActionRequest {\n connectionId: string\n action: string\n input?: unknown\n idempotencyKey?: string\n dryRun?: boolean\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationActionResult<T = unknown> {\n ok: boolean\n action: string\n output?: T\n externalId?: string\n warnings?: string[]\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationTriggerSubscription {\n id: string\n connectionId: string\n trigger: string\n targetUrl?: string\n status: 'active' \| 'paused' \| 'error'\n createdAt: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationTriggerEvent<T = unknown> {\n id: string\n providerId: string\n connectorId: string\n connectionId: string\n trigger: string\n occurredAt: string\n payload: T\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationProvider {\n id: string\n kind: IntegrationProviderKind\n listConnectors(): Promise<IntegrationConnector[]> \| IntegrationConnector[]\n startAuth?(request: StartAuthRequest): Promise<StartAuthResult> \| StartAuthResult\n completeAuth?(request: CompleteAuthRequest): Promise<IntegrationConnection> \| IntegrationConnection\n invokeAction(connection: IntegrationConnection, request: IntegrationActionRequest): Promise<IntegrationActionResult> \| IntegrationActionResult\n subscribeTrigger?(connection: IntegrationConnection, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription> \| IntegrationTriggerSubscription\n unsubscribeTrigger?(subscriptionId: string): Promise<void> \| void\n normalizeTriggerEvent?(raw: unknown): Promise<IntegrationTriggerEvent> \| IntegrationTriggerEvent\n}\n\nexport interface IntegrationConnectionStore {\n get(connectionId: string): Promise<IntegrationConnection \| undefined> \| IntegrationConnection \| undefined\n put(connection: IntegrationConnection): Promise<void> \| void\n listByOwner(owner: IntegrationActor): Promise<IntegrationConnection[]> \| IntegrationConnection[]\n delete?(connectionId: string): Promise<void> \| void\n}\n\nexport interface IssueCapabilityRequest {\n subject: IntegrationActor\n connectionId: string\n scopes: string[]\n allowedActions: string[]\n ttlMs: number\n metadata?: Record<string, unknown>\n}\n\nexport interface IntegrationCapability {\n id: string\n subject: IntegrationActor\n connectionId: string\n scopes: string[]\n allowedActions: string[]\n issuedAt: string\n expiresAt: string\n metadata?: Record<string, unknown>\n}\n\nexport interface IssuedIntegrationCapability {\n capability: IntegrationCapability\n token: string\n}\n\n/*\n Wraps every action invocation with cross-cutting discipline (idempotency,\n * conflict detection, rate-limiting, audit logging). Optional. When set on\n * the hub, runs BEFORE provider.invokeAction; can short-circuit (return a\n * result directly) or pass through (call `proceed()` to invoke the provider).\n \n Why this hook exists: production deployments need conflict-resolution\n * guarantees that span every provider — first-party, Nango, Composio,\n * webhook receivers — and providers shouldn't re-implement them. The\n * canonical implementation is a \"MutationGuard\" that:\n * 1. Short-circuits on a known idempotency key (returns recorded response).\n * 2. Refuses same-key-different-args (drift detection).\n * 3. Wraps `proceed()` and audit-logs the outcome.\n * 4. Translates upstream conflict signals into a structured result with\n * alternatives the agent can act on.\n \n Implementations live in consumers (every product has different\n * persistence + telemetry needs); this interface is the contract.\n /\nexport interface IntegrationActionGuard {\n /* Wrap an invokeAction call. Implementations MUST call `proceed()` to\n * invoke the underlying provider unless they're returning a cached or\n * short-circuited result.\n \n @param ctx connection + request the hub is about to dispatch\n * @param proceed call to invoke the wrapped provider; returns the\n * underlying IntegrationActionResult\n * @returns the result the hub should return to the caller\n /\n invokeAction(\n ctx: IntegrationGuardContext,\n proceed: () => Promise<IntegrationActionResult>,\n ): Promise<IntegrationActionResult>\n}\n\nexport interface IntegrationGuardContext {\n connection: IntegrationConnection\n request: IntegrationActionRequest\n /* The action descriptor from the connector manifest, if discovered. /\n action?: IntegrationConnectorAction\n}\n\nexport interface IntegrationHubOptions {\n providers: IntegrationProvider[]\n store: IntegrationConnectionStore\n capabilitySecret: string\n /* Optional cross-cutting guard. If provided, every invokeAction call\n * passes through it before reaching the provider. See {@link IntegrationActionGuard}. */\n guard?: IntegrationActionGuard\n now?: () => Date\n}\n\nexport interface HttpIntegrationProviderOptions {\n id: string\n kind?: IntegrationProviderKind\n connectors: IntegrationConnector[]\n baseUrl: string\n bearer?: string\n fetchImpl?: typeof fetch\n}\n\nexport interface InvokeWithCapabilityRequest extends Omit<IntegrationActionRequest, 'connectionId'> {\n connectionId?: never\n}\n\nexport class IntegrationError extends Error {\n constructor(\n message: string,\n readonly code:\n \| 'provider_not_found'\n \| 'connector_not_found'\n \| 'connection_not_found'\n \| 'connection_not_active'\n \| 'auth_not_supported'\n \| 'capability_invalid'\n \| 'capability_expired'\n \| 'scope_denied'\n \| 'action_denied'\n \| 'action_not_found',\n ) {\n super(message)\n this.name = 'IntegrationError'\n }\n}\n\nexport class InMemoryConnectionStore implements IntegrationConnectionStore {\n private readonly connections = new Map<string, IntegrationConnection>()\n\n get(connectionId: string): IntegrationConnection \| undefined {\n return this.connections.get(connectionId)\n }\n\n put(connection: IntegrationConnection): void {\n this.connections.set(connection.id, connection)\n }\n\n listByOwner(owner: IntegrationActor): IntegrationConnection[] {\n return [...this.connections.values()].filter((connection) =>\n connection.owner.type === owner.type && connection.owner.id === owner.id,\n )\n }\n\n delete(connectionId: string): void {\n this.connections.delete(connectionId)\n }\n}\n\nexport class IntegrationHub {\n private readonly providers = new Map<string, IntegrationProvider>()\n private readonly store: IntegrationConnectionStore\n private readonly capabilitySecret: string\n private readonly guard: IntegrationActionGuard \| undefined\n private readonly now: () => Date\n\n constructor(options: IntegrationHubOptions) {\n if (!options.capabilitySecret) {\n throw new IntegrationError('capabilitySecret is required.', 'capability_invalid')\n }\n for (const provider of options.providers) this.providers.set(provider.id, provider)\n this.store = options.store\n this.capabilitySecret = options.capabilitySecret\n this.guard = options.guard\n this.now = options.now ?? (() => new Date())\n }\n\n async listConnectors(): Promise<IntegrationConnector[]> {\n const catalogs = await Promise.all([...this.providers.values()].map((provider) => provider.listConnectors()))\n return catalogs.flat()\n }\n\n async startAuth(providerId: string, request: StartAuthRequest): Promise<StartAuthResult> {\n const provider = this.requireProvider(providerId)\n if (!provider.startAuth) throw new IntegrationError(`Provider ${providerId} does not support auth start.`, 'auth_not_supported')\n await this.requireConnector(provider, request.connectorId)\n return provider.startAuth(request)\n }\n\n async completeAuth(providerId: string, request: CompleteAuthRequest): Promise<IntegrationConnection> {\n const provider = this.requireProvider(providerId)\n if (!provider.completeAuth) throw new IntegrationError(`Provider ${providerId} does not support auth completion.`, 'auth_not_supported')\n const connection = await provider.completeAuth(request)\n await this.store.put(connection)\n return connection\n }\n\n async upsertConnection(connection: IntegrationConnection): Promise<IntegrationConnection> {\n await this.store.put(connection)\n return connection\n }\n\n async issueCapability(request: IssueCapabilityRequest): Promise<IssuedIntegrationCapability> {\n const connection = await this.requireConnection(request.connectionId)\n this.assertConnectionActive(connection)\n assertScopes(connection, request.scopes)\n const now = this.now()\n const capability: IntegrationCapability = {\n id: `cap_${randomUUID()}`,\n subject: request.subject,\n connectionId: request.connectionId,\n scopes: unique(request.scopes),\n allowedActions: unique(request.allowedActions),\n issuedAt: now.toISOString(),\n expiresAt: new Date(now.getTime() + request.ttlMs).toISOString(),\n metadata: request.metadata,\n }\n return { capability, token: signCapability(capability, this.capabilitySecret) }\n }\n\n verifyCapability(token: string): IntegrationCapability {\n const capability = verifyCapabilityToken(token, this.capabilitySecret)\n if (Date.parse(capability.expiresAt) <= this.now().getTime()) {\n throw new IntegrationError('Integration capability expired.', 'capability_expired')\n }\n return capability\n }\n\n async invokeWithCapability(token: string, request: InvokeWithCapabilityRequest): Promise<IntegrationActionResult> {\n const capability = this.verifyCapability(token)\n if (!capability.allowedActions.includes(request.action)) {\n throw new IntegrationError(`Capability does not allow action ${request.action}.`, 'action_denied')\n }\n const connection = await this.requireConnection(capability.connectionId)\n this.assertConnectionActive(connection)\n const provider = this.requireProvider(connection.providerId)\n const connector = await this.requireConnector(provider, connection.connectorId)\n const action = connector.actions.find((candidate) => candidate.id === request.action)\n if (!action) throw new IntegrationError(`Action ${request.action} is not defined by connector ${connector.id}.`, 'action_not_found')\n assertScopes(connection, action.requiredScopes)\n assertScopes({ ...connection, grantedScopes: capability.scopes }, action.requiredScopes)\n const fullRequest: IntegrationActionRequest = { ...request, connectionId: connection.id }\n const proceed = () => Promise.resolve(provider.invokeAction(connection, fullRequest))\n if (this.guard) {\n return this.guard.invokeAction({ connection, request: fullRequest, action }, proceed)\n }\n return proceed()\n }\n\n async subscribeTrigger(connectionId: string, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription> {\n const connection = await this.requireConnection(connectionId)\n this.assertConnectionActive(connection)\n const provider = this.requireProvider(connection.providerId)\n const connector = await this.requireConnector(provider, connection.connectorId)\n const spec = connector.triggers?.find((candidate) => candidate.id === trigger)\n if (!spec) throw new IntegrationError(`Trigger ${trigger} is not defined by connector ${connector.id}.`, 'action_not_found')\n assertScopes(connection, spec.requiredScopes)\n if (!provider.subscribeTrigger) {\n throw new IntegrationError(`Provider ${provider.id} does not support triggers.`, 'auth_not_supported')\n }\n return provider.subscribeTrigger(connection, trigger, targetUrl)\n }\n\n private requireProvider(providerId: string): IntegrationProvider {\n const provider = this.providers.get(providerId)\n if (!provider) throw new IntegrationError(`Provider ${providerId} not found.`, 'provider_not_found')\n return provider\n }\n\n private async requireConnector(provider: IntegrationProvider, connectorId: string): Promise<IntegrationConnector> {\n const connector = (await provider.listConnectors()).find((candidate) => candidate.id === connectorId)\n if (!connector) throw new IntegrationError(`Connector ${connectorId} not found.`, 'connector_not_found')\n return connector\n }\n\n private async requireConnection(connectionId: string): Promise<IntegrationConnection> {\n const connection = await this.store.get(connectionId)\n if (!connection) throw new IntegrationError(`Connection ${connectionId} not found.`, 'connection_not_found')\n return connection\n }\n\n private assertConnectionActive(connection: IntegrationConnection): void {\n if (connection.status !== 'active') {\n throw new IntegrationError(`Connection ${connection.id} is ${connection.status}.`, 'connection_not_active')\n }\n if (connection.expiresAt && Date.parse(connection.expiresAt) <= this.now().getTime()) {\n throw new IntegrationError(`Connection ${connection.id} is expired.`, 'connection_not_active')\n }\n }\n}\n\nexport function sanitizeConnection(connection: IntegrationConnection): Record<string, unknown> {\n return {\n id: connection.id,\n owner: connection.owner,\n providerId: connection.providerId,\n connectorId: connection.connectorId,\n status: connection.status,\n grantedScopes: connection.grantedScopes,\n account: connection.account,\n hasSecretRef: Boolean(connection.secretRef),\n createdAt: connection.createdAt,\n updatedAt: connection.updatedAt,\n expiresAt: connection.expiresAt,\n lastUsedAt: connection.lastUsedAt,\n }\n}\n\nexport function createMockIntegrationProvider(options: {\n id?: string\n connectors?: IntegrationConnector[]\n onInvoke?: (connection: IntegrationConnection, request: IntegrationActionRequest) => IntegrationActionResult \| Promise<IntegrationActionResult>\n} = {}): IntegrationProvider {\n const providerId = options.id ?? 'mock'\n const connectors = options.connectors ?? [{\n id: 'gmail',\n providerId,\n title: 'Gmail',\n category: 'email',\n auth: 'oauth2',\n scopes: ['email.read', 'email.write'],\n actions: [\n { id: 'messages.search', title: 'Search messages', risk: 'read', requiredScopes: ['email.read'], dataClass: 'private' },\n { id: 'drafts.create', title: 'Create draft', risk: 'write', requiredScopes: ['email.write'], dataClass: 'private', approvalRequired: true },\n ],\n triggers: [\n { id: 'message.received', title: 'Message received', requiredScopes: ['email.read'], dataClass: 'private' },\n ],\n }]\n return {\n id: providerId,\n kind: 'custom',\n listConnectors: () => connectors,\n startAuth: (request) => ({\n providerId,\n connectorId: request.connectorId,\n authUrl: `https://auth.example.test/${request.connectorId}?state=${encodeURIComponent(request.state ?? 'state')}`,\n state: request.state ?? 'state',\n }),\n completeAuth: (request) => ({\n id: `conn_${request.connectorId}_${request.owner.id}`,\n owner: request.owner,\n providerId,\n connectorId: request.connectorId,\n status: 'active',\n grantedScopes: connectors.find((connector) => connector.id === request.connectorId)?.scopes ?? [],\n secretRef: { provider: providerId, id: `secret_${request.owner.id}` },\n createdAt: new Date(0).toISOString(),\n updatedAt: new Date(0).toISOString(),\n }),\n invokeAction: async (connection, request) => options.onInvoke?.(connection, request) ?? ({\n ok: true,\n action: request.action,\n output: { echo: request.input ?? null },\n }),\n subscribeTrigger: (connection, trigger, targetUrl) => ({\n id: `sub_${connection.id}_${trigger}`,\n connectionId: connection.id,\n trigger,\n targetUrl,\n status: 'active',\n createdAt: new Date(0).toISOString(),\n }),\n }\n}\n\nexport function createHttpIntegrationProvider(options: HttpIntegrationProviderOptions): IntegrationProvider {\n const fetcher = options.fetchImpl ?? fetch\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n return {\n id: options.id,\n kind: options.kind ?? 'custom',\n listConnectors: () => options.connectors,\n async startAuth(request) {\n const response = await postJson<StartAuthResult>(fetcher, `${baseUrl}/auth/start`, request, options.bearer)\n return response\n },\n async completeAuth(request) {\n const response = await postJson<IntegrationConnection>(fetcher, `${baseUrl}/auth/complete`, request, options.bearer)\n return response\n },\n async invokeAction(connection, request) {\n return postJson<IntegrationActionResult>(fetcher, `${baseUrl}/actions/invoke`, {\n connection,\n request,\n }, options.bearer)\n },\n async subscribeTrigger(connection, trigger, targetUrl) {\n return postJson<IntegrationTriggerSubscription>(fetcher, `${baseUrl}/triggers/subscribe`, {\n connection,\n trigger,\n targetUrl,\n }, options.bearer)\n },\n async unsubscribeTrigger(subscriptionId) {\n await postJson(fetcher, `${baseUrl}/triggers/unsubscribe`, { subscriptionId }, options.bearer)\n },\n async normalizeTriggerEvent(raw) {\n return postJson<IntegrationTriggerEvent>(fetcher, `${baseUrl}/triggers/normalize`, { raw }, options.bearer)\n },\n }\n}\n\nexport function signCapability(capability: IntegrationCapability, secret: string): string {\n const payload = base64UrlEncode(JSON.stringify(capability))\n const signature = hmac(payload, secret)\n return `${payload}.${signature}`\n}\n\nexport function verifyCapabilityToken(token: string, secret: string): IntegrationCapability {\n const [payload, signature] = token.split('.')\n if (!payload \|\| !signature) throw new IntegrationError('Malformed integration capability.', 'capability_invalid')\n const expected = hmac(payload, secret)\n if (!constantTimeEqual(signature, expected)) throw new IntegrationError('Invalid integration capability signature.', 'capability_invalid')\n let parsed: IntegrationCapability\n try {\n parsed = JSON.parse(base64UrlDecode(payload)) as IntegrationCapability\n } catch {\n throw new IntegrationError('Invalid integration capability payload.', 'capability_invalid')\n }\n if (!parsed.id \|\| !parsed.connectionId \|\| !Array.isArray(parsed.scopes) \|\| !Array.isArray(parsed.allowedActions)) {\n throw new IntegrationError('Invalid integration capability payload.', 'capability_invalid')\n }\n return parsed\n}\n\nasync function postJson<T = unknown>(\n fetcher: typeof fetch,\n url: string,\n body: unknown,\n bearer?: string,\n): Promise<T> {\n const response = await fetcher(url, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),\n },\n body: JSON.stringify(body),\n })\n if (!response.ok) throw new IntegrationError(`Integration provider returned HTTP ${response.status}.`, 'provider_not_found')\n return response.json() as Promise<T>\n}\n\nfunction assertScopes(connection: Pick<IntegrationConnection, 'grantedScopes'>, requiredScopes: string[]): void {\n const missing = requiredScopes.filter((scope) => !connection.grantedScopes.includes(scope))\n if (missing.length > 0) throw new IntegrationError(`Missing integration scopes: ${missing.join(', ')}`, 'scope_denied')\n}\n\nfunction hmac(payload: string, secret: string): string {\n return createHmac('sha256', secret).update(payload).digest('base64url')\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n const left = Buffer.from(a)\n const right = Buffer.from(b)\n return left.length === right.length && timingSafeEqual(left, right)\n}\n\nfunction base64UrlEncode(value: string): string {\n return Buffer.from(value, 'utf8').toString('base64url')\n}\n\nfunction base64UrlDecode(value: string): string {\n return Buffer.from(value, 'base64url').toString('utf8')\n}\n\nfunction unique<T>(values: T[]): T[] {\n return [...new Set(values)]\n}\n"],"mappings":"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","names":[]}

package/docs/provider-decision-matrix.md ADDED Viewed

@@ -0,0 +1,164 @@
+# Provider Decision Matrix
+Status date: 2026-05-04
+`agent-integrations` should keep product code independent from Nango,
+Pipedream, Zapier, Activepieces, Composio, executor-style services, and our own
+first-party connectors. The strategic goal is not to outsource integrations
+forever. The goal is to get broad connector coverage quickly while preserving a
+clean path to bring important connectors in-house.
+## Default Strategy
+Use a three-tier connector strategy:
+| Tier | Connector type | Default implementation | Why |
+| --- | --- | --- | --- |
+| Tier 1 | Strategic, high-volume, high-trust connectors | First-party provider adapter | Lowest unit cost, best UX, strictest security, strongest product moat. |
+| Tier 2 | Common but non-core connectors | Hosted gateway behind `createHttpIntegrationProvider` | Fast coverage without leaking vendor APIs into apps or sandboxes. |
+| Tier 3 | Long-tail and experimental connectors | Gateway or generated adapter | Cheap validation before committing engineering ownership. |
+The invariant: every connector, no matter who backs it, must expose the same
+`IntegrationConnector`, `IntegrationConnection`, action, trigger, and capability
+contracts.
+## Decision Matrix
+Score each connector from 1 to 5. Higher total means stronger first-party
+priority.
+| Criterion | 1 | 3 | 5 |
+| --- | --- | --- | --- |
+| User demand | Rarely requested | Common in one vertical | Needed across many products/agents |
+| Workflow criticality | Nice-to-have read path | Useful but recoverable | Blocks core product value |
+| Data sensitivity | Public/low-risk | Private business data | Regulated, financial, legal, health, secrets |
+| Write risk | Read-only | Reversible writes | Money movement, external comms, destructive writes |
+| Volume/cost | Low call volume | Moderate calls | High volume where vendor margins matter |
+| API stability | Messy/private/unstable | Usable but quirky | Stable official API + webhook model |
+| Auth complexity | Simple API key | OAuth with refresh | Multi-tenant OAuth, domain-wide delegation, scoped installs |
+| Product differentiation | Commodity | Some UX benefit | Better in-house UX is a moat |
+| Vendor coverage quality | Vendor handles it well | Vendor has gaps | Vendor coverage is weak or too generic |
+| Compliance/control need | Low | Moderate | Requires internal audit, retention, approval, residency controls |
+Decision:
+- `38+`: build or migrate first-party.
+- `26-37`: start behind a gateway, schedule migration once usage proves out.
+- `15-25`: keep gateway-backed unless a product launch depends on it.
+- `<15`: do not build first-party yet; use long-tail gateway or defer.
+## Practical Launch Order
+Build first-party adapters first for connectors that are both broadly useful
+and expensive/risky to delegate:
+1. Gmail / Google Workspace mail
+2. Google Calendar
+3. Google Drive / Docs
+4. Slack
+5. Microsoft 365 mail/calendar/files
+6. HubSpot
+7. Salesforce
+8. Notion
+9. GitHub
+10. Webhooks / generic HTTP actions
+Use gateway-backed coverage for the next large tranche:
+- marketing and ad platforms
+- analytics tools
+- project-management tools
+- form tools
+- storage services
+- social networks
+- long-tail CRM/support/helpdesk systems
+- vendor-specific workflow triggers
+This gives Agent Builder useful breadth immediately without forcing us to own
+hundreds of OAuth apps, refresh-token edge cases, webhook subscription models,
+rate-limit policies, and provider-specific APIs on day one.
+## When To Roll Our Own
+Move a connector first-party when one of these is true:
+- It appears in multiple product launch paths.
+- It is needed by generated sandbox apps, not just back-office automation.
+- Users expect a polished native UX for connection, approval, and failure
+  recovery.
+- The action volume makes gateway pricing materially worse than internal
+  maintenance.
+- The connector touches high-trust data or irreversible writes.
+- We need better replay, idempotency, audit, or conflict handling than a vendor
+  exposes.
+- The vendor abstraction hides too much provider-specific capability.
+- We need to publish open-source agent apps that still reliably route through
+  our platform keys, sandboxes, and audit controls.
+## When To Use A Gateway
+Use a gateway when speed and breadth matter more than deep ownership:
+- The connector is long-tail or unproven.
+- The integration is read-only or low write-risk.
+- The provider API is annoying but not strategic.
+- The product team needs a demo or beta connector this week.
+- The connector is mainly a trigger source, not a rich bidirectional app API.
+- The connector is expected to churn while the product shape is still moving.
+Gateways are acceptable only behind `IntegrationProvider`. Product code must
+not import vendor SDKs or depend on vendor-specific connection records.
+## First-Party Adapter Requirements
+A first-party connector is not just a thin API wrapper. It must ship with:
+- normalized connector manifest
+- OAuth/API-key start and complete flows
+- encrypted token/secret reference handling
+- refresh-token and expiry handling
+- action schemas and output schemas
+- trigger subscription and normalization if supported
+- provider rate-limit and retry policy
+- typed errors that agents can recover from
+- `IntegrationActionGuard` compatibility for idempotency, audit, approval, and
+  conflict handling
+- tests that cover auth, scope denial, capability denial, provider errors, and
+  write approval paths
+## Guard Policy
+Every production hub should install an `IntegrationActionGuard`.
+The guard is where products enforce cross-provider discipline:
+- idempotency key replay
+- same-key-different-args rejection
+- human approval before risky writes
+- per-tenant and per-connection rate limits
+- audit logging
+- conflict detection
+- dry-run handling
+- structured alternatives when an action cannot safely run
+Providers should execute actions. Guards should decide whether an action may
+run, whether it has already run, and how to record it.
+## The Cheap Path
+The cheapest credible path is:
+1. Keep `agent-integrations` as the stable SDK contract.
+2. Use a hosted gateway for broad catalog coverage while demand is uncertain.
+3. Route every sandbox/app action through short-lived capabilities and a guard.
+4. Instrument connector usage, error rate, action volume, and approval friction.
+5. Promote the highest-scoring connectors to first-party adapters.
+6. Keep long-tail connectors gateway-backed until usage justifies ownership.
+This avoids two bad extremes:
+- locking the product into a vendor abstraction that becomes expensive and
+  limiting;
+- spending months cloning hundreds of integrations before knowing which ones
+  matter.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {
@@ -28,6 +28,14 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepare": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
@@ -38,11 +46,5 @@
     "node": ">=20"
   },
   "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "packageManager": "pnpm@10.28.0"
+}