picked 0.0.101-next.2 → 0.0.101

package/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md

@@ -0,0 +1,72 @@
+---
+type: reference
+layout: docs
+---
+
+# Keyboard shortcuts
+
+These shortcuts work when the canvas of the flow builder holds the keyboard input.
+
+## Canvas tools
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `V` | `V` | The choose tool |
+| `H` | `H` | The hand tool, which pans the view |
+| `Space`, held | `Space`, held | The hand tool, while you hold the key |
+
+## Layout
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Shift+L` | `Shift+L` | Auto-layout |
+
+## Choice
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+A` | `Ctrl+A` | Choose every node |
+| `Escape` | `Escape` | Choose no node |
+
+## Edits
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+D` | `Ctrl+D` | Make a copy of each chosen node |
+| `Delete` or `Backspace` | `Delete` or `Backspace` | Delete each chosen node |
+| `Cmd+Z` | `Ctrl+Z` | Undo |
+| `Cmd+Shift+Z` | `Ctrl+Shift+Z` | Redo |
+
+## Movement
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Arrow keys | Arrow keys | Move each chosen node a small distance |
+| `Shift` and an arrow key | `Shift` and an arrow key | Move each chosen node further |
+
+## Zoom
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Scroll | Scroll | Zoom in or out |
+| Pinch | Pinch | Zoom in or out, on a trackpad |
+| `Cmd+=` | `Ctrl+=` | Zoom in |
+| `Cmd+-` | `Ctrl+-` | Zoom out |
+| `Shift+1` | `Shift+1` | Fit the flow to the view |
+| `Shift+0` | `Shift+0` | Zoom to 100% |
+
+## Panels
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+\` | `Ctrl+\` | Turn both side panels on or off |
+| `?` | `?` | Turn this shortcut list on or off |
+
+---
+
+[Overview](/reference/dashboard/flow-builder/canvas) · [Nodes](/reference/dashboard/flow-builder/nodes) · [Build Flows](/how-to/build-a-flow) · **Keyboard Shortcuts** · [Condition Builder](/reference/dashboard/flow-builder/condition-builder)
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow)
+- [Canvas](/reference/dashboard/flow-builder/canvas) — the panels and the view controls.

package/docs/reference/dashboard/flow-builder/nodes.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Nodes
+
+A node is one part of a flow. Each node stands for a block in your experience. There
+are four node types.
+
+## Origin
+
+Every flow starts with an origin node. It is a gray circle on the left side of the
+canvas, and it has one output handle on its right side.
+
+You cannot move the origin, delete it, or make a copy of it. It is always there.
+
+## Step
+
+A step node stands for a screen that a visitor sees. It appears as a blue rectangle
+on the canvas.
+
+A step holds fields. Drag a field from the library onto a step node to assign
+it. The subtitle of the node gives the number of assigned fields.
+
+Each step has a `layoutName`. It tells the SDK which visual layout to use for this
+step. Set the layout name in the inspector.
+
+## Action
+
+An action node stands for a side effect. A side effect happens where the visitor
+cannot see it. The node appears as a green rectangle.
+
+An action runs when the flow reaches it. Use an action to record an event, to send
+data, or to start an integration.
+
+## Condition
+
+A condition node stands for a point where the flow splits. It appears as an amber
+rectangle.
+
+A condition node has two output handles, and not one. The green handle at the top
+right connects to the path for a true result. The red handle at the bottom right
+connects to the path for a false result.
+
+Define the rule in the inspector, with the visual condition builder. See
+[Conditions](/reference/dashboard/conditions) for more detail.
+
+## Handles
+
+A handle is a connection point on a node. An input handle is on the left. An output
+handle is on the right. Drag from an output handle to an input handle to connect two
+nodes.
+
+---
+
+[Overview](/reference/dashboard/flow-builder/canvas) · **Nodes** · [Build Flows](/how-to/build-a-flow) · [Keyboard Shortcuts](/reference/dashboard/flow-builder/keyboard-shortcuts) · [Condition Builder](/reference/dashboard/flow-builder/condition-builder)
+
+## API and MCP
+
+You can also do this task with the [Management API](/reference/management-api/schema), the [MCP server](/reference/tools/mcp), or code that you send to [`picked_run`](/reference/tools/mcp-run).
+
+| Task | GraphQL | MCP tool | Run |
+| --- | --- | --- | --- |
+| Assign fields to a step | [`stepUpdate`](/reference/management-api/schema/step#stepupdate), [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, update_steps })` |
+| Set the layout name of a step | [`stepUpdate`](/reference/management-api/schema/step#stepupdate), [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, update_steps })` |
+| Set the rule of a condition | [`conditionUpdate`](/reference/management-api/schema/condition#conditionupdate), [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, update_conditions })` |
+| Connect two nodes | [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, create_edges })` |
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow)
+- [Canvas](/reference/dashboard/flow-builder/canvas)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/docs/reference/dashboard/labels.md

@@ -0,0 +1,321 @@
+---
+type: reference
+layout: docs
+---
+
+# Labels
+
+A label is a name and a value on a lead, a project or a workflow run. A workflow sets and
+removes labels with tool nodes. A label can expire, a write can be conditional, and a node
+can increment a `number` label.
+
+## Name, type and value
+
+| Part      | Format                                                                                                                      |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Namespace | 1 to 64 characters. Each character is a lowercase letter, a digit, `_` or `-`.                                              |
+| Key       | 1 to 64 characters. Each character is a lowercase letter, a digit, `_` or `-`.                                              |
+| Type      | `text`, `number`, `boolean` or `json`. It tells how to read the value.                                                      |
+| Value     | Text. A `number` label holds a number, a `boolean` label holds `true` or `false`, and a `json` label holds a JSON document. |
+
+The lead, the project or the run that has a label is the owner of the label. An owner has
+one label for each namespace and key.
+
+## Owners
+
+| Owner        | Where the labels stay                                                                                        | Scope to read the labels     | Scope to set and remove the labels |
+| ------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------- |
+| Lead         | Until you delete the lead. Picked deletes the labels of a lead with the lead.                                | `ORGANIZATION_LEADS_READ`    | `ORGANIZATION_LEADS_UPDATE`        |
+| Project      | Picked keeps the labels when you delete the project. These labels hold data for all the runs of the project. | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE`     |
+| Workflow run | With the run. Picked does not delete a run.                                                                  | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE`     |
+
+A run reads, sets and removes its own labels without a scope.
+
+## Labels in the dashboard
+
+The **Labels** card shows the labels of one owner, in one section for each namespace.
+
+| Page           | Where the card shows                                                                                             | Scope to change the labels     |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| Lead           | Next to the responses, or below them on a medium screen. On a narrow screen, it is on the **Labels** tab.        | `ORGANIZATION_LEADS_UPDATE`    |
+| Project labels | At `…/<project>/labels`. **Project labels** in the project menu opens the page for `ORGANIZATION_PROJECTS_READ`. | `ORGANIZATION_PROJECTS_UPDATE` |
+| Run            | Below the details of the run. On a narrow screen, the card is on the **Labels** tab.                             | `ORGANIZATION_PROJECTS_UPDATE` |
+
+The project settings also have a **Labels** link to the Project labels page. To open the project
+settings, you must have `ORGANIZATION_PROJECTS_UPDATE`.
+
+Without the scope, the card shows the labels, and you cannot change them.
+
+With the scope, the card has these controls:
+
+| Control       | Result                                                                                        |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| The value     | Changes the value of the label.                                                               |
+| **Add label** | Adds a label with a namespace, a key, a type and a value. This label does not expire.         |
+| **×**         | Removes the label.                                                                            |
+| **Save**      | Sets and removes the labels that you changed. Picked does not change a label before **Save**. |
+| **Discard**   | Removes your changes.                                                                         |
+
+A label with an expiry shows the time until it expires. You can remove it, but you cannot
+change its value.
+
+## Visitor data in project and run labels
+
+The labels of a project and of a run stay after Picked deletes a lead. Picked does not delete
+visitor data in a project label or a run label with the lead. Visitor data is, for example, an
+email address, a phone number or a visitor ID.
+
+A project label or a run label can have the `sha256` hash of a visitor identifier as its key.
+With a hash, a workflow can hold a label for one visitor across runs. Use `expiresIn` to set
+how long the label stays. Refer to [Example: one run at a time for each visitor](#example-one-run-at-a-time-for-each-visitor).
+
+## Tools
+
+| Tool                    | Name in the editor        | Owner                           | Output                             | Scopes                                                                                 |
+| ----------------------- | ------------------------- | ------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `set_lead_labels`       | **Set lead labels**       | The lead in its `lead` argument | `lead` and `count`                 | `ORGANIZATION_LEADS_UPDATE` and `ORGANIZATION_LEADS_READ`                              |
+| `remove_lead_labels`    | **Remove lead labels**    | The lead in its `lead` argument | `lead` and `removed`               | `ORGANIZATION_LEADS_UPDATE` and `ORGANIZATION_LEADS_READ`                              |
+| `create_lead`           | **Create lead**           | The lead that it makes          | `lead`, `created` and `labelCount` | `ORGANIZATION_LEADS_CREATE`, `ORGANIZATION_LEADS_READ` and `ORGANIZATION_LEADS_UPDATE` |
+| `set_project_labels`    | **Set project labels**    | The project of the run          | `project` and `count`              | `ORGANIZATION_PROJECTS_UPDATE` and `ORGANIZATION_PROJECTS_READ`                        |
+| `remove_project_labels` | **Remove project labels** | The project of the run          | `project` and `removed`            | `ORGANIZATION_PROJECTS_UPDATE` and `ORGANIZATION_PROJECTS_READ`                        |
+| `get_project`           | **Get project**           | The project of the run          | `project`                          | `ORGANIZATION_PROJECTS_READ`                                                           |
+| `set_run_labels`        | **Set run labels**        | The run                         | `run` and `count`                  | None                                                                                   |
+| `remove_run_labels`     | **Remove run labels**     | The run                         | `run` and `removed`                | None                                                                                   |
+| `get_run`               | **Get run**               | The run                         | `run`                              | None                                                                                   |
+
+**Set project labels**, **Remove project labels**, **Set run labels**, **Remove run labels**,
+**Get project** and **Get run** have no argument for the owner.
+
+The `lead`, `project` and `run` outputs hold the labels of the owner at the time that a later
+node reads them, as `labels.<namespace>.<key>`:
+
+| Output    | Fields                    |
+| --------- | ------------------------- |
+| `lead`    | The lead, and `labels`    |
+| `project` | `id`, `name` and `labels` |
+| `run`     | `id` and `labels`         |
+
+For example, `{{ nodes.project.project.labels.cms.sent_today }}` reads the label
+`cms.sent_today` of the project.
+
+When Picked refuses the labels of a node, or cannot find the owner, the node fails with the
+code `tool_failed`. Its reason is the error code in lowercase, such as `label_write_invalid`,
+`value_invalid_for_type` or `owner_not_found`. An edge on the error exit of the node can
+continue the run. Refer to the [workflow runs reference](/reference/dashboard/workflow-runs#run-status).
+
+## Labels in a test run
+
+For the run tools in a test run, refer to
+[What runs](/reference/dashboard/workflow-test-runs#what-runs).
+
+## A row that sets a label
+
+The `labels` argument of **Set lead labels**, **Set project labels**, **Set run labels** and
+**Create lead** is a list of rows. Each row sets one label.
+
+| Field          | Type              | Default                                | Description                                                                                                               |
+| -------------- | ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `namespace`    | Text              | —                                      | The namespace of the label.                                                                                               |
+| `key`          | Text              | —                                      | The key of the label.                                                                                                     |
+| `type`         | Text              | `number` with `increment`, else `text` | The type of the label.                                                                                                    |
+| `value`        | Text              | —                                      | The value of the label.                                                                                                   |
+| `increment`    | Number            | —                                      | An amount to add to the value of a `number` label. Refer to [Increments](#increments).                                    |
+| `expiresIn`    | Number            | No expiry                              | The number of seconds until the label expires, from 1 to 31536000. Refer to [Expiry](#expiry).                            |
+| `onlyIfAbsent` | `true` or `false` | `false`                                | When `true`, the row sets the label only when the owner does not have it. Refer to [Conditional rows](#conditional-rows). |
+
+A row has `value` or `increment`. It cannot have both. When you save a workflow, Picked
+refuses a row that has both, or neither.
+
+A row with a `value` and no `expiresIn` sets a label that does not expire. If the label had
+an expiry, the row removes it.
+
+The namespace, the key, `value`, `increment` and `expiresIn` can have a template. Refer to
+[Workflow templates](/reference/dashboard/workflow-templates).
+
+### Rows in the workflow editor
+
+In the workflow editor, each row has an **Operation** list:
+
+| Operation     | Fields                             | The row that Picked saves   |
+| ------------- | ---------------------------------- | --------------------------- |
+| **Set**       | **Value**                          | `value`                     |
+| **Increment** | **Amount**: a number or a template | `increment` with the amount |
+
+To make the value smaller, give a negative amount. For example, the amount `-3` saves `increment: -3`, and
+the amount `-{{ trigger.cost }}` saves `increment: "-{{ trigger.cost }}"`.
+
+With **Increment**, the type is always `number`. When you change the operation to
+**Increment**, the editor removes `value` and `onlyIfAbsent` and sets the amount to 1. When you
+change it to **Set**, the editor removes `increment`.
+
+**Expires after (seconds)** sets `expiresIn`. It accepts a number or a template. When the
+field is empty, the row has no `expiresIn`.
+
+With **Set**, the **Only while the owner does not hold it** checkbox sets `onlyIfAbsent: true`.
+When the checkbox is clear, the row has no `onlyIfAbsent`.
+
+The full `labels` argument can also be one template. The editor then shows the template, and
+it shows no rows. **Replace with rows** removes the template after you confirm it.
+
+## Expiry
+
+A label with `expiresIn` expires that number of seconds after the node sets it. Picked does
+not show an expired label:
+
+- The `lead`, `project` or `run` output of a tool does not have it.
+- A lead search clause does not match it. A negative clause, such as `-cms.status:*`, matches
+  the lead.
+- A lead sorts as if it does not have the label.
+- The pages of the dashboard do not show it.
+
+A row that sets an expired label makes a new label, with a new ID. The task records it as
+created.
+
+Picked deletes an expired label within 15 minutes after it expires. This delete does not
+record an operation.
+
+## Conditional rows
+
+A row with `onlyIfAbsent: true` sets its label only when the owner does not have a label with
+its namespace and key. An expired label does not count. Picked does the check and the write in
+one step. When two nodes set the same absent label at the same time, only one of them sets it.
+
+When the owner has the label already:
+
+| The label has                     | Result                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------- |
+| The type and the value of the row | The node takes the label. Picked does not change it and does not record an operation. |
+| A different type or value         | The node does not take the label. Picked does not change it, its value or its expiry. |
+
+When the value is an ID unique to one run, such as `{{ run.id }}`, only one run can hold the
+label at a time. When Picked starts a node again after the node set its label, the node takes
+the label again with the same result.
+
+A row with `increment` cannot have `onlyIfAbsent`.
+
+## Atomic writes
+
+**Set lead labels**, **Set project labels** and **Set run labels** have an `atomic`
+argument. In the workflow editor, it is the **Atomic** checkbox. When it is `true`, the node
+takes all of its labels or none of them. If one conditional row does not take its label, the
+node sets no label, records no operation, and gives a `count` of 0.
+
+Two nodes with `atomic` can run at the same time. If both nodes set the same label with
+`onlyIfAbsent` and a value unique to each node, one node at most takes its labels.
+
+## Increments
+
+A row with `increment` adds that amount to the value of a `number` label. When the owner does
+not have the label, or the label expired, the value starts at 0. When many nodes add to the
+same label at the same time, the label counts each amount.
+
+| Rule                        | Description                                                                                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Type                        | The row must be of type `number`, which is the default with `increment`. When you save a workflow, Picked refuses a row with a different type.                           |
+| A label of a different type | The node fails with the code `tool_failed` and the reason `value_invalid_for_type`. Picked does not change the label.                                                    |
+| Expiry                      | The label keeps its expiry. The `expiresIn` of the row applies only when the row makes the label. So the label expires at a fixed time after the first row that made it. |
+| Operations                  | Each row with `increment` records an operation.                                                                                                                          |
+
+When Picked starts a node again after it added its amount, the node adds the amount again.
+
+## A row that removes a label
+
+The `labels` argument of **Remove lead labels**, **Remove project labels** and **Remove run
+labels** is a list of rows. Each row removes one label.
+
+| Field       | Type | Default   | Description                                                                                       |
+| ----------- | ---- | --------- | ------------------------------------------------------------------------------------------------- |
+| `namespace` | Text | —         | The namespace of the label.                                                                       |
+| `key`       | Text | —         | The key of the label.                                                                             |
+| `ifValue`   | Text | Any value | When it is set, the row removes the label only when the value of the label is equal to `ifValue`. |
+
+Picked does the check and the remove in one step. A row with `ifValue: "{{ run.id }}"`
+removes the label only while this run holds it. It does not remove the label when a different
+run holds it.
+
+In the workflow editor, **Only while its value is** sets `ifValue`. It accepts text or a
+template. When the field is empty, the row has no `ifValue`.
+
+A row that names a label that the owner does not have removes nothing. An expired label counts
+as no label.
+
+## Count and removed
+
+| Output       | Value                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `count`      | The number of labels that the node took. The node takes a label when it sets it, or when a conditional row finds the label with its own type and value. |
+| `labelCount` | The same as `count`, for **Create lead**.                                                                                                               |
+| `removed`    | The number of labels that the node removed.                                                                                                             |
+
+## Example: one run at a time
+
+This **Set lead labels** node holds a label for one hour, unless a different run holds it:
+
+```json
+{
+  "lead": "{{ nodes.lead.lead }}",
+  "labels": [
+    {
+      "namespace": "cms",
+      "key": "request-callback",
+      "value": "{{ run.id }}",
+      "onlyIfAbsent": true,
+      "expiresIn": 3600
+    }
+  ]
+}
+```
+
+When `count` is 1, the run holds the label. This **Remove lead labels** node removes the label
+only while the run holds it:
+
+```json
+{
+  "lead": "{{ nodes.lead.lead }}",
+  "labels": [{ "namespace": "cms", "key": "request-callback", "ifValue": "{{ run.id }}" }]
+}
+```
+
+## Example: one run at a time for each visitor
+
+This **Set project labels** node holds a label for the visitor of the run for one hour,
+unless a different run holds it. The key is the `sha256` hash of the visitor ID, and the label
+expires. Refer to [the rule for visitor data](#visitor-data-in-project-and-run-labels).
+
+```json
+{
+  "labels": [
+    {
+      "namespace": "cms-lock-visitor",
+      "key": "{{ trigger.action.userId | default: run.id | sha256 }}",
+      "value": "{{ run.id }}",
+      "onlyIfAbsent": true,
+      "expiresIn": 3600
+    }
+  ]
+}
+```
+
+When `count` is 1, the run holds the label. This **Remove project labels** node removes the
+label only while the run holds it:
+
+```json
+{
+  "labels": [
+    {
+      "namespace": "cms-lock-visitor",
+      "key": "{{ trigger.action.userId | default: run.id | sha256 }}",
+      "ifValue": "{{ run.id }}"
+    }
+  ]
+}
+```
+
+## Related
+
+- [Workflow runs](/reference/dashboard/workflow-runs) — the error exit of a node, and the
+  operations that a task records.
+- [Workflow templates](/reference/dashboard/workflow-templates) — the `sha256` filter and the
+  `run.id` variable.
+- [Lead search](/reference/dashboard/lead-search) — clauses on labels.
+- [Glossary](/reference/glossary) — label, namespace and label type.