picked 0.0.102 → 0.0.103-next.2

package/docs/reference/dashboard/external-apis.md

@@ -59,6 +59,9 @@ OAuth2 credential.
 
 - Picked sends the token request as a `POST` with a form body, so no secret is in a URL.
 - Picked uses an access token until 60 seconds before it expires.
+- **Refresh credentials** on the page of the external API gets a new access token
+  immediately. The page then shows the time of the last refresh, or the reason for the
+  failure.
 - Picked reads the lifetime from `expires_in_sec`, or else from `expires_in`. Picked keeps
   a token with no lifetime for one hour.
 - Picked counts an answer as a success when its JSON body has an `access_token`, for all
@@ -176,6 +179,7 @@ You can also do this task with the [Management API](/reference/management-api/sc
 | --- | --- | --- | --- |
 | Register an external API | [`externalApiCreate`](/reference/management-api/schema/external-api#externalapicreate) | None | None |
 | Set or replace the authorization header | [`externalApiAuthHeaderSet`](/reference/management-api/schema/external-api#externalapiauthheaderset) | None | None |
+| Get a new OAuth2 access token | [`externalApiOAuth2Refresh`](/reference/management-api/schema/external-api#externalapioauth2refresh) | None | None |
 | Delete a registration | [`externalApiDelete`](/reference/management-api/schema/external-api#externalapidelete) | None | None |
 | Set the arguments of an External API node | [`workflowGraphUpdate`](/reference/management-api/schema/workflow#workflowgraphupdate) | [`update_workflow_graph`](/reference/tools/mcp#update_workflow_graph) | `tools.update_workflow_graph({ workflow_id, update_nodes })` |
 

package/docs/reference/dashboard/labels.md

@@ -35,13 +35,13 @@ A run reads, sets and removes its own labels without a scope.
 
 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` |
+| 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>/settings/labels`. The page opens 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
+The project settings 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.

package/docs/reference/dashboard/workflow-tools.md

@@ -0,0 +1,55 @@
+---
+type: reference
+layout: docs
+---
+
+# Workflow tools
+
+A tool node runs one tool. The inspector of the node shows the name of the tool and a short
+description. This page gives the full reference for each tool.
+
+The header of a tool node shows the name of the tool. To show a different name on the node,
+type it in the **Title** field of the inspector. A title can have 80 characters or fewer. A
+condition node also has a **Title** field. Without a title, a condition node shows its rules
+in short form.
+
+## Tools
+
+| Tool                    | Name in the editor        | What it does                                                                                                  | Output                                                   |
+| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `workflow_noop`         | **Log a message**         | Records the text in its `message` argument on the node.                                                       | `message`                                                |
+| `search_leads`          | **Search leads**          | Finds the leads that match a query in the leads query language, the newest lead first. It finds 20 or fewer.  | `leads`                                                  |
+| `get_lead`              | **Get lead**              | Reads the lead of the visitor whose action started the run. `exists` is `false` when the visitor has no lead. | `lead` and `exists`                                      |
+| `create_lead`           | **Create lead**           | Creates a lead for the visitor, and sets the labels in its `labels` argument on it.                           | `lead`, `created` and `labelCount`                       |
+| `set_lead_labels`       | **Set lead labels**       | Adds labels to the lead in its `lead` argument, or changes them.                                              | `lead` and `count`                                       |
+| `remove_lead_labels`    | **Remove lead labels**    | Removes labels from the lead in its `lead` argument.                                                          | `lead` and `removed`                                     |
+| `set_project_labels`    | **Set project labels**    | Adds labels to the project of the run, or changes them.                                                       | `project` and `count`                                    |
+| `remove_project_labels` | **Remove project labels** | Removes labels from the project of the run.                                                                   | `project` and `removed`                                  |
+| `get_project`           | **Get project**           | Reads the project of the run and its labels.                                                                  | `project`                                                |
+| `set_run_labels`        | **Set run labels**        | Adds labels to the run, or changes them.                                                                      | `run` and `count`                                        |
+| `remove_run_labels`     | **Remove run labels**     | Removes labels from the run.                                                                                  | `run` and `removed`                                      |
+| `get_run`               | **Get run**               | Reads the run and its labels.                                                                                 | `run`                                                    |
+| `http`                  | **External API**          | Sends a request to an external API that the project registered. The registration holds the credential.        | `status`, `ok`, `body`, `bodyTruncated` and `durationMs` |
+| `action_response`       | **Action response**       | Sends the payload in its `payload` argument to the visitor who started the action in its `actionId` argument. | `actionId` and `recorded`                                |
+
+## Labels
+
+A row of a label tool can expire. It can set a label only when the owner does not have it. It
+can add to a `number` label. A row of a remove tool can remove a label only when the label
+has a given value. For the arguments, the outputs and the scopes of the label tools, refer to
+the [labels reference](/reference/dashboard/labels#tools).
+
+## External APIs
+
+For the arguments of **External API** and how to register an API, refer to
+[Call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow).
+
+## Action responses
+
+For **Action response**, refer to
+[Wait for an action response](/how-to/wait-for-an-action-response).
+
+## Failures
+
+When a tool fails, the node fails. 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).

package/docs/reference/management-api/schema/external-api.md

@@ -78,6 +78,16 @@ Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 externalApiOAuth2Clear(input: ExternalApiOAuth2ClearInput!): ExternalApiOAuth2ClearPayload! @auth(only: USER)
 ```
 
+### `externalApiOAuth2Refresh`
+
+Fetches a new access token for the OAuth2 credential of an external API now, in place of any
+cached one. An external API with no OAuth2 credential is refused.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
+
+```graphql
+externalApiOAuth2Refresh(input: ExternalApiOAuth2RefreshInput!): ExternalApiOAuth2RefreshPayload! @auth(only: USER)
+```
+
 ### `externalApiDelete`
 
 Deletes an external API and its credential. Workflows then cannot call its origin.
@@ -521,6 +531,16 @@ input ExternalApiOAuth2ClearInput {
 }
 ```
 
+### `ExternalApiOAuth2RefreshInput`
+
+```graphql
+"""The input of `externalApiOAuth2Refresh`."""
+input ExternalApiOAuth2RefreshInput {
+  """The ID of the external API."""
+  id: ID!
+}
+```
+
 ### `ExternalApiDeleteInput`
 
 ```graphql
@@ -606,6 +626,21 @@ type ExternalApiOAuth2ClearPayload {
 }
 ```
 
+### `ExternalApiOAuth2RefreshPayload`
+
+```graphql
+"""The result of `externalApiOAuth2Refresh`."""
+type ExternalApiOAuth2RefreshPayload {
+  """
+  The external API after the refresh. `oauth2.lastRefreshedAt` moves on a new token, and
+  `oauth2.lastRefreshFailure` says why there is none.
+  """
+  externalApi: ExternalApi
+  """The errors. Always empty."""
+  errors: [UserError!]!
+}
+```
+
 ### `ExternalApiDeletePayload`
 
 ```graphql

package/docs/reference/management-api/schema/index.md

@@ -79,6 +79,7 @@ An operation with `@auth` needs a caller that has authenticated. `@auth(only: US
 | [`externalApiCreate`](/reference/management-api/schema/external-api#externalapicreate) | Mutation | Creates an external API in a project, with an optional credential. Scope: `ORGANIZATION_INTEGRATIONS_CREATE`. |
 | [`externalApiDelete`](/reference/management-api/schema/external-api#externalapidelete) | Mutation | Deletes an external API and its credential. Workflows then cannot call its origin. Scope: `ORGANIZATION_INTEGRATIONS_DELETE`. |
 | [`externalApiOAuth2Clear`](/reference/management-api/schema/external-api#externalapioauth2clear) | Mutation | Removes the OAuth2 credential of an external API, with its secrets and cached access token. An external API with no OAuth2 credential is unchanged. Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`. |
+| [`externalApiOAuth2Refresh`](/reference/management-api/schema/external-api#externalapioauth2refresh) | Mutation | Fetches a new access token for the OAuth2 credential of an external API now, in place of any cached one. An external API with no OAuth2 credential is refused. Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`. |
 | [`externalApiOAuth2Set`](/reference/management-api/schema/external-api#externalapioauth2set) | Mutation | Sets the OAuth2 credential of an external API, and removes any static auth header. The next call fetches a new access token. Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`. |
 | [`externalApiUpdate`](/reference/management-api/schema/external-api#externalapiupdate) | Mutation | Updates the name of an external API. To change the origin, delete it and create another. Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`. |
 | [`feature`](/reference/management-api/schema/feature#feature) | Query | Reads a feature flag by its ID and workspace. Scope: `ORGANIZATION_WORKSPACE_READ`. |

package/docs/reference/management-api/schema/workflow.md

@@ -175,6 +175,12 @@ enum WorkflowEventName {
   CONDITION_DELETED
   """An action was deleted."""
   ACTION_DELETED
+  """A lead was created."""
+  LEAD_CREATED
+  """
+  A person or an API key changed a lead. A change a workflow run makes starts no workflow.
+  """
+  LEAD_UPDATED
 }
 ```
 
@@ -305,6 +311,10 @@ type WorkflowToolNode implements WorkflowNode {
   tool: String!
   """The values of the arguments of the tool."""
   configuration: JSON!
+  """
+  The title the author gave the node. Null when the canvas shows the name of the tool.
+  """
+  title: String
 }
 ```
 
@@ -323,6 +333,10 @@ type WorkflowConditionNode implements WorkflowNode {
   position: Position!
   """The rule the node evaluates."""
   logic: JSON!
+  """
+  The title the author gave the node. Null when the canvas shows a summary of the rule.
+  """
+  title: String
 }
 ```
 
@@ -373,6 +387,8 @@ input WorkflowToolNodeInput {
   The values of the arguments of the tool. Omit for a tool with no arguments.
   """
   configuration: JSON
+  """A title for the node, at most 80 characters. Omit for none."""
+  title: String
 }
 ```
 
@@ -383,6 +399,8 @@ input WorkflowToolNodeInput {
 input WorkflowConditionNodeInput {
   """The rule the node evaluates."""
   logic: JSON!
+  """A title for the node, at most 80 characters. Omit for none."""
+  title: String
 }
 ```
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "picked",
   "description": "The Picked SDK front door: the client, the picked.config helpers, and the picked CLI in one install",
-  "version": "0.0.102",
+  "version": "0.0.103-next.2",
   "bin": {
     "picked": "dist/esm/bin.js"
   },
   "dependencies": {
-    "@picked/cli": "0.0.102",
-    "@picked/config": "0.0.102"
+    "@picked/cli": "0.0.103-next.2",
+    "@picked/config": "0.0.103-next.2"
   },
   "devDependencies": {
     "@picked/client": "workspace:*",
@@ -64,7 +64,7 @@
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "peerDependencies": {
-    "@picked/client": "0.0.102"
+    "@picked/client": "0.0.103-next.2"
   },
   "private": false,
   "publishConfig": {