@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.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 (308) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/CLAUDE.md +28 -0
  3. package/README.md +105 -0
  4. package/application/commands/integration-commands.js +20 -10
  5. package/application/commands/scheduler-commands.js +11 -7
  6. package/application/commands/user-commands.js +17 -5
  7. package/application/index.js +6 -2
  8. package/core/Worker.js +31 -7
  9. package/core/create-handler.js +9 -0
  10. package/credential/repositories/credential-repository-documentdb.js +34 -0
  11. package/credential/repositories/credential-repository-interface.js +15 -0
  12. package/credential/repositories/credential-repository-mongo.js +23 -0
  13. package/credential/repositories/credential-repository-postgres.js +28 -0
  14. package/credential/use-cases/credential-operations-for-user.js +202 -0
  15. package/credential/use-cases/reauthorize-credential-for-user.js +73 -0
  16. package/database/config.js +48 -24
  17. package/database/documentdb-encryption-service.js +9 -22
  18. package/database/documentdb-utils.js +2 -2
  19. package/database/encryption/README.md +78 -14
  20. package/database/encryption/documentdb-encryption-service.md +78 -1
  21. package/database/encryption/encryption-config.js +219 -0
  22. package/database/encryption/encryption-schema-registry.js +121 -24
  23. package/database/encryption/field-encryption-service.js +69 -5
  24. package/database/encryption/integration-mapping-encryption.js +1 -1
  25. package/database/encryption/test-support/fake-ciphertext.js +15 -0
  26. package/database/organization-where.js +18 -0
  27. package/database/prisma.js +15 -38
  28. package/database/unique-violation.js +25 -0
  29. package/database/use-cases/check-encryption-health-use-case.js +43 -52
  30. package/errors/index.js +0 -4
  31. package/extensions/bootstrap-runner.js +43 -0
  32. package/extensions/extension-loader.js +230 -0
  33. package/extensions/index.js +44 -0
  34. package/extensions/initialize-app.js +123 -0
  35. package/extensions/prisma-composer.js +270 -0
  36. package/extensions/route-mounter.js +103 -0
  37. package/extensions/schema-composer.js +188 -0
  38. package/generated/prisma-mongodb/edge.js +33 -42
  39. package/generated/prisma-mongodb/index-browser.js +30 -39
  40. package/generated/prisma-mongodb/index.d.ts +3187 -2005
  41. package/generated/prisma-mongodb/index.js +33 -42
  42. package/generated/prisma-mongodb/package.json +1 -1
  43. package/generated/prisma-mongodb/schema.prisma +86 -59
  44. package/generated/prisma-mongodb/wasm.js +33 -42
  45. package/generated/prisma-postgresql/edge.js +33 -42
  46. package/generated/prisma-postgresql/index-browser.js +30 -39
  47. package/generated/prisma-postgresql/index.d.ts +3380 -2177
  48. package/generated/prisma-postgresql/index.js +33 -42
  49. package/generated/prisma-postgresql/package.json +1 -1
  50. package/generated/prisma-postgresql/schema.prisma +81 -57
  51. package/generated/prisma-postgresql/wasm.js +33 -42
  52. package/handlers/WEBHOOKS.md +0 -29
  53. package/handlers/app-definition-loader.js +128 -19
  54. package/handlers/app-handler-helpers.js +27 -8
  55. package/handlers/backend-utils.js +31 -25
  56. package/handlers/integration-event-dispatcher.js +3 -7
  57. package/handlers/middleware/admin-auth.js +14 -1
  58. package/handlers/routers/auth.js +46 -10
  59. package/handlers/routers/health.js +13 -4
  60. package/handlers/routers/integration-defined-routers.js +144 -92
  61. package/handlers/routers/integration-webhook-routers.js +100 -50
  62. package/handlers/workers/integration-defined-workers.js +5 -2
  63. package/index.js +66 -16
  64. package/infrastructure/scheduler/index.js +19 -6
  65. package/infrastructure/scheduler/netlify-scheduler-adapter.js +216 -0
  66. package/infrastructure/scheduler/scheduled-job-repository.js +118 -0
  67. package/infrastructure/scheduler/scheduler-service-factory.js +55 -7
  68. package/integrations/index.js +1 -14
  69. package/integrations/integration-base.js +2 -163
  70. package/integrations/integration-router.js +132 -102
  71. package/integrations/repositories/integration-mapping-repository-documentdb.js +0 -50
  72. package/integrations/repositories/integration-mapping-repository-interface.js +0 -15
  73. package/integrations/repositories/integration-mapping-repository-mongo.js +0 -29
  74. package/integrations/repositories/integration-mapping-repository-postgres.js +0 -30
  75. package/integrations/repositories/integration-mapping-repository.js +0 -29
  76. package/integrations/repositories/integration-not-found.js +14 -0
  77. package/integrations/repositories/integration-repository-documentdb.js +37 -9
  78. package/integrations/repositories/integration-repository-interface.js +17 -4
  79. package/integrations/repositories/integration-repository-mongo.js +64 -96
  80. package/integrations/repositories/integration-repository-postgres.js +63 -81
  81. package/integrations/repositories/process-repository-mongo.js +1 -1
  82. package/integrations/schedule-config.js +80 -0
  83. package/integrations/tests/doubles/test-integration-repository.js +12 -1
  84. package/integrations/use-cases/create-integration.js +56 -31
  85. package/integrations/use-cases/delete-integration-for-user.js +4 -4
  86. package/integrations/use-cases/dispatch-ongoing-syncs.js +100 -0
  87. package/integrations/use-cases/get-integration-for-user.js +2 -4
  88. package/integrations/use-cases/get-integration-instance.js +4 -4
  89. package/integrations/use-cases/get-integrations-for-user.js +79 -39
  90. package/integrations/use-cases/get-possible-integrations.js +2 -7
  91. package/integrations/use-cases/index.js +7 -1
  92. package/integrations/use-cases/integration-operations-for-user.js +256 -0
  93. package/integrations/use-cases/resolve-integration-ownership.js +177 -0
  94. package/integrations/use-cases/update-integration.js +4 -4
  95. package/integrations/utils/map-integration-dto.js +43 -14
  96. package/management-api/create-management-api-router.js +49 -0
  97. package/management-api/error-response.js +116 -0
  98. package/management-api/management-api-config.js +151 -0
  99. package/management-api/meta-router.js +76 -0
  100. package/management-api/openapi/build-openapi.js +144 -0
  101. package/management-api/openapi/components.js +415 -0
  102. package/management-api/openapi/v1-operations.js +83 -0
  103. package/management-api/openapi/v2-operations.js +264 -0
  104. package/management-api/route-registry.js +411 -0
  105. package/management-api/test-support/http-client.js +39 -0
  106. package/management-api/use-cases/get-management-api-meta.js +57 -0
  107. package/management-api/v1-deprecation.js +120 -0
  108. package/management-api/v2/create-v2-router.js +85 -0
  109. package/management-api/v2/dependencies.js +281 -0
  110. package/management-api/v2/dto.js +143 -0
  111. package/management-api/v2/handlers/authorization.js +94 -0
  112. package/management-api/v2/handlers/credentials.js +33 -0
  113. package/management-api/v2/handlers/entities.js +77 -0
  114. package/management-api/v2/handlers/integrations.js +128 -0
  115. package/management-api/v2/handlers/proxy.js +34 -0
  116. package/management-api/v2/request.js +85 -0
  117. package/management-api/v2/test-support/fake-dependencies.js +103 -0
  118. package/modules/domain/authorization-session.js +144 -0
  119. package/modules/entity-scope.js +15 -0
  120. package/modules/entity-type-registry.js +311 -0
  121. package/modules/index.js +14 -0
  122. package/modules/module-factory.js +12 -0
  123. package/modules/module.js +53 -2
  124. package/modules/proxy/proxy-bases.js +169 -0
  125. package/modules/proxy/proxy-errors.js +31 -0
  126. package/modules/proxy/proxy-path.js +183 -0
  127. package/modules/proxy/proxy-policy.js +277 -0
  128. package/modules/repositories/authorization-session-repository-documentdb.js +112 -0
  129. package/modules/repositories/authorization-session-repository-factory.js +31 -0
  130. package/modules/repositories/authorization-session-repository-interface.js +47 -0
  131. package/modules/repositories/authorization-session-repository-prisma.js +87 -0
  132. package/modules/repositories/entity-not-found.js +18 -0
  133. package/modules/repositories/module-repository-documentdb.js +51 -6
  134. package/modules/repositories/module-repository-interface.js +19 -2
  135. package/modules/repositories/module-repository-mongo.js +67 -74
  136. package/modules/repositories/module-repository-postgres.js +66 -74
  137. package/modules/repositories/module-repository.js +2 -1
  138. package/modules/requester/proxy-request.js +245 -0
  139. package/modules/requester/requester.js +35 -5
  140. package/modules/scope-config.js +192 -0
  141. package/modules/scope-policy.js +112 -0
  142. package/modules/scope-resolution.js +288 -0
  143. package/modules/scope-visibility.js +247 -0
  144. package/modules/tests/doubles/in-memory-authorization-session-repository.js +45 -0
  145. package/modules/tests/doubles/ownership-matching.js +18 -0
  146. package/modules/use-cases/authorize-entity-for-user.js +61 -0
  147. package/modules/use-cases/create-entity-from-credential.js +113 -0
  148. package/modules/use-cases/entity-operations-for-user.js +162 -0
  149. package/modules/use-cases/entity-types.js +139 -0
  150. package/modules/use-cases/execute-entity-proxy-request.js +331 -0
  151. package/modules/use-cases/get-authorization-requirements.js +100 -0
  152. package/modules/use-cases/get-entities-for-user.js +26 -13
  153. package/modules/use-cases/get-entity-module-for-user.js +113 -0
  154. package/modules/use-cases/get-entity-options-by-id.js +10 -4
  155. package/modules/use-cases/get-entity-options-by-type.js +1 -1
  156. package/modules/use-cases/get-module-instance-from-type.js +1 -1
  157. package/modules/use-cases/get-module.js +10 -4
  158. package/modules/use-cases/manage-access.js +21 -0
  159. package/modules/use-cases/multi-step-authorization.js +329 -0
  160. package/modules/use-cases/process-authorization-callback.js +53 -19
  161. package/modules/use-cases/refresh-entity-options.js +10 -4
  162. package/modules/use-cases/test-module-auth.js +10 -4
  163. package/package.json +6 -7
  164. package/prisma-mongodb/schema.prisma +86 -59
  165. package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +28 -0
  166. package/prisma-postgresql/migrations/20261015000000_add_organization_membership/migration.sql +26 -0
  167. package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql +25 -0
  168. package/prisma-postgresql/migrations/20261017000000_add_scheduled_job/migration.sql +28 -0
  169. package/prisma-postgresql/schema.prisma +81 -57
  170. package/providers/index.js +23 -0
  171. package/providers/resolve-provider.js +93 -0
  172. package/providers/runtime-detection.js +124 -0
  173. package/queues/index.js +25 -0
  174. package/queues/providers/index.js +11 -0
  175. package/queues/providers/netlify-background-provider.js +150 -0
  176. package/queues/providers/qstash-queue-provider.js +219 -0
  177. package/queues/providers/sqs-queue-provider.js +70 -0
  178. package/queues/queue-client-interface.js +55 -0
  179. package/queues/queue-message-auth.js +193 -0
  180. package/queues/queue-provider-factory.js +101 -0
  181. package/queues/queue-provider.js +65 -0
  182. package/queues/queuer-util.js +2 -9
  183. package/queues/sqs-queue-client.js +81 -0
  184. package/types/index.d.ts +2 -0
  185. package/types/modules/index.d.ts +214 -0
  186. package/types/user/index.d.ts +134 -0
  187. package/user/adopter-jwt-config.js +177 -0
  188. package/user/adopter-jwt-errors.js +59 -0
  189. package/user/adopter-token-verifier.js +122 -0
  190. package/user/app-user-helpers.js +97 -0
  191. package/user/create-user-authentication.js +64 -0
  192. package/user/membership.js +51 -0
  193. package/user/repositories/organization-membership-record.js +19 -0
  194. package/user/repositories/organization-membership-repository-documentdb.js +106 -0
  195. package/user/repositories/organization-membership-repository-factory.js +42 -0
  196. package/user/repositories/organization-membership-repository-interface.js +57 -0
  197. package/user/repositories/organization-membership-repository-mongo.js +13 -0
  198. package/user/repositories/organization-membership-repository-postgres.js +29 -0
  199. package/user/repositories/organization-membership-repository-prisma.js +81 -0
  200. package/user/repositories/user-repository-documentdb.js +27 -2
  201. package/user/repositories/user-repository-interface.js +18 -0
  202. package/user/repositories/user-repository-mongo.js +24 -0
  203. package/user/repositories/user-repository-postgres.js +18 -0
  204. package/user/tests/doubles/adopter-jwt-fixtures.js +220 -0
  205. package/user/use-cases/authenticate-user.js +7 -1
  206. package/user/use-cases/ensure-organization-membership.js +92 -0
  207. package/user/use-cases/find-individual-users-by-organization.js +54 -0
  208. package/user/use-cases/get-user-from-adopter-jwt.js +95 -124
  209. package/user/use-cases/get-user-from-x-frigg-headers.js +83 -80
  210. package/user/user.js +64 -1
  211. package/errors/mapping-already-exists-error.js +0 -14
  212. package/handlers/workers/integration-triggers.js +0 -25
  213. package/infrastructure/scheduler/recurrence.js +0 -204
  214. package/integrations/define/DESIGN.md +0 -122
  215. package/integrations/define/config.js +0 -98
  216. package/integrations/define/define-app.js +0 -66
  217. package/integrations/define/define-extension.js +0 -154
  218. package/integrations/define/define-integration.js +0 -335
  219. package/integrations/define/examples/deal-alerts.js +0 -140
  220. package/integrations/define/extension-binding.js +0 -174
  221. package/integrations/define/index.js +0 -11
  222. package/integrations/define/json-schema-lite.js +0 -68
  223. package/integrations/define/subscriptions.js +0 -186
  224. package/integrations/define/tests/fixtures/hubspot.js +0 -109
  225. package/integrations/define/tests/fixtures/slack.js +0 -26
  226. package/integrations/define/use.js +0 -39
  227. package/integrations/definitions/README.md +0 -278
  228. package/integrations/definitions/canonical.js +0 -11
  229. package/integrations/definitions/capabilities/AUDIT.md +0 -480
  230. package/integrations/definitions/capabilities/acmeerp.capabilities.json +0 -633
  231. package/integrations/definitions/capabilities/asana.capabilities.json +0 -279
  232. package/integrations/definitions/capabilities/calendly.capabilities.json +0 -385
  233. package/integrations/definitions/capabilities/docusign.capabilities.json +0 -314
  234. package/integrations/definitions/capabilities/fathom.capabilities.json +0 -238
  235. package/integrations/definitions/capabilities/github.capabilities.json +0 -585
  236. package/integrations/definitions/capabilities/hubspot.capabilities.json +0 -822
  237. package/integrations/definitions/capabilities/jira.capabilities.json +0 -391
  238. package/integrations/definitions/capabilities/klaviyo.capabilities.json +0 -503
  239. package/integrations/definitions/capabilities/linear.capabilities.json +0 -378
  240. package/integrations/definitions/capabilities/netsuite.capabilities.json +0 -535
  241. package/integrations/definitions/capabilities/notion.capabilities.json +0 -208
  242. package/integrations/definitions/capabilities/phone.capabilities.json +0 -511
  243. package/integrations/definitions/capabilities/pipedrive.capabilities.json +0 -430
  244. package/integrations/definitions/capabilities/quickbooks.capabilities.json +0 -635
  245. package/integrations/definitions/capabilities/salesforce.capabilities.json +0 -568
  246. package/integrations/definitions/capabilities/shopify.capabilities.json +0 -1128
  247. package/integrations/definitions/capabilities/slack.capabilities.json +0 -373
  248. package/integrations/definitions/capabilities/stripe.capabilities.json +0 -630
  249. package/integrations/definitions/capabilities/webflow.capabilities.json +0 -196
  250. package/integrations/definitions/capabilities/zendesk.capabilities.json +0 -422
  251. package/integrations/definitions/compile.js +0 -80
  252. package/integrations/definitions/config-form.js +0 -137
  253. package/integrations/definitions/examples/acme-erp-quickbooks.definition.json +0 -467
  254. package/integrations/definitions/examples/asana-slack.definition.json +0 -219
  255. package/integrations/definitions/examples/calendly-salesforce.definition.json +0 -459
  256. package/integrations/definitions/examples/docusign-salesforce.definition.json +0 -305
  257. package/integrations/definitions/examples/fathom-hubspot-notion.definition.json +0 -575
  258. package/integrations/definitions/examples/github-linear.definition.json +0 -322
  259. package/integrations/definitions/examples/hubspot-slack.definition.json +0 -427
  260. package/integrations/definitions/examples/klaviyo-hubspot.definition.json +0 -336
  261. package/integrations/definitions/examples/phone-hubspot.definition.json +0 -633
  262. package/integrations/definitions/examples/pipedrive-hubspot.definition.json +0 -136
  263. package/integrations/definitions/examples/pipedrive-phone.definition.json +0 -340
  264. package/integrations/definitions/examples/records/phone-hubspot.definition-version.json +0 -652
  265. package/integrations/definitions/examples/records/phone-hubspot.integration.json +0 -86
  266. package/integrations/definitions/examples/records/phone-hubspot.mappings.json +0 -39
  267. package/integrations/definitions/examples/records/phone-hubspot.workflow-run.json +0 -62
  268. package/integrations/definitions/examples/shopify-klaviyo.definition.json +0 -488
  269. package/integrations/definitions/examples/shopify-netsuite.definition.json +0 -622
  270. package/integrations/definitions/examples/stripe-quickbooks.definition.json +0 -476
  271. package/integrations/definitions/examples/webflow-hubspot-slack.definition.json +0 -262
  272. package/integrations/definitions/examples/zendesk-jira.definition.json +0 -604
  273. package/integrations/definitions/expressions.js +0 -229
  274. package/integrations/definitions/index.js +0 -48
  275. package/integrations/definitions/integration-runtime.js +0 -779
  276. package/integrations/definitions/interpreter.js +0 -104
  277. package/integrations/definitions/manifests.js +0 -177
  278. package/integrations/definitions/renderers/common.js +0 -67
  279. package/integrations/definitions/renderers/html.js +0 -129
  280. package/integrations/definitions/renderers/hubspot.js +0 -59
  281. package/integrations/definitions/renderers/preview.js +0 -154
  282. package/integrations/definitions/renderers/slack.js +0 -146
  283. package/integrations/definitions/repositories/definition-version-repository.js +0 -67
  284. package/integrations/definitions/repositories/workflow-run-repository.js +0 -80
  285. package/integrations/definitions/router.js +0 -170
  286. package/integrations/definitions/runtime.js +0 -268
  287. package/integrations/definitions/schema/capability-manifest.v0.1.schema.json +0 -549
  288. package/integrations/definitions/schema/installation.v0.1.schema.json +0 -130
  289. package/integrations/definitions/schema/integration-definition.v0.1.schema.json +0 -909
  290. package/integrations/definitions/schema/records.md +0 -105
  291. package/integrations/definitions/schema-check.js +0 -58
  292. package/integrations/definitions/scripts/check-manifests.js +0 -220
  293. package/integrations/definitions/scripts/validate.js +0 -66
  294. package/integrations/definitions/steps.js +0 -123
  295. package/integrations/definitions/sync-engine.js +0 -297
  296. package/integrations/definitions/tests/helpers-fake-crm.js +0 -49
  297. package/integrations/definitions/transforms.js +0 -91
  298. package/integrations/definitions/use-cases/definition-use-cases.js +0 -245
  299. package/integrations/definitions/validate.js +0 -436
  300. package/integrations/definitions/versioning.js +0 -176
  301. package/integrations/definitions/webhooks.js +0 -119
  302. package/integrations/integration-types.js +0 -73
  303. package/integrations/triggers.js +0 -244
  304. package/integrations/use-cases/run-trigger-tick.js +0 -155
  305. package/integrations/use-cases/run-trigger.js +0 -77
  306. package/prisma-postgresql/migrations/20261018000000_add_data_defined_integrations/migration.sql +0 -66
  307. package/prisma-postgresql/migrations/20261019000000_workflow_run_waits/migration.sql +0 -7
  308. package/prisma-postgresql/migrations/20261019120000_definition_workspace/migration.sql +0 -5
