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 Collect represents a single data-collection run initiated by an authenticated user, typically driven by the browser extension (popup, side panel, or blueprint automation). Each run is bound to one People (the subject being enriched), one Workspace (stamped at creation from req.workspace and never re-derived), and optionally one Task (the automation trigger). The status lifecycle progresses from todo through in_progress to finalized or error. Workspace binding is nullable on legacy rows to handle orphaned people records; all workspace-scoped queries silently exclude those rows via Hasura RLS.
| Naming | Value |
|---|
| Object | Collect |
Resource type (JSON:API type) | collect |
| Collection / records root | — (not a records root) |
| REST base | /v1/collects |
| Entity class | Collect |
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/collects | 🟡 Planned |
| Retrieve | GET /v1/collects/{id} | 🟡 Planned |
| Create | POST /v1/collects | 🟡 Planned |
| Update | PATCH /v1/collects/{id} | 🟡 Planned |
| Delete | DELETE /v1/collects/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| collect_id | string (UUID) | ✅ Yes | unique | — | Public stable identifier for the collect run. Generated server-side via gen_random_uuid(); never user-supplied. |
| provider | string | ⚪ No | varchar(255), nullable | — | Slug identifying the data-collection provider or browser extension surface that initiated the run (e.g. ‘linkedin’, ‘popup’). Null for manual or legacy rows. |
| status | enum (collect_status_enum) | ✅ Yes | native enum collect_status_enum, default ‘todo’ | todo | in_progress | finalized | error | Lifecycle state of the collection run. Defaults to ‘todo’ at creation; transitions to ‘in_progress’, then ‘finalized’ (success) or ‘error’ (terminal failure). Terminal statuses trigger a workspace_connector_sync_logs entry. |
| started_at | 🔒 system — timestamptz | ⚪ No | nullable, timestamptz | — | Timestamp when the run began active processing. Set by the client via PATCH; null until the extension begins extraction. |
| ended_at | 🔒 system — timestamptz | ⚪ No | nullable, timestamptz | — | Timestamp when the run reached a terminal state (finalized or error). Set by the client via PATCH alongside status update. |
| created_at | 🔒 system — timestamptz | ✅ Yes | not null, set once on insert | — | Row creation timestamp. Set via onCreate hook; never user-editable. |
| updated_at | 🔒 system — timestamptz | ⚪ No | nullable, set on insert and every update | — | Last modification timestamp. Automatically set on every update via onUpdate hook. |
| deleted_at | 🔒 system — timestamptz | ⚪ No | nullable | — | Soft-delete timestamp. When set, the row is excluded from all workspace-scoped queries and Hasura RLS filters. Set via DELETE endpoint (CollectService.deleteCollect). |
Relationships
| Name | Type | Required | Description |
|---|
| people | to-one (ManyToOne) | ✅ Yes | The People record being enriched during this collection run. Resolved at creation from the authenticated user’s associated person. FK: collects.people_pk → peoples.pk. Indexed via idx_collects_people (partial, deleted_at IS NULL). |
| workspace | to-one (ManyToOne) | ⚪ No (nullable; required on all new rows by service-layer enforcement) | The Workspace this collect run belongs to. Stamped once at creation from req.workspace and never re-derived from subsequent JWT calls, ensuring cross-workspace switches cannot reroute writes mid-flight. Nullable to absorb legacy orphan rows; all workspace-scoped queries (Hasura RLS, service layer) exclude null rows automatically. FK: collects.workspace_pk → workspaces.pk (cascade update+delete). Indexed via idx_collects_workspace_status. |
| task | to-one (ManyToOne) | ⚪ No | Optional link to the Task that triggered this collection run (blueprint automation). Null for manual/popup/side-panel collections and legacy rows. FK: collects.task_pk → tasks.pk. On Task deletion the FK is set to null (deleteRule: ‘set null’). |
System-computed
- collect_id — generated server-side via gen_random_uuid() defaultRaw; never accepted from client input
- created_at — set once on insert via MikroORM onCreate hook (new Date())
- updated_at — refreshed on every update via onUpdate hook (new Date())
- deleted_at — soft-delete; set to current timestamp by CollectService.deleteCollect; null on active rows
- workspace (workspace_pk) — stamped at creation time from req.workspace by CollectService.createCollect and never subsequently overwritten, even on PATCH calls; this immutability is the tenant-safety guarantee for in-flight runs
- status default — CollectStatusEnum.TODO at row creation unless overridden by the POST body
- idx_collects_status — partial index on status WHERE deleted_at IS NULL
- idx_collects_people — partial index on people_pk WHERE deleted_at IS NULL
- idx_collects_workspace_status — composite index on (workspace_pk, status) for active-run queries
Example
{
"data": {
"type": "collect",
"id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
"attributes": {
"collect_id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
"provider": "linkedin",
"status": "in_progress",
"started_at": "2026-06-02T09:15:00.000Z",
"ended_at": null,
"created_at": "2026-06-02T09:14:58.123Z",
"updated_at": "2026-06-02T09:15:01.450Z",
"deleted_at": null
},
"relationships": {
"people": {
"data": { "type": "people", "id": "d8b1a4f2-11cc-4e77-b933-abc123456789" }
},
"workspace": {
"data": { "type": "workspace", "id": "7e91cd02-0a3b-4f55-8811-fedcba987654" }
},
"task": {
"data": null
}
}
}
}
/Users/maximechampoux/platform/apps/api/src/database/entities/Collect.ts · domain: ingestion · tier: Infrastructure
