picked 0.0.101-next.2 → 0.0.101

package/docs/how-to/read-a-referenced-entry.md

@@ -0,0 +1,109 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to read a referenced entry
+
+This guide shows you how to read the content that a
+[Reference field](/reference/dashboard/content/models#reference-fields) points at. You
+need a component that renders a step first. See
+[How to render a step form](/how-to/render-a-step-form).
+
+A Reference field holds a pointer, and not the content. The entry travels beside the
+content of the step, so you resolve the pointer against the content of the client.
+
+## 1. Resolve a single reference
+
+Pass the raw field value to `useReference()` in React, or to `getReference()` in Svelte.
+
+:::code-group
+
+```tsx [React]
+import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
+
+export function ProductCategory() {
+  const content = useStepContent()
+  const category = useStoreGlobal(useReference(content?.category))
+
+  if (!category) return null
+
+  return <span>{String(category.data.name ?? '')}</span>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReference } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
+</script>
+
+{#if $category}
+  <span>{$category.data.name ?? ''}</span>
+{/if}
+```
+
+:::
+
+In Svelte, pass a store and not a plain value. Content arrives after the component
+starts. A plain value therefore holds the result at "not set".
+
+## 2. Resolve a repeatable reference
+
+Use `useReferences()` or `getReferences()`. They give a list in field order.
+
+:::code-group
+
+```tsx [React]
+import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
+
+export function ProductCategories() {
+  const content = useStepContent()
+  const categories = useStoreGlobal(useReferences(content?.categories))
+
+  return (
+    <ul>
+      {categories.map((category) => (
+        <li key={category.id}>{String(category.data.name ?? '')}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReferences } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
+</script>
+
+<ul>
+  {#each $categories as category (category.id)}
+    <li>{category.data.name ?? ''}</li>
+  {/each}
+</ul>
+```
+
+:::
+
+The list holds no empty places, so you need no check for each item.
+
+## Handle a target that does not resolve
+
+A single reference gives an empty result when Picked cannot resolve the target. A
+repeatable reference leaves the item out of the list.
+
+This happens when somebody deleted the target, when the target belongs to another
+workspace, or when the chain of references is deeper than the limit.
+
+Render something else for the empty case, as the React example above does.
+
+## Related
+
+- [Content](/reference/sdk/content) — every hook and its return type.
+- [About content references](/explanation/content-references) — why the entry travels separately.
+- [How to point one entry at another](/how-to/point-one-entry-at-another) — the dashboard side.

package/docs/how-to/register-a-component.md

@@ -0,0 +1,55 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to register a component
+
+This guide shows you how to connect a component in your application to an experience in
+the dashboard.
+
+## Steps
+
+1. Wrap your component with the adapter for your framework.
+2. Pass it in the `components` object of `createClient()`.
+3. Use the same key as the component name of the experience.
+
+:::code-group
+
+```tsx [React]
+import { createClient } from 'picked'
+import { adaptReactComponent } from '@picked/react'
+import { MyWidget } from './MyWidget'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    MyWidget: adaptReactComponent(MyWidget),
+  },
+})
+```
+
+```ts [Svelte]
+import { createClient } from 'picked'
+import { adaptSvelteComponent } from '@picked/svelte'
+import MyWidget from './MyWidget.svelte'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    MyWidget: adaptSvelteComponent(MyWidget),
+  },
+})
+```
+
+:::
+
+:::warning
+`components` takes an adapted component. A plain React or Svelte component does not work
+without `adaptReactComponent` or `adaptSvelteComponent`.
+:::
+
+## Related
+
+- [SDK experiences](/reference/sdk/experiences) — the experience shape.
+- [How to install the SDK](/how-to/install-the-sdk).

package/docs/how-to/register-an-action-handler.md

@@ -0,0 +1,85 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to register an action handler
+
+This guide shows you how to connect an action node in a flow to a function in your
+application. You need an action in your project first, with a key. See
+[Actions](/reference/dashboard/actions).
+
+A published action that starts a workflow runs without a handler. A handler under its key
+replaces the workflow.
+
+## 1. Register the handler
+
+Pass an `actions` object to `createClient()`. Each key must match an action key from the
+dashboard:
+
+```ts
+import { createClient } from 'picked'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  actions: {
+    'track-signup': () => {
+      analytics.track('signup_completed')
+    },
+    notify: (params) => {
+      sendNotification(params)
+    },
+  },
+})
+```
+
+The SDK calls the function that matches when the flow reaches the action node.
+
+## 2. Throw only for a true error
+
+The flow takes the failure branch when your handler throws or its promise rejects. Throw
+when the request itself did not complete:
+
+```ts
+'check-eligibility': async () => {
+  const response = await fetch('/api/eligibility')
+  // Throw only when the request itself fails. That takes the failure branch.
+  if (!response.ok) throw new Error('Eligibility request failed')
+}
+```
+
+## 3. Return a response
+
+The value that your handler returns is the response of the action. Code that runs the
+action reads this value:
+
+```ts
+'quote-premium': async ({ responses }) => {
+  const age = responses.find((r) => r.fieldKey === 'age')?.value
+  const { premium } = await fetch(`/api/premium?age=${age}`).then((r) => r.json())
+  return { premium }
+}
+```
+
+## 4. Record a negative answer as a response
+
+A valid negative result is not a failure. An endpoint can answer `200` with a "no". Store
+that value as a response and branch on it with a condition instead:
+
+```ts
+'check-serviced-area': async ({ client, responses }) => {
+  const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
+  const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
+  // Store the outcome as a response. A later condition then takes the branch.
+  client.responses.register('is-serviced', serviced)
+}
+```
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)
+  — why a returned `false` is a success.
+- [SDK actions](/reference/sdk/actions) — what the handler receives and returns.
+- [How to wait for the response of an action](/how-to/wait-for-an-action-response) — show the
+  response in a component.
+- [Actions](/reference/dashboard/actions) — the dashboard options.

