Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-18742-customers-merge-graph.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Customers: graph view, merge and split, export (#18742).** A profile now has a **Graph**: a drawing of the person, the things they touched and the other people on those things, read from the customer graph; clicking another person opens their profile, and a read-only user's graph holds only themselves. The owner and read-write users can **merge** a customer into another when they are the same person (identities, tags, goals and activity move across, and two dashboard users are never merged), **undo** a merge exactly (only what the merge brought goes back), and **split off** an identity, which moves it and the activity it produced to a new customer. The owner can **export** everything held about a person in an in-app viewer (the profile, merge history, hints and up to 10,000 activity references). Four new routes under `/api/customers/{id}`, audited as `customer_merge`, `customer_unmerge`, `customer_split` and `customer_export`; a read-only user can use none of them, including on their own profile.
265 changes: 265 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2129,6 +2129,271 @@
}
}
},
"/api/customers/{id}/merge": {
"post": {
"tags": [
"Customers"
],
"summary": "Merge a customer into this one",
"description": "Folds the customer in from into this one: identities, tags, goals and the activity edges move across, and the merge is recorded so it can be undone. Two dashboard users cannot be merged (409). Owner or read-write. Audited as customer_merge.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Customer id, or me for the viewer's own profile"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"from"
],
"properties": {
"from": {
"type": "string",
"description": "Customer id"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The customer after the change",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Customer profile as the viewer sees it, as returned by GET /api/customers/{id}"
}
}
}
},
"400": {
"description": "Malformed body or nothing to do"
},
"403": {
"description": "Owner or read-write access required"
},
"404": {
"description": "No such customer"
},
"503": {
"description": "Customers are turned off on this hive"
},
"409": {
"description": "Two dashboard users, or a conflicting identity"
}
}
}
},
"/api/customers/{id}/unmerge": {
"post": {
"tags": [
"Customers"
],
"summary": "Undo a merge",
"description": "Restores the customer from as it stood before it was merged into this one, and gives back exactly the identities, tags, goals and activity the merge brought. The pair is remembered as different people. Owner or read-write. Audited as customer_unmerge.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Customer id, or me for the viewer's own profile"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"from"
],
"properties": {
"from": {
"type": "string",
"description": "Customer id"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The customer after the change",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Customer profile as the viewer sees it, as returned by GET /api/customers/{id}"
}
}
}
},
"400": {
"description": "Malformed body or nothing to do"
},
"403": {
"description": "Owner or read-write access required"
},
"404": {
"description": "No such customer"
},
"503": {
"description": "Customers are turned off on this hive"
}
}
}
},
"/api/customers/{id}/split": {
"post": {
"tags": [
"Customers"
],
"summary": "Split identities off into a new customer",
"description": "Moves the named identities (kind:value) off this customer onto a new one, and the activity those identities produced moves with them. A hive user identity cannot be split off and a split must leave an identity behind. Returns the new customer. Owner or read-write. Audited as customer_split.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Customer id, or me for the viewer's own profile"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"identities"
],
"properties": {
"identities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Identity keys, kind:value"
},
"name": {
"type": "string",
"description": "Name for the new customer; defaults to the first identity"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The customer after the change",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Customer profile as the viewer sees it, as returned by GET /api/customers/{id}"
}
}
}
},
"400": {
"description": "Malformed body or nothing to do"
},
"403": {
"description": "Owner or read-write access required"
},
"404": {
"description": "No such customer"
},
"503": {
"description": "Customers are turned off on this hive"
}
}
}
},
"/api/customers/{id}/export": {
"get": {
"tags": [
"Customers"
],
"summary": "Export everything held about a customer",
"description": "Owner only. Returns the profile (including notes, the satisfaction assessment and the merge history), open hints and the references behind the person's activity (at most 10,000), as a JSON download. It holds references, never the content of what they point at. Audited as customer_export.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Customer id, or me for the viewer's own profile"
}
],
"responses": {
"200": {
"description": "The export",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"person": {
"type": "object",
"description": "The full profile"
},
"edges": {
"type": "array",
"items": {
"type": "object",
"description": "person, predicate, artefact, via, source, at"
}
},
"truncated": {
"type": "boolean"
},
"hints": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"403": {
"description": "Owner access required"
},
"404": {
"description": "No such customer"
},
"503": {
"description": "Customers are turned off on this hive"
}
}
}
},
"/api/customers/suggestions/{sid}/accept": {
"post": {
"tags": [
Expand Down
20 changes: 20 additions & 0 deletions src/cmd/hive/customerswire.go
Original file line number Diff line number Diff line change
Expand Up @@ -210,3 +210,23 @@ func installCustomersAgentContext(c *customersDashboard, setKickLookup func(sche
setKickLookup(c.svc.KickContext)
}
}

func (c *customersDashboard) Merge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) {
return customerResult(c.svc.Merge(customersViewer(v), id, from))
}

func (c *customersDashboard) Unmerge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) {
return customerResult(c.svc.Unmerge(customersViewer(v), id, from))
}

func (c *customersDashboard) Split(v dashboard.CustomersViewer, id string, keys []string, name string) (dashboard.CustomerResult, error) {
return customerResult(c.svc.Split(customersViewer(v), id, keys, name))
}

func (c *customersDashboard) Export(v dashboard.CustomersViewer, id string) (any, error) {
out, err := c.svc.Export(customersViewer(v), id)
if err != nil {
return nil, customersError(err)
}
return out, nil
}
4 changes: 2 additions & 2 deletions src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh
| Inception | [`api-reference/inception.md`](api-reference/inception.md) | 14 |
| Beads | [`api-reference/beads.md`](api-reference/beads.md) | 5 |
| Sessions | [`api-reference/sessions.md`](api-reference/sessions.md) | 8 |
| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 9 |
| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 13 |
| Dashboard miscellaneous | [`api-reference/dashboard-misc.md`](api-reference/dashboard-misc.md) | 56 |
| Hub SaaS | [`api-reference/hub-saas.md`](api-reference/hub-saas.md) | 102 |
| Hub server | [`api-reference/hub-server.md`](api-reference/hub-server.md) | 46 |
Expand Down Expand Up @@ -82,7 +82,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh

## Customers

9 routes — see [api-reference/customers.md](api-reference/customers.md).
13 routes — see [api-reference/customers.md](api-reference/customers.md).

## Dashboard miscellaneous

Expand Down
20 changes: 12 additions & 8 deletions src/docs/api-reference/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,18 @@ The rules are enforced twice: by the handlers and again by the store's service o

| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:141` |
| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:142` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:143` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:144` |
| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:145` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:146` |
| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:147` |
| `POST` | `/api/customers/hints/{hid}/answer` | Full view | Answer a "Same person?" question: `{same}`. `true` makes the suggested identity the customer's own and deletes the suggestion; `false` closes the question for good. A question between two customers is answered by merging them, so `true` on one is 400. Audited as `customer_hint_answer` | `pkg/dashboard/api_customers.go:148` |
| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:164` |
| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:165` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:166` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:167` |
| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:168` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:169` |
| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:170` |
| `POST` | `/api/customers/hints/{hid}/answer` | Full view | Answer a "Same person?" question: `{same}`. `true` makes the suggested identity the customer's own and deletes the suggestion; `false` closes the question for good. A question between two customers is answered by merging them, so `true` on one is 400. Audited as `customer_hint_answer` | `pkg/dashboard/api_customers.go:171` |
| `POST` | `/api/customers/{id}/merge` | Full view | Fold the customer `{from}` into this one: identities, tags, goals and activity move across and the merge is recorded. 409 for two dashboard users. Audited as `customer_merge` | `pkg/dashboard/api_customers.go:172` |
| `POST` | `/api/customers/{id}/unmerge` | Full view | Undo a merge: `{from}` comes back as it stood, with exactly what the merge brought it. Audited as `customer_unmerge` | `pkg/dashboard/api_customers.go:173` |
| `POST` | `/api/customers/{id}/split` | Full view | Move identities `{identities: ["kind:value"], name?}` off this customer onto a new one, with the activity they produced; returns the new customer. Audited as `customer_split` | `pkg/dashboard/api_customers.go:174` |
| `GET` | `/api/customers/{id}/export` | Owner only | Everything held about one customer as a JSON download: the profile, merge history, hints and up to 10,000 activity references. Audited as `customer_export` | `pkg/dashboard/api_customers.go:175` |
| `POST` | `/api/graph` | Signed-in user | The customer graph over GraphQL, read-only (no mutations, so a read-only user may call it): `{query, operationName?, variables?}`, answered with a GraphQL `{data, errors}` document. Access follows the viewer exactly as above; see [the customer graph](#the-customer-graph). Audited as `customer_graph_query` with the operation name, node count and error count, never the query text | `pkg/dashboard/api_graph.go:47` |

## The customer graph
Expand Down
Loading
Loading