@tangle-network/agent-integrations 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Agent Integrations
+
+`@tangle-network/agent-integrations` is a vendor-neutral integration layer for
+apps, sandboxes, and agents that need user-authorized connections such as email,
+calendar, Slack, CRM, storage, webhooks, and workflow triggers.
+
+The package does not pick a single integration vendor. Nango, Pipedream,
+Zapier-style platforms, Activepieces, executor services, and first-party
+connectors should all sit behind the same provider interface.
+
+## Mental Model
+
+```txt
+Connector catalog -> User connection -> Scoped capability -> Action or trigger
+```
+
+- **Connectors** describe what can be connected: Gmail, Google Calendar, Slack,
+  HubSpot, webhooks, internal tools.
+- **Connections** are user/team-owned grants. They carry secret references, not
+  raw credentials.
+- **Capabilities** are short-lived, sandbox-safe tokens that authorize a subset
+  of actions on a connection.
+- **Actions** are read/write/destructive operations.
+- **Triggers** normalize inbound events from providers into one event shape.
+
+## Why This Exists
+
+Agent Builder and sandbox apps need to support prompts like:
+
+```txt
+At Gmail, build me an app that summarizes unread support emails and drafts replies.
+```
+
+The generated app should be able to request Gmail access, instantiate inside the
+user's sandbox, and let the agent read/write through a scoped integration
+capability. The sandbox should never receive reusable provider secrets.
+
+## Core Usage
+
+```ts
+import {
+  InMemoryConnectionStore,
+  IntegrationHub,
+  createMockIntegrationProvider,
+} from '@tangle-network/agent-integrations'
+
+const hub = new IntegrationHub({
+  providers: [createMockIntegrationProvider()],
+  store: new InMemoryConnectionStore(),
+  capabilitySecret: 'dev-secret',
+})
+
+const connection = await hub.upsertConnection({
+  id: 'conn_1',
+  owner: { type: 'user', id: 'user_1' },
+  providerId: 'mock',
+  connectorId: 'gmail',
+  status: 'active',
+  grantedScopes: ['email.read'],
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+})
+
+const capability = await hub.issueCapability({
+  subject: { type: 'sandbox', id: 'sandbox_1' },
+  connectionId: connection.id,
+  scopes: ['email.read'],
+  allowedActions: ['messages.search'],
+  ttlMs: 60_000,
+})
+
+const result = await hub.invokeWithCapability(capability.token, {
+  action: 'messages.search',
+  input: { q: 'is:unread' },
+})
+```
+
+## Provider Boundary
+
+Providers implement OAuth, action execution, and optional triggers. Product code
+should depend on `IntegrationHub`, not on a vendor SDK.
+
+Provider adapters are expected to store raw credentials in their own secure
+vault or return secret references. Connection records should remain safe to log
+after sanitization.
+
+For a hosted integration gateway, use the generic HTTP adapter:
+
+```ts
+import { createHttpIntegrationProvider } from '@tangle-network/agent-integrations'
+
+const provider = createHttpIntegrationProvider({
+  id: 'gateway',
+  kind: 'pipedream',
+  baseUrl: 'https://integrations.example',
+  bearer: process.env.INTEGRATION_GATEWAY_TOKEN,
+  connectors: [/* normalized connector catalog */],
+})
+```
+
+The HTTP adapter keeps product code stable while the backing provider can be
+Nango, Pipedream, Activepieces, a Zapier-style service, or an internal gateway.
+
+## Security Defaults
+
+- Capabilities expire.
+- Capability tokens contain no provider credential.
+- Secret refs are redacted from public telemetry.
+- Write/destructive actions can be policy-gated.
+- Action invocation checks connection ownership, status, scopes, allowed
+  actions, and expiration.

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+type IntegrationProviderKind = 'first_party' | 'nango' | 'pipedream' | 'zapier' | 'activepieces' | 'executor' | 'custom';
+type IntegrationConnectorCategory = 'email' | 'calendar' | 'chat' | 'crm' | 'storage' | 'docs' | 'database' | 'webhook' | 'workflow' | 'internal' | 'other';
+type IntegrationActionRisk = 'read' | 'write' | 'destructive';
+type IntegrationDataClass = 'public' | 'internal' | 'private' | 'sensitive' | 'secret';
+interface IntegrationActor {
+    type: 'user' | 'team' | 'agent' | 'sandbox' | 'system';
+    id: string;
+}
+interface IntegrationConnectorAction {
+    id: string;
+    title: string;
+    risk: IntegrationActionRisk;
+    requiredScopes: string[];
+    dataClass: IntegrationDataClass;
+    description?: string;
+    approvalRequired?: boolean;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}
+interface IntegrationConnectorTrigger {
+    id: string;
+    title: string;
+    requiredScopes: string[];
+    dataClass: IntegrationDataClass;
+    description?: string;
+    payloadSchema?: unknown;
+}
+interface IntegrationConnector {
+    id: string;
+    providerId: string;
+    title: string;
+    category: IntegrationConnectorCategory;
+    auth: 'oauth2' | 'api_key' | 'none' | 'custom';
+    scopes: string[];
+    actions: IntegrationConnectorAction[];
+    triggers?: IntegrationConnectorTrigger[];
+    metadata?: Record<string, unknown>;
+}
+interface SecretRef {
+    provider: string;
+    id: string;
+    label?: string;
+}
+interface IntegrationConnection {
+    id: string;
+    owner: IntegrationActor;
+    providerId: string;
+    connectorId: string;
+    status: 'pending' | 'active' | 'expired' | 'revoked' | 'error';
+    grantedScopes: string[];
+    account?: {
+        id?: string;
+        email?: string;
+        displayName?: string;
+    };
+    secretRef?: SecretRef;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    lastUsedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface StartAuthRequest {
+    connectorId: string;
+    owner: IntegrationActor;
+    requestedScopes: string[];
+    redirectUri: string;
+    state?: string;
+    metadata?: Record<string, unknown>;
+}
+interface StartAuthResult {
+    providerId: string;
+    connectorId: string;
+    authUrl: string;
+    state: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CompleteAuthRequest {
+    connectorId: string;
+    owner: IntegrationActor;
+    code?: string;
+    state: string;
+    redirectUri: string;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationActionRequest {
+    connectionId: string;
+    action: string;
+    input?: unknown;
+    idempotencyKey?: string;
+    dryRun?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationActionResult<T = unknown> {
+    ok: boolean;
+    action: string;
+    output?: T;
+    externalId?: string;
+    warnings?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationTriggerSubscription {
+    id: string;
+    connectionId: string;
+    trigger: string;
+    targetUrl?: string;
+    status: 'active' | 'paused' | 'error';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationTriggerEvent<T = unknown> {
+    id: string;
+    providerId: string;
+    connectorId: string;
+    connectionId: string;
+    trigger: string;
+    occurredAt: string;
+    payload: T;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationProvider {
+    id: string;
+    kind: IntegrationProviderKind;
+    listConnectors(): Promise<IntegrationConnector[]> | IntegrationConnector[];
+    startAuth?(request: StartAuthRequest): Promise<StartAuthResult> | StartAuthResult;
+    completeAuth?(request: CompleteAuthRequest): Promise<IntegrationConnection> | IntegrationConnection;
+    invokeAction(connection: IntegrationConnection, request: IntegrationActionRequest): Promise<IntegrationActionResult> | IntegrationActionResult;
+    subscribeTrigger?(connection: IntegrationConnection, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription> | IntegrationTriggerSubscription;
+    unsubscribeTrigger?(subscriptionId: string): Promise<void> | void;
+    normalizeTriggerEvent?(raw: unknown): Promise<IntegrationTriggerEvent> | IntegrationTriggerEvent;
+}
+interface IntegrationConnectionStore {
+    get(connectionId: string): Promise<IntegrationConnection | undefined> | IntegrationConnection | undefined;
+    put(connection: IntegrationConnection): Promise<void> | void;
+    listByOwner(owner: IntegrationActor): Promise<IntegrationConnection[]> | IntegrationConnection[];
+    delete?(connectionId: string): Promise<void> | void;
+}
+interface IssueCapabilityRequest {
+    subject: IntegrationActor;
+    connectionId: string;
+    scopes: string[];
+    allowedActions: string[];
+    ttlMs: number;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationCapability {
+    id: string;
+    subject: IntegrationActor;
+    connectionId: string;
+    scopes: string[];
+    allowedActions: string[];
+    issuedAt: string;
+    expiresAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface IssuedIntegrationCapability {
+    capability: IntegrationCapability;
+    token: string;
+}
+interface IntegrationHubOptions {
+    providers: IntegrationProvider[];
+    store: IntegrationConnectionStore;
+    capabilitySecret: string;
+    now?: () => Date;
+}
+interface HttpIntegrationProviderOptions {
+    id: string;
+    kind?: IntegrationProviderKind;
+    connectors: IntegrationConnector[];
+    baseUrl: string;
+    bearer?: string;
+    fetchImpl?: typeof fetch;
+}
+interface InvokeWithCapabilityRequest extends Omit<IntegrationActionRequest, 'connectionId'> {
+    connectionId?: never;
+}
+declare class IntegrationError extends Error {
+    readonly code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found';
+    constructor(message: string, code: 'provider_not_found' | 'connector_not_found' | 'connection_not_found' | 'connection_not_active' | 'auth_not_supported' | 'capability_invalid' | 'capability_expired' | 'scope_denied' | 'action_denied' | 'action_not_found');
+}
+declare class InMemoryConnectionStore implements IntegrationConnectionStore {
+    private readonly connections;
+    get(connectionId: string): IntegrationConnection | undefined;
+    put(connection: IntegrationConnection): void;
+    listByOwner(owner: IntegrationActor): IntegrationConnection[];
+    delete(connectionId: string): void;
+}
+declare class IntegrationHub {
+    private readonly providers;
+    private readonly store;
+    private readonly capabilitySecret;
+    private readonly now;
+    constructor(options: IntegrationHubOptions);
+    listConnectors(): Promise<IntegrationConnector[]>;
+    startAuth(providerId: string, request: StartAuthRequest): Promise<StartAuthResult>;
+    completeAuth(providerId: string, request: CompleteAuthRequest): Promise<IntegrationConnection>;
+    upsertConnection(connection: IntegrationConnection): Promise<IntegrationConnection>;
+    issueCapability(request: IssueCapabilityRequest): Promise<IssuedIntegrationCapability>;
+    verifyCapability(token: string): IntegrationCapability;
+    invokeWithCapability(token: string, request: InvokeWithCapabilityRequest): Promise<IntegrationActionResult>;
+    subscribeTrigger(connectionId: string, trigger: string, targetUrl?: string): Promise<IntegrationTriggerSubscription>;
+    private requireProvider;
+    private requireConnector;
+    private requireConnection;
+    private assertConnectionActive;
+}
+declare function sanitizeConnection(connection: IntegrationConnection): Record<string, unknown>;
+declare function createMockIntegrationProvider(options?: {
+    id?: string;
+    connectors?: IntegrationConnector[];
+    onInvoke?: (connection: IntegrationConnection, request: IntegrationActionRequest) => IntegrationActionResult | Promise<IntegrationActionResult>;
+}): IntegrationProvider;
+declare function createHttpIntegrationProvider(options: HttpIntegrationProviderOptions): IntegrationProvider;
+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 };

package/dist/index.js

@@ -0,0 +1,308 @@
+// src/index.ts
+import { createHmac, randomUUID, timingSafeEqual } from "crypto";
+var IntegrationError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "IntegrationError";
+  }
+  code;
+};
+var InMemoryConnectionStore = class {
+  connections = /* @__PURE__ */ new Map();
+  get(connectionId) {
+    return this.connections.get(connectionId);
+  }
+  put(connection) {
+    this.connections.set(connection.id, connection);
+  }
+  listByOwner(owner) {
+    return [...this.connections.values()].filter(
+      (connection) => connection.owner.type === owner.type && connection.owner.id === owner.id
+    );
+  }
+  delete(connectionId) {
+    this.connections.delete(connectionId);
+  }
+};
+var IntegrationHub = class {
+  providers = /* @__PURE__ */ new Map();
+  store;
+  capabilitySecret;
+  now;
+  constructor(options) {
+    if (!options.capabilitySecret) {
+      throw new IntegrationError("capabilitySecret is required.", "capability_invalid");
+    }
+    for (const provider of options.providers) this.providers.set(provider.id, provider);
+    this.store = options.store;
+    this.capabilitySecret = options.capabilitySecret;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  async listConnectors() {
+    const catalogs = await Promise.all([...this.providers.values()].map((provider) => provider.listConnectors()));
+    return catalogs.flat();
+  }
+  async startAuth(providerId, request) {
+    const provider = this.requireProvider(providerId);
+    if (!provider.startAuth) throw new IntegrationError(`Provider ${providerId} does not support auth start.`, "auth_not_supported");
+    await this.requireConnector(provider, request.connectorId);
+    return provider.startAuth(request);
+  }
+  async completeAuth(providerId, request) {
+    const provider = this.requireProvider(providerId);
+    if (!provider.completeAuth) throw new IntegrationError(`Provider ${providerId} does not support auth completion.`, "auth_not_supported");
+    const connection = await provider.completeAuth(request);
+    await this.store.put(connection);
+    return connection;
+  }
+  async upsertConnection(connection) {
+    await this.store.put(connection);
+    return connection;
+  }
+  async issueCapability(request) {
+    const connection = await this.requireConnection(request.connectionId);
+    this.assertConnectionActive(connection);
+    assertScopes(connection, request.scopes);
+    const now = this.now();
+    const capability = {
+      id: `cap_${randomUUID()}`,
+      subject: request.subject,
+      connectionId: request.connectionId,
+      scopes: unique(request.scopes),
+      allowedActions: unique(request.allowedActions),
+      issuedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + request.ttlMs).toISOString(),
+      metadata: request.metadata
+    };
+    return { capability, token: signCapability(capability, this.capabilitySecret) };
+  }
+  verifyCapability(token) {
+    const capability = verifyCapabilityToken(token, this.capabilitySecret);
+    if (Date.parse(capability.expiresAt) <= this.now().getTime()) {
+      throw new IntegrationError("Integration capability expired.", "capability_expired");
+    }
+    return capability;
+  }
+  async invokeWithCapability(token, request) {
+    const capability = this.verifyCapability(token);
+    if (!capability.allowedActions.includes(request.action)) {
+      throw new IntegrationError(`Capability does not allow action ${request.action}.`, "action_denied");
+    }
+    const connection = await this.requireConnection(capability.connectionId);
+    this.assertConnectionActive(connection);
+    const provider = this.requireProvider(connection.providerId);
+    const connector = await this.requireConnector(provider, connection.connectorId);
+    const action = connector.actions.find((candidate) => candidate.id === request.action);
+    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 });
+  }
+  async subscribeTrigger(connectionId, trigger, targetUrl) {
+    const connection = await this.requireConnection(connectionId);
+    this.assertConnectionActive(connection);
+    const provider = this.requireProvider(connection.providerId);
+    const connector = await this.requireConnector(provider, connection.connectorId);
+    const spec = connector.triggers?.find((candidate) => candidate.id === trigger);
+    if (!spec) throw new IntegrationError(`Trigger ${trigger} is not defined by connector ${connector.id}.`, "action_not_found");
+    assertScopes(connection, spec.requiredScopes);
+    if (!provider.subscribeTrigger) {
+      throw new IntegrationError(`Provider ${provider.id} does not support triggers.`, "auth_not_supported");
+    }
+    return provider.subscribeTrigger(connection, trigger, targetUrl);
+  }
+  requireProvider(providerId) {
+    const provider = this.providers.get(providerId);
+    if (!provider) throw new IntegrationError(`Provider ${providerId} not found.`, "provider_not_found");
+    return provider;
+  }
+  async requireConnector(provider, connectorId) {
+    const connector = (await provider.listConnectors()).find((candidate) => candidate.id === connectorId);
+    if (!connector) throw new IntegrationError(`Connector ${connectorId} not found.`, "connector_not_found");
+    return connector;
+  }
+  async requireConnection(connectionId) {
+    const connection = await this.store.get(connectionId);
+    if (!connection) throw new IntegrationError(`Connection ${connectionId} not found.`, "connection_not_found");
+    return connection;
+  }
+  assertConnectionActive(connection) {
+    if (connection.status !== "active") {
+      throw new IntegrationError(`Connection ${connection.id} is ${connection.status}.`, "connection_not_active");
+    }
+    if (connection.expiresAt && Date.parse(connection.expiresAt) <= this.now().getTime()) {
+      throw new IntegrationError(`Connection ${connection.id} is expired.`, "connection_not_active");
+    }
+  }
+};
+function sanitizeConnection(connection) {
+  return {
+    id: connection.id,
+    owner: connection.owner,
+    providerId: connection.providerId,
+    connectorId: connection.connectorId,
+    status: connection.status,
+    grantedScopes: connection.grantedScopes,
+    account: connection.account,
+    hasSecretRef: Boolean(connection.secretRef),
+    createdAt: connection.createdAt,
+    updatedAt: connection.updatedAt,
+    expiresAt: connection.expiresAt,
+    lastUsedAt: connection.lastUsedAt
+  };
+}
+function createMockIntegrationProvider(options = {}) {
+  const providerId = options.id ?? "mock";
+  const connectors = options.connectors ?? [{
+    id: "gmail",
+    providerId,
+    title: "Gmail",
+    category: "email",
+    auth: "oauth2",
+    scopes: ["email.read", "email.write"],
+    actions: [
+      { id: "messages.search", title: "Search messages", risk: "read", requiredScopes: ["email.read"], dataClass: "private" },
+      { id: "drafts.create", title: "Create draft", risk: "write", requiredScopes: ["email.write"], dataClass: "private", approvalRequired: true }
+    ],
+    triggers: [
+      { id: "message.received", title: "Message received", requiredScopes: ["email.read"], dataClass: "private" }
+    ]
+  }];
+  return {
+    id: providerId,
+    kind: "custom",
+    listConnectors: () => connectors,
+    startAuth: (request) => ({
+      providerId,
+      connectorId: request.connectorId,
+      authUrl: `https://auth.example.test/${request.connectorId}?state=${encodeURIComponent(request.state ?? "state")}`,
+      state: request.state ?? "state"
+    }),
+    completeAuth: (request) => ({
+      id: `conn_${request.connectorId}_${request.owner.id}`,
+      owner: request.owner,
+      providerId,
+      connectorId: request.connectorId,
+      status: "active",
+      grantedScopes: connectors.find((connector) => connector.id === request.connectorId)?.scopes ?? [],
+      secretRef: { provider: providerId, id: `secret_${request.owner.id}` },
+      createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+    }),
+    invokeAction: async (connection, request) => options.onInvoke?.(connection, request) ?? {
+      ok: true,
+      action: request.action,
+      output: { echo: request.input ?? null }
+    },
+    subscribeTrigger: (connection, trigger, targetUrl) => ({
+      id: `sub_${connection.id}_${trigger}`,
+      connectionId: connection.id,
+      trigger,
+      targetUrl,
+      status: "active",
+      createdAt: (/* @__PURE__ */ new Date(0)).toISOString()
+    })
+  };
+}
+function createHttpIntegrationProvider(options) {
+  const fetcher = options.fetchImpl ?? fetch;
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  return {
+    id: options.id,
+    kind: options.kind ?? "custom",
+    listConnectors: () => options.connectors,
+    async startAuth(request) {
+      const response = await postJson(fetcher, `${baseUrl}/auth/start`, request, options.bearer);
+      return response;
+    },
+    async completeAuth(request) {
+      const response = await postJson(fetcher, `${baseUrl}/auth/complete`, request, options.bearer);
+      return response;
+    },
+    async invokeAction(connection, request) {
+      return postJson(fetcher, `${baseUrl}/actions/invoke`, {
+        connection,
+        request
+      }, options.bearer);
+    },
+    async subscribeTrigger(connection, trigger, targetUrl) {
+      return postJson(fetcher, `${baseUrl}/triggers/subscribe`, {
+        connection,
+        trigger,
+        targetUrl
+      }, options.bearer);
+    },
+    async unsubscribeTrigger(subscriptionId) {
+      await postJson(fetcher, `${baseUrl}/triggers/unsubscribe`, { subscriptionId }, options.bearer);
+    },
+    async normalizeTriggerEvent(raw) {
+      return postJson(fetcher, `${baseUrl}/triggers/normalize`, { raw }, options.bearer);
+    }
+  };
+}
+function signCapability(capability, secret) {
+  const payload = base64UrlEncode(JSON.stringify(capability));
+  const signature = hmac(payload, secret);
+  return `${payload}.${signature}`;
+}
+function verifyCapabilityToken(token, secret) {
+  const [payload, signature] = token.split(".");
+  if (!payload || !signature) throw new IntegrationError("Malformed integration capability.", "capability_invalid");
+  const expected = hmac(payload, secret);
+  if (!constantTimeEqual(signature, expected)) throw new IntegrationError("Invalid integration capability signature.", "capability_invalid");
+  let parsed;
+  try {
+    parsed = JSON.parse(base64UrlDecode(payload));
+  } catch {
+    throw new IntegrationError("Invalid integration capability payload.", "capability_invalid");
+  }
+  if (!parsed.id || !parsed.connectionId || !Array.isArray(parsed.scopes) || !Array.isArray(parsed.allowedActions)) {
+    throw new IntegrationError("Invalid integration capability payload.", "capability_invalid");
+  }
+  return parsed;
+}
+async function postJson(fetcher, url, body, bearer) {
+  const response = await fetcher(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...bearer ? { Authorization: `Bearer ${bearer}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) throw new IntegrationError(`Integration provider returned HTTP ${response.status}.`, "provider_not_found");
+  return response.json();
+}
+function assertScopes(connection, requiredScopes) {
+  const missing = requiredScopes.filter((scope) => !connection.grantedScopes.includes(scope));
+  if (missing.length > 0) throw new IntegrationError(`Missing integration scopes: ${missing.join(", ")}`, "scope_denied");
+}
+function hmac(payload, secret) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+function constantTimeEqual(a, b) {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function base64UrlEncode(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+function base64UrlDecode(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+export {
+  InMemoryConnectionStore,
+  IntegrationError,
+  IntegrationHub,
+  createHttpIntegrationProvider,
+  createMockIntegrationProvider,
+  sanitizeConnection,
+  signCapability,
+  verifyCapabilityToken
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/docs/architecture.md

@@ -0,0 +1,46 @@
+# Agent Integrations Architecture
+
+## Non-Goals
+
+- Do not become a full Zapier clone in the SDK.
+- Do not require one OAuth broker or workflow vendor.
+- Do not expose provider tokens to sandboxes or agents.
+- Do not make product repos hand-roll Gmail/Slack/calendar semantics.
+
+## Package Responsibilities
+
+`agent-integrations` owns:
+
+- stable connector, connection, action, trigger, and capability contracts
+- provider adapter interface
+- connection store interface
+- sandbox-safe capability token minting and verification
+- invocation policy enforcement
+- event normalization
+- redaction helpers
+
+Provider-specific services own:
+
+- OAuth client registration
+- provider token vaulting
+- refresh-token rotation
+- webhook subscription lifecycle
+- vendor-specific action mapping
+- provider rate limits and retries
+
+Product apps own:
+
+- UI for connect/install/approve flows
+- tenant/user ownership policy
+- which connectors are enabled
+- human approval before sensitive writes
+- audit log persistence
+
+## Launch Bar
+
+- A generated app can declare required connectors.
+- Builder can ask the user to connect missing accounts.
+- A sandbox can receive a short-lived capability for one user-owned connection.
+- Agents can invoke only actions allowed by that capability.
+- Triggers can wake or enqueue sandbox workflows without exposing credentials.
+- Audit logs can show what happened without leaking secrets.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tangle-network/agent-integrations",
+  "version": "0.1.0",
+  "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
+  "homepage": "https://github.com/tangle-network/agent-integrations#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangle-network/agent-integrations.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tangle-network/agent-integrations/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}