@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.693.d8859c2.0

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 (261) hide show
  1. package/CLAUDE.md +0 -28
  2. package/README.md +0 -105
  3. package/application/commands/integration-commands.js +10 -20
  4. package/application/commands/scheduler-commands.js +7 -11
  5. package/application/commands/user-commands.js +5 -17
  6. package/application/index.js +2 -6
  7. package/core/Worker.js +7 -31
  8. package/core/create-handler.js +0 -9
  9. package/credential/repositories/credential-repository-documentdb.js +0 -34
  10. package/credential/repositories/credential-repository-interface.js +0 -15
  11. package/credential/repositories/credential-repository-mongo.js +0 -23
  12. package/credential/repositories/credential-repository-postgres.js +0 -28
  13. package/database/config.js +24 -48
  14. package/database/documentdb-utils.js +0 -2
  15. package/database/encryption/encryption-schema-registry.js +12 -93
  16. package/database/prisma.js +2 -4
  17. package/errors/index.js +4 -0
  18. package/errors/mapping-already-exists-error.js +14 -0
  19. package/generated/prisma-mongodb/edge.js +38 -33
  20. package/generated/prisma-mongodb/index-browser.js +35 -30
  21. package/generated/prisma-mongodb/index.d.ts +1880 -3191
  22. package/generated/prisma-mongodb/index.js +38 -33
  23. package/generated/prisma-mongodb/package.json +1 -1
  24. package/generated/prisma-mongodb/schema.prisma +50 -86
  25. package/generated/prisma-mongodb/wasm.js +38 -33
  26. package/generated/prisma-postgresql/edge.js +38 -33
  27. package/generated/prisma-postgresql/index-browser.js +35 -30
  28. package/generated/prisma-postgresql/index.d.ts +2050 -3390
  29. package/generated/prisma-postgresql/index.js +38 -33
  30. package/generated/prisma-postgresql/package.json +1 -1
  31. package/generated/prisma-postgresql/schema.prisma +48 -81
  32. package/generated/prisma-postgresql/wasm.js +38 -33
  33. package/handlers/WEBHOOKS.md +29 -0
  34. package/handlers/app-definition-loader.js +19 -128
  35. package/handlers/app-handler-helpers.js +3 -25
  36. package/handlers/backend-utils.js +25 -31
  37. package/handlers/middleware/admin-auth.js +1 -14
  38. package/handlers/routers/auth.js +10 -46
  39. package/handlers/routers/health.js +4 -13
  40. package/handlers/routers/integration-defined-routers.js +92 -144
  41. package/handlers/routers/integration-webhook-routers.js +64 -102
  42. package/handlers/workers/integration-defined-workers.js +2 -5
  43. package/index.js +3 -65
  44. package/infrastructure/scheduler/index.js +6 -19
  45. package/infrastructure/scheduler/scheduler-service-factory.js +7 -55
  46. package/integrations/data-defined/README.md +169 -0
  47. package/integrations/data-defined/canonical.js +11 -0
  48. package/integrations/data-defined/capabilities/acmeerp.capabilities.json +608 -0
  49. package/integrations/data-defined/capabilities/asana.capabilities.json +265 -0
  50. package/integrations/data-defined/capabilities/calendly.capabilities.json +385 -0
  51. package/integrations/data-defined/capabilities/docusign.capabilities.json +314 -0
  52. package/integrations/data-defined/capabilities/fathom.capabilities.json +228 -0
  53. package/integrations/data-defined/capabilities/github.capabilities.json +563 -0
  54. package/integrations/data-defined/capabilities/hubspot.capabilities.json +715 -0
  55. package/integrations/data-defined/capabilities/jira.capabilities.json +376 -0
  56. package/integrations/data-defined/capabilities/klaviyo.capabilities.json +475 -0
  57. package/integrations/data-defined/capabilities/linear.capabilities.json +324 -0
  58. package/integrations/data-defined/capabilities/netsuite.capabilities.json +491 -0
  59. package/integrations/data-defined/capabilities/notion.capabilities.json +208 -0
  60. package/integrations/data-defined/capabilities/phone.capabilities.json +470 -0
  61. package/integrations/data-defined/capabilities/pipedrive.capabilities.json +388 -0
  62. package/integrations/data-defined/capabilities/quickbooks.capabilities.json +615 -0
  63. package/integrations/data-defined/capabilities/salesforce.capabilities.json +507 -0
  64. package/integrations/data-defined/capabilities/shopify.capabilities.json +1082 -0
  65. package/integrations/data-defined/capabilities/slack.capabilities.json +363 -0
  66. package/integrations/data-defined/capabilities/stripe.capabilities.json +580 -0
  67. package/integrations/data-defined/capabilities/webflow.capabilities.json +196 -0
  68. package/integrations/data-defined/capabilities/zendesk.capabilities.json +409 -0
  69. package/integrations/data-defined/compile.js +77 -0
  70. package/integrations/data-defined/config-form.js +110 -0
  71. package/integrations/data-defined/data-defined-integration.js +366 -0
  72. package/integrations/data-defined/examples/acme-erp-quickbooks.definition.json +467 -0
  73. package/integrations/data-defined/examples/asana-slack.definition.json +220 -0
  74. package/integrations/data-defined/examples/calendly-salesforce.definition.json +459 -0
  75. package/integrations/data-defined/examples/docusign-salesforce.definition.json +305 -0
  76. package/integrations/data-defined/examples/fathom-hubspot-notion.definition.json +575 -0
  77. package/integrations/data-defined/examples/github-linear.definition.json +316 -0
  78. package/integrations/data-defined/examples/hubspot-slack.definition.json +409 -0
  79. package/integrations/data-defined/examples/klaviyo-hubspot.definition.json +339 -0
  80. package/integrations/data-defined/examples/phone-hubspot.definition.json +637 -0
  81. package/integrations/data-defined/examples/pipedrive-hubspot.definition.json +136 -0
  82. package/integrations/data-defined/examples/pipedrive-phone.definition.json +340 -0
  83. package/integrations/data-defined/examples/records/phone-hubspot.definition-version.json +652 -0
  84. package/integrations/data-defined/examples/records/phone-hubspot.integration.json +86 -0
  85. package/integrations/data-defined/examples/records/phone-hubspot.mappings.json +39 -0
  86. package/integrations/data-defined/examples/records/phone-hubspot.workflow-run.json +62 -0
  87. package/integrations/data-defined/examples/shopify-klaviyo.definition.json +488 -0
  88. package/integrations/data-defined/examples/shopify-netsuite.definition.json +622 -0
  89. package/integrations/data-defined/examples/stripe-quickbooks.definition.json +476 -0
  90. package/integrations/data-defined/examples/webflow-hubspot-slack.definition.json +262 -0
  91. package/integrations/data-defined/examples/zendesk-jira.definition.json +604 -0
  92. package/integrations/data-defined/expressions.js +225 -0
  93. package/integrations/data-defined/index.js +39 -0
  94. package/integrations/data-defined/interpreter.js +89 -0
  95. package/integrations/data-defined/manifests.js +125 -0
  96. package/integrations/data-defined/repositories/definition-version-repository.js +67 -0
  97. package/integrations/data-defined/repositories/workflow-run-repository.js +59 -0
  98. package/integrations/data-defined/router.js +97 -0
  99. package/integrations/data-defined/runtime.js +208 -0
  100. package/integrations/data-defined/schema/capability-manifest.v0.1.schema.json +377 -0
  101. package/integrations/data-defined/schema/installation.v0.1.schema.json +83 -0
  102. package/integrations/data-defined/schema/integration-definition.v0.1.schema.json +848 -0
  103. package/integrations/data-defined/schema/records.md +98 -0
  104. package/integrations/data-defined/schema-check.js +58 -0
  105. package/integrations/data-defined/scripts/validate.js +66 -0
  106. package/integrations/data-defined/steps.js +89 -0
  107. package/integrations/data-defined/transforms.js +91 -0
  108. package/integrations/data-defined/use-cases/definition-use-cases.js +187 -0
  109. package/integrations/data-defined/validate.js +370 -0
  110. package/integrations/data-defined/versioning.js +161 -0
  111. package/integrations/data-defined/webhooks.js +119 -0
  112. package/integrations/index.js +0 -1
  113. package/integrations/integration-base.js +29 -0
  114. package/integrations/integration-router.js +101 -131
  115. package/integrations/repositories/integration-mapping-repository-documentdb.js +50 -0
  116. package/integrations/repositories/integration-mapping-repository-interface.js +15 -0
  117. package/integrations/repositories/integration-mapping-repository-mongo.js +29 -0
  118. package/integrations/repositories/integration-mapping-repository-postgres.js +30 -0
  119. package/integrations/repositories/integration-mapping-repository.js +29 -0
  120. package/integrations/repositories/integration-repository-documentdb.js +3 -35
  121. package/integrations/repositories/integration-repository-interface.js +1 -17
  122. package/integrations/repositories/integration-repository-mongo.js +77 -60
  123. package/integrations/repositories/integration-repository-postgres.js +76 -62
  124. package/integrations/repositories/process-repository-mongo.js +1 -1
  125. package/integrations/tests/doubles/test-integration-repository.js +1 -12
  126. package/integrations/use-cases/create-integration.js +20 -55
  127. package/integrations/use-cases/get-integrations-for-user.js +40 -80
  128. package/integrations/use-cases/index.js +1 -7
  129. package/integrations/utils/map-integration-dto.js +14 -43
  130. package/modules/index.js +0 -14
  131. package/modules/module-factory.js +0 -12
  132. package/modules/module.js +2 -53
  133. package/modules/repositories/module-repository-documentdb.js +6 -51
  134. package/modules/repositories/module-repository-interface.js +2 -19
  135. package/modules/repositories/module-repository-mongo.js +74 -67
  136. package/modules/repositories/module-repository-postgres.js +74 -66
  137. package/modules/repositories/module-repository.js +1 -2
  138. package/modules/requester/requester.js +5 -35
  139. package/modules/use-cases/get-entities-for-user.js +13 -26
  140. package/modules/use-cases/get-entity-options-by-id.js +4 -10
  141. package/modules/use-cases/get-entity-options-by-type.js +1 -1
  142. package/modules/use-cases/get-module-instance-from-type.js +1 -1
  143. package/modules/use-cases/get-module.js +4 -10
  144. package/modules/use-cases/process-authorization-callback.js +19 -53
  145. package/modules/use-cases/refresh-entity-options.js +4 -10
  146. package/modules/use-cases/test-module-auth.js +4 -10
  147. package/package.json +6 -6
  148. package/prisma-mongodb/schema.prisma +50 -86
  149. package/prisma-postgresql/migrations/20261018000000_add_data_defined_integrations/migration.sql +66 -0
  150. package/prisma-postgresql/schema.prisma +48 -81
  151. package/queues/index.js +0 -25
  152. package/types/index.d.ts +0 -2
  153. package/user/repositories/user-repository-documentdb.js +2 -27
  154. package/user/repositories/user-repository-interface.js +0 -18
  155. package/user/repositories/user-repository-mongo.js +0 -24
  156. package/user/repositories/user-repository-postgres.js +0 -18
  157. package/user/use-cases/authenticate-user.js +1 -7
  158. package/user/use-cases/get-user-from-adopter-jwt.js +124 -95
  159. package/user/use-cases/get-user-from-x-frigg-headers.js +80 -83
  160. package/user/user.js +1 -64
  161. package/credential/use-cases/credential-operations-for-user.js +0 -202
  162. package/credential/use-cases/reauthorize-credential-for-user.js +0 -73
  163. package/database/organization-where.js +0 -18
  164. package/database/unique-violation.js +0 -25
  165. package/extensions/bootstrap-runner.js +0 -43
  166. package/extensions/extension-loader.js +0 -187
  167. package/extensions/index.js +0 -41
  168. package/extensions/initialize-app.js +0 -123
  169. package/extensions/route-mounter.js +0 -103
  170. package/extensions/schema-composer.js +0 -188
  171. package/infrastructure/scheduler/netlify-scheduler-adapter.js +0 -216
  172. package/infrastructure/scheduler/scheduled-job-repository.js +0 -118
  173. package/integrations/repositories/integration-not-found.js +0 -14
  174. package/integrations/schedule-config.js +0 -80
  175. package/integrations/use-cases/dispatch-ongoing-syncs.js +0 -100
  176. package/integrations/use-cases/integration-operations-for-user.js +0 -256
  177. package/integrations/use-cases/resolve-integration-ownership.js +0 -177
  178. package/management-api/create-management-api-router.js +0 -49
  179. package/management-api/error-response.js +0 -116
  180. package/management-api/management-api-config.js +0 -151
  181. package/management-api/meta-router.js +0 -76
  182. package/management-api/openapi/build-openapi.js +0 -144
  183. package/management-api/openapi/components.js +0 -415
  184. package/management-api/openapi/v1-operations.js +0 -83
  185. package/management-api/openapi/v2-operations.js +0 -264
  186. package/management-api/route-registry.js +0 -411
  187. package/management-api/test-support/http-client.js +0 -39
  188. package/management-api/use-cases/get-management-api-meta.js +0 -57
  189. package/management-api/v1-deprecation.js +0 -120
  190. package/management-api/v2/create-v2-router.js +0 -85
  191. package/management-api/v2/dependencies.js +0 -281
  192. package/management-api/v2/dto.js +0 -143
  193. package/management-api/v2/handlers/authorization.js +0 -94
  194. package/management-api/v2/handlers/credentials.js +0 -33
  195. package/management-api/v2/handlers/entities.js +0 -77
  196. package/management-api/v2/handlers/integrations.js +0 -128
  197. package/management-api/v2/handlers/proxy.js +0 -34
  198. package/management-api/v2/request.js +0 -85
  199. package/management-api/v2/test-support/fake-dependencies.js +0 -103
  200. package/modules/domain/authorization-session.js +0 -144
  201. package/modules/entity-scope.js +0 -15
  202. package/modules/entity-type-registry.js +0 -311
  203. package/modules/proxy/proxy-bases.js +0 -169
  204. package/modules/proxy/proxy-errors.js +0 -31
  205. package/modules/proxy/proxy-path.js +0 -183
  206. package/modules/proxy/proxy-policy.js +0 -277
  207. package/modules/repositories/authorization-session-repository-documentdb.js +0 -112
  208. package/modules/repositories/authorization-session-repository-factory.js +0 -31
  209. package/modules/repositories/authorization-session-repository-interface.js +0 -47
  210. package/modules/repositories/authorization-session-repository-prisma.js +0 -87
  211. package/modules/repositories/entity-not-found.js +0 -18
  212. package/modules/requester/proxy-request.js +0 -245
  213. package/modules/scope-config.js +0 -192
  214. package/modules/scope-policy.js +0 -112
  215. package/modules/scope-resolution.js +0 -288
  216. package/modules/scope-visibility.js +0 -247
  217. package/modules/tests/doubles/in-memory-authorization-session-repository.js +0 -45
  218. package/modules/tests/doubles/ownership-matching.js +0 -18
  219. package/modules/use-cases/authorize-entity-for-user.js +0 -61
  220. package/modules/use-cases/create-entity-from-credential.js +0 -113
  221. package/modules/use-cases/entity-operations-for-user.js +0 -162
  222. package/modules/use-cases/entity-types.js +0 -139
  223. package/modules/use-cases/execute-entity-proxy-request.js +0 -331
  224. package/modules/use-cases/get-authorization-requirements.js +0 -100
  225. package/modules/use-cases/get-entity-module-for-user.js +0 -113
  226. package/modules/use-cases/manage-access.js +0 -21
  227. package/modules/use-cases/multi-step-authorization.js +0 -329
  228. package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +0 -28
  229. package/prisma-postgresql/migrations/20261015000000_add_organization_membership/migration.sql +0 -26
  230. package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql +0 -25
  231. package/prisma-postgresql/migrations/20261017000000_add_scheduled_job/migration.sql +0 -28
  232. package/providers/index.js +0 -23
  233. package/providers/resolve-provider.js +0 -93
  234. package/providers/runtime-detection.js +0 -124
  235. package/queues/providers/index.js +0 -11
  236. package/queues/providers/netlify-background-provider.js +0 -150
  237. package/queues/providers/qstash-queue-provider.js +0 -219
  238. package/queues/providers/sqs-queue-provider.js +0 -70
  239. package/queues/queue-client-interface.js +0 -55
  240. package/queues/queue-message-auth.js +0 -193
  241. package/queues/queue-provider-factory.js +0 -101
  242. package/queues/queue-provider.js +0 -65
  243. package/queues/sqs-queue-client.js +0 -81
  244. package/types/modules/index.d.ts +0 -214
  245. package/types/user/index.d.ts +0 -134
  246. package/user/adopter-jwt-config.js +0 -177
  247. package/user/adopter-jwt-errors.js +0 -59
  248. package/user/adopter-token-verifier.js +0 -122
  249. package/user/app-user-helpers.js +0 -97
  250. package/user/create-user-authentication.js +0 -64
  251. package/user/membership.js +0 -51
  252. package/user/repositories/organization-membership-record.js +0 -19
  253. package/user/repositories/organization-membership-repository-documentdb.js +0 -106
  254. package/user/repositories/organization-membership-repository-factory.js +0 -42
  255. package/user/repositories/organization-membership-repository-interface.js +0 -57
  256. package/user/repositories/organization-membership-repository-mongo.js +0 -13
  257. package/user/repositories/organization-membership-repository-postgres.js +0 -29
  258. package/user/repositories/organization-membership-repository-prisma.js +0 -81
  259. package/user/tests/doubles/adopter-jwt-fixtures.js +0 -220
  260. package/user/use-cases/ensure-organization-membership.js +0 -92
  261. package/user/use-cases/find-individual-users-by-organization.js +0 -54
