@picked/client 0.0.70 → 0.0.71-next.2

package/dist/docs/content/asset-library.mdx

@@ -1,124 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Asset Library
-
-The Asset Library holds the files that your content points at. These are images,
-video, documents, and HTML.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/assets"
-  alt="The asset library on the Picked dashboard"
-/>
-
-## Upload and control your assets
-
-The Asset Library is a project-level store. Upload a file, then point at it from any
-Content Entry in the project.
-
-- **Size limit:** 50 MB for each file.
-- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
-  or WebM. A common document format. HTML, as `text/html`.
-
-Picked rejects a file of another type. It also rejects a file above the size limit.
-
-## Reference an asset from a field
-
-Two field types point at an item in the library:
-
-- An **Asset** field points at an image, a video, or a document.
-- An **HTML asset** field takes a `.html` file from your library.
-
-Add the field to a [layout](/content/layouts). Then choose an item from the library
-when you fill in the [Content Entry](/content/content-entries).
-
-## Pick an asset
-
-Every Asset field opens the same picker. Click **Choose file** to open it. On a field
-with a value already, click **Replace**. The modal has two tabs: **Library**, where
-you browse the assets that are there, and **Upload**, where you add a new file.
-
-<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 by menu"
-  renderWidth={1072}
-  renderHeight={790}
-/>
-
-### Search, filter, and sort
-
-The Library tab has three controls that make a large asset list smaller. The server
-applies each one across the whole library, and not only across the assets that it
-loaded already:
-
-- **Search:** narrows the list by file name while you type.
-- **Type filter:** narrows the list to one media type. The choices are All types,
-  Images, Video, Audio, Documents, and Archive files.
-- **Sort by:** orders the list by the Name or by the Date uploaded, each one
-  ascending or descending.
-
-:::note
-The results come one page at a time. Click **Load more** at the bottom of the list to
-read the next page.
-:::
-
-### Choose one asset or several
-
-The picker changes with the number of assets that the field takes:
-
-- A field that holds one asset shows a **radio** indicator next to each row. The
-  Asset field of a layout and the guidance file of a design system both do this. A
-  new choice replaces the current asset.
-- A place that takes several assets at once shows a **checkbox** indicator. The
-  detail panel then also shows a count of what you chose. The Files tab of a
-  workbench does this.
-
-The detail panel on the right shows the kind, the dimensions, the size, and the
-upload date of the asset that you chose.
-
-### Open an asset in a new tab
-
-Each row has an **Open in new tab** control, and so does the detail panel of the
-asset that you chose. It links to the full detail page of the asset, and your choice
-in the picker stays as it is.
-
-:::tip
-Use this to check an asset again before you choose it. You can see the full-size
-preview and every version that somebody uploaded.
-:::
-
-## HTML assets
-
-Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
-the file. The scan is advisory: it helps you, and it never stops you. It
-reports findings about speed, about search rank, and about accessibility, so that you
-can improve the file before you publish it:
-
-- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
-- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
-- **Image dimensions:** an image with no width and no height. Such an image can move
-  the content around it while the page loads.
-- **Lazy load:** an image with no `loading="lazy"` attribute.
-- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
-- **Link search rank:** an external link with no `rel="nofollow"`.
-- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
-  contrast, and more.
-
-Every finding is advisory. You can always upload the file as it is.
-
-## How assets are served
-
-Picked serves each asset from a sandboxed storage origin. That origin is separate
-from the trusted origin of your application. HTML therefore comes from its own
-origin, so a document that you upload runs in isolation and cannot reach the page
-that holds it.
-
-An [Experience Content](/delivery-api/experience-content) response can hold an HTML
-asset. The response then carries the content of that asset, and the SDK renders it
-with no second request to storage.

package/dist/docs/content/pages.mdx

