@picked/client 0.0.70-next.6 → 0.0.70

package/dist/docs/pickedql/virtual-functions.md

@@ -4,34 +4,41 @@ layout: docs
 
 # Virtual functions
 
-Virtual functions are shorthand for aggregate expressions. They are **table-aware** — the same function expands differently on `metrics` (pre-aggregated) vs `events` (user-level).
+A virtual function is a short form of an aggregate expression. Each one is
+**table-aware**. The same function expands one way on `metrics`, where PickedQL
+aggregates the data first. It expands another way on `events`, where there is one row
+for each user.
 
 ## A/B test metrics
 
 | Function | Description |
 |---|---|
-| `control_users([condition])` | Unique users in the Control group, optionally filtered by a custom condition |
-| `variant_users([condition])` | Unique users in the Variant group, optionally filtered by a custom condition |
-| `all_users()` | All unique users |
-| `control_sessions([condition])` | Unique sessions in the Control group, optionally filtered by a custom condition |
-| `variant_sessions([condition])` | Unique sessions in the Variant group, optionally filtered by a custom condition |
-| `all_sessions()` | All unique sessions |
+| `control_users([condition])` | The different users in the Control group. A condition of your own can narrow them. |
+| `variant_users([condition])` | The different users in the Variant group. A condition of your own can narrow them. |
+| `all_users()` | Every different user |
+| `control_sessions([condition])` | The different sessions in the Control group. A condition of your own can narrow them. |
+| `variant_sessions([condition])` | The different sessions in the Variant group. A condition of your own can narrow them. |
+| `all_sessions()` | Every different session |
 
-### Custom filters on `events`
+### Your own filters on `events`
 
-On the `events` table, `control_*`/`variant_*` functions accept **one optional filter argument** to count only users/sessions matching the given expression, in addition to the implicit `variant_type` filter. The argument can be **positional** or **named** (`filter=`).
+On the `events` table, each `control_*` function and each `variant_*` function takes
+**one optional filter argument**. The filter counts only a user or a session that
+matches your expression. It applies together with the `variant_type` filter that
+PickedQL adds. Give the argument in the first place, or by the name `filter=`.
 
-The filter uses the same `column=value` syntax as conversion-rate conditions, with `AND`/`OR` operators and parentheses for grouping.
+The filter uses the same `column=value` syntax as a conversion-rate condition. It
+takes the `AND` and `OR` operators, and parentheses can hold a set of terms.
 
 ```sql
--- Default: all Control users
+-- The default: every Control user.
 SELECT control_users() FROM events
 
--- Custom filter (positional)
+-- Your own filter, in the first place.
 SELECT control_users('event_type=app_initialize') FROM events
 SELECT variant_users('event_type=app_initialize AND step_id=xxx') FROM events
 
--- AND/OR + parentheses
+-- The AND and OR operators, with parentheses.
 SELECT control_users('event_type=app_initialize OR event_type=app_load') FROM events
 SELECT control_users('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
 
@@ -44,7 +51,9 @@ SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM ev
 ```
 
 :::note
-Custom filters are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions ignore any arguments and use the default Control/Variant filter only.
+A filter of your own is **not supported on `metrics`**, because PickedQL aggregates
+that data first. On `metrics` these functions ignore every argument. They use the
+default Control filter and Variant filter only.
 :::
 
 ## Conversion metrics
@@ -62,15 +71,19 @@ Custom filters are **not supported on `metrics`** (pre-aggregated data). On `met
 
 | Function | Description |
 |---|---|
-| `control_conversion_rate([numerator [, denominator]])` | Conversion rate for Control. Defaults to purchase users / all users |
-| `variant_conversion_rate([numerator [, denominator]])` | Conversion rate for Variant. Same args as above |
-| `conversion_rate_uplift([numerator [, denominator]])` | Relative improvement: `(variant CR - control CR) / control CR`. Same args as above |
+| `control_conversion_rate([numerator [, denominator]])` | The conversion rate of the Control group. By default it divides the users with a purchase by all users. |
+| `variant_conversion_rate([numerator [, denominator]])` | The conversion rate of the Variant group. It takes the same arguments. |
+| `conversion_rate_uplift([numerator [, denominator]])` | The gain of the Variant over the Control: `(variant CR - control CR) / control CR`. It takes the same arguments. |
 
-### Custom conditions on `events`
+### Your own conditions on `events`
 
-On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Each argument can be either a **condition expression string** or a **nested virtual function call** (see below). Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
+On the `events` table, each conversion-rate function takes up to **two optional
+arguments**. They set the numerator and the denominator. Each argument is either a
+**condition expression string** or a **nested virtual function call**. See below.
+Give the arguments in order, or by the names `numerator=` and `denominator=`.
 
-Each condition expression uses `column=value` with `AND`/`OR` operators and parentheses for grouping.
+Each condition expression uses `column=value`, with the `AND` and `OR` operators.
+Parentheses can hold a set of terms.
 
 ```sql
 -- Default: purchase users / all users
@@ -79,11 +92,11 @@ SELECT control_conversion_rate() FROM events
 -- Custom numerator, default denominator (all users)
 SELECT control_conversion_rate('event_type=form_submit_success') FROM events
 
--- AND/OR in conditions
+-- The AND and OR operators in a condition.
 SELECT control_conversion_rate('event_type=checkout_complete OR event_type=order_create') FROM events
 SELECT control_conversion_rate('step_id=lead-capture AND event_type=form_submit_success') FROM events
 
--- Parentheses for grouping
+-- Parentheses hold a set of terms.
 SELECT control_conversion_rate('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
 
 -- Custom numerator AND denominator (positional)
@@ -95,18 +108,23 @@ SELECT control_conversion_rate(numerator='event_type=form_submit', denominator='
 -- Named: denominator only (numerator defaults to purchase)
 SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
 
--- Uplift with named args
+-- The uplift, with the arguments given by name.
 SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
 ```
 
-#### Nested virtual functions as numerator / denominator
+#### A nested virtual function as the numerator or the denominator
 
-Instead of a condition string, you can pass a **virtual function call** as the numerator or denominator. The inner aggregate is substituted in place — no implicit `variant_type` filter is added on top of it (the nested function controls its own filter).
+You can pass a **virtual function call** as the numerator or the denominator, in
+place of a condition string. PickedQL puts the inner aggregate there directly. It
+adds no `variant_type` filter above it, because the nested function sets its own
+filter.
 
-This is the most flexible form when the numerator and denominator have different segments (e.g., Control users who fired event X over **all** users regardless of variant):
+This form is the most flexible one when the numerator and the denominator come from
+different segments. An example is the Control users who fired one event, over **all**
+users of every variant:
 
 ```sql
--- (Control users who fired app_initialize) / (all users)
+-- The Control users who fired `app_initialize`, over all users.
 SELECT control_conversion_rate(
   control_users('event_type=app_initialize'),
   all_users()
@@ -118,7 +136,7 @@ SELECT control_conversion_rate(
   all_users()
 ) FROM events
 
--- Uplift with nested args
+-- The uplift, with a nested function in each place.
 SELECT conversion_rate_uplift(
   control_users('event_type=app_initialize'),
   all_users()
@@ -126,7 +144,9 @@ SELECT conversion_rate_uplift(
 ```
 
 :::note
-Custom conditions and nested virtual function args are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
+A condition of your own, and a nested virtual function, are both **not supported on
+`metrics`**, because PickedQL aggregates that data first. On `metrics` these
+functions always divide the users with a purchase by all users.
 :::
 
 ## Visitor segmentation (`metrics` only)
@@ -141,7 +161,7 @@ Custom conditions and nested virtual function args are **not supported on `metri
 ## Funnel metrics (`events` only)
 
 :::note
-Funnel metrics are being continuously updated. Check back for new functions.
+We add to the funnel metrics all the time. Read this page again for a new function.
 :::
 
 | Function | Description |
@@ -151,14 +171,18 @@ Funnel metrics are being continuously updated. Check back for new functions.
 
 ## Cohort filters (`events` only)
 
-Predicate-shaped functions that emit a `user_canonical_id IN (SELECT … FROM events …)` subquery. Use in `WHERE` to restrict any analysis to users who have at least one event matching a custom condition.
+Each of these functions has the shape of a predicate. It writes a
+`user_canonical_id IN (SELECT … FROM events …)` subquery. Put one in a `WHERE` clause
+to limit any analysis to a user with at least one event that matches a condition of
+your own.
 
 | Function | Description |
 |---|---|
-| `user_cohort_filter('<condition>')` | Restrict the query to users with ≥1 `events` row matching `<condition>` |
-| `user_cohort_filter(filter='<condition>')` | Same, named-arg form |
+| `user_cohort_filter('<condition>')` | Limits the query to a user with one or more `events` rows that match `<condition>` |
+| `user_cohort_filter(filter='<condition>')` | The same, with the argument given by name |
 
-`<condition>` uses the same `column=value [AND\|OR …]` shorthand as `control_users` / `variant_users`.
+`<condition>` uses the same short `column=value [AND\|OR …]` form as `control_users`
+and `variant_users`.
 
 ```sql
 -- Funnel scoped to users who eventually submitted lead capture
@@ -174,9 +198,11 @@ WHERE project_id = 'proj-abc'
   AND user_cohort_filter('event_type=signup OR event_type=trial_start')
 ```
 
-The outer query MUST filter by a single `project_id` — the function bakes that tenant into the inner subquery so the cohort scan is scoped to your project, not the whole warehouse.
+The outer query MUST hold one `project_id` filter. The function puts that tenant into
+the inner subquery. The read of the cohort therefore covers your project, and not the
+whole warehouse.
 
-## Feature functions (`features` / `events`)
+## Feature functions, on `features` and on `events`
 
 Parameterized functions that accept the feature name, bucket, and an optional feature key:
 

package/dist/docs/projects.mdx

@@ -6,16 +6,17 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Projects
 
-A project represents one website or app you want to instrument with Picked. Each project has its own set of experiences, entities, and configuration.
+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, listing the projects in an organization"
+  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 don't have one, create it when you sign up.
+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**.
@@ -24,14 +25,20 @@ You need an organization first. If you don't have one, create it when you sign u
 
 ## Workspaces
 
-Each project contains one or more [Workspaces](/workspaces) for configuring and previewing experiences before publishing.
+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 installation snippet and a getting-started checklist.
+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. This connects your site to the project and enables experience delivery. See [SDK Installation](/sdk) for setup details.
+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 all sections available in your project: **Experiences**, **Fields**, **Steps**, **Actions**, **Conditions**, and more. Some sections appear only when enabled for your account.
+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

@@ -6,13 +6,15 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Reports
 
-Reports show analytics data for your project. Track how visitors interact with your experiences and feature flags.
+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"
 />
 
-## View report data
+## See report data
 
-Open a report to see its analytics. Data updates as new visitor interactions are recorded.
+Open a report to see its analytics. The data updates when Picked records a new
+visitor interaction.

package/dist/docs/sdk/actions.md

@@ -4,11 +4,13 @@ layout: docs
 
 # Actions
 
-Register action handlers on the Picked client so the SDK can invoke them when an experience flow reaches an action node.
+Register an action handler on the Picked client. The SDK then invokes the handler
+when an experience flow reaches an action node.
 
-## Registering actions
+## Register an action
 
-Register actions when creating the Picked client. Each key in the `actions` object must match an action key defined in the dashboard:
+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'
@@ -26,41 +28,55 @@ const picked = createClient({
 })
 ```
 
-Each action is a function that receives optional parameters and usually runs a side effect. When the flow reaches an action node, the SDK calls the matching function and branches on whether it succeeds or throws (see [Success and failure branching](#success-and-failure-branching)).
+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**: Actions are registered to the Picked client during initialization
-2. **Flow traversal**: When the SDK traverses the experience flow and reaches an action node, it looks up the action by its key
-3. **Execution**: The matching function is called and awaited. The SDK then continues to the next node based on the action's outcome
-4. **Non-blocking**: Actions don't interrupt the visitor's experience. The current step stays on screen while an async action runs
+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 branching
+## Success and failure branches
 
-An action node can have separate **success** and **failure** branches. The SDK selects the branch from the action's outcome:
+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 follows the failure (`onFail`) branch.
-- **Success** — the action resolves to any value (`void`, `true`, `false`, or a string). A resolved `false` is a valid response, not a failure. The flow follows the success (`onSuccess`) branch.
+- **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`.
 
-Reserve the failure branch for genuine errors — throw on the failure case, since a returned value never routes to `onFail`:
+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.
+  // 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 that returns `200` with a "no" (for example `{ serviced: false }`) should record that value as a response and branch on it with a condition, rather than throw:
+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())
-  // Commit the outcome as a response; a downstream condition routes the flow.
+  // Store the outcome as a response. A later condition then takes the branch.
   client.responses.register('is-serviced', serviced)
 }
 ```
 
-If an action node has only a single plain connection (no explicit success or failure branch), the flow continues through it on either outcome.
+An action node can also have one plain connection, with no success or failure branch.
+The flow then continues through it on either outcome.

package/dist/docs/sdk/conditions.md

@@ -4,11 +4,13 @@ layout: docs
 
 # Conditions
 
-Conditions use JSON Logic to evaluate client state. Use them to gate experience activation, branch step navigation, and control field visibility.
+A condition uses JSON Logic to evaluate the client state. Use a condition to control
+when an experience starts, to choose the next step, and to show or hide a field.
 
 ## Conditions in experiences
 
-A common pattern is using conditions between steps to branch the flow based on form responses:
+A common pattern puts a condition between two steps. The flow then takes a branch
+that the form responses decide:
 
 ```ts
 import { createExperience } from '@picked/client/plugins/create-experience'
@@ -47,12 +49,13 @@ isSigningUpForNewsletter.addFalse(userDoesNotWantNewsletter)
 
 ## Conditional fields
 
-Fields can be shown or hidden based on previous responses or [predicates](./predicates) using JSON Logic conditions:
+A JSON Logic condition can show or hide a field. The condition can read an earlier
+response or a [predicate](./predicates):
 
 ```ts
 import { createField } from '@picked/client/plugins/create-experience'
 
-// Show email field only if user selected "email" as a contact method
+// Show the email field only when the user chose "email" as a contact method.
 export const emailField = createField({
   id: 'email-input',
   name: 'email-input',
@@ -70,7 +73,7 @@ export const emailField = createField({
   },
 })
 
-// Show field based on predicate
+// Show the field when the predicate returns true.
 export const mailingAddressField = createField({
   id: 'mailing-address',
   name: 'mailing-address',

package/dist/docs/sdk/content-security-policy.md

@@ -4,15 +4,16 @@ layout: docs
 
 # Content Security Policy
 
-The Picked SDK loads resources from the following domains. Add each to the matching CSP directive.
+The Picked SDK loads resources from the domains below. Add each domain to the CSP
+directive that the table gives.
 
 ## Required domains
 
 | Domain | Directive | Purpose |
 | --- | --- | --- |
-| `api.picked.app` | `connect-src` | API requests, project configuration, experiences, session tracking |
-| `evnts.pckd.dev` | `connect-src` | Analytics event collection (Snowplow) |
-| `img.picked-content.com` | `img-src` | Optimised images served via the [image optimisation service](../image-optimisation-service.md) |
+| `api.picked.app` | `connect-src` | API requests, project options, experiences, and the record of each session |
+| `evnts.pckd.dev` | `connect-src` | Analytics events, which Snowplow collects |
+| `img.picked-content.com` | `img-src` | Optimised images, which the [image optimisation service](../image-optimisation-service.md) serves |
 
 ## Configuration
 

package/dist/docs/sdk/experiences.md

@@ -4,11 +4,18 @@ layout: docs
 
 # Experiences
 
-Define experiences in code with `createExperience()`, or load them from the dashboard at runtime with the [Dynamic Experiences Plugin](./plugins/dynamic-experiences).
+Define an experience in code with `createExperience()`. You can also load an
+experience from the dashboard at runtime with the
+[Dynamic Experiences Plugin](./plugins/dynamic-experiences).
 
-The execution flow below targets a DOM selector and renders into it. A Page experience instead renders through a named slot: target it to `.picked-slot-<name>` and render `<ExperienceSlot name="<name>" />` on your server. Use the slot path for SEO-critical, server-rendered Pages; use the selector path for browser-rendered Flows. See [Server-Side Rendering](/sdk/ssr) and [Slots & Placements](/sdk/ssr/slots-and-placements).
+The flow below points at a DOM selector and renders into it. A Page experience
+renders through a named slot instead. Point it at `.picked-slot-<name>` and render
+`<ExperienceSlot name="<name>" />` on your server. Use the slot path for a Page that
+the server renders and that search engines must read. Use the selector path for a
+Flow that the browser renders. See [Server-Side Rendering](/sdk/ssr) and
+[Slots and Placements](/sdk/ssr/slots-and-placements).
 
-## Creating experiences
+## Create an experience
 
 ```ts
 import { createExperience } from '@picked/client/plugins/create-experience'
@@ -32,15 +39,26 @@ export const productPageExperience = createExperience({
 })
 ```
 
-Register experiences using the [Create Experience Plugin](./plugins/create-experience) for code-defined experiences, or the [Dynamic Experiences Plugin](./plugins/dynamic-experiences) to fetch and manage them from the dashboard at runtime.
+To register an experience that you define in code, use the
+[Create Experience Plugin](./plugins/create-experience). To read an experience from
+the dashboard at runtime and control it there, use the
+[Dynamic Experiences Plugin](./plugins/dynamic-experiences).
 
 ## How experiences work
 
-When an experience is registered, the SDK follows this execution flow:
+After you register an experience, the SDK follows this flow:
 
-1. **Registration**: Experiences are registered to the Picked client using [createExperiencePlugin](./plugins/create-experience) for code-defined experiences, or [dynamicExperiencesPlugin](./plugins/dynamic-experiences) for dashboard-managed experiences
-2. **Condition evaluation**: The SDK evaluates the experience's `condition` using the logic engine to determine if it should be shown
-3. **Target resolution**: The SDK searches the DOM for elements matching the `targets` selectors (e.g., `body`, `.product-page`, `#checkout`)
-4. **Initialization**: If the condition evaluates to `true` and at least one target element exists, the experience is initialized
-5. **Component rendering**: The experience's component is rendered and injected into the DOM at the specified target location and placement (before, after, append, prepend, or replace)
-6. **Flow execution**: If the experience contains steps, fields, and conditionals, users can progress through the multi-step flow with validation and branching logic
+1. **Registration**: You register the experience on the Picked client. Use
+   `createExperiencePlugin` for an experience that you define in code. Use
+   `dynamicExperiencesPlugin` for one that you control from the dashboard.
+2. **Condition evaluation**: The SDK evaluates the `condition` of the experience with
+   the logic engine. The result decides whether a visitor sees it.
+3. **Target resolution**: The SDK searches the DOM for an element that matches a
+   selector in `targets`. Examples are `body`, `.product-page`, and `#checkout`.
+4. **Initialization**: The SDK starts the experience when the condition is `true` and
+   at least one target element is there.
+5. **Component rendering**: The SDK renders the component of the experience. It puts
+   the component into the DOM at the target and the placement that you set. A
+   placement is `before`, `after`, `append`, `prepend`, or `replace`.
+6. **Flow execution**: An experience can hold steps, fields, and conditions. A user
+   then moves through the flow. The flow checks each answer and takes a branch.