@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

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

@@ -0,0 +1,67 @@
+---
+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).
+
+## 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/client'
+
+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. 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.
+- [Actions](/reference/dashboard/actions) — the dashboard options.

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

@@ -0,0 +1,132 @@
+---
+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 } from '@picked/react/hooks'
+import { useUnit } from 'effector-react'
+
+function StepForm() {
+  const { fields, form } = useStep()
+  const currentFields = useUnit(fields)
+  const isSubmitting = useUnit(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/dist/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/dist/docs/how-to/reuse-a-section.md

@@ -0,0 +1,37 @@
+---
+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 layout.
+
+## Create a section
+
+1. Open your workspace.
+2. Click **Pages** in the sidebar, then **Sections**.
+3. Click **New block**.
+4. Enter a **Name** and a **Key**.
+5. Add your fields.
+6. Click **Create block**.
+
+## Use it in a layout
+
+1. Open a page layout or a step layout.
+2. Add a **Section** field.
+3. Point that field at your section.
+
+The layout now carries the fields of the section at every place where that field appears.
+
+:::warning
+An edit to a section does not migrate the entries that use it. Check each affected content
+entry again, and correct every field error before you publish.
+:::
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [Sections](/reference/dashboard/content/sections) — the reference.

package/dist/docs/how-to/reuse-a-step-field-or-action.md

@@ -0,0 +1,28 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to reuse a step, a field, or an action
+
+This guide shows you how to use one step, field, action, or condition in more than one
+flow. All four belong to the project, and not to the experience that you made them in.
+
+## Steps
+
+1. Open the flow builder for the second experience.
+2. Find the step, the action, or the condition in the library on the left.
+3. Drag it onto the canvas, or onto a step node for a field.
+
+The same one now appears in both flows.
+
+:::warning
+A change to the options applies at every place that uses it. Check the other flows before
+you change a shared step, field, action, or condition.
+:::
+
+## Related
+
+- [Steps](/reference/dashboard/steps) — the step options.
+- [Fields](/reference/dashboard/fields) — the field options.
+- [Actions](/reference/dashboard/actions) — the action options.

package/dist/docs/how-to/roll-back-a-published-version.md

@@ -0,0 +1,26 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to roll back a published version
+
+This guide shows you how to make an earlier published version live again. Your current
+draft does not change.
+
+## Steps
+
+1. Open **Publish history** from the project sidebar.
+2. Find the version that you want to restore.
+3. Click **Restore**.
+4. Read the diff preview. It compares the current live version against the one that you
+   chose.
+5. Click **Restore this version** to confirm.
+
+The restored version is live immediately.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
+  changes no data.
+- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

package/dist/docs/how-to/run-an-ab-test.md

@@ -0,0 +1,49 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to run an A/B test
+
+This guide shows you how to split your traffic with a feature flag and read the result in
+your application.
+
+Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
+point at which you read the feature flag decides when a visitor enters the test.
+
+## 1. Create the feature flag
+
+1. Open your project.
+2. Click **Feature flags** in the sidebar.
+3. Click **New feature flag**.
+4. Enter a name.
+5. Click **Create feature flag**.
+
+You cannot change the key after you create the feature flag.
+
+## 2. Set the allocation
+
+Open the detail page of the feature flag and set these controls:
+
+1. Turn **Enabled** on. A feature flag that is off allocates nobody.
+2. Set **Weight** to the percentage of visitors that you want in the test.
+3. Enter a **Description** that says what the feature flag tests.
+
+## 3. Read the feature flag in your application
+
+See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
+the decision matters, and not at startup.
+
+## 4. Change the weight later
+
+1. Change **Weight** on the detail page.
+2. Increment the version.
+
+The new weight then applies to a visitor with a cached decision. Leave the version as it
+is to apply the new weight only to a visitor who is not allocated yet.
+
+## Related
+
+- [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
+  flags at the same weight give four groups, not two.
+- [Feature flags](/reference/dashboard/features) — the controls.

package/dist/docs/how-to/run-code-on-a-form-submission.md

@@ -0,0 +1,125 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to run code on a form submission
+
+This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
+in React, or to `getStep()` in Svelte.
+
+## What the SDK does on submit
+
+1. It collects the field values from the HTML form.
+2. It runs each `onBeforeSubmit` callback, one after another.
+3. It checks each required field and each validation rule.
+4. It commits the responses to the experience state.
+5. It fires `form_submit_success` or `form_submit_error` on the event bus.
+6. It runs your `onSuccess` or `onError` callback.
+7. It moves to the next step.
+
+## Change the data before it is stored
+
+:::code-group
+
+```tsx [React]
+const { form } = useStep({
+  onBeforeSubmit: async (data) => ({
+    ...data,
+    'email-address': String(data['email-address']).toLowerCase(),
+  }),
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const { form } = getStep({
+    onBeforeSubmit: async (data) => ({
+      ...data,
+      'email-address': String(data['email-address']).toLowerCase(),
+    }),
+  })
+</script>
+```
+
+:::
+
+:::warning
+An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
+anything, and the step does not advance. Use it for a transform and for a check. Put a
+side effect, such as an analytics call, in `onSuccess`.
+:::
+
+## Act on the outcome
+
+:::code-group
+
+```tsx [React]
+const { form } = useStep({
+  onSuccess: ({ data }) => analytics.track('lead_captured', data),
+  onError: (errors) => console.error('Validation errors:', errors),
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const { form } = getStep({
+    onSuccess: ({ data }) => analytics.track('lead_captured', data),
+    onError: (errors) => console.error('Validation errors:', errors),
+  })
+</script>
+```
+
+:::
+
+A callback belongs to the component that passes it, and the SDK releases it when that
+component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
+reports the failure as `form_submit_callback_error`.
+
+## Choose the next step yourself
+
+Call `stopNavigation()` inside `onSuccess`, then move where you want:
+
+:::code-group
+
+```tsx [React]
+const experience = useExperience()
+
+const { form } = useStep({
+  onSuccess: ({ data, stopNavigation }) => {
+    stopNavigation()
+    if (data['plan-type'] === 'enterprise') {
+      experience.goToStepById('enterprise-contact')
+    } else {
+      experience.goToNextStep()
+    }
+  },
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const experience = getExperience()
+
+  const { form } = getStep({
+    onSuccess: ({ data, stopNavigation }) => {
+      stopNavigation()
+      if (data['plan-type'] === 'enterprise') {
+        experience.goToStepById('enterprise-contact')
+      } else {
+        experience.goToNextStep()
+      }
+    },
+  })
+</script>
+```
+
+:::
+
+`goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
+step matches, the call does nothing.
+
+## Related
+
+- [How to render a step form](/how-to/render-a-step-form).
+- [SDK steps](/reference/sdk/steps) — the `form` object.

package/dist/docs/how-to/server-render-a-page.md

@@ -0,0 +1,81 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to server-render a page
+
+This guide shows you how to render a Picked Page on your server and hydrate it in the
+browser. You need a published Page and a server that renders React or Svelte.
+
+## 1. Make the snapshot
+
+Create one client for each request, then call `serialize()`:
+
+```ts
+import { createClient } from '@picked/client'
+import { serialize } from '@picked/client/server'
+
+const client = createClient(options)
+
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: url.pathname } },
+})
+```
+
+:::warning
+Give `serialize()` one client for each request. It does not support two calls at the same
+time on one client.
+:::
+
+## 2. Embed the snapshot
+
+```ts
+const html = `
+  <div id="root">${appHtml}</div>
+  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
+`
+```
+
+## 3. Seed the client and render the slot
+
+:::code-group
+
+```tsx [React]
+import { PickedProvider, ExperienceSlot } from '@picked/react'
+
+export function Page({ snapshot }) {
+  return (
+    <PickedProvider options={options} snapshot={snapshot}>
+      <ExperienceSlot name="page" />
+    </PickedProvider>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
+
+  const { snapshot } = $props()
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+:::
+
+The provider seeds the client at once, so the server HTML and the first paint match.
+
+## 4. Point the experience at the slot
+
+Set the target selector of your Page experience to `.picked-slot-page`, then publish.
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why the
+  snapshot carries condition results.
+- [Server snapshot](/reference/sdk/ssr/serialize) — every parameter.
+- [Your first server-rendered page](/tutorials/first-server-rendered-page).

package/dist/docs/how-to/set-a-content-security-policy.md

@@ -0,0 +1,32 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to set a Content Security Policy
+
+This guide shows you how to let the Picked SDK load its resources under a CSP.
+
+## Steps
+
+Add the Picked domains to your policy.
+
+As an HTTP header:
+
+```
+Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
+```
+
+Or as a `<meta>` tag:
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
+/>
+```
+
+## Related
+
+- [Content Security Policy](/reference/sdk/content-security-policy) — what each domain is
+  for.

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

@@ -0,0 +1,69 @@
+---
+type: how-to
+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.
+
+## 1. Add a factor
+
+```graphql
+mutation {
+  mfaFactorEnroll(input: {
+    factorType: PHONE
+    phone: "+15551234567"
+    friendlyName: "My Phone"
+  }) {
+    factor { id factorType status }
+  }
+}
+```
+
+A new factor has the status `UNVERIFIED`.
+
+## 2. Send a challenge
+
+```graphql
+mutation {
+  mfaChallengeSend(input: { factorId: "factor-id" }) {
+    challengeId
+  }
+}
+```
+
+This sends a code to the telephone number of the factor.
+
+## 3. Verify the challenge
+
+```graphql
+mutation {
+  mfaChallengeVerify(input: {
+    factorId: "factor-id"
+    challengeId: "challenge-id"
+    code: "123456"
+  }) {
+    session { accessToken refreshToken aal }
+  }
+}
+```
+
+The session moves to `AAL2`, and the factor status changes to `VERIFIED`.
+
+## Remove a factor
+
+```graphql
+mutation {
+  mfaFactorUnenroll(input: { factorId: "factor-id" }) {
+    success
+  }
+}
+```
+
+## Related
+
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — which
+  operations need `AAL2`.
+- [Authentication](/reference/management-api/authentication) — every mutation.