@picked/client 0.0.84 → 0.0.85-next.2

package/dist/docs/how-to/set-up-mfa.md

@@ -5,38 +5,60 @@ layout: docs
 
 # How to set up MFA
 
-This guide shows you how to add a second factor to an account. Every MFA mutation needs
-authentication.
+This guide shows you how to add an authenticator app to an account, and how to sign in
+with it. Picked supports TOTP authenticator apps only, such as Google Authenticator.
+Every MFA mutation needs authentication.
 
-## 1. Add a factor
+## Who must use MFA
+
+Picked staff, and every member of an organization that requires MFA, must sign in with an
+authenticator app. For these users, a session at `AAL1` can only read `user` and call the
+MFA mutations. Every other operation returns the error code `MFA_REQUIRED` until the
+session reaches `AAL2`. The `user.mfa` field tells you where a user stands:
+
+```graphql
+query {
+  user {
+    mfa { required reason enrolled satisfied }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `required` | The user must hold an `AAL2` session to use the fields that need it. |
+| `reason` | `STAFF` or `ORGANIZATION`. Empty when `required` is false. |
+| `enrolled` | The user holds a verified authenticator. |
+| `satisfied` | The session that made the request meets the requirement. |
+
+## 1. Add an authenticator
 
 ```graphql
 mutation {
-  mfaFactorEnroll(input: {
-    factorType: PHONE
-    phone: "+15551234567"
-    friendlyName: "My Phone"
-  }) {
+  mfaFactorEnroll(input: { friendlyName: "Work phone" }) {
     factor { id factorType status }
+    totp { qrCode secret uri }
   }
 }
 ```
 
-A new factor has the status `UNVERIFIED`.
+A new factor has the status `UNVERIFIED`. Show `qrCode` (SVG markup) for the user to scan,
+or `secret` for the user to enter into the app. The API returns it one time only.
+The mutation first deletes the caller's factors that are not verified, so a setup that did
+not finish does not block a new one.
 
-## 2. Send a challenge
+## 2. Open a challenge
 
 ```graphql
 mutation {
-  mfaChallengeSend(input: { factorId: "factor-id" }) {
+  mfaChallengeCreate(input: { factorId: "factor-id" }) {
     challengeId
+    expiresAt
   }
 }
 ```
 
-This sends a code to the telephone number of the factor.
-
-## 3. Verify the challenge
+## 3. Verify the code
 
 ```graphql
 mutation {
@@ -50,9 +72,17 @@ mutation {
 }
 ```
 
-The session moves to `AAL2`, and the factor status changes to `VERIFIED`.
+The session moves to `AAL2`, and the factor status changes to `VERIFIED`. Use the returned
+tokens from this point. A wrong code returns `MFA_CHALLENGE_FAILED`.
+
+## Sign in with an authenticator
 
-## Remove a factor
+After `sessionCreate`, the session is at `AAL1`. When `session.user.mfa.enrolled` is
+`true`, do steps 2 and 3 against one of the user's verified factors. The query
+`user { mfaFactors { id status } }` lists them. When `required` is `true` and `enrolled`
+is `false`, do steps 1 to 3.
+
+## Remove an authenticator
 
 ```graphql
 mutation {
@@ -62,8 +92,17 @@ mutation {
 }
 ```
 
+To remove a verified factor, the session must be at `AAL2`. An `AAL1` session receives
+`MFA_REQUIRED`.
+
+A user who must use MFA always keeps at least one authenticator. A request to remove
+their last one fails with `VALIDATION_ERROR`. To replace an authenticator, add the new
+one first, then remove the old one. A user with the `users/reset_mfa` scope clears the
+last one with `userMfaReset`.
+
 ## Related
 
-- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — which
-  operations need `AAL2`.
-- [Authentication](/reference/management-api/authentication) — every mutation.
+- [Authentication](/reference/management-api/authentication) — every mutation and the
+  assurance levels.
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — who
+  can reset the MFA of another user.

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

@@ -0,0 +1,65 @@
+---
+type: reference
+layout: docs
+---
+
+# External APIs
+
+An external API is an origin that this project's workflows are allowed to call with the
+**External API** node.
+
+## Registration
+
+| Field | Rule |
+| --- | --- |
+| Display name | Required. 1 to 120 characters. For you only; it does not go out with the request. |
+| Origin | Required. The scheme, the host and the optional port, with no path, query, fragment or sign-in details. `http` or `https` only, on port 80 or 443. Must not point at a private, loopback or link-local address. One live registration per origin per project. |
+| Authorization header | Optional. A header name and a value. The value is encrypted and is never returned. The dashboard shows the header name and a mask. |
+
+To change an origin, delete the registration and register the new origin. The origin is
+the registration's identity.
+
+## Node arguments
+
+| Argument | Default | Rule |
+| --- | --- | --- |
+| `method` | — | Required. `GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`. |
+| `url` | — | Required. The full address. Its origin must be registered to this project. |
+| `headers` | none | A JSON object of headers to send. Picked refuses a credential here when you save. |
+| `body` | none | The JSON body. Used by `POST`, `PUT` and `PATCH`. |
+| `timeoutMs` | 10000 | 1000 to 30000. The time that the whole call has, with every retry. |
+| `retry` | on | Whether to send the request again after a timeout, a transport error, a 408 or a 429. |
+| `failOnErrorStatus` | on | Whether a status of 400 or more fails the node. |
+| `recordBody` | on | Whether to record the answer's body. |
+
+## Output
+
+| Name | Value |
+| --- | --- |
+| `status` | The HTTP status, or null when nothing answered. |
+| `ok` | True for a status below 400. |
+| `body` | The parsed JSON answer, or null when it is not JSON or was not recorded. |
+| `bodyTruncated` | True when the answer was too large to record in full. |
+| `durationMs` | The time the call took. |
+
+## Limits
+
+- The request body is limited to 1 MiB.
+- The recorded answer is limited to 256 KiB. A larger answer sets `bodyTruncated`.
+- Picked records the status that asks the caller to redirect. Picked does not go to the
+  new address.
+- Picked sends a request three times at most. Picked waits longer before each retry, and
+  waits for the time that a `Retry-After` header gives.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `no external API is registered for <origin>` | The URL's origin has no live registration in this project. |
+| `the API answered <status>` | The status was 400 or more and `failOnErrorStatus` is on. |
+| `the API did not answer in time` | Nothing answered within `timeoutMs`. |
+| `the API could not be reached` | The connection failed. |
+| `the URL is not allowed` | The URL points at a private, loopback or link-local address. |
+
+Picked also refuses a workflow when you save it if a node holds a credential in
+`headers`. Register the external API, and put the credential on the registration.

package/dist/docs/reference/dashboard/lead-search.md

@@ -0,0 +1,149 @@
+---
+type: reference
+layout: docs
+---
+
+# Lead search
+
+A lead is one set of answers that a visitor gave to your flow. The **Leads** page lists
+them, and it has one search box. The box accepts a plain word, a filter, or both. The
+dashboard holds the query in the address, so you can share the link.
+
+## The three parts of a lead that a query reads
+
+| Part | How to write it | Example |
+| --- | --- | --- |
+| Every captured answer | a plain word | `melbourne` |
+| One label | `namespace.key` | `acme.status:sent` |
+| One answer | the key of the field | `suburb:Sydney` |
+| The capture date | `createdAt` | `createdAt>2026-08-01` |
+| The visitor | `userId` | `userId:sess_7x2k9q3m1n4a` |
+
+A path of two parts is a label, because a label namespace and a label key cannot contain a
+full stop. A path of one part is the key of a field, unless the name is `createdAt` or
+`userId`.
+
+## Operators
+
+| Operator | Meaning | Example |
+| --- | --- | --- |
+| `:` | equal to | `details.phone:"0400000000"` |
+| `~` | contains | `details.email~example.com` |
+| `:*` | the lead has a value | `acme.status:*` |
+| `>` `>=` `<` `<=` | compare a number or a date | `scoring.value>=50` |
+| `-` | makes the clause negative | `-acme.status:*` |
+
+Each part accepts a different set:
+
+| Part | `:` | `~` | `:*` | `>` `>=` `<` `<=` |
+| --- | --- | --- | --- | --- |
+| Label | yes | yes | yes | yes |
+| Answer | yes | yes | yes | no |
+| `createdAt` | yes | no | no | yes |
+| `userId` | yes | no | no | no |
+
+## How clauses combine
+
+A space between two clauses means AND. The word `OR` between them means OR.
+
+```
+acme.status:sent scoring.contacted:true
+acme.status:sent OR acme.status:queued
+```
+
+One query holds a maximum of 10 clauses. One query uses AND or OR, and not both: there is
+no way to show which one comes first. A query that mixes them gives an error.
+
+## Values with a space
+
+Put `"` at each end of a value that has a space. To search for `"` inside a value, write
+`\"`.
+
+```
+details.company:"Acme Corporation"
+```
+
+## Plain words
+
+A plain word searches every answer that the visitor gave, and it includes the text inside
+a JSON answer.
+
+A plain word matches a whole word. `amy@example.com` finds the lead with that address, and
+`example.com` finds nothing. To match a part of a value, name the field and use `~`:
+
+```
+email-address~example.com
+```
+
+Two plain words both must match.
+
+## Examples
+
+**Plain words**
+
+| Query | What it finds |
+| --- | --- |
+| `melbourne` | Leads with `melbourne` in an answer |
+| `amy@example.com` | The lead with that address |
+| `Amy Rockwell` | Leads with both words in their answers |
+| `dental` | Leads with `dental` inside a JSON answer |
+
+**Labels**
+
+| Query | What it finds |
+| --- | --- |
+| `details.phone:"0400000000"` | Leads with that exact telephone number |
+| `details.email~example.com` | Leads with an email label that holds `example.com` |
+| `acme.status:sent` | Leads that the `acme` workflow sent |
+| `acme.status:*` | Leads with an `acme` status |
+| `-acme.status:*` | Leads with no `acme` status, which no workflow took |
+| `scoring.value>=50` | Leads with a score of 50 or more |
+| `scoring.contacted:true` | Leads with that boolean label set to true |
+| `crm.payload:*` | Leads with a JSON label under `crm` |
+
+**Answers and the capture date**
+
+| Query | What it finds |
+| --- | --- |
+| `suburb:Sydney` | Leads whose `suburb` answer is `Sydney` |
+| `email-address~rocketrides` | Leads whose `email-address` answer holds `rocketrides` |
+| `quote-preferences:*` | Leads that answered `quote-preferences` |
+| `createdAt>2026-08-01` | Leads captured after that date |
+| `userId:sess_7x2k9q3m1n4a` | Leads captured for that visitor |
+
+**More than one clause**
+
+| Query | What it finds |
+| --- | --- |
+| `details.first_name:Amy scoring.contacted:true` | Both clauses are true |
+| `acme.status:sent OR acme.status:queued` | Either clause is true |
+| `Sydney details.phone:"0400000000"` | A plain word and a label clause together |
+
+## The `labels.` and `responses.` prefixes
+
+A path takes an optional `labels.` or `responses.` prefix. Two cases need it:
+
+- A label namespace with the name `labels` or `responses`: write
+  `labels.responses.status:sent`.
+- The key of a field that holds a full stop: write `responses.quote.preferences:*`. Without
+  the prefix the query reads that path as a label.
+
+A field with the name `createdAt` or `userId` also needs the prefix. A path of one part with
+that name reads as the capture date or the visitor.
+
+## Errors
+
+The search box shows an error, and the list does not change, for each of these:
+
+| Cause | Example |
+| --- | --- |
+| A `"` with no second `"` | `details.company:"Acme` |
+| A namespace or a key outside `a-z`, `0-9`, `_` and `-` | `Details.Phone:1` |
+| An operator that the part does not accept | `createdAt~2026` |
+| AND together with OR | `a.b:1 c.d:2 OR e.f:3` |
+| More than 10 clauses | 11 clauses in one query |
+
+## Related
+
+- [Fields](/reference/dashboard/fields) — the keys that name each answer
+- [Glossary](/reference/glossary) — lead, label, and the other terms

package/dist/docs/reference/dashboard/workflow-runs.md

@@ -0,0 +1,79 @@
+---
+type: reference
+layout: docs
+---
+
+# Workflow runs
+
+A run is one execution of a published workflow. An event or an action starts it. Picked
+records each run, each node that the run reached, and each lead that the run created or
+changed.
+
+## Where runs show
+
+| Page | Address | Content |
+| --- | --- | --- |
+| Runs | `…/workflows/<workflow>/runs` | The runs of one workflow, the last run first. Open it with **Runs** in the workflow editor. |
+| Run | `…/workflows/<workflow>/runs/<run>` | One run: its records, its tasks and its details. |
+| Lead | `…/leads/<lead>` | The **Workflow runs** card. It lists the runs that created or changed the lead. |
+
+A run starts only from a published version of the workspace. A change to a workflow that
+you did not publish does not start runs.
+
+## Run status
+
+| Status | Meaning |
+| --- | --- |
+| `Running` | The run started and did not stop yet. A **Wait** node can keep a run in this status for days. |
+| `Completed` | Each node that the run reached did its work. |
+| `Failed` | A node failed. The run stopped at that node. The run shows the reason. |
+
+## Records
+
+The **Records** card lists each lead that the run created or changed. It shows each lead
+one time.
+
+| Label | Meaning |
+| --- | --- |
+| `Created` | A node of the run created the lead. This label replaces `Updated` for the same lead. |
+| `Updated` | A node of the run changed the lead or its labels. |
+| `Deleted` | A node of the run deleted the lead. This label replaces `Created` and `Updated` for the same lead. |
+
+When a lead does not exist now, the card shows `Deleted lead` and the ID of the lead,
+with no link.
+
+## Tasks
+
+A task is one node that the run reached. The **Tasks** card lists the tasks in the order
+that the run reached them.
+
+| Column | Value |
+| --- | --- |
+| Name | The tool of a tool node, or the kind of node: **Start**, **Condition** or **Wait**. |
+| Node | The ID of the node. It links to the node in the editor while the workflow has the node. |
+| Status | `Running`, `Succeeded` or `Failed`. |
+| Time | The time from the start of the task to its end. |
+| Operations | The leads and the labels that the task created, changed or removed, the first operation first. A label shows its namespace and its key. It never shows its value. |
+
+A condition task does not show which branch it chose.
+
+## Leads and runs
+
+A lead lists a run when a node of that run created the lead, set one of its labels, or
+removed one of its labels. A change to the labels of a lead is a change to the lead.
+
+The **Workflow runs** card shows 20 runs. **Show older runs** adds the next 20.
+
+## Access
+
+| Surface | Scopes |
+| --- | --- |
+| Runs, Run | `ORGANIZATION_WORKSPACE_READ` and `ORGANIZATION_PROJECTS_READ` |
+| **Runs** in the workflow editor | `ORGANIZATION_WORKSPACE_READ` and `ORGANIZATION_PROJECTS_READ`. Without these scopes, the editor does not show **Runs**. |
+| Workflow runs card | `ORGANIZATION_LEADS_READ` for the lead, and `ORGANIZATION_WORKSPACE_READ` and `ORGANIZATION_PROJECTS_READ` for its runs. Without the last two scopes, the card does not show. |
+
+## Deleted workflows
+
+A run stays after you delete its workflow. The run page and the lead card show it as
+**Deleted workflow**. The **Runs** page of a deleted workflow does not exist, and the run
+page has no link to the editor.

package/dist/docs/reference/glossary.md

@@ -92,6 +92,16 @@ documentation uses, and it names the others.
 | **Asset version** | One file that somebody uploaded for an asset. The library keeps the earlier versions. |
 | **Validation error** | A report that one field in a content entry does not match its schema. It carries the path to the exact field. |
 
+## Leads
+
+| Term | What it is |
+| --- | --- |
+| **Lead** | One set of answers that a visitor gave to a flow. It belongs to the project, and it stays after you publish a new version. |
+| **Response** | One answer in a lead, held under the key of the field that asked for it. |
+| **Label** | A name and a value that you or a workflow puts on a lead. It sits outside the answers, and it stays when you change your fields. |
+| **Namespace** | The first part of the name of a label, which groups related keys, such as `details` in `details.phone`. |
+| **Label type** | How to read the value of a label: text, number, boolean, or JSON. |
+
 ## The SDK
 
 | Term | What it is |

package/dist/docs/reference/management-api/authentication.md

@@ -29,16 +29,23 @@ The session holds an `aal` field, and it gives the strength of the authenticatio
 | Level | Meaning |
 |-------|---------|
 | `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
-| `AAL2` | More than one factor: the user completed an MFA challenge |
+| `AAL2` | Two factors: the user verified a code from an authenticator app |
 
-Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
-returns an authorization error.
+Picked staff, and every member of an organization that requires MFA, must use `AAL2`.
+For these users, an `AAL1` session can only read `user` and call the MFA mutations. Every
+other operation returns the error code `MFA_REQUIRED`. Read `session.user.mfa` after
+`sessionCreate` to find out whether the user must verify, and see
+[How to set up MFA](/how-to/set-up-mfa) for the steps.
+
+The API checks the level when it creates a token. An OAuth token for an MCP client or the
+CLI is created at consent, which needs `AAL2` for these users. The token stays valid
+until it is revoked.
 
 ## The mutations
 
 | Mutation | What it does |
 | --- | --- |
-| `sessionCreate` | Authenticates an email address and a password. Returns a session, or `requiresMfa`. |
+| `sessionCreate` | Authenticates an email address and a password. Returns a session at `AAL1`. `session.user.mfa` says whether the user must verify. |
 | `sessionRefresh` | Exchanges a refresh token for a new session. Needs no `Authorization` header. |
 | `accountCreate` | Creates an account. `metadata` takes any JSON. |
 | `accountVerifyEmail` | Completes email verification with the token from the email. |
@@ -50,10 +57,10 @@ returns an authorization error.
 | `passwordResetSend` | Sends a password reset email. |
 | `passwordReset` | Completes a reset with the token from the email. |
 | `passwordUpdate` | Changes a password. Needs authentication. |
-| `mfaFactorEnroll` | Adds an MFA factor. A new factor is `UNVERIFIED`. |
-| `mfaChallengeSend` | Sends a code to the telephone number of the factor. |
-| `mfaChallengeVerify` | Verifies a challenge. Moves the session to `AAL2`. |
-| `mfaFactorUnenroll` | Removes an MFA factor. |
+| `mfaFactorEnroll` | Adds an authenticator app. A new factor is `UNVERIFIED`. Returns the QR code and the key one time. |
+| `mfaChallengeCreate` | Opens a challenge against a factor. |
+| `mfaChallengeVerify` | Verifies the code from the authenticator app. Moves the session to `AAL2`. |
+| `mfaFactorUnenroll` | Removes an authenticator. Needs `AAL2` for a verified factor. |
 | `apiKeyCreate` | Creates an API key. Only a user with a session can call it. |
 | `apiKeyRevoke` | Invalidates a key immediately. |
 

package/dist/docs/reference/management-api/authorization-and-scopes.md

@@ -205,7 +205,11 @@ Some mutations do not require organization-level scopes because they operate on
 | `passwordResetSend` / `passwordReset` | No authentication required |
 | `passwordUpdate` | Authenticated session (no specific scope) |
 | `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
-| `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
+| `mfaFactorEnroll` / `mfaChallengeCreate` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope). Exempt from the MFA requirement, so a user can add a factor and verify it. |
+
+`userMfaReset` needs the root-level scope `users/reset_mfa` (`USERS_RESET_MFA`). The
+mutation removes every authenticator of a user and signs the user out everywhere, so
+their next sign-in starts at the setup.
 
 ## Read your scopes
 

package/dist/docs/reference/management-api/error-handling.md

@@ -54,6 +54,7 @@ operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 | `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
 | `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
 | `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
+| `MFA_REQUIRED` | The user must verify a code from an authenticator app before this operation. Complete the challenge, then use the returned session. |
 | `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
 | `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
 
@@ -63,9 +64,7 @@ operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 {
   "data": {
     "sessionCreate": {
-      "session": null,
-      "requiresMfa": false,
-      "mfaFactors": null
+      "session": null
     }
   },
   "errors": [

package/dist/docs/reference/sdk/analytics-events.md

@@ -128,6 +128,7 @@ For a Shopify store, the `session` context also holds `shopify_client_id`,
 | `page_view` | The visitor opens a page. | `app`, `feature_list`, `session` | `experience`, `product_list`, `step` |
 | `identify` | The SDK connects the session to a known person or store client. | `app`, `session` | `experience`, `feature_list`, `step` |
 | `lead_capture` | The visitor gives contact details. | `feature_list`, `session` | `experience`, `step` |
+| `lead_created` | The Picked API records the lead from a capture. | `app`, `session` | None. |
 | `modal_open` | A modal opens. | `feature_list`, `modal`, `session` | `experience`, `step` |
 | `modal_close` | A modal closes. | `feature_list`, `modal`, `session` | `experience`, `step` |
 
@@ -193,15 +194,13 @@ the analytics plugin is true. The option is off by default.
 
 ### Interactions with no listener
 
-The SDK declares these four types and sends none of them, because it binds no listener for
+The SDK declares these two types and sends none of them, because it binds no listener for
 them. A query on one of them gives an empty result set.
 
 | Interaction type | When it fires | Always attached | Attached when available |
 | --- | --- | --- | --- |
 | `back` | Nothing sends it. | `feature_list`, `session` | `experience`, `step` |
 | `forward` | Nothing sends it. | `feature_list`, `session` | `experience`, `step` |
-| `video_play` | Nothing sends it. | `element`, `feature_list`, `session` | `experience`, `step` |
-| `video_pause` | Nothing sends it. | `element`, `feature_list`, `session` | `experience`, `step` |
 
 ## Schemas
 

package/dist/docs/tutorials/first-api-call.md

@@ -90,8 +90,11 @@ mutation {
       accessToken
       refreshToken
       expiresAt
+      aal
+      user {
+        mfa { required enrolled }
+      }
     }
-    requiresMfa
   }
 }
 ```
@@ -106,16 +109,20 @@ A successful response returns a `Session` with an `accessToken` and a
       "session": {
         "accessToken": "eyJhbGciOiJIUzI1NiIs...",
         "refreshToken": "v1.refresh-token...",
-        "expiresAt": "2025-01-15T12:00:00Z"
-      },
-      "requiresMfa": false
+        "expiresAt": "2025-01-15T12:00:00Z",
+        "aal": "AAL1",
+        "user": {
+          "mfa": { "required": false, "enrolled": false }
+        }
+      }
     }
   }
 }
 ```
 
-When `requiresMfa` is `true`, you must complete the MFA challenge before you receive
-a session. See the [Authentication](/reference/management-api/authentication) guide.
+When `required` is `true`, the token can only read `user` and call the MFA mutations
+until you verify a code from an authenticator app. See
+[How to set up MFA](/how-to/set-up-mfa).
 
 For a server-to-server integration, use
 [API key authentication](/how-to/authenticate-with-an-api-key) and not a