picked 0.0.101-next.2 → 0.0.101

package/docs/how-to/upload-and-use-an-asset.mdx

@@ -0,0 +1,87 @@
+---
+type: how-to
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# How to upload and use an asset
+
+This guide shows you how to put a file in the asset library and point at it from your
+content.
+
+## 1. Add the field to a layout
+
+Two field types point at the library:
+
+- An **Asset** field takes an image, a video, or a document.
+- An **HTML** field takes a `.html` file.
+
+Add one of them to a page layout or a step layout.
+
+## 2. Choose a file
+
+1. Open the content entry.
+2. Click **Choose file** on the asset field. On a field that holds a value already, click
+   **Replace**.
+3. Open the **Upload** tab to add a new file.
+4. Open the **Library** tab to use a file that is there already.
+5. Choose your asset.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/design-systems/new"
+  wait='button:has-text("Upload file")'
+  click='button:has-text("Upload file")'
+  selector="[role=dialog]"
+  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
+  renderWidth={1072}
+  renderHeight={790}
+/>
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/design-systems/new"
+  wait='button:has-text("Upload file")'
+  click='button:has-text("Upload file")'
+  selector="[role=dialog]"
+  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
+  renderWidth={1072}
+  renderHeight={790}
+/>
+
+The detail panel on the right shows the kind, the dimensions, the size, and the upload
+date.
+
+## 3. Find an asset in a large library
+
+The **Library** tab has three controls, and the server applies each one across the whole
+library:
+
+- **Search by name** narrows the list by file name while you type.
+- The type filter narrows the list to one media type. **All types** is the default.
+- **Sort** orders the list by **Name**, **Date created**, or **Date updated**.
+
+Click **Load more** at the bottom to read the next page of results.
+
+:::tip
+Each row has an **Open in new tab** control. Use it to check an asset again before you
+choose it. Your choice in the picker stays as it is.
+:::
+
+## 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 |
+| --- | --- | --- | --- |
+| Add the field to a layout | [`contentModelUpdate`](/reference/management-api/schema/cms-models#contentmodelupdate) | [`update_content_model`](/reference/tools/mcp#update_content_model) | `tools.update_content_model({ content_model_id, schema })` |
+| Upload a file | [`assetUploadInit`](/reference/management-api/schema/cms-models#assetuploadinit), [`assetCommit`](/reference/management-api/schema/cms-models#assetcommit) | [`init_asset_upload`](/reference/tools/mcp#init_asset_upload), [`commit_asset_upload`](/reference/tools/mcp#commit_asset_upload) | `tools.init_asset_upload({ project_id, file_name, content_type })`, `tools.commit_asset_upload({ project_id, asset_id, version_id, file_name, storage_path })` |
+| Find an asset in the library | [`assets`](/reference/management-api/schema/cms-models#assets) | [`list_assets`](/reference/tools/mcp#list_assets) | `tools.list_assets({ project_id })` |
+| Choose the asset in an entry | [`contentEntryUpdate`](/reference/management-api/schema/cms-models#contententryupdate) | [`update_content_entry`](/reference/tools/mcp#update_content_entry) | `tools.update_content_entry({ content_entry_id, data })` |
+
+Between the two calls, send the file in a `PUT` request to the URL that the first call gives.
+The `list_assets` tool has no search, no type filter and no sort.
+
+## Related
+
+- [Asset library](/reference/dashboard/content/asset-library) — the limits, the file
+  types, and how Picked serves an uploaded file.

package/docs/how-to/validate-a-field.md

@@ -0,0 +1,52 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to validate a field
+
+This guide shows you how to check what a visitor enters. Write the rule in JSON Logic. The
+`$input` variable holds the current value of the field.
+
+## Steps
+
+Add a `validation` rule to `createField()`:
+
+```ts
+import { createField } from '@picked/client/plugins/create-experience'
+
+const quantityField = createField({
+  id: 'quantity',
+  name: 'quantity',
+  type: 'number',
+  label: 'Quantity',
+  multiple: false,
+  required: true,
+  validation: {
+    catch: {
+      or: [
+        {
+          and: [
+            { '>': [{ var: '$input' }, 0] },
+            { '<=': [{ var: '$input' }, 999] },
+          ],
+        },
+        { throw: 'Please enter a value between 1 and 999' },
+      ],
+    },
+  },
+})
+```
+
+:::tip
+The `catch` and `throw` pattern checks that the condition gives `true`. When it does not,
+the SDK shows the `throw` message to your visitor.
+:::
+
+The SDK runs the rule on blur and on submit.
+
+## Related
+
+- [SDK fields](/reference/sdk/fields) — every field option.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  the rule format.

package/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/docs/how-to/write-a-condition.md

@@ -0,0 +1,57 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to write a condition
+
+This guide shows you how to build a rule in the visual condition builder. The builder
+appears on a condition node, on an experience condition, on an initialize-open condition,
+and on a field option.
+
+## Steps
+
+1. Choose the node or the field that takes the condition.
+2. Find the **Logic** section in the inspector.
+3. Choose a data source: **Responses**, **Actions**, **Feature flags**, **Conditions**,
+   or **Window Location**.
+4. Choose an operator. The choices include equals, not equals, greater than, and
+   contains.
+5. Enter a value.
+
+## Join more than one rule
+
+1. Create an AND group or an OR group.
+2. Add your rules inside it.
+
+With **AND** every rule must match. With **OR** one rule must match. Put a group inside
+another group to build a larger rule.
+
+## Example
+
+To show a step only to a visitor who is on one page and who accepted marketing:
+
+1. Create an AND group.
+2. Add a rule: **Window Location → pathname** equals `/pricing`.
+3. Add a rule: **Responses → `marketing_opt_in`** equals `true`.
+
+The group matches only when both rules are true.
+
+## 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 |
+| --- | --- | --- | --- |
+| Write the rule of a condition node | [`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 })` |
+| Write the experience condition or the initialize-open condition | [`experienceUpdate`](/reference/management-api/schema/experience#experienceupdate), [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, condition, initialize_open })` |
+| Write the condition of a field option | [`fieldUpdate`](/reference/management-api/schema/field#fieldupdate), [`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_fields })` |
+
+The API and the MCP server take each rule as a JSON Logic expression.
+
+## Related
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what a rule can read.
+- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the rule
+  structure.

package/docs/how-to/write-a-predicate.md

@@ -0,0 +1,60 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to write a predicate
+
+This guide shows you how to let a condition read data that only your application holds,
+such as a cart total or an account level.
+
+## 1. Define the predicate
+
+Pass a `predicates` object to `createClient()`:
+
+```ts
+import { createClient } from 'picked'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  predicates: {
+    'is-example-page': ({ location }) => location?.pathname === '/example',
+    'get-account-tier': async () => {
+      const data = await fetch('/api/get-account-tier').then((r) => r.json())
+      return data.result
+    },
+  },
+})
+```
+
+A predicate returns a boolean, a string, an array of strings, or `undefined`. It can also
+return a promise that resolves to one of those.
+
+## 2. Invoke it from a condition
+
+```ts
+condition: {
+  '==': [
+    { invoke: { var: 'predicates.is-example-page' } },
+    true,
+  ],
+}
+```
+
+:::tip
+A predicate also works inside `validation` logic.
+:::
+
+## Keep it pure and fast
+
+- The same snapshot must always give the same result.
+- Check that a response or a field is there before you read its value. Return `undefined`
+  when the data is not available, and do not throw.
+- The SDK can invoke a predicate many times, so keep the logic small.
+- Do not change the snapshot. It is frozen, and a change to it throws in strict mode.
+
+## Related
+
+- [Predicates](/reference/sdk/predicates) — the state snapshot shape.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  why predicates exist.

package/docs/index.md

@@ -0,0 +1,59 @@
+---
+type: map
+layout: docs
+---
+
+# Picked documentation
+
+Picked lets you build personalized UI flows in a visual editor. The SDK then serves them
+to the visitors on your site.
+
+There are two paths to follow. Choose the one that matches your work.
+
+## Work in the dashboard
+
+Build experiences, write content, and publish.
+
+Start with [build your first experience](/tutorials/first-experience-in-the-dashboard).
+It takes you from an empty project to a survey on your own site, and it needs no
+development tools.
+
+One thing must happen first: a developer adds the Picked SDK to your site one time. After
+that, the dashboard is all you need.
+
+Then:
+
+- **[Build](/how-to/create-an-experience)** — experiences, flows, conditions, and A/B
+  tests.
+- **[Content](/how-to/define-a-page-layout)** — Models, Blocks, entries, pages, and assets.
+- **[Publish](/how-to/publish-a-workspace)** — preview, publish, and roll back.
+- **[Administer and measure](/how-to/invite-and-remove-members)** — members, API keys,
+  analytics, and the tools that connect Picked to Google Tag Manager and to an AI tool.
+- **[Dashboard reference](/reference/dashboard/projects)** — every dashboard screen and
+  every option, plus the [glossary](/reference/glossary).
+- **[How Picked works](/explanation/how-picked-works)** — what happens when you publish.
+
+## Integrate with code
+
+Add Picked to a site or an application. Your code then renders the experiences that the
+dashboard describes.
+
+Start with [add Picked to your application](/tutorials/first-experience). It goes from an
+empty project to a survey that runs in React or in Svelte.
+
+Read the dashboard documents above also. Everything your code renders is described
+there, so the two paths link to each other rather than repeat.
+
+Then:
+
+- **[Integrate the SDK](/how-to/install-the-sdk)** — install, register a component, read
+  a feature flag.
+- **[Build a step form](/how-to/render-a-step-form)** — render fields, act on a
+  submission, validate input.
+- **[Server-side rendering](/how-to/server-render-a-page)** — a page that a search engine
+  can read.
+- **[Authenticate](/how-to/authenticate-with-a-password)** — the management API.
+- **[SDK reference](/reference/sdk)**, **[Delivery API](/reference/delivery-api)**,
+  **[PickedQL](/reference/pickedql)**.
+- **[Why it works this way](/explanation/why-server-side-rendering)** — the design
+  behind the SDK.

package/docs/reference/dashboard/actions.mdx

@@ -0,0 +1,65 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Actions
+
+An action is a side effect that starts when the flow reaches it. Use an action to
+track an event, to send data to an external service, or to call a webhook.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/actions"
+  alt="The actions list for a workspace on the Picked dashboard"
+/>
+
+## Set up an action
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier that your application uses for this action. Your visitors do
+not see it.
+
+## Register in your application
+
+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.
+
+## Use actions in flows
+
+In the flow builder, drag an action from the library onto the canvas. Connect it to
+the point in the flow where you want it to start.
+
+An action runs when the flow reaches its node. It does not interrupt your visitor. By
+default the flow continues to the next connected node.
+
+An action node can carry a **success** branch and a **failure** branch. Which one the flow
+takes depends on whether your handler throws, and a returned `false` is a success. See
+[How an action decides which way to go](/explanation/how-picked-works#how-an-action-decides-which-way-to-go).
+
+## Reuse actions
+
+An action belongs to the project. Use the same action in more than one experience flow.
+A change to the options of an action applies at every place that uses it.
+
+## 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 |
+| --- | --- | --- | --- |
+| Create an action | [`actionCreate`](/reference/management-api/schema/action#actioncreate), [`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_actions, create_nodes })` |
+| Add an action to a flow | [`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_nodes, create_edges })` |
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+- [How to register an action handler](/how-to/register-an-action-handler)
+- [SDK actions](/reference/sdk/actions) — what the handler receives and returns.

package/docs/reference/dashboard/api-keys.mdx

@@ -0,0 +1,47 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# API keys
+
+An API key lets your code reach the Picked API. Use one where your own code calls the API,
+such as a server-side integration. It does not sign the
+[CLI](/reference/tools/cli) in.
+
+<Screenshot
+  route="/{orgSlug}/api-keys"
+  alt="The API keys list for an organization on the Picked dashboard"
+/>
+
+## Use an API key
+
+Put your API key in the `x-api-key` header of each request to the
+[Picked API](/tutorials/first-api-call).
+
+```
+x-api-key: your-api-key
+```
+
+## Scopes
+
+An API key carries scopes, and the scopes limit what the key can reach. Choose the
+scopes that your integration needs when you create the key. A key can do only the
+operations that its scopes permit.
+
+## 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 |
+| --- | --- | --- | --- |
+| List the API keys | [`apiKeys`](/reference/management-api/schema/api-key#apikeys) | None | None |
+| Create a key with its scopes | [`apiKeyCreate`](/reference/management-api/schema/api-key#apikeycreate) | None | None |
+
+## Related
+
+- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key) — the API
+  side.

package/docs/reference/dashboard/conditions.mdx

@@ -0,0 +1,51 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Conditions
+
+A condition evaluates a rule and splits the flow into two paths. One path is for a
+true result, the other for a false result.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
+  alt="The conditions list for a workspace on the Picked dashboard"
+/>
+
+## Set up a condition
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier for your application. You set it once and you cannot change
+it. Your visitors do not see it.
+
+## Branches
+
+In the flow builder, a condition node has two output handles. The green handle, for a
+true result, leads to the path for a match. The red handle, for a false result, leads
+to the other path.
+
+You can chain conditions. Connect the output of one condition to the input of another
+to build a decision tree.
+
+## 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 |
+| --- | --- | --- | --- |
+| Create a condition | [`conditionCreate`](/reference/management-api/schema/condition#conditioncreate), [`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_conditions, create_nodes })` |
+| Connect the true path and the false path | [`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 add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what a rule can read.
+- [How to write a condition](/how-to/write-a-condition)
+- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the data
+  sources and the rule structure.