Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
A Contribution is an audit and progress-tracking record for a user-initiated blueprint contribution run — typically triggered when a workspace user submits or publishes a new provider blueprint (e.g. building a connector for “amazon” or “qonto”). It captures the run lifecycle (status, started/ended timestamps, progress payload), the provider being built (provider_slug), the originating page (source_url), and the structured input data (addresses, country, flow_json). Each contribution is workspace-scoped via a nullable FK to Workspace that is stamped at creation time to prevent cross-tenant drift. The entity is written exclusively by the blueprint contribution pipeline (POST /v1/contribution) and updated by dedicated PATCH handlers for appending steps and transitioning status; no fields are user-editable via the records-table PATCH surface.
| Naming | Value |
|---|
| Object | Contribution |
Resource type (JSON:API type) | contribution |
| Collection / records root | — (not a records root) |
| REST base | /v1/contributions |
| Entity class | Contribution |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/contributions | 🟡 Planned |
| Retrieve | GET /v1/contributions/{id} | 🟡 Planned |
| Create | POST /v1/contributions | 🟡 Planned |
| Update | PATCH /v1/contributions/{id} | 🟡 Planned |
| Delete | DELETE /v1/contributions/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| contribution_id | string (UUID) 🔒 system | ✅ Yes | unique; generated by gen_random_uuid() on INSERT | — | Public-facing UUID identifier for the contribution. Never editable after creation. |
| name | string | ✅ Yes | NOT NULL (no explicit length limit in entity) | — | Human-readable label for the contribution run, typically set by the client at creation time. |
| addresses | json (array of objects) | ✅ Yes | NOT NULL; stored as JSONB array | — | Array of address objects captured during the contribution run. Schema is open-ended (Record<string, unknown>[]). |
| country | string[] (array) | ✅ Yes | NOT NULL; stored as Postgres text[] | — | ISO-3166-1 alpha-2 country codes relevant to this contribution. Populated by the extension at run start. |
| status | string (enum ContributionStatus) | ✅ Yes | NOT NULL; default ‘initial’; stored as plain string (not native Postgres enum) | initial | processing | cancel | done | Lifecycle status of the contribution run. Transitions are driven by PATCH /:id/status — not by the records-table PATCH surface. |
| flow_json | json (object) | ✅ Yes | NOT NULL; stored as JSONB | — | Structured blueprint-flow payload recorded during the contribution. Contains the sequence of steps (navigate, interact, extract) that the extension executed. |
| ai_historic | json (object) | ⚪ No | nullable | — | AI processing history for the contribution — model used, phases completed, token usage, and intermediate LLM outputs. Populated by the blueprint analyzer pipeline. |
| provider_slug | string | ⚪ No | nullable; max length 255 | — | Provider identifier (e.g. ‘amazon’, ‘qonto’) for the new blueprint being built by this contribution. Set by the extension at run start. |
| source_url | string | ⚪ No | nullable; max length 2048 | — | The page the user was on in the Well app when they initiated the contribution run. Useful for support and replay context. |
| started_at | datetime | ⚪ No | nullable; timestamptz | — | Timestamp when the extension began executing the contribution run. Set by PATCH /:id/status or the pipeline on first step. |
| ended_at | datetime | ⚪ No | nullable; timestamptz | — | Timestamp when the contribution run completed (status = done or cancel). Set by the pipeline or PATCH /:id/status. |
| progress | json (ContributionProgress object) | ⚪ No | nullable; stored as JSONB | — | Live progress snapshot for the in-flight run. Fields: total (int), current (int), inserted (int), status (string), message (string), error (string). All sub-fields are optional. |
| created_at | datetime 🔒 system | ✅ Yes | NOT NULL; set once on INSERT via onCreate hook | — | Row creation timestamp. Stamped automatically by the MikroORM lifecycle hook; never supplied by the client. |
| updated_at | datetime 🔒 system | ✅ Yes | NOT NULL; updated on every write via onUpdate hook | — | Last-modified timestamp. Refreshed automatically by the MikroORM lifecycle hook on every flush. |
| deleted_at | datetime 🔒 system | ⚪ No | nullable; soft-delete sentinel | — | Soft-delete timestamp. NULL means the record is active. When set, the row is excluded from all workspace-scoped Hasura queries via the user-role RLS filter. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | No | The Workspace this contribution was initiated from. Nullable FK (workspace_pk) stamped at creation to prevent cross-tenant drift. Orphan rows whose workspace no longer resolves are excluded from scoped queries automatically by Hasura RLS. Target: core_api.workspaces. |
System-computed
- contribution_id: generated by gen_random_uuid() on INSERT — never supplied by the client
- created_at: set once on INSERT by MikroORM onCreate hook (new Date())
- updated_at: refreshed on every flush by MikroORM onUpdate hook (new Date())
- deleted_at: soft-delete sentinel — NULL on active rows; set by a soft-delete operation, never by the client directly
- status default: ‘initial’ set by the entity class initializer and the DB column default — no application code needs to supply it on creation
- workspace_pk: stamped at creation by ContributionService/route handler from req.workspace (JWT-resolved) so in-flight runs are always correctly tenant-scoped; nullable on pre-migration legacy rows
Example
{
"data": {
"type": "contribution",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"name": "Amazon blueprint contribution — 2026-05-01",
"addresses": [
{ "street": "410 Terry Ave N", "city": "Seattle", "country": "US" }
],
"country": ["US"],
"status": "done",
"flow_json": {
"steps": [
{ "type": "navigate", "url": "https://www.amazon.com/gp/b2b/manage" }
]
},
"ai_historic": {
"model": "gemini-3-flash-preview",
"phases": ["navigation", "exploration", "generation"],
"token_usage": 12400
},
"provider_slug": "amazon",
"source_url": "https://app.wellapp.ai/workspaces/ws_abc/settings/connectors",
"started_at": "2026-05-01T09:12:00.000Z",
"ended_at": "2026-05-01T09:14:35.000Z",
"progress": {
"total": 8,
"current": 8,
"inserted": 8,
"status": "complete",
"message": "Blueprint published successfully"
},
"created_at": "2026-05-01T09:11:55.000Z",
"updated_at": "2026-05-01T09:14:35.000Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "9f3a2b1c-0000-4abc-8def-000000000001" }
}
}
}
}
/Users/maximechampoux/platform/apps/api/src/database/entities/Contribution.ts · domain: intelligence · tier: Activity
