@tangle-network/agent-integrations 0.14.0 → 0.16.0

package/docs/architecture.md

@@ -16,6 +16,10 @@
 - connection store interface
 - sandbox-safe capability token minting and verification
 - invocation policy enforcement
+- approval persistence contracts and resume helpers
+- audit, idempotency, healthcheck, and webhook-ingestion primitives
+- credential resolver interfaces over product-owned vaults
+- sandbox/CLI bridge payloads for scoped capabilities
 - event normalization
 - redaction helpers
 
@@ -44,3 +48,6 @@ Product apps own:
 - 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.
+- Writes can pause for approval, resume by approval id, and replay safely by
+  idempotency key.
+- Products can healthcheck connections and ingest webhooks with dedupe.

package/docs/production-completion-checklist.md

@@ -0,0 +1,63 @@
+# Production Completion Checklist
+
+This is the library-owned done bar for `agent-integrations`. Product repos still
+own UI, DB adapters, vault deployment, enabled-connector policy, and live
+provider credentials.
+
+## Complete In This Package
+
+- [x] Normalized connector, action, trigger, connection, and capability types.
+- [x] Vendor-neutral `IntegrationHub` facade for provider catalogs, auth,
+      connections, scoped capability issue/verify, and action invocation.
+- [x] First-party connector adapter boundary and declarative REST adapter path.
+- [x] Generated setup specs and runbook/admin-UI renderers.
+- [x] Canonical registry that dedupes setup specs, first-party adapters,
+      gateway catalogs, and long-tail catalog metadata.
+- [x] Catalog-only safety: long-tail metadata is discoverable but not callable
+      unless promoted to an executable support tier.
+- [x] App/agent `IntegrationManifest` resolution against user connections.
+- [x] Persistent grants from user-owned connections to apps, agents, sandboxes,
+      and generated software.
+- [x] Sandbox bundles with short-lived capability tokens and tool definitions.
+- [x] Bridge payload/env helpers for sandbox processes and executor-style CLIs.
+- [x] Sandbox invocation host that validates envelopes before hub invocation and
+      normalizes success, failure, and approval-required results.
+- [x] Policy engine for allow/deny/approval decisions.
+- [x] Approval store and approval-backed policy resume path.
+- [x] Idempotency guard with replay, same-key drift detection, dry-run mutation
+      handling, optional rate-limit hook, and audit records.
+- [x] Audit event store/sink and redaction helpers.
+- [x] Healthcheck primitives for connection status, executable tier, scope
+      shape, and optional live provider tests.
+- [x] Credential resolver and secret-store interface for resolving secret refs,
+      refreshing expired OAuth credentials, and revoking connections.
+- [x] Workflow runtime for trigger subscription install and normalized event
+      dispatch.
+- [x] Webhook ingestion runtime for signature checks, provider-event dedupe, and
+      workflow dispatch.
+- [x] Focused tests for hub, registry, runtime grants, workflow triggers,
+      sandbox invocation, approval resume, idempotency, credentials,
+      healthchecks, bridge payloads, and webhook dedupe.
+
+## Product Integration Checklist
+
+- [ ] Persist `IntegrationConnection`, `IntegrationGrant`, approval, audit,
+      healthcheck, workflow, and event stores in the product database.
+- [ ] Back `IntegrationSecretStore` with the production vault/KMS.
+- [ ] Add OAuth/API-key setup UI from `IntegrationSpec` renderers.
+- [ ] Add connect, approve, revoke, rotate, healthcheck, and audit-log screens.
+- [ ] Feed generated app requirements into `IntegrationManifest`.
+- [ ] Inject `buildIntegrationBridgeEnvironment()` into sandbox launches.
+- [ ] Route sandbox tool calls through `dispatchIntegrationInvocation()`.
+- [ ] Run live OAuth and browser E2E tests for each shipped product.
+
+## Executor.sh And Sandbox CLIs
+
+Executor-style CLIs are an execution layer, not the integration source of truth.
+They can consume this package cleanly by receiving the bridge env payload inside
+the sandbox and calling back to the product integration hub with capability
+tokens. The CLI never needs OAuth refresh tokens or provider API keys.
+
+Use executor-style tooling when it improves sandbox process orchestration,
+command execution, or workflow hosting. Do not make it the credential broker or
+canonical connector registry unless a product explicitly chooses that provider.

package/docs/repo-structure.md