@@ -1,82 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Pages
-
-A Page is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
-  alt="The experiences list, where Pages and Flows are created on the Picked dashboard"
-/>
-
-## Pages and flows
-
-Picked has two experience kinds:
-
-| Experience | What it is | Use it for |
-| --- | --- | --- |
-| **Page** | A standalone experience that your server renders from a Content Entry. | A landing page or a campaign page where the search rank matters, and any content that a crawler must see. |
-| **Flow** | An interactive experience of more than one step, which the browser renders. | A quiz, a survey, a product finder, and onboarding of more than one step. |
-
-Choose a **Page** when the content must be in the HTML from your server, for a search
-engine and for a social preview. Choose a **Flow** when the value is in the
-interaction, and a browser render is acceptable. See
-[Experiences](/experiences) for the wider picture.
-
-## How a page fits together
-
-Four pieces back every Page:
-
-1. A **Page Layout** defines the shape: the fields a page can hold. See [Page & Step Layouts](/content/layouts).
-2. A **Content Entry** fills that shape with real data. See [Content Entries](/content/content-entries).
-3. A **Page** binds one entry so the SDK can render it.
-4. The **SDK** fetches the entry and renders it on your server. See [Server-Side Rendering](/sdk/ssr).
-
-A layout defines the shape, a content entry fills it with data, a Page binds an entry so the SDK can render it. Step Layouts do the same for individual Steps inside a Flow.
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
-```
-
-## Create a page
-
-1. Open your project.
-2. Choose a workspace.
-3. Click **Experiences** in the sidebar.
-4. Click **New Experience**.
-5. Choose the **Page** type.
-6. Choose a **Page Layout**. The layout sets which fields the page holds.
-7. Click **Create**.
-
-A Content Entry is created and linked to the page on its first save, so the page always has somewhere to store its data.
-
-## Edit page content
-
-The Page editor has two tabs. The **Properties** tab holds the content of the page.
-The **Settings** tab holds its name, its condition, and its layout. Fill in the
-fields on the **Properties** tab. The inspector on the right edits the field that you
-choose, and the preview panel shows the page while it fills in.
-
-## Change or remove the layout
-
-Use the change-layout control on the **Settings** tab to move the page to another
-Page Layout. When you unlink a layout, Picked separates the Content Entry from the
-page. It deletes no entry, but the page then has no content to render until you
-attach a layout again.
-
-## Validate and publish
-
-An invalid field shows an error next to it while you edit, so that you can correct it
-before you publish. When the page is valid, publish the workspace to make it live.
-That makes the version that the Delivery API serves to an anonymous reader.
-
-## Render a page
-
-The SDK renders a published Page on your server. See the
-[Build a Personalized Page](/guides/build-a-personalized-page) guide for the full
-steps, and [Server-Side Rendering](/sdk/ssr) for the SDK reference.

package/dist/docs/content/sections.mdx

@@ -1,44 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Sections
-
-Sections are reusable schema fragments you embed inside layouts, so common structures such as a hero or a feature list are defined once.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
-  alt="The sections list in the schema builder on the Picked dashboard"
-/>
-
-## What a section is
-
-A Section is a reusable schema fragment with its own **Key**. A
-[layout](/content/layouts) gives its shape to a whole Page or Step. A Section is a
-part that you put into one or more layouts. Define the shape one time, then reuse it
-everywhere.
-
-## Create a section
-
-1. Open your workspace.
-2. Click **Sections** in the sidebar.
-3. Click **New Section**.
-4. Enter a name and a **Key**. The Key is a unique, stable identifier. Your SDK code
-   and your API calls both use it.
-5. Add your fields.
-6. Save.
-
-## Use a section in a layout
-
-Add a **Section** field to a Page Layout or a Step Layout. Point that field at the
-Section that you want. The layout then carries the fields of the Section at every
-place where that field appears. A Content Entry from the layout fills in the fields
-of the Section in the same way as every other field.
-
-## Change a section
-
-An edit to a Section does not migrate the entries that use it. After you change a
-Section, check each affected [Content Entry](/content/content-entries) again. Correct
-every field error before you publish.

package/dist/docs/delivery-api/index.md

@@ -1,53 +0,0 @@
----
-layout: docs
----
-
-# Delivery API
-
-The Delivery API is a public REST API. It is read-only, and it serves the published
-options of your project together with your page content. It is separate from the
-GraphQL management API.
-
-## The Delivery API and the management API
-
-Picked has two HTTP APIs. Use the one that fits your work:
-
-| | Delivery API | Management API |
-| --- | --- | --- |
-| Style | REST | GraphQL |
-| Access | Public, anonymous | Authenticated |
-| Operations | Read-only | Read and write |
-| Use it to | Serve published options and content to your application | Control your projects, experiences, and content |
-
-The [API Reference](/api) covers the management API. This section covers the Delivery
-API.
-
-## Base URL and versioning
-
-All Delivery API routes are versioned under `/api/v1`:
-
-```
-https://api.picked.app/api/v1
-```
-
-## Published content and preview content
-
-Each endpoint serves two surfaces:
-
-- **Published** content is anonymous. Anybody can read your published options and
-  your published content.
-- **Preview** content needs a `preview_token` query parameter. With it you can render
-  an unpublished draft before you make it live.
-
-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.
-
-## Endpoints
-
-| Endpoint | Description |
-| --- | --- |
-| [Project Config](/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published options of the project, with the content link of each step. |
-| [Experience Content](/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
-
-Both endpoints share some behaviour. See
-[Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).

package/dist/docs/guides/build-a-personalized-page.mdx

@@ -1,161 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Build a Personalized Page
-
-Build a personalized landing page with Picked: model it in the dashboard, publish it, and render it server-side in your app.
-
-## What you will build
-
-A standalone landing page where the search rank matters. Its content lives in the
-Picked CMS, and your server renders it. You describe the shape of the page one time,
-fill it with content, and publish it. Your server then reads it and renders it in
-React or in Svelte. These are the stages, from the first draft to a hydrated page:
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
-```
-
-## Model a page layout
-
-A [Page Layout](/content/layouts) defines the fields your page can hold.
-
-1. Open your workspace.
-2. Click **Models** in the sidebar.
-3. Click **New Model**.
-4. Choose **Page Layout**.
-5. Enter a name and a **Key**, for example `page-hero`. The Key is a unique, stable
-   identifier. Your SDK code and your API calls both use it.
-6. Add three fields: a **Single-line text** field `title`, a **Markdown** field
-   `body`, and an **Asset** field `image`.
-7. Save the layout.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
-  alt="A page layout in the schema builder on the Picked dashboard"
-/>
-
-See [Page & Step Layouts](/content/layouts) for every field type.
-
-## Create and fill the page
-
-1. Click **Experiences** in the sidebar.
-2. Click **New Experience**.
-3. Choose the **Page** type.
-4. Choose your `page-hero` layout.
-5. On the **Properties** tab, fill in `title`, `body`, and `image`. On the first save,
-   Picked creates a [Content Entry](/content/content-entries) and links it to the
-   page.
-6. Correct every field error.
-7. Publish the workspace to make the page live.
-
-See [Pages](/content/pages) for the full editor reference.
-
-## Fetch the config and content
-
-Your server reads two things from the [Delivery API](/delivery-api). The first is the
-options of the project, which give the experiences and the steps. The second is the
-content of the experience that matches.
-
-```bash
-# 1. The project options: find the steps and their content links.
-curl https://api.picked.app/api/v1/projects/proj_123
-
-# 2. The experience content: the entry data of the page.
-curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
-```
-
-In practice you fetch the config, then let `serialize()` fetch the content for you. See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content).
-
-## Render server-side and hydrate
-
-On the server, create a per-request client, call `serialize()` to produce a snapshot, render your app, and embed the snapshot. On the client, seed from the snapshot and hydrate.
-
-```ts
-// `server.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 } },
-})
-// Render your app, then embed `snapshot` in the HTML response.
-```
-
-Render `<ExperienceSlot name="page" />` inside the provider, and register the component the Page maps to (here, `CMSPage`):
-
-:::code-group
-
-```tsx [React]
-import type { CreateClientOptions } from '@picked/client'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { useStepContent } from '@picked/react/hooks'
-
-function CMSPage() {
-  const content = useStepContent()
-  const title = typeof content?.title === 'string' ? content.title : ''
-  return <h1>{title}</h1>
-}
-
-const options = {
-  projectId: 'proj_123',
-  components: { CMSPage: adaptReactComponent(CMSPage) },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-} satisfies CreateClientOptions
-
-export function Page({ snapshot }) {
-  return (
-    <PickedProvider options={options} snapshot={snapshot}>
-      <ExperienceSlot name="page" />
-    </PickedProvider>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import type { CreateClientOptions } from '@picked/client'
-  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
-  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-  import CMSPage from './CMSPage.svelte'
-
-  const { snapshot } = $props()
-
-  const options = {
-    projectId: 'proj_123',
-    components: { CMSPage: adaptSvelteComponent(CMSPage) },
-    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-  } satisfies CreateClientOptions
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
-
-The provider seeds synchronously, so the server HTML and the client's first paint match, then the SDK hydrates. See [Server-Side Rendering](/sdk/ssr) for the full reference.
-
-## Verify SEO
-
-Confirm the page is crawlable end to end:
-
-1. Read the response from your server. Use `curl`, or the view-source command of
-   your browser.
-2. Check that the HTML holds your `title` and your `body`, and that it is not an
-   empty shell.
-3. Check that the content endpoint answers an anonymous request.
-4. Check that it returns your entry data.
-
-A crawler can read a published Delivery API response. A preview URL is disallowed.
-See [Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).

package/dist/docs/pickedql/index.md

@@ -1,54 +0,0 @@
----
-layout: docs
----
-
-# PickedQL
-
-PickedQL is a SQL query language for your Picked analytics data. Write short SQL with
-a virtual table and a virtual function. PickedQL expands them into a full query, and
-it adds the joins and the A/B test aggregations for you.
-
-## Quick start
-
-```sql
--- How many users are in the control group, and how many in the variant group?
-SELECT control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-```
-
-PickedQL maps each table and adds each dimension join for you. You write short SQL
-that a person can read, and PickedQL does the rest.
-
-## How PickedQL works
-
-1. **Virtual table expansion**: a table name such as `metrics` maps to the data
-   tables below it.
-2. **Virtual function expansion**: a short function such as `control_users()` expands
-   to a full aggregate expression.
-3. **Automatic dimension joins**: PickedQL adds a `LEFT JOIN` when you point at a
-   dimension column, such as `device_category` or `country_code`. You write no join.
-4. **Tenant isolation**: every query must hold a tenant filter in the `WHERE` clause.
-   That filter is `project_id` for most tables. The `projects` table uses `id`
-   instead, because the `id` of the row is the project ID. PickedQL reads the filter
-   and checks that you have permission for that project.
-5. **SQL passthrough**: standard SQL works next to a virtual function. This includes
-   `CASE WHEN`, a window function, and a subquery.
-
-## Best practices
-
-- **Use `metrics` for a dashboard**: data that PickedQL aggregates first is much
-  faster than raw events for a standard report.
-- **Use `events` to go deeper**: raw event data lets you build any breakdown or
-  funnel that you want.
-- **Use `experience_journey` for a sankey chart or a funnel chart**: one line of SQL
-  returns `source, target, users`. PickedQL builds the eight common table expressions
-  for you. Those remove the duplicates, rank the top paths, and call `lagInFrame`.
-  Pass your parameters in the `WHERE` clause.
-- **Write no JOIN**: PickedQL adds each one when you point at a dimension column.
-- **Group by any dimension**: add a dimension column to `SELECT` and to `GROUP BY`.
-  PickedQL adds the join that it needs.
-- **Read the reference tables for no cost**: use `step_title`, `experience_title`, and
-  `project_name` directly in an `events` query. PickedQL joins the `steps`,
-  `experiences`, and `projects` reference tables for you.
-

package/dist/docs/projects.mdx

@@ -1,44 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Projects
-
-A project is one site or one application that you want to measure with Picked. Each
-project has its own experiences, entities, and options.
-
-<Screenshot
-  route="/{orgSlug}"
-  alt="The organization home page on the Picked dashboard, with the projects in an organization"
-/>
-
-## Create a project
-
-You need an organization first. If you do not have one, create it when you sign up.
-
-1. Open your organization.
-2. Click **New Project**.
-3. Enter a name.
-4. Click **Create**.
-
-## Workspaces
-
-Each project holds one or more [Workspaces](/workspaces). In a workspace you set the
-options for an experience and you see a preview of it before you make it live.
-
-## Project home
-
-When you open a project, you land on the project home page. It shows your SDK
-snippet and a list of the setup tasks that are still open.
-
-Copy the snippet and add it to your site. The snippet connects your site to the
-project and lets Picked serve experiences to it. See
-[SDK Installation](/sdk) for the setup detail.
-
-## Project navigation
-
-The sidebar shows every section of your project: **Experiences**, **Fields**,
-**Steps**, **Actions**, **Conditions**, and more. Some sections appear only when your
-account has them.

package/dist/docs/reports.mdx

@@ -1,20 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Reports
-
-A report shows analytics data for your project. Use a report to track how your
-visitors use your experiences and feature flags.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/reports"
-  alt="The reports list for a project on the Picked dashboard"
-/>
-
-## See report data
-
-Open a report to see its analytics. The data updates when Picked records a new
-visitor interaction.

package/dist/docs/sdk/actions.md

@@ -1,82 +0,0 @@
----
-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.
-
-## Register an action
-
-Register your actions when you create the Picked client. Each key in the `actions`
-object 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)
-    },
-  },
-})
-```
-
-Each action is a function. It takes optional parameters and it usually runs a side
-effect. When the flow reaches an action node, the SDK calls the function that
-matches. The SDK then takes a branch, which depends on whether the function succeeds
-or throws. See [Success and failure branches](#success-and-failure-branches).
-
-## How actions work
-
-1. **Registration**: you register each action on the Picked client at startup.
-2. **Flow traversal**: the SDK walks the experience flow. When it reaches an action
-   node, it finds the action by its key.
-3. **Execution**: the SDK calls the function that matches and awaits it. The outcome
-   then decides which node comes next.
-4. **No block**: an action does not interrupt your visitor. The current step
-   stays on the screen while an async action runs.
-
-## Success and failure branches
-
-An action node can have a **success** branch and a **failure** branch. The SDK
-chooses the branch from the outcome of the action:
-
-- **Failure** — the action throws, or its promise rejects. The flow takes the failure
-  branch, `onFail`.
-- **Success** — the action resolves to any value: `void`, `true`, `false`, or a
-  string. A resolved `false` is a valid response and not a failure. The flow takes
-  the success branch, `onSuccess`.
-
-Keep the failure branch for a true error. Throw on the failure case, because a
-returned value never takes the `onFail` branch:
-
-```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')
-}
-```
-
-A valid negative result is not a failure. An API can return `200` with a "no", for
-example `{ serviced: false }`. Record that value as a response and branch on it with
-a condition. Do not throw:
-
-```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)
-}
-```
-
-An action node can also have one plain connection, with no success or failure branch.
-The flow then continues through it on either outcome.