@picked/client 0.0.1-dev.1788925875333 → 0.0.1-next.1

package/dist/docs/explanation/the-content-model.md

@@ -1,87 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About the content model
-
-Picked splits your content into three pieces: a Model, a Block, and a content entry.
-Why three, when a page editor needs only one?
-
-## Schema and data are separate
-
-A **Model** is a schema. It sets which fields a piece of content can hold, and it holds
-no data itself. A **content entry** is one instance of that schema, filled with real
-values.
-
-One Model backs many entries. Describe a campaign page one time, then make many pages
-from it. Each entry carries its own title, its own body, and its own image, but they all
-share the shape.
-
-That split is also what lets your code depend on content that it never saw. Your component
-reads `content.title` because the Model promises a `title`. It works for every entry that
-comes from that Model.
-
-## A category gives a Model a role
-
-A Model can carry a **category**, and the category decides what the Model gives its shape
-to. A **page layout** backs a standalone Page. A **step layout** backs one Step inside a
-Flow.
-
-The category is fixed because it decides where the SDK renders the entry. That is not a
-property that you can change under an entry that exists already.
-
-A Model can also carry no category. Such a Model has no layout role, and nothing renders
-its entries directly. It holds the content that other content points at, such as a
-product or a category of your own. See
-[About content references](/explanation/content-references).
-
-The three roles are one machine. A layout is a Model with a job in the render path. A
-Model with no category is the same machine with no such job.
-
-## A Block is a schema fragment
-
-A Model gives shape to a whole page or a whole step. A **Block** is a part that you put
-inside one or more Models.
-
-Define a hero one time as a Block, then point at it from every Model that needs one.
-Change the Block and every Model that holds it changes with it.
-
-This is the reason Blocks exist at all. Without them you must describe a common
-structure again in each Model, and the copies then become different. It is the same
-argument for one fact in one place that runs through the rest of this documentation.
-
-A Block sits **inside** the entry that embeds it. It has no entry of its own, and no id
-that you can point at.
-
-That is the difference between a Block and a reference. A Block is a shape that many
-entries hold. A reference is a pointer at one entry that many entries share.
-
-## Why a schema change does not migrate your data
-
-Change a Model or a Block, and Picked does not rewrite the entries behind it. An entry
-that no longer matches its schema becomes invalid, and the dashboard shows an error on
-each field that does not fit.
-
-That is deliberate. An automatic change must decide what a new required field holds for
-every entry that came before it. Any value that it chooses is content that nobody wrote.
-Picked reports the error instead, and you correct it.
-
-The cost is real. After a schema change, check every entry that uses that Model and fix
-each error before you publish. Picked serves valid content only, so an entry with an error
-does not reach a visitor.
-
-## An error points at the exact field
-
-A validation error carries a path in JSON style, such as `sections[0].data.title`. The
-path holds through nested groups, repeated fields, and Blocks. An error inside a
-repeated group therefore tells you which item in that group holds it.
-
-## Related
-
-- [Models](/reference/dashboard/content/models) — every field type.
-- [Blocks](/reference/dashboard/content/blocks) — the reusable fragments.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor and the
-  validation.
-- [About content references](/explanation/content-references) — how one entry points at another.
-- [About pages and flows](/explanation/pages-and-flows) — which category you need.

package/dist/docs/explanation/the-two-apis.md

