@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.
- package/CLAUDE.md +0 -28
- package/README.md +0 -105
- package/application/commands/integration-commands.js +10 -20
- package/application/commands/scheduler-commands.js +7 -11
- package/application/commands/user-commands.js +5 -17
- package/application/index.js +2 -6
- package/core/Worker.js +7 -31
- package/core/create-handler.js +0 -9
- package/credential/repositories/credential-repository-documentdb.js +0 -34
- package/credential/repositories/credential-repository-interface.js +0 -15
- package/credential/repositories/credential-repository-mongo.js +0 -23
- package/credential/repositories/credential-repository-postgres.js +0 -28
- package/database/config.js +24 -48
- package/database/documentdb-utils.js +0 -2
- package/database/encryption/encryption-schema-registry.js +12 -93
- package/database/prisma.js +2 -4
- package/errors/index.js +4 -0
- package/errors/mapping-already-exists-error.js +14 -0
- package/generated/prisma-mongodb/edge.js +38 -33
- package/generated/prisma-mongodb/index-browser.js +35 -30
- package/generated/prisma-mongodb/index.d.ts +1880 -3191
- package/generated/prisma-mongodb/index.js +38 -33
- package/generated/prisma-mongodb/package.json +1 -1
- package/generated/prisma-mongodb/schema.prisma +50 -86
- package/generated/prisma-mongodb/wasm.js +38 -33
- package/generated/prisma-postgresql/edge.js +38 -33
- package/generated/prisma-postgresql/index-browser.js +35 -30
- package/generated/prisma-postgresql/index.d.ts +2050 -3390
- package/generated/prisma-postgresql/index.js +38 -33
- package/generated/prisma-postgresql/package.json +1 -1
- package/generated/prisma-postgresql/schema.prisma +48 -81
- package/generated/prisma-postgresql/wasm.js +38 -33
- package/handlers/WEBHOOKS.md +29 -0
- package/handlers/app-definition-loader.js +19 -128
- package/handlers/app-handler-helpers.js +3 -25
- package/handlers/backend-utils.js +25 -31
- package/handlers/middleware/admin-auth.js +1 -14
- package/handlers/routers/auth.js +10 -46
- package/handlers/routers/health.js +4 -13
- package/handlers/routers/integration-defined-routers.js +92 -144
- package/handlers/routers/integration-webhook-routers.js +64 -102
- package/handlers/workers/integration-defined-workers.js +2 -5
- package/index.js +3 -65
- package/infrastructure/scheduler/index.js +6 -19
- package/infrastructure/scheduler/scheduler-service-factory.js +7 -55
- package/integrations/data-defined/README.md +169 -0
- package/integrations/data-defined/canonical.js +11 -0
- package/integrations/data-defined/capabilities/acmeerp.capabilities.json +608 -0
- package/integrations/data-defined/capabilities/asana.capabilities.json +265 -0
- package/integrations/data-defined/capabilities/calendly.capabilities.json +385 -0
- package/integrations/data-defined/capabilities/docusign.capabilities.json +314 -0
- package/integrations/data-defined/capabilities/fathom.capabilities.json +228 -0
- package/integrations/data-defined/capabilities/github.capabilities.json +563 -0
- package/integrations/data-defined/capabilities/hubspot.capabilities.json +715 -0
- package/integrations/data-defined/capabilities/jira.capabilities.json +376 -0
- package/integrations/data-defined/capabilities/klaviyo.capabilities.json +475 -0
- package/integrations/data-defined/capabilities/linear.capabilities.json +324 -0
- package/integrations/data-defined/capabilities/netsuite.capabilities.json +491 -0
- package/integrations/data-defined/capabilities/notion.capabilities.json +208 -0
- package/integrations/data-defined/capabilities/phone.capabilities.json +470 -0
- package/integrations/data-defined/capabilities/pipedrive.capabilities.json +388 -0
- package/integrations/data-defined/capabilities/quickbooks.capabilities.json +615 -0
- package/integrations/data-defined/capabilities/salesforce.capabilities.json +507 -0
- package/integrations/data-defined/capabilities/shopify.capabilities.json +1082 -0
- package/integrations/data-defined/capabilities/slack.capabilities.json +363 -0
- package/integrations/data-defined/capabilities/stripe.capabilities.json +580 -0
- package/integrations/data-defined/capabilities/webflow.capabilities.json +196 -0
- package/integrations/data-defined/capabilities/zendesk.capabilities.json +409 -0
- package/integrations/data-defined/compile.js +77 -0
- package/integrations/data-defined/config-form.js +110 -0
- package/integrations/data-defined/data-defined-integration.js +366 -0
- package/integrations/data-defined/examples/acme-erp-quickbooks.definition.json +467 -0
- package/integrations/data-defined/examples/asana-slack.definition.json +220 -0
- package/integrations/data-defined/examples/calendly-salesforce.definition.json +459 -0
- package/integrations/data-defined/examples/docusign-salesforce.definition.json +305 -0
- package/integrations/data-defined/examples/fathom-hubspot-notion.definition.json +575 -0
- package/integrations/data-defined/examples/github-linear.definition.json +316 -0
- package/integrations/data-defined/examples/hubspot-slack.definition.json +409 -0
- package/integrations/data-defined/examples/klaviyo-hubspot.definition.json +339 -0
- package/integrations/data-defined/examples/phone-hubspot.definition.json +637 -0
- package/integrations/data-defined/examples/pipedrive-hubspot.definition.json +136 -0
- package/integrations/data-defined/examples/pipedrive-phone.definition.json +340 -0
- package/integrations/data-defined/examples/records/phone-hubspot.definition-version.json +652 -0
- package/integrations/data-defined/examples/records/phone-hubspot.integration.json +86 -0
- package/integrations/data-defined/examples/records/phone-hubspot.mappings.json +39 -0
- package/integrations/data-defined/examples/records/phone-hubspot.workflow-run.json +62 -0
- package/integrations/data-defined/examples/shopify-klaviyo.definition.json +488 -0
- package/integrations/data-defined/examples/shopify-netsuite.definition.json +622 -0
- package/integrations/data-defined/examples/stripe-quickbooks.definition.json +476 -0
- package/integrations/data-defined/examples/webflow-hubspot-slack.definition.json +262 -0
- package/integrations/data-defined/examples/zendesk-jira.definition.json +604 -0
- package/integrations/data-defined/expressions.js +225 -0
- package/integrations/data-defined/index.js +39 -0
- package/integrations/data-defined/interpreter.js +89 -0
- package/integrations/data-defined/manifests.js +125 -0
- package/integrations/data-defined/repositories/definition-version-repository.js +67 -0
- package/integrations/data-defined/repositories/workflow-run-repository.js +59 -0
- package/integrations/data-defined/router.js +97 -0
- package/integrations/data-defined/runtime.js +208 -0
- package/integrations/data-defined/schema/capability-manifest.v0.1.schema.json +377 -0
- package/integrations/data-defined/schema/installation.v0.1.schema.json +83 -0
- package/integrations/data-defined/schema/integration-definition.v0.1.schema.json +848 -0
- package/integrations/data-defined/schema/records.md +98 -0
- package/integrations/data-defined/schema-check.js +58 -0
- package/integrations/data-defined/scripts/validate.js +66 -0
- package/integrations/data-defined/steps.js +89 -0
- package/integrations/data-defined/transforms.js +91 -0
- package/integrations/data-defined/use-cases/definition-use-cases.js +187 -0
- package/integrations/data-defined/validate.js +370 -0
- package/integrations/data-defined/versioning.js +161 -0
- package/integrations/data-defined/webhooks.js +119 -0
- package/integrations/index.js +0 -1
- package/integrations/integration-base.js +29 -0
- package/integrations/integration-router.js +101 -131
- package/integrations/repositories/integration-mapping-repository-documentdb.js +50 -0
- package/integrations/repositories/integration-mapping-repository-interface.js +15 -0
- package/integrations/repositories/integration-mapping-repository-mongo.js +29 -0
- package/integrations/repositories/integration-mapping-repository-postgres.js +30 -0
- package/integrations/repositories/integration-mapping-repository.js +29 -0
- package/integrations/repositories/integration-repository-documentdb.js +3 -35
- package/integrations/repositories/integration-repository-interface.js +1 -17
- package/integrations/repositories/integration-repository-mongo.js +77 -60
- package/integrations/repositories/integration-repository-postgres.js +76 -62
- package/integrations/repositories/process-repository-mongo.js +1 -1
- package/integrations/tests/doubles/test-integration-repository.js +1 -12
- package/integrations/use-cases/create-integration.js +20 -55
- package/integrations/use-cases/get-integrations-for-user.js +40 -80
- package/integrations/use-cases/index.js +1 -7
- package/integrations/utils/map-integration-dto.js +14 -43
- package/modules/index.js +0 -14
- package/modules/module-factory.js +0 -12
- package/modules/module.js +2 -53
- package/modules/repositories/module-repository-documentdb.js +6 -51
- package/modules/repositories/module-repository-interface.js +2 -19
- package/modules/repositories/module-repository-mongo.js +74 -67
- package/modules/repositories/module-repository-postgres.js +74 -66
- package/modules/repositories/module-repository.js +1 -2
- package/modules/requester/requester.js +5 -35
- package/modules/use-cases/get-entities-for-user.js +13 -26
- package/modules/use-cases/get-entity-options-by-id.js +4 -10
- package/modules/use-cases/get-entity-options-by-type.js +1 -1
- package/modules/use-cases/get-module-instance-from-type.js +1 -1
- package/modules/use-cases/get-module.js +4 -10
- package/modules/use-cases/process-authorization-callback.js +19 -53
- package/modules/use-cases/refresh-entity-options.js +4 -10
- package/modules/use-cases/test-module-auth.js +4 -10
- package/package.json +6 -6
- package/prisma-mongodb/schema.prisma +50 -86
- package/prisma-postgresql/migrations/20261018000000_add_data_defined_integrations/migration.sql +66 -0
- package/prisma-postgresql/schema.prisma +48 -81
- package/queues/index.js +0 -25
- package/types/index.d.ts +0 -2
- package/user/repositories/user-repository-documentdb.js +2 -27
- package/user/repositories/user-repository-interface.js +0 -18
- package/user/repositories/user-repository-mongo.js +0 -24
- package/user/repositories/user-repository-postgres.js +0 -18
- package/user/use-cases/authenticate-user.js +1 -7
- package/user/use-cases/get-user-from-adopter-jwt.js +124 -95
- package/user/use-cases/get-user-from-x-frigg-headers.js +80 -83
- package/user/user.js +1 -64
- package/credential/use-cases/credential-operations-for-user.js +0 -202
- package/credential/use-cases/reauthorize-credential-for-user.js +0 -73
- package/database/organization-where.js +0 -18
- package/database/unique-violation.js +0 -25
- package/extensions/bootstrap-runner.js +0 -43
- package/extensions/extension-loader.js +0 -187
- package/extensions/index.js +0 -41
- package/extensions/initialize-app.js +0 -123
- package/extensions/route-mounter.js +0 -103
- package/extensions/schema-composer.js +0 -188
- package/infrastructure/scheduler/netlify-scheduler-adapter.js +0 -216
- package/infrastructure/scheduler/scheduled-job-repository.js +0 -118
- package/integrations/repositories/integration-not-found.js +0 -14
- package/integrations/schedule-config.js +0 -80
- package/integrations/use-cases/dispatch-ongoing-syncs.js +0 -100
- package/integrations/use-cases/integration-operations-for-user.js +0 -256
- package/integrations/use-cases/resolve-integration-ownership.js +0 -177
- package/management-api/create-management-api-router.js +0 -49
- package/management-api/error-response.js +0 -116
- package/management-api/management-api-config.js +0 -151
- package/management-api/meta-router.js +0 -76
- package/management-api/openapi/build-openapi.js +0 -144
- package/management-api/openapi/components.js +0 -415
- package/management-api/openapi/v1-operations.js +0 -83
- package/management-api/openapi/v2-operations.js +0 -264
- package/management-api/route-registry.js +0 -411
- package/management-api/test-support/http-client.js +0 -39
- package/management-api/use-cases/get-management-api-meta.js +0 -57
- package/management-api/v1-deprecation.js +0 -120
- package/management-api/v2/create-v2-router.js +0 -85
- package/management-api/v2/dependencies.js +0 -281
- package/management-api/v2/dto.js +0 -143
- package/management-api/v2/handlers/authorization.js +0 -94
- package/management-api/v2/handlers/credentials.js +0 -33
- package/management-api/v2/handlers/entities.js +0 -77
- package/management-api/v2/handlers/integrations.js +0 -128
- package/management-api/v2/handlers/proxy.js +0 -34
- package/management-api/v2/request.js +0 -85
- package/management-api/v2/test-support/fake-dependencies.js +0 -103
- package/modules/domain/authorization-session.js +0 -144
- package/modules/entity-scope.js +0 -15
- package/modules/entity-type-registry.js +0 -311
- package/modules/proxy/proxy-bases.js +0 -169
- package/modules/proxy/proxy-errors.js +0 -31
- package/modules/proxy/proxy-path.js +0 -183
- package/modules/proxy/proxy-policy.js +0 -277
- package/modules/repositories/authorization-session-repository-documentdb.js +0 -112
- package/modules/repositories/authorization-session-repository-factory.js +0 -31
- package/modules/repositories/authorization-session-repository-interface.js +0 -47
- package/modules/repositories/authorization-session-repository-prisma.js +0 -87
- package/modules/repositories/entity-not-found.js +0 -18
- package/modules/requester/proxy-request.js +0 -245
- package/modules/scope-config.js +0 -192
- package/modules/scope-policy.js +0 -112
- package/modules/scope-resolution.js +0 -288
- package/modules/scope-visibility.js +0 -247
- package/modules/tests/doubles/in-memory-authorization-session-repository.js +0 -45
- package/modules/tests/doubles/ownership-matching.js +0 -18
- package/modules/use-cases/authorize-entity-for-user.js +0 -61
- package/modules/use-cases/create-entity-from-credential.js +0 -113
- package/modules/use-cases/entity-operations-for-user.js +0 -162
- package/modules/use-cases/entity-types.js +0 -139
- package/modules/use-cases/execute-entity-proxy-request.js +0 -331
- package/modules/use-cases/get-authorization-requirements.js +0 -100
- package/modules/use-cases/get-entity-module-for-user.js +0 -113
- package/modules/use-cases/manage-access.js +0 -21
- package/modules/use-cases/multi-step-authorization.js +0 -329
- package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +0 -28
- package/prisma-postgresql/migrations/20261015000000_add_organization_membership/migration.sql +0 -26
- package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql +0 -25
- package/prisma-postgresql/migrations/20261017000000_add_scheduled_job/migration.sql +0 -28
- package/providers/index.js +0 -23
- package/providers/resolve-provider.js +0 -93
- package/providers/runtime-detection.js +0 -124
- package/queues/providers/index.js +0 -11
- package/queues/providers/netlify-background-provider.js +0 -150
- package/queues/providers/qstash-queue-provider.js +0 -219
- package/queues/providers/sqs-queue-provider.js +0 -70
- package/queues/queue-client-interface.js +0 -55
- package/queues/queue-message-auth.js +0 -193
- package/queues/queue-provider-factory.js +0 -101
- package/queues/queue-provider.js +0 -65
- package/queues/sqs-queue-client.js +0 -81
- package/types/modules/index.d.ts +0 -214
- package/types/user/index.d.ts +0 -134
- package/user/adopter-jwt-config.js +0 -177
- package/user/adopter-jwt-errors.js +0 -59
- package/user/adopter-token-verifier.js +0 -122
- package/user/app-user-helpers.js +0 -97
- package/user/create-user-authentication.js +0 -64
- package/user/membership.js +0 -51
- package/user/repositories/organization-membership-record.js +0 -19
- package/user/repositories/organization-membership-repository-documentdb.js +0 -106
- package/user/repositories/organization-membership-repository-factory.js +0 -42
- package/user/repositories/organization-membership-repository-interface.js +0 -57
- package/user/repositories/organization-membership-repository-mongo.js +0 -13
- package/user/repositories/organization-membership-repository-postgres.js +0 -29
- package/user/repositories/organization-membership-repository-prisma.js +0 -81
- package/user/tests/doubles/adopter-jwt-fixtures.js +0 -220
- package/user/use-cases/ensure-organization-membership.js +0 -92
- 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
|
-
|
|
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 };
|