@picked/client 0.0.98-next.1 → 0.0.98-next.2

package/dist/docs/how-to/wait-for-an-action-response.md

@@ -0,0 +1,182 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to wait for the response of an action
+
+This guide shows you how to run an action from your application and show its response. You
+need an action in your project first, with a key and a workflow that the action starts. See
+[Actions](/reference/dashboard/actions).
+
+The response is the value that the action returns. For an action that starts a workflow in
+Picked, the response is the payload of the **Action response** node in the workflow.
+
+## 1. Generate the types of your project
+
+Run type generation. The generated types name the actions that start a workflow. For those
+keys, the types of `useAction` and `getAction` include `run`. At runtime, the value includes
+`run` for each key. See [Type generation](/reference/sdk/type-generation).
+
+## 2. Bind the action to a component
+
+Call `useAction` in React, or `getAction` in Svelte. Neither runs the action. The action runs
+only when you call `run`. The action receives the arguments of `run` in `args`.
+
+All the components that use the same key and the same experience share one run state. When
+one of them calls `run`, all of them show that run.
+
+:::code-group
+
+```tsx [React]
+import { useAction } from '@picked/react/hooks'
+
+function CallbackButton() {
+  const callback = useAction('request-callback')
+
+  return (
+    <button onClick={() => void callback.run()} disabled={callback.status === 'running'}>
+      Get a call back
+    </button>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getAction } from '@picked/svelte/hooks'
+
+  const callback = getAction('request-callback')
+</script>
+
+<button onclick={() => $callback.run()} disabled={$callback.status === 'running'}>
+  Get a call back
+</button>
+```
+
+:::
+
+## 3. Show the response
+
+Read `status`, `response` and `error` for the last run. Compare `response` with the values
+that your workflow sends.
+
+:::code-group
+
+```tsx [React]
+import { useAction } from '@picked/react/hooks'
+
+// Reads the status that the workflow sends in its response.
+function answerStatus(response: unknown): unknown {
+  return typeof response === 'object' && response !== null && 'status' in response
+    ? response.status
+    : undefined
+}
+
+function CallbackButton() {
+  const callback = useAction('request-callback')
+
+  if (callback.status === 'failed') return <p>We could not send your request.</p>
+  if (callback.status === 'succeeded') {
+    if (answerStatus(callback.response) === 'closed') {
+      return <p>We call back on weekdays, 8 am to 5 pm.</p>
+    }
+    return <p>Thank you. We will call you soon.</p>
+  }
+
+  return (
+    <button onClick={() => void callback.run()} disabled={callback.status === 'running'}>
+      Get a call back
+    </button>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getAction } from '@picked/svelte/hooks'
+
+  const callback = getAction('request-callback')
+
+  // Reads the status that the workflow sends in its response.
+  function answerStatus(response: unknown): unknown {
+    return typeof response === 'object' && response !== null && 'status' in response
+      ? response.status
+      : undefined
+  }
+</script>
+
+{#if $callback.status === 'failed'}
+  <p>We could not send your request.</p>
+{:else if $callback.status === 'succeeded' && answerStatus($callback.response) === 'closed'}
+  <p>We call back on weekdays, 8 am to 5 pm.</p>
+{:else if $callback.status === 'succeeded'}
+  <p>Thank you. We will call you soon.</p>
+{:else}
+  <button onclick={() => $callback.run()} disabled={$callback.status === 'running'}>
+    Get a call back
+  </button>
+{/if}
+```
+
+:::
+
+`run` does not reject. It resolves to `{ status: 'succeeded', response }` or to
+`{ status: 'failed', error }`.
+
+## 4. Run the action outside a component
+
+Call `client.actions.run` with the action key. It resolves to the response, and it rejects
+when the action fails.
+
+The client registers the actions of your project when it loads the configuration of your
+project. For this, the client must have `dynamicExperiencesPlugin`, and you must start the
+client. Until the client is ready, `run` rejects with `Action '<key>' is not registered`. A
+handler that your application registers in `createClient({ actions })` is available
+immediately.
+
+```ts
+import { createClient } from 'picked'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin()],
+})
+
+picked.start()
+
+// Waits until the client is ready.
+async function whenReady(): Promise<void> {
+  if (picked.readyStore.getState()) return
+
+  await new Promise<void>((resolve) => {
+    const subscription = picked.readyStore.updates.watch((ready) => {
+      if (!ready) return
+      subscription.unsubscribe()
+      resolve()
+    })
+  })
+}
+
+async function requestCallback(): Promise<void> {
+  await whenReady()
+
+  try {
+    const response = await picked.actions.run('request-callback', { timeoutMs: 15_000 })
+    console.info('Callback response', response)
+  } catch (error) {
+    console.warn('Callback request failed', error)
+  }
+}
+```
+
+Set `timeoutMs` to stop the wait sooner. Set `signal` to stop the wait from your own code.
+
+## Related
+
+- [SDK actions](/reference/sdk/actions) — every outcome, error and limit.
+- [How to register an action handler](/how-to/register-an-action-handler) — return a
+  response from your own handler.
+- [How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow)
+  — a workflow that sends a response.

