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

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

@@ -0,0 +1,237 @@
+---
+type: reference
+layout: docs
+---
+
+# Virtual functions
+
+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])` | 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 |
+
+### Your own filters on `events`
+
+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 a conversion-rate condition. It
+takes the `AND` and `OR` operators, and parentheses can hold a set of terms.
+
+```sql
+-- The default: every Control user.
+SELECT control_users() FROM events
+
+-- 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
+
+-- 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
+
+-- Sessions
+SELECT control_sessions('event_type=step_enter') FROM events
+SELECT variant_sessions('event_type=step_enter AND step_id=checkout') FROM events
+
+-- Named form
+SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM events
+```
+
+:::note
+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
+
+| Function | Description |
+|---|---|
+| `all_purchase_users()` | Users who completed a purchase |
+| `control_purchase_users()` | Control users who purchased (`metrics` only) |
+| `variant_purchase_users()` | Variant users who purchased (`metrics` only) |
+| `all_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
+| `all_purchase_orders()` | Unique order count (`metrics` only) |
+| `all_cart_add_users()` | Users who added to cart |
+
+## Conversion rates
+
+| Function | Description |
+|---|---|
+| `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. |
+
+### Your own conditions on `events`
+
+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 the `AND` and `OR` operators.
+Parentheses can hold a set of terms.
+
+```sql
+-- Default: purchase users / all users
+SELECT control_conversion_rate() FROM events
+
+-- Custom numerator, default denominator (all users)
+SELECT control_conversion_rate('event_type=form_submit_success') FROM events
+
+-- 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 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)
+SELECT control_conversion_rate('event_type=form_submit', 'step_id=lead-capture') FROM events
+
+-- Named arguments (explicit, any order)
+SELECT control_conversion_rate(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
+
+-- Named: denominator only (numerator defaults to purchase)
+SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
+
+-- The uplift, with the arguments given by name.
+SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
+```
+
+#### A nested virtual function as the numerator or the denominator
+
+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 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
+-- The Control users who fired `app_initialize`, over all users.
+SELECT control_conversion_rate(
+  control_users('event_type=app_initialize'),
+  all_users()
+) FROM events
+
+-- Mix string and nested forms
+SELECT control_conversion_rate(
+  'event_type=form_submit',
+  all_users()
+) FROM events
+
+-- The uplift, with a nested function in each place.
+SELECT conversion_rate_uplift(
+  control_users('event_type=app_initialize'),
+  all_users()
+) FROM events
+```
+
+:::note
+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)
+
+| Function | Description |
+|---|---|
+| `new_users()` | First-time visitors |
+| `returning_users()` | Returning visitors |
+| `new_sessions()` | Sessions from new visitors |
+| `returning_sessions()` | Sessions from returning visitors |
+
+## Funnel metrics (`events` only)
+
+:::note
+We add to the funnel metrics all the time. Read this page again for a new function.
+:::
+
+| Function | Description |
+|---|---|
+| `step_enter_users()` | Users who entered a funnel step |
+| `step_enter_sessions()` | Sessions that entered a funnel step |
+
+## Cohort filters (`events` only)
+
+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>')` | 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 short `column=value [AND\|OR …]` form as `control_users`
+and `variant_users`.
+
+```sql
+-- Funnel scoped to users who eventually submitted lead capture
+SELECT all_users(), all_purchase_users()
+FROM events
+WHERE project_id = 'proj-abc'
+  AND user_cohort_filter('event_type=lead_capture')
+
+-- Multi-condition cohort with OR-grouping
+SELECT all_sessions()
+FROM events
+WHERE project_id = 'proj-abc'
+  AND user_cohort_filter('event_type=signup OR event_type=trial_start')
+```
+
+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, on `features` and on `events`
+
+Parameterized functions that accept the feature name, bucket, and an optional feature key:
+
+| Function | Description |
+|---|---|
+| `feature_users('name', 'bucket' [, 'key'])` | Unique users in a feature bucket |
+| `feature_sessions('name', 'bucket' [, 'key'])` | Unique sessions in a feature bucket |
+| `feature_events('name', 'bucket' [, 'key'])` | Unique events in a feature bucket |
+
+```sql
+-- Compare feature buckets
+SELECT
+  feature_users('homepage_test', 'control') AS control,
+  feature_users('homepage_test', 'variant') AS variant
+FROM features
+
+-- With feature key filter
+SELECT feature_users('homepage_test', 'control', 'v1') FROM features
+```
+
+## Other (`metrics` only)
+
+| Function | Description |
+|---|---|
+| `event_count()` | Total event count (from pre-aggregation) |
+
+## Related
+
+- [Filters](/reference/pickedql/filtering) — the filter string a function takes.
+- [Analytics queries](/how-to/analytics)
+- [About PickedQL](/explanation/how-pickedql-works)

package/dist/docs/reference/sdk/actions.md

@@ -0,0 +1,30 @@
+---
+type: reference
+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.
+
+## Outcome and branch
+
+| Handler outcome | Branch the flow takes |
+| --- | --- |
+| Throws, or its promise rejects | `onFail` |
+| Resolves to any value, and that includes `false` | `onSuccess` |
+
+An action node can also carry one plain connection, with no success or failure branch. The
+flow then continues through it on either outcome.
+
+An action does not interrupt your visitor. The current step stays on the screen while an
+async action runs.
+
+## Related
+
+- [How to register an action handler](/how-to/register-an-action-handler) — the handler,
+  and when to throw.
+- [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)
+  — why a returned `false` is a success.
+- [Actions](/reference/dashboard/actions) — the dashboard options.

package/dist/docs/{sdk → reference/sdk}/conditions.md

@@ -1,14 +1,17 @@
 ---
+type: reference
 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 +50,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](/reference/sdk/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 +74,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',
@@ -135,3 +139,9 @@ export const contactMethodsField = createField({
   ],
 })
 ```
+
+## Related
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine)
+- [How to write a condition](/how-to/write-a-condition)
+- [Predicates](/reference/sdk/predicates)

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

@@ -0,0 +1,21 @@
+---
+type: reference
+layout: docs
+---
+
+# Content Security Policy
+
+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, 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](/reference/tools/image-optimisation-service) serves |
+
+## Related
+
+- [How to set a Content Security Policy](/how-to/set-a-content-security-policy)

package/dist/docs/reference/sdk/experiences.md

@@ -0,0 +1,51 @@
+---
+type: reference
+layout: docs
+---
+
+# Experiences
+
+Define an experience in code with `createExperience()`. You can also load an
+experience from the dashboard at runtime with the
+[Dynamic Experiences Plugin](/reference/sdk/plugins/dynamic-experiences).
+
+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](/reference/sdk/ssr) and
+[Slots and Placements](/reference/sdk/ssr/slots-and-placements).
+
+## Create an experience
+
+```ts
+import { createExperience } from '@picked/client/plugins/create-experience'
+import { adaptSvelteComponent } from '@picked/svelte'
+import appCss from '../app.css?inline'
+
+export const productPageExperience = createExperience({
+  id: 'product-page-experience',
+  name: 'Product Page Experience',
+  condition: {
+    '==': [
+      { var: 'location.pathname' },
+      '/product/',
+    ],
+  },
+  targets: [{ selector: 'body', placement: 'after' }],
+  component: adaptSvelteComponent(
+    import('../ui/ProductPageExperience.svelte'),
+    { css: [appCss] },
+  ),
+})
+```
+
+To register an experience that you define in code, use the
+[Create Experience Plugin](/reference/sdk/plugins/create-experience). To read an experience from
+the dashboard at runtime and control it there, use the
+[Dynamic Experiences Plugin](/reference/sdk/plugins/dynamic-experiences).
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — the startup order.
+- [How to register a component](/how-to/register-a-component)

package/dist/docs/reference/sdk/features.md

@@ -0,0 +1,233 @@
+---
+type: reference
+layout: docs
+---
+
+# Feature flags
+
+A feature flag lets you run an A/B test and roll a change out in stages. Control a
+feature flag from the dashboard, or define it in SDK code when you need your own decision
+rules.
+
+## Where feature flags come from
+
+You control most feature flags from the dashboard. The
+[dynamic experiences plugin](/reference/sdk/plugins/dynamic-experiences) reads the options of
+your project at runtime and registers every feature flag for you. You declare no feature flag in
+code.
+
+For a feature flag that you control from the dashboard, the SDK makes the definition:
+
+| Field | Value |
+| --- | --- |
+| `id` | The dashboard key of the feature flag |
+| `key` | `v{version}`, for example `v3` |
+| `name` | The dashboard name of the feature flag |
+| `enabled` | The dashboard **Enabled** toggle |
+| `weight` | The dashboard **Weight**, 0 to 100 |
+| `storage` | `local`, or `session` in [preview mode](/explanation/feature-flag-allocation#preview-mode) |
+| `decide` | Made by the SDK. It compares the stable value of the visitor for this feature flag against `weight`. |
+
+The `decide` function that the SDK makes derives from the visitor ID, the ID of the
+feature flag, and the weight. A feature flag that you control from the dashboard
+therefore cannot use the data of your application. Define the feature flag in SDK code
+when you need that.
+
+## Define a feature flag in SDK code
+
+Define your feature flags when you create the Picked client. Pass a `features` object. Use
+this when a decision needs data that only your application holds. Each feature flag needs a
+unique identifier, a version key, a name that a person can read, and a `decide`
+function:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  features: {
+    'summer-sale': {
+      key: 'summer-sale-v1', // The version key. Change it to invalidate the cache.
+      name: 'Summer Sale Experiment', // A name for analytics that a person can read.
+      decide: async () => {
+        // Put your decision rules here.
+        const isEligible = await checkUserEligibility()
+        return isEligible // Returns a boolean.
+      },
+      storage: 'local', // Optional: 'local' is the default, or 'session'.
+    },
+    'homepage-variant': {
+      key: 'homepage-test-v2',
+      name: 'Homepage A/B Test',
+      decide: async () => {
+        // Return a string for a test of more than two variants.
+        return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
+      },
+    },
+  },
+})
+```
+
+A feature flag can also be a factory function, which starts the feature flag only when it is
+first needed:
+
+```ts
+features: {
+  'my-feature': () => ({
+    key: 'my-feature-v1',
+    name: 'My Feature',
+    decide: async () => true,
+  }),
+}
+```
+
+## Overrides in the URL
+
+You can override a feature flag decision from the URL search parameters, for a test:
+
+```
+https://example.com?picked-feature=my-feature:true
+```
+
+You can give more than one override value:
+
+```
+https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
+```
+
+The format is `?picked-feature=<feature-id>:<bucket-value>`.
+
+This is useful for QA, because you can test one bucket value and change no code. The
+SDK keeps the override value in session storage. The browser clears it when you close
+the tab.
+
+## Use a feature flag in an experience condition
+
+You can use a feature flag in an experience condition through JSON logic:
+
+```ts
+const myExperience = createExperience({
+  // The other options go here.
+  condition: {
+    and: [
+      {
+        '==': [
+          {
+            invoke: {
+              var: 'features.summer-sale', // Point at the feature flag by its ID.
+            },
+          },
+          true, // Check that the bucket equals true.
+        ],
+      },
+    ],
+  },
+})
+```
+
+The ID in `features.<id>` is the **Key** of the feature flag from the dashboard. It is the
+same value that the detail page of the feature flag shows.
+
+An evaluation of a condition reads the bucket. Picked therefore allocates a visitor
+to a feature flag when the condition that points at it runs.
+
+## Watch for feature flag decisions
+
+Subscribe to the `feature_decide` event to track when a feature flag resolves:
+
+```ts
+client.eventBus.watch((event) => {
+  if (event.type !== 'feature_decide') return
+
+  const { feature } = event
+  console.log(`Flag "${feature.id}" resolved to bucket:`, feature.bucket)
+  // Example output: the feature flag resolved to the bucket true.
+
+  // Send the decision to your analytics.
+  analytics.track('Feature Decision', {
+    featureId: feature.id,
+    bucket: feature.bucket,
+  })
+})
+```
+
+A watch on `eventBus` reports only what happens after you subscribe.
+
+## Read the events that already happened
+
+`client.events` is a store of every event since the client started, in order. Each entry
+holds an `id`, the time `at`, and the `payload` that went on the bus.
+
+```ts
+const alreadyAllocated = client.events
+  .getState()
+  .filter((entry) => entry.payload.type === 'feature_decide')
+```
+
+Use it when your code starts after Picked does, and a `feature_decide` that you needed
+already happened before you subscribed.
+
+## Versions and cache invalidation
+
+The SDK caches a feature flag decision in browser storage. It uses `localStorage`, or
+`sessionStorage` in a preview. The cache key derives from the feature flag ID and the version,
+so a visitor keeps the same decision across page loads.
+
+:::note
+The SDK keeps a bucket value in storage as text. It reads `'true'` and `'false'` back as
+booleans. A variant with the name `true` or `false` therefore comes back as a boolean.
+Give each variant a different name.
+:::
+
+### How versions work
+
+A feature flag that you create in the dashboard starts at version 1. The SDK uses the
+version to build the cache key. A feature flag at version 3 caches under `v3`.
+
+The version affects **the cache only**. It is not part of the allocation. For a feature flag
+that you control from the dashboard, the allocation derives from the visitor ID and
+the weight of the feature flag.
+
+### What happens when you increment the version
+
+When you increment the version of a feature flag in the dashboard:
+
+1. **The cache key changes.** The old entry, `v3`, no longer matches the new key,
+   `v4`. The SDK therefore treats the feature flag as undecided.
+2. **The `decide` function runs again.** On the next page load, the SDK calls
+   `decide()` again and caches the new result.
+3. **Picked evaluates each visitor again and moves nobody.** For a feature flag that you
+   control from the dashboard the allocation is deterministic. The same visitor
+   against an unchanged weight gives the same bucket.
+
+:::note
+The new version clears the cached decisions and runs the allocation again. It moves
+no visitor between groups. With an unchanged weight, everybody lands where they were.
+Increment the version after you change a weight, so that Picked evaluates a visitor
+with a cached decision against the new weight.
+:::
+
+### The SDK `key` and the dashboard version
+
+For a feature flag that you define in SDK code, use the `key` field to set the version
+yourself. This applies when you do not read the feature flag from the dashboard:
+
+```ts
+features: {
+  'summer-sale': {
+    key: 'summer-sale-v2', // Change this to invalidate the cache.
+    // The other options go here.
+  },
+}
+```
+
+For a feature flag that you control from the dashboard, Picked sets the version for you. The
+dashboard adds the version number to the end of the cache key that the SDK uses.
+
+## Related
+
+- [How to read a feature flag](/how-to/read-a-feature-flag) — the accessors in use.
+- [About feature flag allocation](/explanation/feature-flag-allocation) — when a visitor
+  enters a test.
+- [Feature flags](/reference/dashboard/features) — the dashboard controls.
+