@@ -0,0 +1,47 @@
+# Repository Structure
+
+This repo intentionally separates catalog breadth from executable runtime code.
+
+## Source
+
+- `src/index.ts` exports the public package surface.
+- `src/actions.ts` defines canonical launch action ids and schemas for the
+  first product-ready connectors.
+- `src/client.ts` is the tiny generated-app/sandbox client over platform
+  `/v1/integrations/invoke`.
+- `src/manifest.ts` validates and infers `IntegrationManifest` values.
+- `src/consent.ts` renders user-facing consent/approval copy from manifests.
+- `src/runtime.ts` resolves manifests, creates grants, and builds sandbox
+  bundles.
+- `src/bridge.ts` encodes scoped sandbox/CLI bridge payloads.
+- `src/sandbox.ts` validates sandbox invocation envelopes and normalizes
+  invocation results.
+- `src/policy.ts`, `src/presets.ts`, `src/approval.ts`, `src/guard.ts`,
+  `src/audit.ts`, `src/healthcheck.ts`, `src/credentials.ts`, and
+  `src/events.ts` are production control-plane primitives.
+- `src/connectors/` contains first-party adapter contracts and implementations.
+- `src/specs/` is the structured OAuth/setup/runbook source of truth.
+- `src/registry.ts`, `src/gateway-catalog.ts`, `src/coverage-catalog.ts`, and
+  `src/activepieces-catalog.ts` compose broad connector catalogs without
+  pretending catalog-only entries are executable.
+
+## Data
+
+- `data/activepieces-catalog.json` is large by design. It is lazy-loaded and
+  keeps long-tail discovery out of TypeScript source so `tsc --watch` does not
+  re-check a generated 40k-line module. It is catalog metadata, not executable
+  support.
+
+## Build Artifacts
+
+- `dist/` is published because the package ships compiled ESM and `.d.ts`
+  files to npm.
+- `node_modules/` is local development state and is not published.
+
+## Docs
+
+- `docs/production-completion-checklist.md` defines what this package owns and
+  what product repos must still implement.
+- `docs/catalog-registry.md` explains support tiers.
+- `docs/provider-decision-matrix.md` explains when to use first-party adapters,
+  gateway providers, or catalog-only metadata.

package/examples/calendar-exercise-app.ts

@@ -0,0 +1,78 @@
+import {
+  CANONICAL_INTEGRATION_ACTIONS,
+  buildIntegrationBridgeEnvironment,
+  calendarExercisePlannerManifest,
+  createTangleIntegrationsClient,
+  renderConsentSummary,
+  type IntegrationSandboxBundle,
+} from '../src/index.js'
+
+const manifest = calendarExercisePlannerManifest()
+const consent = renderConsentSummary(manifest, { appName: 'Exercise Planner' })
+
+console.log(consent.body)
+
+// In production this bundle comes from id.tangle.tools after the user grants
+// the generated app access to their Google Calendar connection.
+const bundle: IntegrationSandboxBundle = {
+  manifestId: manifest.id,
+  subject: { type: 'sandbox', id: 'sandbox_preview_1' },
+  connectors: [],
+  expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+  capabilities: [{
+    requirementId: 'calendar-read',
+    connectorId: 'google-calendar',
+    connectionId: 'conn_google_calendar',
+    grantId: 'grant_calendar_read',
+    scopes: ['https://www.googleapis.com/auth/calendar.readonly'],
+    allowedActions: [CANONICAL_INTEGRATION_ACTIONS.googleCalendarEventsList],
+    allowedTriggers: [],
+    capability: {
+      capability: {
+        id: 'cap_calendar_read',
+        subject: { type: 'sandbox', id: 'sandbox_preview_1' },
+        connectionId: 'conn_google_calendar',
+        scopes: ['https://www.googleapis.com/auth/calendar.readonly'],
+        allowedActions: [CANONICAL_INTEGRATION_ACTIONS.googleCalendarEventsList],
+        issuedAt: new Date().toISOString(),
+        expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+      },
+      token: 'short-lived-capability-token',
+    },
+  }],
+  tools: [{
+    name: 'google_calendar_events_list',
+    title: 'Google Calendar: List calendar events',
+    description: 'Read events from a Google Calendar over a bounded time range.',
+    providerId: 'tangle-platform',
+    connectorId: 'google-calendar',
+    connectorTitle: 'Google Calendar',
+    category: 'calendar',
+    action: {
+      id: CANONICAL_INTEGRATION_ACTIONS.googleCalendarEventsList,
+      title: 'List calendar events',
+      risk: 'read',
+      requiredScopes: ['https://www.googleapis.com/auth/calendar.readonly'],
+      dataClass: 'private',
+    },
+    risk: 'read',
+    dataClass: 'private',
+    requiredScopes: ['https://www.googleapis.com/auth/calendar.readonly'],
+    tags: ['google', 'calendar', 'events', 'list'],
+  }],
+}
+
+const env = buildIntegrationBridgeEnvironment(bundle)
+const client = createTangleIntegrationsClient({
+  endpoint: 'https://id.tangle.tools',
+  env,
+})
+
+await client.invoke({
+  tool: CANONICAL_INTEGRATION_ACTIONS.googleCalendarEventsList,
+  input: {
+    calendarId: 'primary',
+    timeMin: new Date().toISOString(),
+    timeMax: new Date(Date.now() + 7 * 24 * 60 * 60_000).toISOString(),
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {