@tangle-network/agent-integrations 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +40 -31
  2. package/data/bundled-adapter-manifests.json +1 -1
  3. package/dist/{adapters-SSISY8Yg.js → adapters-DBNiLfQN.js} +133 -113
  4. package/dist/{adapters-SSISY8Yg.js.map → adapters-DBNiLfQN.js.map} +1 -1
  5. package/dist/{billing-access-policy-CtvuHvM8.d.ts → billing-access-policy-Ce3WWxG5.d.ts} +2 -3
  6. package/dist/billing-access-policy-Ce3WWxG5.d.ts.map +1 -0
  7. package/dist/billing-access-policy-DJ63AxZ5.js.map +1 -1
  8. package/dist/{bundled-manifest-data-y4NLBbZM.js → bundled-manifest-data-4LjLh6q9.js} +57 -1
  9. package/dist/{bundled-manifest-data-y4NLBbZM.js.map → bundled-manifest-data-4LjLh6q9.js.map} +1 -1
  10. package/dist/{bundled-manifest-runtime-EpjLQKA9.d.ts → bundled-manifest-runtime-nc86Eowo.d.ts} +2 -2
  11. package/dist/{bundled-manifest-runtime-EpjLQKA9.d.ts.map → bundled-manifest-runtime-nc86Eowo.d.ts.map} +1 -1
  12. package/dist/{catalog-CFvKzwVj.js → catalog-DEbD4Cn3.js} +6 -10
  13. package/dist/catalog-DEbD4Cn3.js.map +1 -0
  14. package/dist/{catalog-z4zNeXVL.d.ts → catalog-VQlC1Ew0.d.ts} +8 -12
  15. package/dist/{catalog-z4zNeXVL.d.ts.map → catalog-VQlC1Ew0.d.ts.map} +1 -1
  16. package/dist/catalog.d.ts +1 -1
  17. package/dist/catalog.js +1 -1
  18. package/dist/connect/index.d.ts +1 -1
  19. package/dist/connectors/adapters/index.d.ts +3 -2
  20. package/dist/connectors/adapters/index.js +1 -1
  21. package/dist/connectors/index.d.ts +7 -7
  22. package/dist/connectors/index.js +2 -2
  23. package/dist/connectors/oauth.d.ts +1 -1
  24. package/dist/{consumer-PHOoRorX.d.ts → consumer-BMWxApGG.d.ts} +10 -122
  25. package/dist/consumer-BMWxApGG.d.ts.map +1 -0
  26. package/dist/consumer.d.ts +1 -1
  27. package/dist/{types-Bq85dJDW.d.ts → core-types-ZuEjjJAr.d.ts} +546 -14
  28. package/dist/core-types-ZuEjjJAr.d.ts.map +1 -0
  29. package/dist/{coverage-catalog-5LheuThC.d.ts → coverage-catalog-CsJmShn5.d.ts} +3 -4
  30. package/dist/{coverage-catalog-5LheuThC.d.ts.map → coverage-catalog-CsJmShn5.d.ts.map} +1 -1
  31. package/dist/coverage-catalog.d.ts +2 -2
  32. package/dist/coverage-catalog.js +1 -22
  33. package/dist/coverage-catalog.js.map +1 -1
  34. package/dist/{errors-8ePwEZRM.d.ts → errors-CvjrGB5r.d.ts} +4 -1
  35. package/dist/errors-CvjrGB5r.d.ts.map +1 -0
  36. package/dist/{errors-CvO_y8JO.js → errors-DSdeYms8.js} +16 -3
  37. package/dist/errors-DSdeYms8.js.map +1 -0
  38. package/dist/{hub-DkiKVWJX.d.ts → hub-CRteFmOR.d.ts} +3 -3
  39. package/dist/{hub-DkiKVWJX.d.ts.map → hub-CRteFmOR.d.ts.map} +1 -1
  40. package/dist/{hub-Du6wsA1o.js → hub-DnPkr4xn.js} +2 -1
  41. package/dist/hub-DnPkr4xn.js.map +1 -0
  42. package/dist/hub.d.ts +1 -1
  43. package/dist/hub.js +1 -1
  44. package/dist/{index-BFK-G6g1.d.ts → index-BAI3O7bc.d.ts} +2 -2
  45. package/dist/{index-BFK-G6g1.d.ts.map → index-BAI3O7bc.d.ts.map} +1 -1
  46. package/dist/{index-poLalSQ6.d.ts → index-BbluAb0U.d.ts} +3 -12
  47. package/dist/index-BbluAb0U.d.ts.map +1 -0
  48. package/dist/{index-HBXVPkSs.d.ts → index-C5W0VfzQ.d.ts} +19 -194
  49. package/dist/index-C5W0VfzQ.d.ts.map +1 -0
  50. package/dist/{index-CkCYzn8f.d.ts → index-CezgaMuD.d.ts} +3 -3
  51. package/dist/{index-CkCYzn8f.d.ts.map → index-CezgaMuD.d.ts.map} +1 -1
  52. package/dist/{index-DoJFdW9K.d.ts → index-Dev4r3_u.d.ts} +3 -3
  53. package/dist/{index-DoJFdW9K.d.ts.map → index-Dev4r3_u.d.ts.map} +1 -1
  54. package/dist/index.d.ts +19 -20
  55. package/dist/index.js +11 -11
  56. package/dist/internal/bundled-manifest-runtime.d.ts +1 -1
  57. package/dist/internal/bundled-manifest-runtime.js +1 -1
  58. package/dist/mcp.d.ts +2 -2
  59. package/dist/mcp.js +2 -2
  60. package/dist/middleware/index.d.ts +1 -1
  61. package/dist/{oauth-DoUCpYU_.d.ts → oauth-Br5r5Ms0.d.ts} +2 -2
  62. package/dist/{oauth-DoUCpYU_.d.ts.map → oauth-Br5r5Ms0.d.ts.map} +1 -1
  63. package/dist/{policy-C8jynxf9.d.ts → policy-BH4ZAZ4s.d.ts} +3 -14
  64. package/dist/policy-BH4ZAZ4s.d.ts.map +1 -0
  65. package/dist/{policy-UOPcZqdE.js → policy-C0XpcajG.js} +5 -30
  66. package/dist/policy-C0XpcajG.js.map +1 -0
  67. package/dist/{redaction-B6R-ZeWT.js → redaction-dXj4op-I.js} +16 -2
  68. package/dist/redaction-dXj4op-I.js.map +1 -0
  69. package/dist/{registry-0xWMSBUu.d.ts → registry-CJFl46d3.d.ts} +3 -3
  70. package/dist/{registry-0xWMSBUu.d.ts.map → registry-CJFl46d3.d.ts.map} +1 -1
  71. package/dist/{registry-core-B1ApiG47.d.ts → registry-core-_BnkpeSe.d.ts} +2 -2
  72. package/dist/{registry-core-B1ApiG47.d.ts.map → registry-core-_BnkpeSe.d.ts.map} +1 -1
  73. package/dist/registry.d.ts +2 -2
  74. package/dist/registry.js +1 -1
  75. package/dist/runtime.d.ts +1 -1
  76. package/dist/runtime.js +1 -1
  77. package/dist/sandbox.d.ts +2 -2
  78. package/dist/sandbox.js +5 -20
  79. package/dist/sandbox.js.map +1 -1
  80. package/dist/{specs-B7c5wARo.js → specs-Cy0EZELv.js} +4 -23
  81. package/dist/specs-Cy0EZELv.js.map +1 -0
  82. package/dist/specs.d.ts +2 -2
  83. package/dist/specs.js +2 -2
  84. package/dist/{src-ZNpLV5ka.js → src-BPV-clp-.js} +8 -186
  85. package/dist/src-BPV-clp-.js.map +1 -0
  86. package/dist/stripe/index.d.ts +3 -79
  87. package/dist/stripe/index.d.ts.map +1 -1
  88. package/dist/stripe/index.js +5 -52
  89. package/dist/stripe/index.js.map +1 -1
  90. package/dist/{tangle-id-BW5dTiGi.d.ts → tangle-id-BnzGOA_W.d.ts} +2 -2
  91. package/dist/{tangle-id-BW5dTiGi.d.ts.map → tangle-id-BnzGOA_W.d.ts.map} +1 -1
  92. package/dist/triggers/index.d.ts +20 -1
  93. package/dist/triggers/index.d.ts.map +1 -1
  94. package/dist/triggers/index.js +183 -14
  95. package/dist/triggers/index.js.map +1 -1
  96. package/dist/types-CjrugGcd.js.map +1 -1
  97. package/dist/worker.d.ts +3 -3
  98. package/dist/worker.js +2 -2
  99. package/docs/external-product-integration.md +14 -5
  100. package/docs/integration-coverage-checklist.md +1 -12
  101. package/docs/private-audio-transcription.md +1 -1
  102. package/package.json +2 -1
  103. package/dist/billing-access-policy-CtvuHvM8.d.ts.map +0 -1
  104. package/dist/catalog-CFvKzwVj.js.map +0 -1
  105. package/dist/consumer-PHOoRorX.d.ts.map +0 -1
  106. package/dist/core-types-0BenSoZJ.d.ts +0 -365
  107. package/dist/core-types-0BenSoZJ.d.ts.map +0 -1
  108. package/dist/errors-8ePwEZRM.d.ts.map +0 -1
  109. package/dist/errors-CvO_y8JO.js.map +0 -1
  110. package/dist/hub-Du6wsA1o.js.map +0 -1
  111. package/dist/index-HBXVPkSs.d.ts.map +0 -1
  112. package/dist/index-poLalSQ6.d.ts.map +0 -1
  113. package/dist/policy-C8jynxf9.d.ts.map +0 -1
  114. package/dist/policy-UOPcZqdE.js.map +0 -1
  115. package/dist/redaction-B6R-ZeWT.js.map +0 -1
  116. package/dist/specs-B7c5wARo.js.map +0 -1
  117. package/dist/src-ZNpLV5ka.js.map +0 -1
  118. package/dist/types-Bq85dJDW.d.ts.map +0 -1
  119. package/docs/generated-integration-coverage-checklist.md +0 -156