package/docs/how-to/register-an-api-that-uses-oauth2.md

@@ -0,0 +1,107 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to register an API that uses OAuth2
+
+This guide shows you how to let a workflow call an API whose access tokens expire, such as
+Zoho CRM. You need a client ID and a client secret from the provider. For the refresh token
+grant, you also need a refresh token.
+
+Picked keeps the credential, gets an access token from the provider, and sends the token
+with each request. Picked gets a new token before the old token expires.
+
+## 1. Make a refresh token in Zoho
+
+Do this step for Zoho CRM only. For another provider, get the credential from the
+provider's documentation.
+
+1. Open the Zoho API console for the region of your Zoho account.
+2. Add a client of the type `Self Client`.
+3. Make a grant code with the scopes that the workflow needs, such as
+   `ZohoCRM.modules.leads.CREATE`.
+4. Send a `POST` request to the token URL of your region, such as
+   `https://accounts.zoho.com.au/oauth/v2/token`. Put the parameters in the form body, not
+   in the URL. The parameters are `grant_type=authorization_code`, `client_id`,
+   `client_secret`, and `code` with the grant code. The grant code expires soon, so do this
+   step immediately.
+5. Keep the `refresh_token` from the answer.
+
+:::warning
+Make the refresh token as a Zoho user that only Picked uses. Zoho keeps 20 refresh tokens
+for each user and client. When you make one more, Zoho stops the oldest refresh token. That
+token can be the token that Picked uses.
+:::
+
+## 2. Register the external API
+
+1. Open **Integrations**.
+2. Choose **Configure external APIs**.
+3. Choose **New external API**.
+4. For Zoho CRM, set **Preset** to the region of your Zoho account. The preset sets the
+   **Display name**, the **Origin**, the **Credential** and the settings of the OAuth2
+   credential. Then go to step 10. If **Preset** does not show your region, do steps 5 to 9.
+5. Enter a **Display name**.
+6. Enter the **Origin**, such as `https://www.zohoapis.com.au`.
+7. Set **Credential** to **OAuth2 credential**.
+8. Enter the **Token URL** from the provider's documentation. Do not put a secret in the
+   token URL.
+9. Set the **Grant**, the **Client authentication** and the **Header scheme** from the
+   provider's documentation.
+10. Enter the **Client ID**.
+11. Enter the **Client secret**.
+12. For the refresh token grant, enter the **Refresh token**.
+13. Choose **Register external API**.
+
+The client secret and the refresh token are write-only. After you save them, Picked shows
+only that they are stored.
+
+## 3. Add a credential to an external API that you registered
+
+1. Open the external API.
+2. Choose **Use an OAuth2 credential**.
+3. For Zoho CRM, set **Preset** to the region of your Zoho account. For another provider,
+   do steps 8 and 9 of section 2.
+4. Do steps 10 to 12 of section 2.
+5. Choose **Save credential**.
+
+The credential replaces the authorization header of the external API.
+
+## 4. Refresh only for an expired token
+
+Some APIs answer 401 for an error that a new token does not correct. To get a new token only
+for an expired token:
+
+1. Open the external API.
+2. Choose **Edit OAuth2 credential**.
+3. In **401 rule: response body path**, enter the path of the error code in the 401 answer,
+   such as `code`. Put a dot between the parts of the path, for example `data.0.code`.
+4. In **401 rule: values**, enter the error codes that show an expired token, such as
+   `INVALID_TOKEN`.
+5. Choose **Save credential**.
+
+The Zoho CRM preset sets this rule for you.
+
+## 5. Replace a refresh token that the provider rejected
+
+When the provider rejects the credential, the external API page shows the reason in **Last
+refresh failure**. Each call fails with `credential_rejected` until you correct the
+credential.
+
+1. Make a new refresh token.
+2. Open the external API.
+3. Choose **Edit OAuth2 credential**.
+4. Enter the new **Refresh token**.
+5. Choose **Save credential**.
+
+Leave the **Client secret** empty to keep the stored client secret. If you change the
+**Token URL**, the **Client ID** or the **Client authentication**, enter the client secret
+and the refresh token again.
+
+## Related
+
+- [External APIs](/reference/dashboard/external-apis#oauth2-credential) — every setting of
+  an OAuth2 credential, and when Picked gets a new token.
+- [How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow)
+  — the node that sends the request.

package/docs/how-to/render-a-step-form.md

@@ -0,0 +1,131 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to render a step form
+
+This guide shows you how to render the fields of the active step and let a visitor submit
+them.
+
+## 1. Put the steps in a router
+
+`StepRouter` watches the step state and activates the `Step` whose `id` matches.
+
+:::code-group
+
+```tsx [React]
+import { StepRouter, Step } from '@picked/react/router'
+
+function MyExperience() {
+  return (
+    <StepRouter>
+      <Step id="welcome">
+        <WelcomeScreen />
+      </Step>
+      <Step id="contact">
+        <ContactForm />
+      </Step>
+    </StepRouter>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { StepRouter, Step } from '@picked/svelte/router'
+</script>
+
+<StepRouter>
+  <Step id="welcome">
+    <WelcomeScreen />
+  </Step>
+  <Step id="contact">
+    <ContactForm />
+  </Step>
+</StepRouter>
+```
+
+:::
+
+:::note
+A router must hold every Step, even when there is only one Step.
+:::
+
+## 2. Render the fields
+
+Bind `form.props` to your `<form>` element and map over the fields.
+
+:::code-group
+
+```tsx [React]
+import { useStep, useStoreGlobal } from '@picked/react/hooks'
+
+function StepForm() {
+  const { fields, form } = useStep()
+  const currentFields = useStoreGlobal(fields)
+  const isSubmitting = useStoreGlobal(form.submitting)
+
+  return (
+    <form {...form.props}>
+      {currentFields.map((field) => (
+        <div key={field.id}>
+          <label htmlFor={field.id}>{field.label}</label>
+          <input
+            id={field.id}
+            name={field.id}
+            value={field.value ?? ''}
+            onChange={field.onChange}
+            onBlur={field.onBlur}
+          />
+          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
+        </div>
+      ))}
+      <button type="submit" disabled={isSubmitting}>Continue</button>
+    </form>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { fields, form } = getStep()
+  const isSubmitting = form.submitting
+</script>
+
+<form {...form.props}>
+  {#each $fields as field}
+    <div>
+      <label for={field.id}>{field.label}</label>
+      <input
+        id={field.id}
+        name={field.id}
+        value={field.value ?? ''}
+        onchange={field.onChange}
+        onblur={field.onBlur}
+      />
+      {#if field.error && field.touched}
+        <p class="error">{field.error.userMessage}</p>
+      {/if}
+    </div>
+  {/each}
+  <button type="submit" disabled={$isSubmitting}>Continue</button>
+</form>
+```
+
+:::
+
+The SDK checks a field on blur, and not while the visitor types.
+
+## 3. Load a large step lazily
+
+Pass a dynamic import to the `component` prop of `<Step>`. The SDK does not load the
+content until that step becomes active.
+
+## Related
+
+- [How to run code on a form submission](/how-to/run-code-on-a-form-submission) — the
+  callbacks.
+- [SDK steps](/reference/sdk/steps) — the `StepContext` shape.

package/docs/how-to/render-an-unpublished-preview.md

@@ -0,0 +1,41 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to render an unpublished preview
+
+This guide shows you how to render draft content on your server. Your server cannot read
+the query string of the browser, so you must pass the token yourself.
+
+## 1. Get the token
+
+The management API holds the preview token of a workspace in the `previewToken` field. The
+preview action in the dashboard also makes one for you.
+
+## 2. Read the config with the token
+
+```bash
+curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
+```
+
+A preview response returns `versionId: null`. An invalid token returns `401`.
+
+## 3. Pass the same token to `serialize()`
+
+```ts
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: '/promo' } },
+  previewToken,
+})
+```
+
+Use the same token for both requests. The configuration and the content then come from the same
+preview.
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
+  index.
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).