@@ -1,68 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About the two APIs
-
-Picked has two HTTP APIs, and a new reader often reaches for the wrong one. This page
-covers which is which and why they are separate.
-
-## The split
-
-| | Delivery API | Management API |
-| --- | --- | --- |
-| Style | REST | GraphQL |
-| Access | Public, anonymous | Authenticated |
-| Operations | Read-only | Read and write |
-| Base | `https://api.picked.app/api/v1` | `POST https://api.picked.app/api/graphql` |
-| Use it to | Serve published configuration and content to your application | Control your projects, experiences, and content |
-
-The short rule is this: **the Delivery API serves your visitors, and the management API
-serves you.**
-
-## Why they are not one API
-
-Three properties of the delivery path make it a different kind of API.
-
-**It is anonymous.** A crawler must read your published page content with no credential at
-all. An API that requires a token cannot serve a search engine, and an API that serves a
-search engine cannot require one.
-
-**It is cacheable.** A published response is the same for every reader, so a shared cache
-can hold it. The Delivery API sends `s-maxage` for an SDK request, and it sends
-`Vary: Picked-Client`. A GraphQL endpoint that takes any query over a `POST` has none of
-those properties.
-
-**It is read-only.** Nothing that a reader reaches without a credential can change your
-data. Every write stays on a separate authenticated surface, so that property holds by
-design.
-
-## What the Delivery API serves
-
-Two endpoints, and the SDK calls both:
-
-- **Project config** returns the published configuration of a project: its experiences and
-  steps, and the content link on each step.
-- **Experience content** returns the content entries behind an experience.
-
-Your server usually calls the first and lets `serialize()` call the second. See
-[About server-side rendering](/explanation/why-server-side-rendering).
-
-## How a preview stays out of the search index
-
-A preview needs unpublished content, and by the definition of it that content is not
-public. The Delivery API takes a `preview_token` query parameter for exactly that. It then
-treats the result differently. `versionId` comes back `null`, the response is `no-store`,
-and `robots.txt` does not allow the preview path.
-
-That last part matters more than it looks. A draft that anybody can read over an anonymous
-URL is a draft that a search engine can find. A campaign page that is only part complete
-can then appear in the search results of a customer.
-
-## Related
-
-- [Delivery API](/reference/delivery-api) — the endpoints and their responses.
-- [Management API](/reference/management-api/authentication) — authentication and scopes.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — the
-  exact cache rules and `robots.txt` rules.

package/dist/docs/explanation/why-server-side-rendering.md