package/dist/docs/reference/dashboard/actions.mdx

@@ -24,8 +24,11 @@ not see it.
 
 ## Register in your application
 
-Each action key must match a key in the `actions` object that you pass to
-`createClient()`. See
+A published action that starts a workflow needs no code in your application. The SDK
+sends the request to Picked, and the workflow runs there.
+
+To run your own code, pass a handler under the action key in `createClient()`. That handler
+replaces the workflow for this key. See
 [How to register an action handler](/how-to/register-an-action-handler) for the code, and
 [SDK actions](/reference/sdk/actions) for what the handler receives and returns.
 

package/dist/docs/reference/delivery-api/workspace-schema.md

@@ -28,13 +28,16 @@ The response is a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020
 | `x-picked-source` | `"published"` or `"preview"` — mirrors the surface you requested. |
 | `x-picked-version-id` | Published workspace version id, or `null` on preview. |
 | `x-picked-step-content-models` | Map of step key → content model key, which gives each layout its type. |
+| `x-picked-step-fields` | Map of step key → the keys of the fields on that step, in order. |
 | `x-picked-feature-values` | Map of feature key → the values that the feature can serve. Picked adds this field only when the workspace has a Text feature flag. |
+| `x-picked-workflow-action-keys` | Keys of the actions that start a workflow, sorted. Picked adds this field only when the workspace has such an action. |
 | `$defs.contentModels` | JSON Schema definitions for each content model. |
 | `$defs.contentBlocks` | JSON Schema definitions for reusable content blocks. |
 | `$defs.fields` | Object schema for project field values. |
 | `$defs.featureKeys` | String enum of feature keys. |
 | `$defs.experienceKeys` | String enum of experience keys. |
 | `$defs.stepKeys` | String enum of step keys. |
+| `$defs.actionKeys` | String enum of action keys. A schema from a version that Picked published before this field existed has none. |
 
 ## Field values
 

package/dist/docs/reference/sdk/actions.md

@@ -5,8 +5,23 @@ layout: docs
 
 # Actions
 
-Register an action handler on the Picked client. The SDK then invokes the handler
-when an experience flow reaches an action node.
+An action is a function that the SDK runs by its key. An action comes from one of two
+places:
+
+- **Your application** registers a handler in `createClient({ actions })`.
+- **Your project** publishes the action. Its handler sends the visitor's answers to Picked,
+  and the workflow of the action runs there.
+
+A handler from your application replaces a published action that has the same key. The
+workflow then does not start.
+
+## Response
+
+The value that a handler returns is the response of the action. A handler can return any
+value, or a promise of any value.
+
+The response of a published action is the payload of the **Action response** node in its
+workflow. A workflow that has no **Action response** node gives `undefined`.
 
 ## Outcome and branch
 
@@ -19,10 +34,119 @@ An action node can also carry one plain connection, with no success or failure b
 flow then continues through it on either outcome.
 
 An action does not interrupt your visitor. The current step stays on the screen while an
-async action runs.
+async action runs. While the action runs, the flow ignores a request to go to the next step
+or to a specified step. The outcome of the action then chooses the branch. If your visitor
+goes back before the action completes, the flow stays on that step. The signal that the
+handler receives then stops.
+
+## Published actions
+
+A published action waits for the response of its workflow. It stops after 30 seconds.
+
+| Cause | The action rejects with |
+| --- | --- |
+| Picked refuses the request | An `Error` that names the HTTP status |
+| Picked does not accept the request in 25 seconds | A `TimeoutError` |
+| Picked accepts the request, but gives no run to wait for | An `Error` that says that no run is available |
+| The workflow fails before it sends a response | `ActionRunFailedError` |
+| Picked refuses a request for the response with a `4xx` status | An `Error` that names the HTTP status |
+| No response in 30 seconds | `ActionResponseTimeoutError` |
+| Your code stops the wait with a signal | The reason of the signal |
+
+A request for the response can fail because of a network error, a timeout, a `5xx` status or
+a body that the SDK cannot read. The SDK then sends the request again. It waits 1 second after
+the first failure, and two times longer after each failure that follows. If the requests
+continue to fail, the 30-second limit stops the wait with `ActionResponseTimeoutError`.
+
+To identify `ActionRunFailedError` and `ActionResponseTimeoutError` with `instanceof`, import
+them from `@picked/client/plugins/dynamic-experiences`. The `name` of each error is the same
+as the name that you import.
+
+## Run an action from code
+
+| API | Returns | Rejects |
+| --- | --- | --- |
+| `client.actions.run(key, options)` | A promise of the response | Yes, with the error of the action |
+| `useAction(key, options)` (React) | For an action that starts a workflow: `{ run, status, response, error }`. For other actions: the action as a function. | `run`: No. The function: it returns or throws what the action returns or throws. |
+| `getAction(key, options)` (Svelte) | A store of the same value | The same as `useAction` |
+| `useActionResult(key, options)` (React) | The last result of your own action | No |
+| `getActionResult(key, options)` (Svelte) | A store of the last result of your own action | No |
+| `client.actions.getActionBinding(key, options)` | A store of the value that `useAction` and `getAction` give | The same as `useAction` |
+| `client.actions.getActionResult(key, options)` | A store of the last result of your own action, which `useActionResult` and `getActionResult` read | No |
+
+Type generation names the actions that start a workflow (`WorkflowActionKeys`). Without generated
+types, `useAction` and `getAction` give the action as a function. For each key, the value also
+includes `run`, `status`, `response` and `error`.
+
+The handler receives the arguments of a call to the function in `args`. It also receives the
+arguments of `run(...args)` in `args`.
+
+`status` is `idle`, `running`, `succeeded` or `failed`, for the last run. When a run starts,
+`response` and `error` are `undefined`. `run(...args)` resolves to
+`{ status: 'succeeded', response }` or to `{ status: 'failed', error }`.
+
+The SDK keeps one run state for each key and experience. All the components that use the
+same key and the same experience share that run state, and they show the same last run. When
+one of them calls `run`, all of them show that run.
+
+`useActionResult` and `getActionResult` run your own action again when a response, a field or
+the handler of the action changes. They also run it when a component that reads the result
+starts. In React, the action runs when the component mounts, and when an `<Activity>` shows the
+component again. In Svelte, it runs each time a component calls `getActionResult`. A change that
+occurs outside Picked, for example a login, then shows in a component that starts after the
+change.
+
+The components that read the same key and the same experience share one result. The action
+runs one time for each change. It also runs one time for the components that React renders
+together. React can stop while it renders and continue later, for example in a transition. Then
+the components that React renders after it continues run the action again.
+
+The result is always from the run that started last. If that run throws, the result is
+`undefined`. For a published action they give `undefined` and do not send a request. The types
+refuse the key of an action that starts a workflow.
+
+A result for an experience follows the changes only while `client.experienceInstances`
+contains that experience. When `client.experienceInstances` adds the experience, the action
+runs if a response, a field or the handler changed after the last run.
+
+The options of `client.actions.run`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `args` | `unknown[]` | The values that the handler receives in `args`. |
+| `experience` | `ExperienceInstance` | The experience that the handler receives as `context.experience`. |
+| `signal` | `AbortSignal` | Stops the wait. The handler receives a signal that stops too. |
+| `timeoutMs` | `number` | Stops the wait after this many milliseconds, with a `TimeoutError`. |
+
+`useAction` and `getAction` take `experience` only.
+
+## Other methods of `client.actions`
+
+| Method | Description |
+| --- | --- |
+| `refreshActionResult(key, options)` | Runs your own action again for the result that `getActionResult` gives. It does nothing until a component or your code reads that result. The calls in one task start one run. |
+| `isPublished(key)` | Returns `true` when the handler of the key is a published action. |
+| `unregister(key)` | Removes the handler of the key. If the key has no handler, nothing changes. |
+
+`refreshActionResult` and `getActionResult` take `experience` only.
+
+## Rule logic
+
+A rule reads the response of an action with `{ "invoke": [{ "var": "actions.<key>" }] }`. A
+response that is a string, a number, a Boolean, `null`, or an array or object of these
+reaches the rule. A different response reaches the rule as `undefined`.
+
+A rule runs the action each time the SDK evaluates the rule.
+
+A condition node can have a rule that runs an action. While the condition node waits for that
+rule, the flow ignores a request to go to the next step or to a specified step. The result of
+the rule then chooses the branch. If your visitor goes back before the rule has a result, the
+flow ignores the result.
 
 ## Related
 
+- [How to wait for the response of an action](/how-to/wait-for-an-action-response) — show
+  the response in a component.
 - [How to register an action handler](/how-to/register-an-action-handler) — the handler,
   and when to throw.
 - [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)

package/dist/docs/reference/sdk/type-generation.md

@@ -244,6 +244,14 @@ Each key type has a `Known` form that holds the workspace keys alone —
 `KnownFeatureKeys`, `KnownActionKeys`, `KnownFieldKeys`, `KnownStepKeys`, and
 `KnownExperienceKeys`. Use one where you want the workspace set and nothing else.
 
+## Actions that start a workflow
+
+`WorkflowActionKeys` holds the keys of the actions that start a workflow in the workspace. For one
+of these keys, the types of `useAction` and `getAction` give `run`, `status`, `response` and
+`error`. For every other key, the types give the action as a function. Without generated types,
+and with a schema that has no such actions, `WorkflowActionKeys` is `never`. See
+[Actions](/reference/sdk/actions).
+
 ## Cache
 
 Type generation writes its artefacts under `.picked/`: the schema JSON and a manifest. The first run adds this directory to `.gitignore` for you.