@@ -7,22 +7,16 @@
7
7
  * Environment Detection:
8
8
  * - SCHEDULER_PROVIDER=eventbridge -> Use AWS EventBridge Scheduler
9
9
  * - SCHEDULER_PROVIDER=mock -> Use in-memory mock scheduler
10
- * - SCHEDULER_PROVIDER=netlify -> Netlify poll-and-dispatch scheduler
11
- * (friggframework/frigg#545; needs `repository`, usually `queueProvider`)
12
- * - Default on Netlify (NETLIFY=true, set by the Netlify runtime and build;
13
- * provider-netlify's generated functions also set SCHEDULER_PROVIDER) -> Netlify
14
10
  * - Default in dev/test/local stages -> Mock scheduler
15
11
  * - Default in other stages -> EventBridge scheduler
16
- * - Any other name -> require('@friggframework/provider-<name>').SchedulerAdapter
17
- *
18
- * Adapters are required inside their branch so building one never loads
19
- * another's SDK (@aws-sdk/client-scheduler is not a core dependency).
20
12
  */
21
13
 
14
+ const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
15
+ const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
16
+
22
17
  const SCHEDULER_PROVIDERS = {
23
18
  EVENTBRIDGE: 'eventbridge',
24
19
  MOCK: 'mock',
25
- NETLIFY: 'netlify',
26
20
  };
27
21
 
28
22
  const LOCAL_STAGES = ['dev', 'test', 'local'];
@@ -38,12 +32,6 @@ function determineProvider() {
38
32
  return explicitProvider;
39
33
  }
40
34
 
41
- // Checked before the stage: a Netlify site with no STAGE (or STAGE=dev)
42
- // must still persist schedules where scheduled-sync reads them.
43
- if (process.env.NETLIFY === 'true') {
44
- return SCHEDULER_PROVIDERS.NETLIFY;
45
- }
46
-
47
35
  const stage = process.env.STAGE || 'dev';
48
36
  if (LOCAL_STAGES.includes(stage)) {
49
37
  return SCHEDULER_PROVIDERS.MOCK;
@@ -52,13 +40,6 @@ function determineProvider() {
52
40
  return SCHEDULER_PROVIDERS.EVENTBRIDGE;
53
41
  }
54
42
 
55
- function createDefaultScheduledJobRepository() {
56
- const { ScheduledJobRepository } = require('./scheduled-job-repository');
57
- // The prisma export is a lazy proxy: nothing connects until a query runs.
58
- const { prisma } = require('../../database/prisma');
59
- return new ScheduledJobRepository({ prismaClient: prisma });
60
- }
61
-
62
43
  /**
63
44
  * Create a scheduler service instance
64
45
  *
@@ -66,51 +47,22 @@ function createDefaultScheduledJobRepository() {
66
47
  * @param {string} options.provider - Scheduler provider ('eventbridge' or 'mock')
67
48
  * @param {string} options.region - AWS region (for EventBridge)
68
49
  * @param {boolean} options.verbose - Verbose logging (for Mock)
69
- * @param {Object} [options.repository] - Schedule repository (for Netlify: persists schedules)
70
- * @param {Object} [options.queueProvider] - Queue provider (for Netlify: dispatches due jobs)
71
50
  * @returns {SchedulerServiceInterface} Implementation of scheduler interface
72
51
  */
73
52
  function createSchedulerService(options = {}) {
74
53
  const provider = options.provider || determineProvider();
75
54
 
76
55
  switch (provider) {
77
- case SCHEDULER_PROVIDERS.EVENTBRIDGE: {
78
- const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
56
+ case SCHEDULER_PROVIDERS.EVENTBRIDGE:
79
57
  return new EventBridgeSchedulerAdapter({
80
58
  region: options.region,
81
59
  });
82
- }
83
- case SCHEDULER_PROVIDERS.MOCK: {
84
- const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
60
+ case SCHEDULER_PROVIDERS.MOCK:
85
61
  return new MockSchedulerAdapter({
86
62
  verbose: options.verbose,
87
63
  });
88
- }
89
- case SCHEDULER_PROVIDERS.NETLIFY: {
90
- const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
91
- return new NetlifySchedulerAdapter({
92
- // Default: the Prisma ScheduledJob rows that the Netlify
93
- // scheduled-sync function polls. Without it the adapter
94
- // falls back to memory, and a schedule made in one function
95
- // is never seen by the cron.
96
- repository: options.repository || createDefaultScheduledJobRepository(),
97
- queueProvider: options.queueProvider,
98
- });
99
- }
100
- default: {
101
- let plugin;
102
- try {
103
- plugin = require('../../providers/resolve-provider').resolveProvider(null, {
104
- provider,
105
- });
106
- } catch (error) {
107
- throw new Error(`Unknown scheduler provider: ${provider} (${error.message})`);
108
- }
109
- if (!plugin.SchedulerAdapter) {
110
- throw new Error(`Unknown scheduler provider: ${provider}`);
111
- }
112
- return new plugin.SchedulerAdapter(options);
113
- }
64
+ default:
65
+ throw new Error(`Unknown scheduler provider: ${provider}`);
114
66
  }
115
67
  }
116
68
 
@@ -0,0 +1,169 @@
1
+ # Data-defined integrations (v0.1)
2
+
3
+ ADR-063, implemented to the point where a definition can be validated, compiled into Frigg events, executed, rendered
4
+ and versioned. An integration becomes a **document** (what it connects, what it syncs, which workflows and UI it has)
5
+ run by **one** runtime class, instead of a hand-written class per integration.
6
+
7
+ ```
8
+ definition (JSON, immutable per version) ─┐
9
+ capability manifests (one per API module) ─┼─ validate ─ compile ─▶ this.events (same shape as hand-written)
10
+ installation (Integration.config) ─┘ │
11
+ event arrives ─▶ runWorkflow ─▶ steps ─▶ Api methods
12
+ ```
13
+
14
+ ## Layout
15
+
16
+ | Path | What |
17
+ |---|---|
18
+ | `schema/integration-definition.v0.1.schema.json` | The definition format (JSON Schema 2020-12) |
19
+ | `schema/capability-manifest.v0.1.schema.json` | What an API module declares it can do |
20
+ | `schema/installation.v0.1.schema.json` | `Integration.config` for a data-defined installation |
21
+ | `schema/records.md` | Database records: definition versions, installation, mappings, workflow runs |
22
+ | `capabilities/*.capabilities.json` | Mock manifests (HubSpot, Phone, and the apps the examples use) |
23
+ | `examples/*.definition.json` | Example definitions; `examples/records/` has Phone ↔ HubSpot database records |
24
+ | `expressions.js` | `$.ref`, `{{template \| filter}}` and conditions. No eval. |
25
+ | `steps.js`, `interpreter.js`, `transforms.js` | The step catalogue and the interpreter |
26
+ | `validate.js` | Structure + cross-references against the manifests (steps, templates, views, settings, `$.install`) |
27
+ | `manifests.js` | `validateManifest`: the manifests themselves (kinds, option lists, account fields) |
28
+ | `compile.js` | Definition + installation → events, webhook routes, schedules, user actions |
29
+ | `runtime.js` | Ports (Api calls, link store), `runWorkflow`, `runQuery`, `renderSurface`, `runLifecycle`, `resolveOptions`, `installContext` |
30
+ | `versioning.js` | `diff`, `checkBump`, `planUpgrade` |
31
+ | `data-defined-integration.js` | `defineIntegrationClass`: the IntegrationBase subclass that runs it all |
32
+ | `use-cases/definition-use-cases.js` | Publish, deprecate, catalogue, history, upgrade plan; `createDefinitionCatalog()` (the store the runtime reads) |
33
+ | `repositories/` | `IntegrationDefinitionVersion` and `WorkflowRun` rows (MongoDB, PostgreSQL, DocumentDB) |
34
+ | `router.js` | The publish, catalogue, upgrade and run-history routes |
35
+
36
+ ## The pieces of a definition
37
+
38
+ - **modules** — module keys used everywhere else (`phone`, `hubspot`), each naming a capability manifest.
39
+ - **settings** — integration-level choices (`fromNumber`); workflows can declare their own. An option setting draws
40
+ its choices from a module's option list, and may pass it inputs read from earlier choices
41
+ (`{ "source": "asana.project", "with": { "workspaceGid": "$.settings.workspace" } }`); `resolveOptions` fills the
42
+ dropdown and returns nothing until those inputs are chosen.
43
+ - **syncs** — records kept as copies on both sides: identity keys, field mapping (with transforms and master rules),
44
+ backfill and ongoing mode. A sync maintains the link + identity index every workflow uses (`links.find`).
45
+ A definition can have no workflows at all (`pipedrive-hubspot` is sync only).
46
+ - **links** — link sets: records on two modules known to be the same thing, with no sync behind them (a Calendly
47
+ invitee and the Salesforce Lead it booked as). Same storage and identity index as a sync, addressed as
48
+ `links.find { link: "people", ... }`.
49
+ - **workflows** — trigger (`webhook`, `schedule`, `userAction`, `syncRecord`) + steps. Default on or off.
50
+ - **queries** — read-only steps that return data, used by UI surfaces.
51
+ - **ui** — a surface in a host app (`hubspot` `crm.record.sidebar`): a query for data and a view tree from a fixed
52
+ component set. A generic renderer deployed once per host draws it; changing the card is a publish, not a deploy.
53
+ - **templates** — message bodies. **lifecycle** — steps run on install / uninstall (webhook subscriptions). Each
54
+ `onInstall` step with an `id` keeps its result as `$.install.runtime.installed.<id>`, which is how `onUninstall`
55
+ deletes exactly what install created.
56
+
57
+ ## How it plugs into Frigg
58
+
59
+ - **Hydration**: Frigg's use cases call `initialize()` on every hydrated integration; the class loads its pinned
60
+ definition there.
61
+ - **Webhooks**: install steps register `$.install.webhookUrls.<key>` (the URL names the module). The manifest's
62
+ `webhook` block (`webhooks.js`) splits batches and reads each event's topic, id and account; `verify` must return
63
+ true; handshakes are answered at receipt. App-level webhooks (`webhook.scope: "app"`, one URL per provider app)
64
+ are fanned out to the installations connected to each account.
65
+ - **Routes**: Frigg's existing authenticated ones. `GET/POST /api/integrations/:id/config/options[/refresh]` is the
66
+ generated configure form (dependent dropdowns on refresh); `POST /api/integrations/:id/actions/:event` runs a
67
+ button workflow (`WF_*`), a backfill, or renders a UI surface (`UI_*`, body `{ record }`).
68
+
69
+ `$.install` is the same everywhere a definition runs: integration settings, `webhookUrl`, `integrationId`,
70
+ `runtime.installed`, and `accounts.<module key>.<field>` — values about the connected account that the module's
71
+ manifest declares under `account` (`$.install.accounts.quickbooks.realmId`). Nothing undeclared is exposed.
72
+
73
+ ## Publishing, installing, upgrading
74
+
75
+ Definitions live in the `IntegrationDefinitionVersion` table (Prisma models in both schemas, PostgreSQL migration
76
+ `20261018000000_add_data_defined_integrations`), and runs in `WorkflowRun`. Point the class at the store:
77
+
78
+ ```js
79
+ const { defineSharedIntegrationClass, createDefinitionCatalog } = require('@friggframework/core/integrations/data-defined');
80
+ // A database store is read asynchronously, so it goes with the shared class (one class, every definition).
81
+ const DataDefined = defineSharedIntegrationClass({ definitions: createDefinitionCatalog(), manifests, modules });
82
+ ```
83
+
84
+ | Route | Auth | |
85
+ |---|---|---|
86
+ | `POST /admin/integrations/definitions` `{ document, notes?, publish?, strict? }` | admin key | Validate (both layers) and publish, or save a draft with `publish: false` |
87
+ | `GET /admin/integrations/definitions/:id` | admin key | Version history |
88
+ | `POST /admin/integrations/definitions/:id/versions/:v/deprecate` | admin key | Stop new installs of a version |
89
+ | `GET /api/data-defined/definitions` | user | What can be installed |
90
+ | `POST /api/integrations` with `config: { type, definition: { id } }` | user | Install; pins the latest published version and its checksum |
91
+ | `GET` / `POST /api/integrations/:id/upgrade` `{ to? }` | user | Plan / apply an upgrade (409 with the plan while something is needed) |
92
+ | `GET /api/integrations/:id/runs` | user | Run history, newest first |
93
+
94
+ Published versions cannot change. Publishing a document that is identical to a published one returns that row. A
95
+ different document at the same version is refused. So is a version that is not newer than the latest, and so is a
96
+ semver bump smaller than the changes. Publishing goes through a conditional write, so two concurrent publishes of one
97
+ version cannot both win. With `memoryDefinitions()` (definitions bundled in the app) the admin routes answer 501.
98
+
99
+ ## Steps (v0.1)
100
+
101
+ Built-ins: `links.find`, `links.upsert`, `map`, `merge`, `template`, `set`, `stop`, `foreach` (≤1000), `branch`, `code`.
102
+
103
+ - `map` rows read a `source` field or write a fixed `value` (`{ "target": "Line[0].DetailType", "value": "SalesItemLineDetail" }`).
104
+ - `merge` deep-merges objects (later wins, lists replaced).
105
+ - `foreach` takes `where` (skip items, checked before the cap) and `collect` (the step's result becomes one value per
106
+ item, which may read that iteration's steps); `do` is optional when `collect` is set. A digest is
107
+ `collect` + `{{steps.lines | join: '\n'}}`, not a string grown with `set`.
108
+ - Template filters include arithmetic as named, total functions: `plus`, `minus`, `times`, `divided_by`, `round`,
109
+ `abs`, `number`, `to_cents` / `from_cents`, `to_minor_units` / `from_minor_units` (currency-aware: JPY has no minor
110
+ unit, KWD three), `from_unix` / `to_unix`, and `join`, `size`, `first`. Bad input gives blank, never a throw. A
111
+ string that is exactly one tag keeps the value's type, so `"{{item.Amount | to_cents}}"` is the number 2000.
112
+ Everything else is `<moduleKey>.<object>.<verb>`, a capability the module's manifest declares and maps to one Api
113
+ method. There is no http, script or eval step. `code` calls a named, versioned function shipped in reviewed code
114
+ (`@scope/pkg#fn@1.2.0`) for logic that does not fit steps. Per step: `when` (skip), `onError`
115
+ (`fail` → the queue retries the run, `continue`, `stop`).
116
+
117
+ ## Versioning
118
+
119
+ Published versions are immutable and each installation pins one. `checkBump` refuses a release whose declared semver
120
+ bump is smaller than its changes (patch: steps/templates/view/mapping; minor: additive, including a new link set or
121
+ changed option-list inputs; major: removed workflow or link set, required setting, identity change, new module). `planUpgrade` lists what a person must supply first and what the
122
+ runtime does (enable/disable workflows, rebuild links, re-run install steps). Queued messages carry the version
123
+ they were routed under and finish on it.
124
+
125
+ ## Running the tests
126
+
127
+ ```bash
128
+ npx jest --config '{}' --rootDir packages/core/integrations/data-defined tests
129
+ ```
130
+
131
+ `tests/persistence.test.js` runs the repositories and the publish rules against real databases. Each leg runs only
132
+ when its URL is set. Point them at a migrated PostgreSQL database and a MongoDB replica set with the schema pushed:
133
+
134
+ ```bash
135
+ DATA_DEFINED_POSTGRES_URL=postgresql://… DATA_DEFINED_MONGO_URL=mongodb://… npx jest … tests
136
+ ```
137
+
138
+ ## Validating
139
+
140
+ Validation is two layers, and a document is valid only when both pass (`schema-check.js`):
141
+
142
+ 1. **JSON Schema** (`schema/*.schema.json`): the published shape.
143
+ 2. **References** (`validate.js`, `manifests.js`): what a schema cannot see — steps name declared capabilities,
144
+ `$.steps.x` is an earlier step, view paths exist, option inputs are declared, `$.install` paths resolve.
145
+
146
+ ```bash
147
+ npm run validate:definitions --workspace @friggframework/core # bundled manifests + examples
148
+ node packages/core/integrations/data-defined/scripts/validate.js my.definition.json --strict
149
+ node packages/core/integrations/data-defined/scripts/validate.js --manifests ./capabilities --json defs/
150
+ ```
151
+
152
+ Exit codes: `0` valid, `1` invalid (or a warning with `--strict`), `2` could not run (unreadable JSON, missing file,
153
+ unknown option, `ajv` not installed). Manifests are checked first and an invalid manifest fails the run, because a
154
+ definition is only as trustworthy as the manifests it is checked against.
155
+
156
+ `ajv` comes from the monorepo root (`@friggframework/schemas` depends on it); core's runtime stays dependency-free and
157
+ loads it only for validation. `tests/schemas.test.js` runs both layers over every example and manifest and drives the
158
+ CLI as a child process; it fails, rather than skips, if `ajv` is missing. Core's `npm test`, and so CI's
159
+ `npm run test:all`, runs it on every change.
160
+
161
+ ## Not in v0.1
162
+
163
+ - The sync engine (backfill pages, ongoing deltas, two-way master rules) — specified by the schema, to be executed by
164
+ the existing `SYNC_PAGE` pattern. `runSync` throws until then.
165
+ - `delay` / wait steps, approvals that pause a run, and per-tenant rate limits.
166
+ - The host renderers (the HubSpot app extension and Phone panel that draw `renderSurface` output).
167
+ - Registering `compiled.schedules` as recurring schedules (Frigg's scheduler commands are one-time jobs). They compile
168
+ today; nothing creates them yet.
169
+ - Rebuilding `link:` / `idx:` rows after an identity change; `planUpgrade` reports it as `relink` / `reindex`.
@@ -0,0 +1,11 @@
1
+ /** Canonical JSON (sorted keys, no whitespace) and its sha256: the checksum a published version is stored under. */
2
+ const crypto = require('crypto');
3
+ // Canonical order is by UTF-16 code unit (what a bare sort() does), never locale: the checksum must not depend on the host's locale.
4
+ const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
5
+ function canonical(v) {
6
+ if (Array.isArray(v)) return '[' + v.map(canonical).join(',') + ']';
7
+ if (v && typeof v === 'object') return '{' + Object.keys(v).sort(byCodeUnit).filter((k) => v[k] !== undefined).map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',') + '}';
8
+ return JSON.stringify(v);
9
+ }
10
+ const checksum = (doc) => 'sha256:' + crypto.createHash('sha256').update(canonical(doc)).digest('hex');
11
+ module.exports = { canonical, checksum };