@@ -1,76 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About server-side rendering
-
-Why does a Page need a snapshot, when the SDK can fetch its content in the browser?
-Because the reader that matters most does not run JavaScript.
-
-## The constraint
-
-A crawler and a social preview read the HTML your server returns, and they do not wait for
-the browser to fetch anything. If the content of a Page arrives after the first response,
-those readers never see it.
-
-So the content has to be in the HTML. That means your server has to know, before it
-answers, which experiences match this URL and what their content is.
-
-## What the snapshot is for
-
-`serialize()` answers that question on the server. It registers your project configuration and
-evaluates each experience condition against the URL. It then reads the content for each
-experience that matches, and returns a `PickedSnapshot` as plain JSON.
-
-```
-projectConfig (Delivery API)
-  -> serialize(client, params) on the server -> PickedSnapshot
-  -> embed snapshot in HTML
-  -> client seeds from snapshot -> renders the same markup -> hydrates
-```
-
-The snapshot carries the exact options the server chose with, and the condition results it
-reached. The first render in the browser therefore reuses the decisions of the server. It
-does not evaluate them a second time.
-
-That last point is the whole reason the snapshot holds condition results and not only
-content. A browser that evaluates the conditions itself can reach a different answer. A different URL shape, a
-different time, or a different flag value each give a different result. The markup then does not
-match what the server sent, and hydration discards the server HTML. That failure is the
-one server-side rendering exists to prevent.
-
-## Why a slot instead of a selector
-
-A browser-rendered flow points at a DOM selector, and the SDK inserts the component next
-to the element that it finds. That cannot work on a server, because a server has no DOM
-to search.
-
-A slot reverses that. `<ExperienceSlot name="page" />` is a mount point that you place in
-your own markup. An experience joins it when its target selector is `.picked-slot-<name>`.
-Your component tree decides where the content goes, so the server renders it in one pass.
-
-## Why placements have an order
-
-More than one experience can point at the same slot, so the slot needs a rule. The order
-is:
-
-```
-replace -> before -> prepend -> append -> after
-```
-
-`replace` wins: an active experience with that placement renders alone. Every other active
-experience renders in the order above.
-
-The rule exists so the outcome does not depend on which experience came first. Two editors
-can add an experience to the same slot on the same day. The result then follows from the
-placements, and not from the database.
-
-## Related
-
-- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
-  path, in practice.
-- [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
-- [Slots and placements](/reference/sdk/ssr/slots-and-placements) — the exact rules for
-  the order.
-- [About pages and flows](/explanation/pages-and-flows) — which kind you need.

package/dist/docs/explanation/workspaces-and-versions.md

@@ -1,71 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About workspaces and versions
-
-Why can you not edit what your visitors see? Because Picked keeps two things separate on
-purpose: the work in progress, and the thing that it serves.
-
-## The two states
-
-A **workspace** holds your changes. Edit a flow, a feature flag, a step, a field, an
-action, or a condition, and the change stays in the workspace. No visitor sees it.
-
-A **version** is what your visitors get. When you publish, Picked takes the current
-workspace and makes an immutable snapshot of it. A project serves exactly one version at a
-time, the live one.
-
-Everything else follows from that split.
-
-## Why the snapshot is immutable
-
-A published version cannot change. That is what makes a roll-back safe. When you restore
-an earlier version, Picked moves the live pointer of the project and changes no data. The
-version that you restore is the exact version that was live before, and not a copy that
-Picked builds again.
-
-It is also what lets your draft continue. When you publish, your workspace stays
-editable, and a roll-back discards no draft. The two move at their own speed.
-
-## The three workspace states
-
-- **Live** — the workspace whose snapshot the SDK serves. Each project has exactly one.
-- **Draft** — a workspace that no visitor sees. Edit it, see a preview of it, publish it.
-- **Archived** — a draft that you put to one side. It is still editable, but it is out of
-  the default list.
-
-Picked keeps these two operations separate on purpose. Archive a draft when you are not
-certain about it. You cannot reverse a delete, but you can always unarchive.
-
-## Why the publish modal shows a diff
-
-It is the one step in the dashboard that you cannot take back. It is therefore the one
-place that shows you exactly what changes. The modal compares the current workspace
-against the last published snapshot. It puts the changes into groups, and marks each row
-added, removed, or modified.
-
-The diff also carries a warning that a plain list of changes cannot give you. Some changes
-break other records. Remove a field while steps still point at it, and those steps
-now have an error. The preview shows that above the diff, before you publish and not after.
-
-The first publish of a workspace has no earlier snapshot to compare against, so the modal
-shows the contents instead of a diff.
-
-## A preview does not reach production
-
-A preview sends the workspace state to the SDK in the query parameters. Your unpublished
-workspace therefore applies to your browser and to nothing else. The visitors on your live
-site see no change.
-
-One result of this matters. In a preview the SDK stores a feature flag decision in session
-storage and not in local storage. A preview allocation is therefore disposable, and it can
-differ from a production one. See
-[About feature flag allocation](/explanation/feature-flag-allocation).
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — what a publish feeds.
-- [Workspaces](/reference/dashboard/workspaces) — the states and the settings.
-- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

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

@@ -1,43 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to add a step, a field, an action, or a condition
-
-This guide shows you how to create the parts that a flow is built from. All four follow
-the same shape, and all four belong to the project: you can use one in more than one flow.
-
-## Steps
-
-1. Open a flow. The library is on the left of the flow builder.
-2. Find the **Steps**, **Fields**, **Actions**, or **Conditions** section in it.
-3. Click the **+** next to that section.
-4. Enter a name. The dashboard makes the key from it.
-5. Click the **Create** button for that kind: **Create step**, **Create field**,
-   **Create action**, **Create condition**.
-
-The flow builder opens again, and the new one is in the library.
-
-**Fields** also has its own sidebar entry, so you can make a field without a flow. A step,
-an action, and a condition belong to a flow, and the library is the only way to reach
-them.
-
-The key is the identifier that your application uses. You set it one time, and you cannot
-change it later. Your visitors never see a name or a key.
-
-## What each one needs after that
-
-| Kind | Set this next |
-| --- | --- |
-| Step | A **Layout**, such as `card`, `modal`, or `fullscreen`. |
-| Field | A **Label**, a type, and any validation rule. |
-| Action | Nothing in the dashboard. Register the handler in your code. |
-| Condition | The rule, in the **Logic** section of the inspector. |
-
-## Related
-
-- [How to build a flow](/how-to/build-a-flow) — put it on the canvas.
-- [How to write a condition](/how-to/write-a-condition)
-- [How to register an action handler](/how-to/register-an-action-handler)
-- [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)

package/dist/docs/how-to/analytics/index.md

@@ -1,316 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run an analytics query
-
-This guide gives you a query for each common analytics question. Copy one, put your own
-project ID in the `WHERE` clause, and run it.
-
-Every query must carry a tenant filter. See
-[About PickedQL](/explanation/how-pickedql-works) for why, and
-[Data sources](/reference/pickedql/data-sources) for every table.
-
-## Daily A/B test trend
-
-```sql
-SELECT
-  project_local_date,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-**Result:**
-
-| project_local_date | control | variant |
-| ----------------- | ------- | ------- |
-| 2026-04-11        | 4361    | 101     |
-| 2026-04-12        | 4178    | 126     |
-| 2026-04-13        | 5008    | 176     |
-
-## Conversion rate uplift by date
-
-```sql
-SELECT
-  project_local_date,
-  control_conversion_rate()        AS control_conversion_rate,
-  variant_conversion_rate()        AS variant_conversion_rate,
-  conversion_rate_uplift()         AS conversion_rate_uplift_pct
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-**Result:**
-
-| project_local_date | control_conversion_rate | variant_conversion_rate | conversion_rate_uplift_pct |
-| ----------------- | ----------------------- | ----------------------- | -------------------------- |
-| 2026-04-01        | 0.0322     | 0.0349     | 0.0349        |
-| 2026-04-02        | 0.0398     | 0.0416     | 0.0416        |
-| 2026-04-03        | 0.0462     | 0          | -0.0001       |
-
-## Custom conversion rate definition
-
-Override the default conversion, which counts a `purchase` event, with your own
-numerator and denominator. Use this when a form submission, a lead capture, or
-another event of your own defines a conversion.
-
-```sql
--- Lead capture conversion: form submissions / lead-capture step entries
-SELECT
-  project_local_date,
-  control_conversion_rate(
-    numerator='event_type=form_submit_success',
-    denominator='step_id=lead-capture-step'
-  ) AS control_lead_cr,
-  variant_conversion_rate(
-    numerator='event_type=form_submit_success',
-    denominator='step_id=lead-capture-step'
-  ) AS variant_lead_cr
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-You can also combine multiple events with `OR` and group with parentheses:
-
-```sql
--- A `checkout_complete` event or an `order_create` event counts as a conversion.
-SELECT
-  control_conversion_rate(
-    'event_type=checkout_complete OR event_type=order_create'
-  ) AS control_cr,
-  variant_conversion_rate(
-    'event_type=checkout_complete OR event_type=order_create'
-  ) AS variant_cr
-FROM events
-WHERE project_id = '{{ your project ID }}'
-```
-
-## Your own segment with `control_users` and `variant_users`
-
-On `events`, four functions take an optional filter string: `control_users`,
-`variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
-user or a session that matches your expression. It applies together with the
-`variant_type` filter that PickedQL adds.
-
-```sql
--- The control users who fired an `app_initialize` event, by step.
-SELECT
-  step_id,
-  control_users('event_type=app_initialize')                      AS control_initialized,
-  variant_users('event_type=app_initialize')                      AS variant_initialized
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-GROUP BY step_id
-ORDER BY control_initialized DESC
-```
-
-The named form (`filter=`) is also supported:
-
-```sql
-SELECT control_users(filter='event_type=form_submit AND step_id=lead-capture') FROM events
-WHERE project_id = '{{ your project ID }}'
-```
-
-## Conversion rate from nested virtual functions
-
-The numerator and the denominator can come from different segments. An example is the
-control users who fired an event of your own, divided by **all** users and not by the
-control users alone. For that, pass a virtual function call directly as an argument
-of the conversion rate:
-
-```sql
--- The control users who fired `app_initialize`, over all users of every variant.
-SELECT
-  control_conversion_rate(
-    control_users('event_type=app_initialize'),
-    all_users()
-  ) AS control_initialize_rate
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-```
-
-## A/B test by device
-
-```sql
-SELECT
-  device_category,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-GROUP BY device_category
-```
-
-**Result:**
-
-| device_category | control | variant |
-| --------------- | ------- | ------- |
-| Phone           | 193430  | 1723    |
-| Desktop         | 23423   | 309     |
-| Tablet          | 13294   | 65      |
-
-## Daily A/B test trend by device
-
-Combine date and device dimensions to spot device-specific trends:
-
-```sql
-SELECT
-  project_local_date,
-  device_category,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date, device_category
-ORDER BY project_local_date, device_category
-```
-
-**Result:**
-
-| project_local_date | device_category | control | variant |
-| ----------------- | --------------- | ------- | ------- |
-| 2026-04-13        | Tablet          | 175     | 2       |
-| 2026-04-14        | Desktop         | 37      | 1       |
-| 2026-04-14        | Phone           | 244     | 1       |
-
-## Purchase by UTM source
-
-```sql
-SELECT
-  utm_source,
-  all_users()                      AS users,
-  all_purchase_users()             AS purchasers
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-GROUP BY utm_source
-```
-
-**Result:**
-
-| utm_source | users  | purchasers |
-| ---------- | ------ | ---------- |
-| `meta`       | 12031  | 101        |
-| `fb`         | 3656   | 31         |
-| `an`         | 100366 | 299        |
-
-## Step funnel for variant users
-
-Count unique variant users per step to understand the conversion funnel:
-
-```sql
-SELECT
-  step_id,
-  variant_users()                    AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY step_id
-ORDER BY variant DESC
-```
-
-**Result:**
-
-| step_id                        | variant |
-| ------------------------------ | ------- |
-| `who-are-you-protecting-step`    | 1093    |
-| `about-yourself-step`            | 533     |
-| `date-of-birth-step`             | 435     |
-| `employment-status-step`         | 408     |
-| `nicotine-usage-step`            | 407     |
-| `coverage-motivation-step`       | 405     |
-| `lead-capture-step`              | 398     |
-
-
-## Sankey — overall user journey
-
-A forward window from the starting step. A user who never reaches `targeting_step`
-still gives edges, up to `num_nodes_after_start`.
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id            = '{{ your project ID }}'
-  AND starting_step         = '{{ starting step ID }}'
-  AND targeting_step        = '{{ target step ID }}'
-  AND num_nodes_after_start = 10
-```
-
-**Result:**
-
-| source                    | target                    | users |
-| ------------------------- | ------------------------- | ----- |
-| `001. step-start`           | `002. step-questionnaire-1` | 182   |
-| `002. step-questionnaire-1` | `003. step-quote`           | 144   |
-| `003. step-quote`           | `004. step-target`          | 121   |
-
-## Sankey — the top paths to a target step
-
-A backward window anchored at the target. It also ranks the paths and keeps the ones
-with the most users.
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id              = '{{ your project ID }}'
-  AND experience_id           = '{{ experience ID }}'
-  AND starting_step           = '{{ starting step ID }}'
-  AND targeting_step          = '{{ target step ID }}'
-  AND num_nodes_before_target = 5
-  AND top_n_path              = 10
-```
-
-## Sankey — drop-off view
-
-Starts at `starting_step` and emits every consecutive transition until `num_nodes_after_start` steps later (no target).
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id            = '{{ your project ID }}'
-  AND experience_id         = '{{ experience ID }}'
-  AND starting_step         = '{{ starting step ID }}'
-  AND num_nodes_after_start = 10
-```
-
-## List all control users for mobile (user-level)
-
-Use `events` when you need data at the individual user level:
-
-```sql
-SELECT
-  device_category,
-  user_canonical_id
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND device_category = 'Mobile'
-  AND variant_type = 'Control'
-```
-
-**Result:**
-
-| device_category | user_canonical_id                    |
-| --------------- | ------------------------------------ |
-| Mobile          | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
-| Mobile          | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
-| Mobile          | `019cc80f-503c-7181-b2c6-986b1f76d496` |
-
-## Related
-
-- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
-- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
-- [Dimensions](/reference/pickedql/dimensions) — every dimension column.
-- [Analytics events](/reference/sdk/analytics-events) — every `event_type` value that a
-  filter can use.
-- [Reports](/reference/dashboard/reports) — the same data as an embedded dashboard.