@@ -0,0 +1,415 @@
1
+ /**
2
+ * OpenAPI components for the Management API documents. The shapes match what
3
+ * the v2 handlers return (management-api/v2/dto.js) and are reconciled with
4
+ * packages/schemas/schemas/api-*.schema.json (a test checks the two agree).
5
+ */
6
+
7
+ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
8
+
9
+ const nullable = (schema) => ({ ...schema, nullable: true });
10
+
11
+ // Whose a record is and what the caller may do with it (ADR-056 §3.4). Added to
12
+ // entities, credentials and integrations by the list and get use cases.
13
+ const tenancyProperties = {
14
+ scope: { type: 'string', enum: ['individual', 'organization'], description: 'Whose it is. `global` records are not shown to tenants.' },
15
+ owner: {
16
+ type: 'object',
17
+ properties: { type: { type: 'string', enum: ['individual', 'organization'] }, id: { type: 'string' } },
18
+ description: "The user that owns it: the person, or the organization's user",
19
+ },
20
+ organizationId: nullable({
21
+ type: 'string',
22
+ description:
23
+ 'The organization it belongs to. Null for an individual entity connected outside an organization, or under ownership.individualAcross "all".',
24
+ }),
25
+ access: {
26
+ type: 'string',
27
+ enum: ['manage', 'use', 'view'],
28
+ description: 'manage (create, reauthorize, delete), use (bind it, proxy through it) or view (metadata only)',
29
+ },
30
+ };
31
+
32
+ const errorBody = {
33
+ type: 'object',
34
+ required: ['error'],
35
+ properties: {
36
+ error: {
37
+ type: 'object',
38
+ required: ['code', 'message'],
39
+ properties: {
40
+ code: {
41
+ type: 'string',
42
+ description:
43
+ 'Machine-readable code, e.g. VALIDATION_ERROR, NOT_FOUND, ENTITY_NOT_FOUND, AUTHORIZATION_SESSION_NOT_FOUND, PROXY_NOT_ALLOWED, PROXY_UNKNOWN_BASE. New codes may be added.',
44
+ },
45
+ message: { type: 'string' },
46
+ details: { description: 'Optional structured details' },
47
+ },
48
+ },
49
+ },
50
+ };
51
+
52
+ const authorizationRequirements = {
53
+ type: 'object',
54
+ required: ['type', 'data', 'step', 'totalSteps', 'isMultiStep'],
55
+ properties: {
56
+ type: {
57
+ type: 'string',
58
+ description: 'oauth2, api-key, basic, form, or a module-specific step type (e.g. email, otp)',
59
+ },
60
+ data: {
61
+ type: 'object',
62
+ description:
63
+ 'Step data: { url } for OAuth2, { jsonSchema, uiSchema } for forms',
64
+ additionalProperties: true,
65
+ },
66
+ step: { type: 'integer', minimum: 1 },
67
+ totalSteps: { type: 'integer', minimum: 1 },
68
+ isMultiStep: { type: 'boolean' },
69
+ sessionId: {
70
+ type: 'string',
71
+ description: 'Present for multi-step flows; send it with every later step',
72
+ },
73
+ },
74
+ };
75
+
76
+ const SCHEMAS = {
77
+ Error: errorBody,
78
+
79
+ Integration: {
80
+ type: 'object',
81
+ required: ['id', 'entities', 'status', 'config'],
82
+ properties: {
83
+ id: { type: 'string' },
84
+ entities: {
85
+ type: 'array',
86
+ items: {},
87
+ description: 'Entity ids (or entity summaries) the integration connects',
88
+ },
89
+ status: nullable({ type: 'string', description: 'e.g. ENABLED, DISABLED, ERROR, NEEDS_CONFIG' }),
90
+ config: { type: 'object', additionalProperties: true },
91
+ version: nullable({ type: 'string' }),
92
+ messages: { type: 'object', additionalProperties: true },
93
+ ...tenancyProperties,
94
+ },
95
+ },
96
+ ListIntegrationsResponse: {
97
+ type: 'object',
98
+ required: ['integrations'],
99
+ properties: { integrations: { type: 'array', items: ref('Integration') } },
100
+ },
101
+ ListIntegrationOptionsResponse: {
102
+ type: 'object',
103
+ required: ['integrations'],
104
+ properties: {
105
+ integrations: {
106
+ type: 'array',
107
+ items: { type: 'object', additionalProperties: true },
108
+ description: 'Integration types this app offers (each integration Definition option details)',
109
+ },
110
+ },
111
+ },
112
+ CreateIntegrationRequest: {
113
+ type: 'object',
114
+ required: ['entities', 'config'],
115
+ properties: {
116
+ entities: {
117
+ type: 'array',
118
+ items: { type: 'string' },
119
+ description: 'Ids of entities the caller owns',
120
+ },
121
+ config: {
122
+ type: 'object',
123
+ required: ['type'],
124
+ properties: { type: { type: 'string', description: 'Integration name' } },
125
+ additionalProperties: true,
126
+ },
127
+ },
128
+ },
129
+ UpdateIntegrationRequest: {
130
+ type: 'object',
131
+ required: ['config'],
132
+ properties: { config: { type: 'object', additionalProperties: true } },
133
+ },
134
+ AuthTestResult: {
135
+ type: 'object',
136
+ required: ['status'],
137
+ properties: {
138
+ status: { type: 'string', enum: ['ok', 'failed'] },
139
+ errors: { type: 'array', items: { type: 'object', additionalProperties: true } },
140
+ },
141
+ },
142
+
143
+ Entity: {
144
+ type: 'object',
145
+ required: ['id', 'type', 'userId'],
146
+ properties: {
147
+ id: { type: 'string' },
148
+ type: nullable({ type: 'string', description: 'Module name' }),
149
+ name: nullable({ type: 'string' }),
150
+ externalId: nullable({ type: 'string' }),
151
+ credentialId: nullable({ type: 'string' }),
152
+ userId: nullable({ type: 'string' }),
153
+ authIsValid: nullable({ type: 'boolean' }),
154
+ ...tenancyProperties,
155
+ },
156
+ },
157
+ ListEntitiesResponse: {
158
+ type: 'object',
159
+ required: ['entities'],
160
+ properties: { entities: { type: 'array', items: ref('Entity') } },
161
+ },
162
+ EntityType: {
163
+ type: 'object',
164
+ required: ['type', 'name', 'authType', 'isMultiStep', 'stepCount', 'usedBy'],
165
+ properties: {
166
+ type: { type: 'string' },
167
+ name: { type: 'string' },
168
+ description: { type: 'string' },
169
+ usedBy: {
170
+ type: 'array',
171
+ items: { type: 'string' },
172
+ description:
173
+ 'Names of the integrations that bind this entity type. Empty for a type registered only in appDefinition.entities.',
174
+ },
175
+ authType: { type: 'string', description: 'oauth2, oauth1, api-key, basic or custom' },
176
+ isMultiStep: { type: 'boolean' },
177
+ stepCount: { type: 'integer', minimum: 1 },
178
+ capabilities: {},
179
+ scope: {
180
+ type: 'object',
181
+ description:
182
+ 'The scope a new connection of this type gets and the scopes a request may choose (ADR-056 §3.1). `global` is never offered.',
183
+ properties: {
184
+ default: { type: 'string', enum: ['individual', 'organization', 'global'] },
185
+ allow: { type: 'array', items: { type: 'string', enum: ['individual', 'organization'] } },
186
+ source: { type: 'string', enum: ['binding', 'integration', 'entityType', 'app', 'default'] },
187
+ },
188
+ },
189
+ },
190
+ },
191
+ ListEntityTypesResponse: {
192
+ type: 'object',
193
+ required: ['types'],
194
+ properties: { types: { type: 'array', items: ref('EntityType') } },
195
+ },
196
+
197
+ Credential: {
198
+ type: 'object',
199
+ required: ['id', 'type', 'userId', 'authIsValid'],
200
+ description: 'Every provider field in data is masked; values never leave the server.',
201
+ properties: {
202
+ id: { type: 'string' },
203
+ type: nullable({ type: 'string', description: 'Module name, from the entities using it' }),
204
+ externalId: nullable({ type: 'string' }),
205
+ userId: nullable({ type: 'string' }),
206
+ authIsValid: nullable({ type: 'boolean' }),
207
+ entityIds: { type: 'array', items: { type: 'string' } },
208
+ entityCount: { type: 'integer', minimum: 0 },
209
+ ...tenancyProperties,
210
+ createdAt: nullable({ type: 'string', format: 'date-time' }),
211
+ updatedAt: nullable({ type: 'string', format: 'date-time' }),
212
+ data: {
213
+ type: 'object',
214
+ additionalProperties: true,
215
+ description: 'Masked provider fields, e.g. { "access_token": "****WXYZ" }',
216
+ },
217
+ },
218
+ },
219
+ ListCredentialsResponse: {
220
+ type: 'object',
221
+ required: ['credentials'],
222
+ properties: { credentials: { type: 'array', items: ref('Credential') } },
223
+ },
224
+
225
+ AuthorizationRequirements: authorizationRequirements,
226
+ AuthorizeRequest: {
227
+ type: 'object',
228
+ required: ['entityType', 'data'],
229
+ properties: {
230
+ entityType: { type: 'string', description: 'Module name' },
231
+ data: { type: 'object', additionalProperties: true, description: 'OAuth callback params or step form data' },
232
+ step: { type: 'integer', minimum: 1, default: 1 },
233
+ sessionId: { type: 'string', description: 'Required for step 2 and later' },
234
+ scope: {
235
+ type: 'string',
236
+ enum: ['individual', 'organization'],
237
+ description:
238
+ "The scope to connect at, from the entity type's allow list (ADR-056 §3.1). Omit to take the type's default. `global` is refused (403).",
239
+ },
240
+ },
241
+ },
242
+ ReauthorizeRequest: {
243
+ type: 'object',
244
+ required: ['data'],
245
+ properties: {
246
+ data: { type: 'object', additionalProperties: true },
247
+ step: { type: 'integer', minimum: 1, default: 1 },
248
+ sessionId: { type: 'string' },
249
+ },
250
+ },
251
+ AuthorizeComplete: {
252
+ type: 'object',
253
+ required: ['status', 'entity', 'credential'],
254
+ properties: {
255
+ status: { type: 'string', enum: ['complete'] },
256
+ entity: ref('Entity'),
257
+ credential: ref('Credential'),
258
+ previousCredentialId: {
259
+ type: 'string',
260
+ description: 'Re-authorization only: the credential being renewed, when the provider account changed and a new credential was stored',
261
+ },
262
+ },
263
+ },
264
+ AuthorizePending: {
265
+ type: 'object',
266
+ required: ['status', 'step', 'totalSteps', 'sessionId', 'requirements'],
267
+ properties: {
268
+ status: { type: 'string', enum: ['pending'] },
269
+ step: { type: 'integer', minimum: 2 },
270
+ totalSteps: { type: 'integer', minimum: 2 },
271
+ sessionId: { type: 'string' },
272
+ requirements: ref('AuthorizationRequirements'),
273
+ message: { type: 'string', description: 'e.g. "Code sent to your email"' },
274
+ },
275
+ },
276
+ AuthorizeResponse: {
277
+ oneOf: [ref('AuthorizeComplete'), ref('AuthorizePending')],
278
+ discriminator: { propertyName: 'status' },
279
+ },
280
+
281
+ ProxyRequest: {
282
+ type: 'object',
283
+ required: ['method', 'path'],
284
+ properties: {
285
+ method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] },
286
+ path: {
287
+ type: 'string',
288
+ pattern: '^/',
289
+ description:
290
+ "Path relative to the module's base URL (the one named by `base`). No //, backslashes, ? or #, dot segments, encoded separators or double encoding. The host always comes from the module.",
291
+ },
292
+ base: {
293
+ type: 'string',
294
+ pattern: '^[a-z][a-z0-9-]*$',
295
+ description:
296
+ "Name of one of the module's base URLs (ADR-052 amendment); default when omitted. A name the module declares, never a URL or host. An unknown name is 400 PROXY_UNKNOWN_BASE.",
297
+ },
298
+ query: {
299
+ type: 'object',
300
+ additionalProperties: {
301
+ oneOf: [
302
+ { type: 'string' },
303
+ { type: 'number' },
304
+ { type: 'boolean' },
305
+ { type: 'array', items: { type: 'string' } },
306
+ ],
307
+ },
308
+ description:
309
+ 'Array values are sent comma-separated (`ids: ["1","2"]` → `ids=1,2`), except under a key ending in `[]`, which is sent once per value (`"fields[]": ["a","b"]` → `fields%5B%5D=a&fields%5B%5D=b`; an empty array sends nothing).',
310
+ },
311
+ headers: {
312
+ type: 'object',
313
+ additionalProperties: { type: 'string' },
314
+ description:
315
+ 'Only accept, content-type, accept-language, if-match, if-none-match and module-listed headers are forwarded. Credential, Host and forwarding headers are refused.',
316
+ },
317
+ body: { description: 'JSON value or string; POST, PUT, PATCH and DELETE only' },
318
+ },
319
+ },
320
+ ProxyResponse: {
321
+ type: 'object',
322
+ required: ['success', 'status', 'headers', 'data'],
323
+ properties: {
324
+ success: { type: 'boolean', description: 'False for relayed upstream 4xx' },
325
+ status: { type: 'integer', description: 'Upstream status; also the HTTP status of this response' },
326
+ headers: { type: 'object', additionalProperties: { type: 'string' } },
327
+ data: { description: 'Parsed JSON, text, or base64 when dataEncoding is set' },
328
+ dataEncoding: { type: 'string', enum: ['base64'] },
329
+ },
330
+ },
331
+ ProxyError: {
332
+ type: 'object',
333
+ required: ['success', 'status', 'error'],
334
+ properties: {
335
+ success: { type: 'boolean', enum: [false] },
336
+ status: { type: 'integer' },
337
+ error: errorBody.properties.error,
338
+ },
339
+ },
340
+
341
+ ApiMeta: {
342
+ type: 'object',
343
+ required: ['api', 'capabilities'],
344
+ properties: {
345
+ api: {
346
+ type: 'object',
347
+ required: ['versions', 'preferred'],
348
+ properties: {
349
+ versions: {
350
+ type: 'object',
351
+ additionalProperties: {
352
+ type: 'object',
353
+ required: ['status', 'openapi'],
354
+ properties: {
355
+ status: { type: 'string', enum: ['stable', 'beta', 'deprecated', 'disabled'] },
356
+ deprecatedAt: { type: 'string', format: 'date' },
357
+ sunset: nullable({ type: 'string', format: 'date' }),
358
+ openapi: { type: 'string' },
359
+ },
360
+ },
361
+ },
362
+ preferred: { type: 'string' },
363
+ },
364
+ },
365
+ capabilities: {
366
+ type: 'array',
367
+ items: { type: 'string' },
368
+ description: 'Stable feature flags, e.g. credentials, multiStepAuthorize, entityProxy',
369
+ },
370
+ frigg: {
371
+ type: 'object',
372
+ description: 'Only for callers with x-frigg-admin-api-key',
373
+ properties: { coreVersion: { type: 'string' } },
374
+ },
375
+ },
376
+ },
377
+ };
378
+
379
+ const errorResponse = (description) => ({
380
+ description,
381
+ content: { 'application/json': { schema: ref('Error') } },
382
+ });
383
+
384
+ const RESPONSES = {
385
+ BadRequest: errorResponse('Invalid request (VALIDATION_ERROR, INVALID_JSON, INVALID_STEP, ...)'),
386
+ Unauthorized: errorResponse('Missing or invalid authentication'),
387
+ Forbidden: errorResponse('Not allowed'),
388
+ NotFound: errorResponse('Not found, or not owned by the caller'),
389
+ Conflict: errorResponse('Conflicts with the current state'),
390
+ Gone: errorResponse('This API version is disabled for the app'),
391
+ BadGateway: errorResponse('The provider failed'),
392
+ };
393
+
394
+ const SECURITY_SCHEMES = {
395
+ bearerAuth: {
396
+ type: 'http',
397
+ scheme: 'bearer',
398
+ description: 'Frigg user token (POST /user/login) or, when enabled, an adopter JWT',
399
+ },
400
+ friggApiKey: {
401
+ type: 'apiKey',
402
+ in: 'header',
403
+ name: 'x-frigg-api-key',
404
+ description:
405
+ 'Backend-to-backend shared secret. Send x-frigg-appuserid (and x-frigg-apporgid for organisation users) to act for a user.',
406
+ },
407
+ adminApiKey: {
408
+ type: 'apiKey',
409
+ in: 'header',
410
+ name: 'x-frigg-admin-api-key',
411
+ description: 'Admin key; on /api/meta it only adds the core version',
412
+ },
413
+ };
414
+
415
+ module.exports = { SCHEMAS, RESPONSES, SECURITY_SCHEMES, ref };
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Documentation for the frozen Management API v1 routes, keyed by
3
+ * "METHOD path" as in the route registry. Each names its v2 replacement
4
+ * (docs/reference/api-reference.md has the full migration table).
5
+ */
6
+
7
+ const any = { description: 'Response body as returned by v1' };
8
+ const v1 = (operationId, summary, replacement, extra = {}) => ({
9
+ operationId,
10
+ summary,
11
+ description: replacement ? `Deprecated. Use ${replacement}.` : 'Deprecated.',
12
+ responses: { 200: any },
13
+ ...extra,
14
+ });
15
+
16
+ const V1_OPERATIONS = {
17
+ 'GET /api/integrations': v1(
18
+ 'v1ListIntegrations',
19
+ 'List integrations, integration options and authorized entities in one response',
20
+ 'GET /api/v2/integrations, GET /api/v2/integrations/options and GET /api/v2/entities'
21
+ ),
22
+ 'POST /api/integrations': v1('v1CreateIntegration', 'Create an integration', 'POST /api/v2/integrations', {
23
+ responses: { 201: any },
24
+ }),
25
+ 'PATCH /api/integrations/:integrationId': v1('v1UpdateIntegration', 'Update an integration', 'PATCH /api/v2/integrations/{integrationId}'),
26
+ 'DELETE /api/integrations/:integrationId': v1('v1DeleteIntegration', 'Delete an integration', 'DELETE /api/v2/integrations/{integrationId}', {
27
+ responses: { 204: any },
28
+ }),
29
+ 'GET /api/integrations/:integrationId/config/options': v1(
30
+ 'v1GetIntegrationConfigOptions',
31
+ 'Get config options',
32
+ 'GET /api/v2/integrations/{integrationId}/config/options'
33
+ ),
34
+ 'POST /api/integrations/:integrationId/config/options/refresh': v1(
35
+ 'v1RefreshIntegrationConfigOptions',
36
+ 'Refresh config options',
37
+ 'POST /api/v2/integrations/{integrationId}/config/options/refresh'
38
+ ),
39
+ 'ANY /api/integrations/:integrationId/actions': v1(
40
+ 'v1ListIntegrationActions',
41
+ 'List user actions (any method)',
42
+ 'GET /api/v2/integrations/{integrationId}/actions'
43
+ ),
44
+ 'ANY /api/integrations/:integrationId/actions/:actionId/options': v1(
45
+ 'v1GetIntegrationActionOptions',
46
+ 'Get user action options (any method)',
47
+ 'POST /api/v2/integrations/{integrationId}/actions/{actionId}/options'
48
+ ),
49
+ 'POST /api/integrations/:integrationId/actions/:actionId/options/refresh': v1(
50
+ 'v1RefreshIntegrationActionOptions',
51
+ 'Refresh user action options',
52
+ 'POST /api/v2/integrations/{integrationId}/actions/{actionId}/options/refresh'
53
+ ),
54
+ 'POST /api/integrations/:integrationId/actions/:actionId': v1(
55
+ 'v1RunIntegrationAction',
56
+ 'Run an integration event',
57
+ 'POST /api/v2/integrations/{integrationId}/actions/{actionId} (user actions only)'
58
+ ),
59
+ 'GET /api/integrations/:integrationId': v1('v1GetIntegration', 'Get an integration', 'GET /api/v2/integrations/{integrationId}'),
60
+ 'GET /api/integrations/:integrationId/test-auth': v1(
61
+ 'v1TestIntegrationAuth',
62
+ 'Test integration auth',
63
+ 'GET /api/v2/integrations/{integrationId}/test-auth'
64
+ ),
65
+ 'GET /api/authorize': v1('v1GetAuthorizeRequirements', 'Get authorization requirements', 'GET /api/v2/authorize'),
66
+ 'POST /api/authorize': v1('v1Authorize', 'Authorize an entity', 'POST /api/v2/authorize'),
67
+ 'POST /api/entity': v1('v1CreateEntity', 'Create an entity from a credential', 'POST /api/v2/authorize (authorization creates the entity)'),
68
+ 'GET /api/entity/options/:credentialId': v1(
69
+ 'v1GetEntityOptionsByCredential',
70
+ 'Get entity options for a credential',
71
+ 'GET /api/v2/entities/{entityId}/options'
72
+ ),
73
+ 'GET /api/entities/:entityId/test-auth': v1('v1TestEntityAuth', 'Test entity auth', 'GET /api/v2/entities/{entityId}/test-auth'),
74
+ 'GET /api/entities/:entityId': v1('v1GetEntity', 'Get an entity', 'GET /api/v2/entities/{entityId}'),
75
+ 'POST /api/entities/:entityId/options': v1('v1GetEntityOptions', 'Get entity options', 'GET /api/v2/entities/{entityId}/options'),
76
+ 'POST /api/entities/:entityId/options/refresh': v1(
77
+ 'v1RefreshEntityOptions',
78
+ 'Refresh entity options',
79
+ 'POST /api/v2/entities/{entityId}/options/refresh'
80
+ ),
81
+ };
82
+
83
+ module.exports = { V1_OPERATIONS };