@tangle-network/agent-integrations 0.15.0 → 0.16.0

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.15.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": {