@picked/client 0.0.101-next.1 → 0.0.101-next.3

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

@@ -1,81 +0,0 @@
----
-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'
-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

@@ -1,32 +0,0 @@
----
-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

@@ -1,113 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to set up MFA
-
-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.
-
-## 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, most operations return the error code `MFA_REQUIRED`
-until the session reaches `AAL2`. The operations that a session at `AAL1` can use are in
-[Authenticator assurance levels](/reference/management-api/authentication#authenticator-assurance-levels).
-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: { friendlyName: "Work phone" }) {
-    factor { id factorType status }
-    totp { qrCode secret uri }
-  }
-}
-```
-
-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.
-
-Before it adds the factor, the mutation deletes the caller's factors that are not verified.
-But it keeps the two newest of these factors if they are less than 60 seconds old. A
-different setup can still use them, for example in a different browser tab. The mutation
-also deletes a factor that is not verified and has the `friendlyName` that you give.
-Therefore, a setup that did not finish does not stop a new setup.
-
-## 2. Open a challenge
-
-```graphql
-mutation {
-  mfaChallengeCreate(input: { factorId: "factor-id" }) {
-    challengeId
-    expiresAt
-  }
-}
-```
-
-## 3. Verify the code
-
-```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`. Use the returned
-tokens from this point. A wrong code returns `MFA_CHALLENGE_FAILED`.
-
-## Sign in with an authenticator
-
-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 {
-  mfaFactorUnenroll(input: { factorId: "factor-id" }) {
-    success
-  }
-}
-```
-
-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
-
-- [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/how-to/switch-workspaces.md

@@ -1,122 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to switch workspaces
-
-This guide shows you how to point your local tooling at a different project or workspace.
-Your application then renders that workspace's content and types on your machine. It expects
-a `picked.config.ts` and the [CLI](/reference/tools/cli).
-
-Your tooling reads the project and surface named in the committed `picked.config.ts`. The
-CLI writes your choice to `.picked/settings.json` instead. That file is per-developer and
-Git ignores it, so the committed default stays as it is and one command puts it back.
-
-See [Workspaces](/reference/dashboard/workspaces) for what Live, Draft, and Archived mean.
-
-## 1. Sign in
-
-```bash
-picked login
-```
-
-This opens your browser for a one-time OAuth sign-in and stores a session under
-`~/.picked/`. Confirm it with `picked whoami`. See
-[CLI authentication](/how-to/authenticate-the-cli).
-
-## 2. Find a workspace
-
-```bash
-picked workspace list
-```
-
-```
-Acme Corp. (acme-corporation)
-  Storefront [proj_a1b2]
-    Default Storefront [LIVE] (live)
-    Checkout rework [DRAFT]
-```
-
-Note the **project id** (`proj_a1b2`) and the name or the id of the workspace you want.
-
-## 3. Switch to the draft
-
-```bash
-picked workspace use --project proj_a1b2 --workspace ws_draft
-```
-
-```
-Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
-Generated types at /app/src/picked-env.d.ts
-```
-
-A command that names **one specific workspace** (draft, live, or archived):
-
-- writes the selection (and its [preview token](/reference/delivery-api/preview-caching-crawling)) to
-  `.picked/settings.json`,
-- switches the resolved `source` to `preview` for that project, and
-- regenerates `picked-env.d.ts` from that workspace's schema (skip with `--no-generate`).
-
-To browse instead, run `picked workspace use` with no flags. The interactive picker lists
-every project, with **Published (live version)** and each of its workspaces.
-
-## 4. See the draft in your app
-
-Both readers of the selection use `.picked/settings.json` with no change to your
-configuration:
-
-- **Type generation** now reads the draft schema. Rerun `picked generate types` after more
-  edits.
-- The **[Vite plugin](/reference/tools/vite-plugin)** reads the draft's configuration and
-  content in development and in a build. It sends the preview token to the
-  [Delivery API](/reference/delivery-api). Restart the dev server to apply a switch.
-
-Your application renders the unpublished draft on your machine, with types.
-
-## 5. Switch back to live
-
-```bash
-picked workspace use --project proj_a1b2
-```
-
-A command that names a project with no `--workspace`, or **Published (live version)** in the
-picker, discards the preview token and returns `source` to `published`. To confirm what is
-active:
-
-```bash
-picked status
-```
-
-```
-Config default: project proj_a1b2 (source: published)
-Active selection: none (using the config default).
-```
-
-## CI and headless runs
-
-`.picked/settings.json` is a local, per-developer file. Do not commit it. To choose one
-workspace in CI with no selection file, set the environment directly:
-
-```bash
-PICKED_PROJECT_ID=proj_a1b2 \
-PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
-  picked generate types --check
-```
-
-`PICKED_PREVIEW_TOKEN` applies only when the resolved `source` is `preview`. See the
-[CLI environment variables](/reference/tools/cli#environment-variables) for the full
-precedence order.
-
-:::note
-A preview token is a long-lived credential for one workspace. Keep it out of the version
-control system, as you do with each other credential. Git ignores `.picked/settings.json`
-for this reason, because `picked workspace use` writes a token there.
-:::
-
-## Related
-
-- [CLI](/reference/tools/cli) — every command and flag.
-- [Workspaces](/reference/dashboard/workspaces) — Live, Draft, and Archived states.
-- [Type generation](/reference/sdk/type-generation) — how the schema becomes types.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — preview tokens on the Delivery API.

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

@@ -1,73 +0,0 @@
----
-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.
-:::
-
-## Related
-
-- [Asset library](/reference/dashboard/content/asset-library) — the limits, the file
-  types, and how Picked serves an uploaded file.

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

@@ -1,52 +0,0 @@
----
-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/dist/docs/how-to/wait-for-an-action-response.md

@@ -1,182 +0,0 @@
----
-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/how-to/write-a-condition.md

@@ -1,45 +0,0 @@
----
-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.
-
-## 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.