@tangle-network/agent-integrations 0.32.0 → 0.33.0

package/dist/consumer-CzJgntej.d.ts

@@ -0,0 +1,292 @@
+import { I as IntegrationActor, e as IntegrationConnectorAction, g as IntegrationDataClass, i as IntegrationActionGuard, c as IntegrationConnection, j as IntegrationActionRequest, b as IntegrationConnector, k as IntegrationActionResult } from './core-types-D5Dc65Ud.js';
+import { IntegrationSandboxBundle, IntegrationRequirementMode, IntegrationRequirementResolution, IntegrationManifest, IntegrationManifestResolution, IntegrationGrant } from './runtime.js';
+import { IntegrationRegistry } from './registry.js';
+
+type IntegrationAuditEventType = 'connection.created' | 'connection.updated' | 'connection.revoked' | 'grant.created' | 'grant.revoked' | 'capability.issued' | 'action.invoked' | 'action.failed' | 'trigger.subscribed' | 'trigger.received' | 'workflow.installed' | 'approval.requested' | 'approval.resolved' | 'healthcheck.completed';
+interface IntegrationAuditEvent {
+    id: string;
+    type: IntegrationAuditEventType;
+    occurredAt: string;
+    actor?: IntegrationActor;
+    connectionId?: string;
+    providerId?: string;
+    connectorId?: string;
+    action?: string;
+    risk?: IntegrationConnectorAction['risk'];
+    dataClass?: IntegrationDataClass;
+    ok?: boolean;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationAuditSink {
+    record(event: IntegrationAuditEvent): Promise<void> | void;
+}
+interface IntegrationAuditStore extends IntegrationAuditSink {
+    list(filter?: IntegrationAuditFilter): Promise<IntegrationAuditEvent[]> | IntegrationAuditEvent[];
+}
+interface IntegrationAuditFilter {
+    type?: IntegrationAuditEventType;
+    actor?: IntegrationActor;
+    connectionId?: string;
+    providerId?: string;
+    connectorId?: string;
+    action?: string;
+}
+declare class InMemoryIntegrationAuditStore implements IntegrationAuditStore {
+    private readonly events;
+    record(event: IntegrationAuditEvent): void;
+    list(filter?: IntegrationAuditFilter): IntegrationAuditEvent[];
+}
+declare function createIntegrationAuditEvent(input: Omit<IntegrationAuditEvent, 'id' | 'occurredAt'> & {
+    id?: string;
+    occurredAt?: string | Date;
+    now?: () => Date;
+}): IntegrationAuditEvent;
+declare function createAuditingActionGuard(options: {
+    sink: IntegrationAuditSink;
+    subject?: IntegrationActor;
+    now?: () => Date;
+    includeInputPreview?: boolean;
+}): IntegrationActionGuard;
+declare function sanitizeAuditConnection(connection: IntegrationConnection): Record<string, unknown>;
+
+type IntegrationHealthcheckStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
+interface IntegrationHealthcheckCheck {
+    id: string;
+    status: IntegrationHealthcheckStatus;
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationHealthcheckResult {
+    connectionId: string;
+    providerId: string;
+    connectorId: string;
+    status: IntegrationHealthcheckStatus;
+    checkedAt: string;
+    checks: IntegrationHealthcheckCheck[];
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationHealthcheckStore {
+    put(result: IntegrationHealthcheckResult): Promise<void> | void;
+    get(connectionId: string): Promise<IntegrationHealthcheckResult | undefined> | IntegrationHealthcheckResult | undefined;
+    list(): Promise<IntegrationHealthcheckResult[]> | IntegrationHealthcheckResult[];
+}
+declare class InMemoryIntegrationHealthcheckStore implements IntegrationHealthcheckStore {
+    private readonly results;
+    put(result: IntegrationHealthcheckResult): void;
+    get(connectionId: string): IntegrationHealthcheckResult | undefined;
+    list(): IntegrationHealthcheckResult[];
+}
+declare function runIntegrationHealthcheck(input: {
+    connection: IntegrationConnection;
+    connector?: IntegrationConnector;
+    registry?: IntegrationRegistry;
+    test?: (connection: IntegrationConnection, connector: IntegrationConnector) => Promise<IntegrationActionResult | boolean> | IntegrationActionResult | boolean;
+    audit?: IntegrationAuditSink;
+    now?: () => Date;
+}): Promise<IntegrationHealthcheckResult>;
+declare function runIntegrationHealthchecks(input: {
+    connections: IntegrationConnection[];
+    registry?: IntegrationRegistry;
+    store?: IntegrationHealthcheckStore;
+    audit?: IntegrationAuditSink;
+    now?: () => Date;
+    test?: (connection: IntegrationConnection, connector: IntegrationConnector) => Promise<IntegrationActionResult | boolean> | IntegrationActionResult | boolean;
+}): Promise<IntegrationHealthcheckResult[]>;
+declare function healthcheckRequest(action?: string): IntegrationActionRequest;
+
+/**
+ * @stable Integration Hub consumer client.
+ *
+ * The third client-shaped surface a product needs, alongside the two that
+ * already ship:
+ *
+ *   - `createTangleIntegrationsClient` (`client.ts`) — the *invoke* client.
+ *     Capability-token auth, runs INSIDE a sandbox / generated app, single
+ *     endpoint `/v1/integrations/invoke`.
+ *   - `startConnectFlow` / `finishConnectFlow` (`connect/index.ts`) — the
+ *     *user-consent* flow, mirrors `/cross-site/*`.
+ *   - **this** — the S2S *management* client. A product BACKEND (blueprint-
+ *     agent, sandbox, gtm-agent, tax-agent, legal-agent, evals, …) drives the
+ *     `/v1/integrations/{resolve-manifest,grants,capabilities/bundle,
+ *     healthchecks/run}` management surface on `id.tangle.tools` on behalf of
+ *     an identified user.
+ *
+ * Every consumer needs the identical client — the wire protocol, the
+ * `{ success, data }` envelope, the auth header shape are all platform-owned.
+ * Re-implementing a bespoke fetch loop per product forks the protocol and the
+ * copies drift. This module is that shared implementation. It mirrors the
+ * `connect/index.ts` design rule one-for-one: DO NOT invent the wire protocol
+ * — speak exactly what `products/platform/api/src/routes/integrations.ts`
+ * serves.
+ *
+ * Two auth modes — the route layer (`authMiddleware`) accepts either:
+ *
+ *   - `service`  — a `svc_*` service token + `X-Service-Name`. The acting
+ *     user travels in `X-Platform-User-Id`. The platform honors that header
+ *     only for service tokens whose `SERVICE_SCOPES` set contains
+ *     `impersonate:user`; a token without it is rejected (403). Reaches the
+ *     four management paths the platform allowlists for service tokens.
+ *   - `user-key` — a per-user `sk-tan-*` API key (minted via the connect
+ *     flow). The key identifies the user; no impersonation header. Reaches
+ *     every route the user themselves can.
+ *
+ * The capability-token `invoke` endpoint is intentionally NOT exposed here —
+ * that is `createTangleIntegrationsClient`'s job and uses a different auth.
+ */
+
+type IntegrationHubAuth = {
+    mode: 'service';
+    /** The `svc_*` token issued to this product. */
+    serviceToken: string;
+    /** Registered service name — sent as `X-Service-Name`. Required
+     *  because one token may be shared across services, in which case the
+     *  platform demands the header to disambiguate. */
+    serviceName: string;
+} | {
+    mode: 'user-key';
+    /** A per-user `sk-tan-*` key bound to the acting user. */
+    apiKey: string;
+};
+interface IntegrationHubClientOptions {
+    /** The product / consumer identifier (e.g. `blueprint-agent`). Sent as the
+     *  `product` field of resolve-manifest calls; recorded platform-side. */
+    product: string;
+    /** Service-token or per-user-key auth. */
+    auth: IntegrationHubAuth;
+    /** Platform base URL. Defaults to `https://id.tangle.tools`. */
+    endpoint?: string;
+    /** Injected for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+    /** Max attempts on transient (network / 502 / 503 / 504) failures.
+     *  Default 2 — i.e. one retry. */
+    maxAttempts?: number;
+}
+/** Thrown for every non-2xx response and every transport failure. Carries the
+ *  HTTP status and the platform error code so callers can branch precisely
+ *  (`403` + `impersonate` → the service token lacks the scope; `409` /
+ *  `missing_connection` → prompt the user to connect). */
+declare class IntegrationHubRequestError extends Error {
+    readonly name = "IntegrationHubRequestError";
+    /** HTTP status, or 0 for a network-level failure. */
+    readonly status: number;
+    /** Platform error code (`VALIDATION_ERROR`, `scope_missing`, …) or
+     *  `network_error` / `http_error` when no structured code was returned. */
+    readonly code: string;
+    /** `METHOD /path` the request targeted. */
+    readonly endpoint: string;
+    /** True when the failure class is transient and a retry could succeed. */
+    readonly retryable: boolean;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        endpoint: string;
+        retryable: boolean;
+    });
+}
+interface ResolveManifestInput {
+    /** The acting user — the connection owner. */
+    userId: string;
+    manifest: IntegrationManifest;
+    /** Overrides the client-level `product` for this call. */
+    product?: string;
+}
+interface CreateGrantsInput {
+    /** The acting user — the connection owner. */
+    userId: string;
+    /** Who the grant is FOR (the sandbox / agent / app that will invoke). */
+    grantee: IntegrationActor;
+    manifest: IntegrationManifest;
+    metadata?: Record<string, unknown>;
+}
+interface ListGrantsInput {
+    /** The acting user — the connection owner. */
+    userId: string;
+    /** Optional grantee filter; both fields travel together as query params. */
+    grantee?: IntegrationActor;
+}
+interface MintCapabilityBundleInput {
+    /** The acting user — must own every connection behind the grants. */
+    userId: string;
+    /** Who the capability bundle is issued TO (the sandbox / agent process). */
+    subject: IntegrationActor;
+    /** Mint from every grant of a manifest … */
+    manifestId?: string;
+    /** … or from an explicit grant id list. Exactly one of the two is required. */
+    grantIds?: string[];
+    grantee?: IntegrationActor;
+    /** Bundle TTL in ms. Platform clamps to [1s, 60m]; default 15m. */
+    ttlMs?: number;
+}
+interface CapabilityBundleResult {
+    bundle: IntegrationSandboxBundle;
+    /** Bridge environment variables to inject into the sandbox process —
+     *  `buildIntegrationBridgeEnvironment(bundle)`, computed platform-side. */
+    env: Record<string, string>;
+}
+interface CheckConnectorInput {
+    /** The acting user. */
+    userId: string;
+    /** Connector to probe — `github`, `google-calendar`, `tangle-id`, … */
+    connectorId: string;
+    /** Defaults to `read`. */
+    mode?: IntegrationRequirementMode;
+    requiredScopes?: string[];
+    requiredActions?: string[];
+}
+interface CheckConnectorResult {
+    /** True when the user has an active connection satisfying the requirement. */
+    connected: boolean;
+    /** The satisfying connection, present iff `connected`. */
+    connection?: IntegrationConnection;
+    /** The full requirement resolution — status, missing scopes/actions, message. */
+    resolution: IntegrationRequirementResolution;
+}
+/**
+ * S2S management client for the `id.tangle.tools` integration hub. One per
+ * product; methods are stateless and safe to call concurrently.
+ */
+declare class IntegrationHubClient {
+    private readonly endpoint;
+    private readonly product;
+    private readonly auth;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxAttempts;
+    constructor(options: IntegrationHubClientOptions);
+    /**
+     * Resolve a manifest against a user's connections. The returned
+     * `ready` / `missing` split is the canonical way to ask "does this user
+     * have the connections this work needs" — the raw connection list is not
+     * reachable by a service token by design.
+     */
+    resolveManifest(input: ResolveManifestInput): Promise<IntegrationManifestResolution>;
+    /**
+     * Convenience over {@link resolveManifest} — probe a single connector and
+     * get back a boolean plus the satisfying connection. The Surface-A quest
+     * primitive ("is the user's GitHub linked?").
+     */
+    checkConnector(input: CheckConnectorInput): Promise<CheckConnectorResult>;
+    /** Create grants for every satisfiable requirement of a manifest. The
+     *  platform rejects the call if any non-optional requirement is missing a
+     *  connection. */
+    createGrants(input: CreateGrantsInput): Promise<IntegrationGrant[]>;
+    /** List the acting user's grants, optionally filtered to one grantee. */
+    listGrants(input: ListGrantsInput): Promise<IntegrationGrant[]>;
+    /** Mint a short-lived capability bundle for a sandbox / agent process.
+     *  Provider credentials never leave the platform — the bundle carries only
+     *  scoped, expiring capability tokens. */
+    mintCapabilityBundle(input: MintCapabilityBundleInput): Promise<CapabilityBundleResult>;
+    /** Run live healthchecks across all of the acting user's connections. */
+    runHealthchecks(input: {
+        userId: string;
+    }): Promise<IntegrationHealthcheckResult[]>;
+    private buildHeaders;
+    private request;
+}
+declare function createIntegrationHubClient(options: IntegrationHubClientOptions): IntegrationHubClient;
+
+export { type CapabilityBundleResult as C, type IntegrationAuditSink as I, type ListGrantsInput as L, type MintCapabilityBundleInput as M, type ResolveManifestInput as R, type CheckConnectorInput as a, type CheckConnectorResult as b, type CreateGrantsInput as c, InMemoryIntegrationAuditStore as d, InMemoryIntegrationHealthcheckStore as e, type IntegrationAuditEvent as f, type IntegrationAuditEventType as g, type IntegrationAuditFilter as h, type IntegrationAuditStore as i, type IntegrationHealthcheckCheck as j, type IntegrationHealthcheckResult as k, type IntegrationHealthcheckStatus as l, type IntegrationHealthcheckStore as m, type IntegrationHubAuth as n, IntegrationHubClient as o, type IntegrationHubClientOptions as p, IntegrationHubRequestError as q, createAuditingActionGuard as r, createIntegrationAuditEvent as s, createIntegrationHubClient as t, healthcheckRequest as u, runIntegrationHealthcheck as v, runIntegrationHealthchecks as w, sanitizeAuditConnection as x };

package/dist/consumer.d.ts

@@ -1,8 +1,6 @@
-export { C as CapabilityBundleResult, A as CheckConnectorInput, B as CheckConnectorResult, D as CreateGrantsInput, E as IntegrationHubAuth, F as IntegrationHubClient, G as IntegrationHubClientOptions, H as IntegrationHubRequestError, L as ListGrantsInput, J as MintCapabilityBundleInput, R as ResolveManifestInput, K as createIntegrationHubClient } from './registry.js';
-import './tangle-id-Dj0ipP4E.js';
-import './errors-Bg3_rxnQ.js';
-import './connect/index.js';
-import './middleware/index.js';
-import './connectors/index.js';
-import './connectors/adapters/index.js';
-import 'node:http';
+import './core-types-D5Dc65Ud.js';
+import './runtime.js';
+export { C as CapabilityBundleResult, a as CheckConnectorInput, b as CheckConnectorResult, c as CreateGrantsInput, n as IntegrationHubAuth, o as IntegrationHubClient, p as IntegrationHubClientOptions, q as IntegrationHubRequestError, L as ListGrantsInput, M as MintCapabilityBundleInput, R as ResolveManifestInput, t as createIntegrationHubClient } from './consumer-CzJgntej.js';
+import './types-XdpvaIzW.js';
+import './catalog.js';
+import './registry.js';

package/dist/consumer.js

@@ -2,8 +2,8 @@ import {
   IntegrationHubClient,
   IntegrationHubRequestError,
   createIntegrationHubClient
-} from "./chunk-S2MVWQYL.js";
-import "./chunk-Q5X3QNHR.js";
+} from "./chunk-RF3RH374.js";
+import "./chunk-NQ7OPDUM.js";
 export {
   IntegrationHubClient,
   IntegrationHubRequestError,

package/dist/core-types-D5Dc65Ud.d.ts

@@ -0,0 +1,355 @@
+import { a as ConnectorCredentials } from './types-XdpvaIzW.js';
+
+/**
+ * Vendor-neutral integration contracts.
+ *
+ * Pure type module: every interface, type alias, and enum that other
+ * source files reference lives here. Holds zero runtime symbols so any
+ * module can import from it without forming a cycle through the package
+ * barrel (`./index.ts`).
+ *
+ * Runtime classes (`IntegrationError`, `InMemoryConnectionStore`,
+ * `IntegrationHub`, helpers) stay in `./index.ts` or are split out into
+ * their own focused modules (`./core-error.ts`).
+ */
+
+type IntegrationProviderKind = 'first_party' | 'nango' | 'pipedream' | 'zapier' | 'activepieces' | 'tangle_catalog' | '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' | 'app' | '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;
+}
+/**
+ * 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, gateway, and webhook receiver. 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;
+}
+type IntegrationPolicyDecision = {
+    decision: 'allow';
+    reason: string;
+    metadata?: Record<string, unknown>;
+} | {
+    decision: 'require_approval';
+    reason: string;
+    approval: IntegrationApprovalRequest;
+    metadata?: Record<string, unknown>;
+} | {
+    decision: 'deny';
+    reason: string;
+    metadata?: Record<string, unknown>;
+};
+interface IntegrationApprovalRequest {
+    id: string;
+    connectionId: string;
+    providerId: string;
+    connectorId: string;
+    action: string;
+    actor: IntegrationActor;
+    risk: IntegrationActionRisk;
+    dataClass: IntegrationDataClass;
+    reason: string;
+    requestedAt: string;
+    inputPreview?: unknown;
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationPolicyEngine {
+    decide(ctx: IntegrationGuardContext & {
+        subject: IntegrationActor;
+    }): Promise<IntegrationPolicyDecision> | IntegrationPolicyDecision;
+}
+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;
+    /** Optional policy engine. Runs after capability/scope checks and before
+     *  provider invocation. Use it to pause writes, deny destructive actions,
+     *  or apply tenant-specific allow rules. */
+    policy?: IntegrationPolicyEngine;
+    /** Host-injectable secret store. Multi-tenant hubs inject a durable
+     *  encrypted store; defaults to InMemoryIntegrationSecretStore for
+     *  local/dev and tests. The interface is the contract — the lib never
+     *  ships a D1/KV/encryption impl. */
+    secretStore?: IntegrationSecretStore;
+    /** Host-injectable single-use OAuth-state store guarding the start →
+     *  callback CSRF boundary. Defaults to InMemoryIntegrationOAuthStateStore. */
+    oauthStateStore?: IntegrationOAuthStateStore;
+    /** TTL applied to OAuth-state records the hub stashes at startAuth.
+     *  Defaults to 10 minutes. */
+    oauthStateTtlMs?: number;
+    /** Fired whenever a provider surfaces rotated credentials during an
+     *  invoke (e.g. an OAuth access token refreshed on expiry). The host
+     *  re-encrypts + persists the rotated envelope so the next expiry does
+     *  not force a reconnect. The hub also writes the rotated credentials to
+     *  {@link secretStore} when the connection carries a secretRef. */
+    credentialsRotated?: (event: IntegrationCredentialsRotatedEvent) => Promise<void> | void;
+    now?: () => Date;
+}
+/** Emitted when a provider rotates credentials mid-invoke. The host
+ *  re-persists `credentials` against `secretRef` (when present) so the
+ *  refreshed token survives the call. */
+interface IntegrationCredentialsRotatedEvent {
+    connection: IntegrationConnection;
+    secretRef?: SecretRef;
+    credentials: ConnectorCredentials;
+}
+interface HttpIntegrationProviderOptions {
+    id: string;
+    kind?: IntegrationProviderKind;
+    connectors: IntegrationConnector[];
+    baseUrl: string;
+    bearer?: string;
+    fetchImpl?: typeof fetch;
+}
+interface InvokeWithCapabilityRequest extends Omit<IntegrationActionRequest, 'connectionId'> {
+    connectionId?: never;
+}
+/** A catalog of connectors keyed by stable source id. The registry merges
+ *  multiple sources (first-party adapter packs, Activepieces import, custom
+ *  HTTP catalog, …) into a canonical view with conflict reporting. */
+interface IntegrationCatalogSource {
+    id: string;
+    connectors: IntegrationConnector[];
+    precedence?: number;
+}
+/** Host-injectable persistent store for OAuth tokens and other connector
+ *  credentials. Multi-tenant hubs inject a durable encrypted store; defaults
+ *  to an in-memory implementation for local/dev and tests. The interface is
+ *  the contract — the lib never ships a D1/KV/encryption impl. */
+interface IntegrationSecretStore {
+    get(ref: SecretRef): Promise<ConnectorCredentials | undefined> | ConnectorCredentials | undefined;
+    put(ref: SecretRef, credentials: ConnectorCredentials): Promise<void> | void;
+    delete?(ref: SecretRef): Promise<void> | void;
+}
+/** Single-use record stashed at OAuth-start and consumed once at callback to
+ *  guard against CSRF / replay. The hub injects its own durable
+ *  implementation (KV/Redis/D1) so the callback can land on any worker. */
+interface IntegrationOAuthState {
+    /** Opaque value round-tripped through the provider redirect. */
+    state: string;
+    /** Provider the auth flow targets. */
+    providerId: string;
+    /** Connector the user is connecting. */
+    connectorId: string;
+    /** Owner initiating the flow. */
+    owner: IntegrationActor;
+    /** Scopes requested at start; verified against the granted scopes on callback. */
+    requestedScopes: string[];
+    /** Redirect URI used at start; MUST match exactly on callback exchange. */
+    redirectUri: string;
+    /** PKCE code_verifier, when the connector uses PKCE. */
+    codeVerifier?: string;
+    /** Absolute expiry (UTC ms since epoch). consume() MUST treat an expired
+     *  record as a miss. */
+    expiresAt: number;
+    /** Arbitrary non-secret context the host pinned at start-time. */
+    metadata?: Record<string, unknown>;
+}
+/** Outcome of consuming an OAuth state record. Callers MUST inspect `ok`
+ *  before using `state`; a miss (`unknown`/`expired`) is the CSRF/replay
+ *  guard firing, not an exception. */
+type IntegrationOAuthStateOutcome = {
+    ok: true;
+    state: IntegrationOAuthState;
+} | {
+    ok: false;
+    reason: 'unknown' | 'expired';
+};
+/** Host-injectable store for single-use OAuth-start records. The default is
+ *  in-memory for local/dev and tests; multi-tenant hubs inject a durable
+ *  encrypted store so callbacks survive worker hops. consume() MUST be
+ *  single-use: a second consume of the same state returns `{ ok: false }`. */
+interface IntegrationOAuthStateStore {
+    put(state: IntegrationOAuthState): Promise<void> | void;
+    consume(state: string): Promise<IntegrationOAuthStateOutcome> | IntegrationOAuthStateOutcome;
+    sweep?(now: number): Promise<void> | void;
+}
+
+export type { IntegrationTriggerEvent as A, InvokeWithCapabilityRequest as B, CompleteAuthRequest as C, IntegrationCapability as D, IntegrationHubOptions as E, IssueCapabilityRequest as F, IntegrationConnectorTrigger as G, HttpIntegrationProviderOptions as H, IntegrationActor as I, StartAuthRequest as S, IssuedIntegrationCapability as a, IntegrationConnector as b, IntegrationConnection as c, IntegrationConnectorCategory as d, IntegrationConnectorAction as e, IntegrationActionRisk as f, IntegrationDataClass as g, IntegrationCatalogSource as h, IntegrationActionGuard as i, IntegrationActionRequest as j, IntegrationActionResult as k, StartAuthResult as l, IntegrationProvider as m, IntegrationSecretStore as n, IntegrationPolicyEngine as o, IntegrationApprovalRequest as p, IntegrationGuardContext as q, IntegrationPolicyDecision as r, IntegrationProviderKind as s, IntegrationConnectionStore as t, IntegrationCredentialsRotatedEvent as u, IntegrationOAuthStateStore as v, IntegrationOAuthState as w, IntegrationOAuthStateOutcome as x, SecretRef as y, IntegrationTriggerSubscription as z };