package/README.md CHANGED
@@ -33,35 +33,23 @@ provider SDK.
33
33
 
34
34
  ## What It Provides
35
35
 
36
- - A normalized connector/action/trigger catalog.
37
- - Tangle integration contracts for every catalog connector.
38
- - User-owned connection records that reference secrets without storing raw
36
+ - A normalized connector/action/trigger catalog with Tangle contracts for
37
+ every connector, and generated `IntegrationSpec`s for setup docs,
38
+ permissions, healthchecks, and tool descriptions.
39
+ - User-owned connection records referencing secrets in vaults, never raw
39
40
  credentials in public shapes.
40
- - Short-lived capability tokens for sandbox-safe access to a subset of a user's
41
- connection.
42
- - Policy checks for read/write/destructive actions.
43
- - Invocation-envelope validation before sandbox tool calls reach the hub.
44
- - A generic HTTP provider boundary for hosted integration gateways.
45
- - A gateway catalog provider for hosted integration gateways, executor-style
46
- runtimes, and internal connector registries.
47
- - A first-party `ConnectorAdapter` boundary for direct provider execution.
48
- - A declarative REST adapter factory for promoting REST APIs from reviewed specs.
49
- - A broad catalog for discovering hundreds of integrations while keeping
50
- executable backend state explicit.
41
+ - Short-lived, scoped capability tokens for sandbox-safe access to a subset of
42
+ a user's connection, with policy checks and invocation-envelope validation.
43
+ - First-party `ConnectorAdapter` and declarative REST factories for direct
44
+ execution; gateway providers for hosted gateways, executor-style runtimes,
45
+ and internal registries.
51
46
  - A canonical registry that deduplicates overlapping catalogs, keeps support
52
- tiers explicit, and reports auth/category conflicts.
47
+ tiers explicit, and keeps executable backend state distinct from discovery.
53
48
  - App/agent manifests, grants, and sandbox bundles so generated apps, domain
54
- agents, and executor-backed runtimes can reuse the same user-owned
55
- connections safely.
56
- - Workflow trigger installation and normalized event dispatch for non-agent UI
57
- automation, sync jobs, webhooks, and product workflows.
58
- - Approval persistence, audit events, healthchecks, credential resolution,
59
- webhook ingestion, idempotency guards, and sandbox/CLI bridge payloads.
60
- - Generated-app client helpers, manifest inference/validation, consent copy,
61
- platform policy presets, canonical launch action schemas, and controlled
62
- provider-native passthrough validation.
63
- - A generated `IntegrationSpec` registry used for setup docs, admin UI steps,
64
- normalized permissions, healthcheck plans, and tool descriptions.
49
+ agents, and runtimes reuse user-owned connections safely.
50
+ - Workflow trigger installation, normalized event dispatch, approvals, audit
51
+ events, healthchecks, idempotency guards, webhook ingestion, consent copy,
52
+ and sandbox/CLI bridge payloads.
65
53
 
66
54
  ## Architecture
67
55
 
@@ -178,8 +166,8 @@ configured factories plus catalog-only declarations that cannot execute.
178
166
  | `IntegrationGrant` | Persistent grant from a user-owned connection to an app, agent, or sandbox consumer. |
179
167
  | `createIntegrationRuntime` | Facade for manifest resolution, grant creation, and sandbox capability bundles. |
180
168
  | `createIntegrationWorkflowRuntime` | Installs trigger workflows and dispatches normalized provider events. |
181
- | `createApprovalBackedPolicyEngine` | Persists approval requests and allows approved invocations to resume. |
182
- | `createDefaultIntegrationActionGuard` | Adds idempotency replay, dry-run mutation handling, rate-limit hooks, and audit events. |
169
+ | `ApprovalBackedPolicyEngine` | Persists approval requests and allows approved invocations to resume. |
170
+ | `DefaultIntegrationActionGuard` | Adds idempotency replay, dry-run mutation handling, rate-limit hooks, and audit events. |
183
171
  | `createConnectionCredentialResolver` | Resolves secret refs into in-memory connector credentials and refreshes expired OAuth credentials. |
184
172
  | `runIntegrationHealthchecks` | Checks connection status, registry executability, scope shape, and optional live provider tests. |
185
173
  | `receiveIntegrationWebhook` | Verifies inbound webhooks, dedupes provider events, and dispatches normalized trigger events. |
@@ -189,7 +177,7 @@ configured factories plus catalog-only declarations that cannot execute.
189
177
  | `handleDelegatedToolCall` / `handleDelegatedToolRequest` | Transport-agnostic JSON-RPC 2.0 callback handler with fail-closed gates (token fresh, tool allow-listed, integration connected) via product-supplied seams. |
190
178
  | `createTangleIntegrationsClient` | Tiny generated-app/sandbox client for platform `/v1/integrations/invoke`. |
191
179
  | `inferIntegrationManifestFromTools` / `validateIntegrationManifest` | Deterministic manifest helpers for Builder and platform APIs. |
192
- | `renderConsentSummary` / `renderApprovalCopy` | User-facing consent and approval copy from manifests/actions. |
180
+ | `renderConsentSummary` | User-facing consent copy from manifests/actions. |
193
181
  | `createPlatformIntegrationPolicyPreset` | Secure defaults: reads allowed after grant, writes need approval, destructive denied, passthrough disabled. |
194
182
  | `buildCanonicalLaunchConnectors` | Product-ready launch action schemas for Calendar, Gmail, Drive, GitHub, and Slack. |
195
183
  | `validateProviderPassthroughRequest` | Policy-gated provider-native HTTP escape hatch validation. |
@@ -211,7 +199,7 @@ configured factories plus catalog-only declarations that cannot execute.
211
199
  | `declarativeRestConnector` | Builds REST-backed first-party adapters from compact specs. |
212
200
  | `listIntegrationSpecs` | Generates setup/execution specs from the coverage catalog and family defaults. |
213
201
  | `renderRunbookMarkdown` / `renderConsoleSteps` | Render operator docs or admin UI steps from the same spec source. |
214
- | `validateCredentialSet` / `buildHealthcheckPlan` | Validate setup input and describe the correct healthcheck path. |
202
+ | `validateCredentialFormat` / `buildHealthcheckPlan` | Validate setup input and describe the correct healthcheck path. |
215
203
 
216
204
  ## Worker-safe Imports
217
205
 
@@ -384,6 +372,19 @@ See [Integration Execution Audit](./docs/integration-execution-audit.md) for
384
372
  the exact current split between catalog, setup, first-party execution, and
385
373
  package-runtime execution.
386
374
 
375
+ ### Readiness States
376
+
377
+ Copy names a connector's state instead of implying execution: **catalogued**
378
+ (discovery only), **configured** (product registered an adapter or gateway
379
+ backend), **connected** (user completed setup and owns a connection record),
380
+ **authorized** (a grant scopes actions to an app or agent), **executed** (a
381
+ provider call ran and returned a result). Catalog breadth is not a promise
382
+ that every action works for every customer: say "Available in the catalog;
383
+ account setup required" rather than a generic "Connected", and surface the
384
+ provider's own result — limits, failures, and revocation intact — for executed
385
+ writes. Tool descriptors carry `supportTier` and `runnable` so discovery
386
+ tools stay distinguishable from runtime tools.
387
+
387
388
  ## Executable Coverage
388
389
 
389
390
  Current first-party adapters:
@@ -469,7 +470,7 @@ The test suite packs the npm artifact and bundles `/worker`, `/specs`, and
469
470
 
470
471
  Feature PRs must leave the package version and `CHANGELOG.md` unchanged.
471
472
  After features merge, run the **Prepare Release** workflow and choose a patch, minor, or major bump.
472
- The workflow uses Node and Git to open a `release/v<version>` PR from current `main`.
473
+ The workflow reads the stable npm predecessor and uses Node and Git to open a `release/v<version>` PR from current `main`. An unpublished tag does not become the changelog baseline. Compatible releases after 1.0 use a patch; the shared archive admission check decides whether a change requires a major.
473
474
  It does not install dependencies or publish a package.
474
475
 
475
476
  Review that the release branch version matches the next package version.
@@ -485,3 +486,11 @@ Confirm that the published archive installs and its intended consumer flow works
485
486
  ## License
486
487
 
487
488
  MIT
489
+
490
+ ### Drive change-feed triggers
491
+
492
+ `google-drive.file.changed` reads metadata and removals through `get_start_page_token` and `list_changes`, using the existing `drive.readonly` grant. It does not request document contents or create watch channels. Its first poll obtains the current change-feed position; later polls consume one bounded page in provider order, independent of timestamp ties.
493
+
494
+ Hosts keep `HostedTriggerCursor.state` opaque. Pass a durable `checkpoint(cursor)` callback to `pollHostedTrigger`: the Drive provider freezes each pending page there before returning events. Admit every event with its stable `id`, then persist the returned cursor only after all admissions succeed. On interruption, retry the checkpoint cursor; it replays identical events without rereading mutable metadata. A missing checkpoint sink, invalid cursor, incomplete continuation or malformed page fails without resetting the feed. Existing timestamp-based definitions and callers keep their prior behavior. See Google's [change-feed contract](https://developers.google.com/workspace/drive/api/guides/manage-changes).
495
+
496
+ Timestamp providers retain all admitted IDs at the active timestamp boundary and discard them only when the boundary advances. The retained-key bound lives in `MAX_BOUNDARY_KEYS` in the trigger runner; overflow fails explicitly with the prior cursor intact. These definitions remain limited by each provider's existing listing/history contract; they do not provide Drive's token-based feed guarantees.