package/docs/how-to/retry-a-failed-call-with-a-loop.md

@@ -0,0 +1,81 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to retry a failed call with a loop
+
+This guide shows you how to make a workflow send a request again after the request fails.
+The workflow waits before each new try. It stops after a number of tries that you set.
+
+You need a workflow with an **External API** node first. Refer to
+[How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow).
+
+## The loop
+
+A loop is a path of edges that goes back to a node that the run reached before. This loop
+has three nodes:
+
+| Node                | Function                                         |
+| ------------------- | ------------------------------------------------ |
+| External API `send` | Sends the request.                               |
+| Condition `check`   | Decides if the workflow sends the request again. |
+| Sleep `pause`       | Waits before the next try.                       |
+
+When you save a workflow, Picked refuses a loop that does not have a sleep node and a
+condition node on it. Picked also refuses an edge from a node to the same node.
+
+## 1. Connect the error exit to a condition
+
+1. Open the workflow.
+2. Choose **Add condition** on the error exit of `send`.
+3. In the rule of `check`, test `{{ nodes.send.error.retryable }}`.
+4. Connect the `false` exit of `check` to the nodes that record the failure.
+
+`check` runs only when the call fails. The rule can then read the error of the last try.
+
+## 2. Add the sleep node
+
+1. Choose **Add sleep** on the `true` exit of `check`.
+2. Set **Wait for** to the time between two tries.
+3. Connect the exit of `pause` to the input of `send`.
+
+The editor shows a loop as an edge that goes back to `send`.
+
+## 3. Set the number of tries
+
+Each node in the loop runs one time for each try. A run can visit one node a maximum
+number of times. This number is the visit cap of the workflow.
+
+1. Open the workflow settings.
+2. Set **Visit cap** to a number from 1 to 100. If you do not set it, the visit cap is 10.
+
+A node can get to the visit cap. If the run then gets to the node again, the run stops.
+The run shows `Failed` with the code `loop_limit_reached`.
+
+To stop the loop before the visit cap, test `current.visit` in the rule of `check`.
+Its value is the number of the visit to `check`. This is also the number of failed tries.
+This rule tries a maximum of 3 times:
+
+```json
+{
+  "and": [{ "var": "nodes.send.error.retryable" }, { "<": ["{{ current.visit }}", 3] }]
+}
+```
+
+With this rule, the run continues on the `false` exit of `check` after 3 failures.
+
+## 4. Read the result
+
+A node reads the last visit of another node. After the loop, `{{ nodes.send.status }}`
+gives the status of the last try.
+
+The **Tasks** card of the run shows each visit as a task. Refer to the
+[Workflow runs reference](/reference/dashboard/workflow-runs#tasks).
+
+## Related
+
+- [Workflow runs](/reference/dashboard/workflow-runs) — the tasks of each visit, and the
+  visit cap.
+- [Workflow templates](/reference/dashboard/workflow-templates) — the data that a node
+  reads in a loop.

package/docs/how-to/reuse-a-section.md

@@ -0,0 +1,64 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to reuse a section
+
+This guide shows you how to define a common structure one time and use it in more than
+one Model.
+
+## 1. Create the section
+
+1. Click **Pages** in the sidebar.
+2. Click **Page Sections**.
+3. Click **New block**.
+4. Enter a **Name** and a **Key**.
+5. Add your fields.
+6. Click **Create block**.
+
+The **Category** is **Section** already, because you opened the list from **Page
+Sections**.
+
+## 2. Accept the section in a Model
+
+1. Open a page layout or a step layout.
+2. Add a **Page Sections** field to the schema.
+3. Click **Save**.
+
+The field now accepts any Block of the Section category. Make the field repeatable to
+build a page from a list of sections.
+
+If you want one section at a fixed place instead of a list, add a **Content block** field.
+Set its **Block category** to the **Section** category.
+
+## 3. Choose the section in an entry
+
+1. Open a content entry that uses the Model.
+2. Find the field that you added.
+3. Choose your Block.
+4. Fill in the fields of the Block.
+5. Click **Save**.
+
+:::warning
+An edit to a Block does not migrate the entries that use it. Check each affected content
+entry again, and correct every field error before you publish.
+:::
+
+## 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 the section | [`contentBlockCreate`](/reference/management-api/schema/cms-models#contentblockcreate) | [`create_content_block`](/reference/tools/mcp#create_content_block) | `tools.create_content_block({ workspace_id, name, key, schema })` |
+| Accept the section in a Model | [`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 })` |
+| Choose the section 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 })` |
+| Check the entries after you edit a Block | [`workspaceContentEntryValidation`](/reference/management-api/schema/cms-models#workspacecontententryvalidation) | [`validate_workspace_content_entries`](/reference/tools/mcp#validate_workspace_content_entries) | `tools.validate_workspace_content_entries({ workspace_id })` |
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [Blocks](/reference/dashboard/content/blocks) — the reference.
+- [Models](/reference/dashboard/content/models) — every field type.