@picked/client 0.0.1-dev.1776647766999 → 0.0.1-dev.1776837084253

package/dist/docs/pickedql/examples.md

@@ -0,0 +1,249 @@
+---
+layout: docs
+---
+
+# Example queries
+
+## 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 purchase conversion with your own numerator and denominator. Useful when conversion is defined by a form submission, lead capture, or any custom event.
+
+```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
+-- Either checkout_complete or order_create 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 }}'
+```
+
+## 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,
+  total_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
+
+Forward window from the starting step. Non-reachers of `targeting_step` still contribute edges up to `num_nodes_after_start`. Mirrors dashboard 1156 card 4129's semantics.
+
+```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 — top paths leading to a target step
+
+Backward window anchored at the target, plus top-N path ranking. Mirrors dashboard 1156 card 3961 / dashboard 991 card 2740 semantics.
+
+```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). Mirrors card 2744.
+
+```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 |

package/dist/docs/pickedql/filtering.md

@@ -0,0 +1,31 @@
+---
+layout: docs
+---
+
+# Filtering
+
+Add `WHERE` clauses as usual. Every query must include a `project_id` filter — PickedQL extracts it and verifies you have permission to access that project. Queries without a `project_id` filter are rejected.
+
+```sql
+-- Date range
+SELECT control_users() FROM metrics
+WHERE project_id = 'your-project-id'
+  AND project_local_date BETWEEN '2026-03-01' AND '2026-03-31'
+
+-- By experience
+SELECT step_enter_users() FROM events
+WHERE project_id = 'your-project-id'
+  AND experience_id = 'my-experience'
+GROUP BY step_id
+
+-- Combined filters
+SELECT control_users(), variant_users() FROM metrics
+WHERE project_id = 'your-project-id'
+  AND project_local_date >= '2026-03-01'
+  AND experience_id = 'my-experience'
+  AND device_category = 'Mobile'
+```
+
+:::warning
+Each query can only filter on a single `project_id`. Queries that reference multiple projects will be rejected.
+:::

package/dist/docs/pickedql/index.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+---
+
+# PickedQL
+
+PickedQL is a SQL query language for querying your Picked analytics data. Write simple SQL using virtual tables and functions — PickedQL expands them into optimized queries with automatic joins and A/B test aggregations.
+
+## Quick start
+
+```sql
+-- How many users are in the control vs variant group?
+SELECT control_users(), variant_users()
+FROM metrics
+WHERE project_id = 'your-project-id'
+```
+
+PickedQL handles table mapping and dimension joins automatically. You write concise, readable SQL — PickedQL does the rest.
+
+## How PickedQL works
+
+1. **Virtual table expansion**: Table names like `metrics` map to underlying data tables
+2. **Virtual function expansion**: Shorthand functions like `control_users()` expand to full aggregate expressions
+3. **Auto dimension joins**: References to dimension columns (like `device_category` or `country_code`) trigger automatic `LEFT JOIN` clauses — you never write joins yourself
+4. **Tenant isolation**: Every query must include a `project_id` filter in the `WHERE` clause. PickedQL extracts it and verifies you have permission to access that project
+5. **SQL passthrough**: Standard SQL (including `CASE WHEN`, window functions, and subqueries) works alongside virtual functions
+
+## Best practices
+
+- **Use `metrics` for dashboards**: Pre-aggregated data is significantly faster than raw events for standard reporting
+- **Use `events` for deep dives**: Raw event-level data gives full flexibility for custom breakdowns and funnels
+- **Use `experience_journey` for sankey / funnel charts**: One line of SQL returns `source, target, users` — the 8-CTE scaffold (dedup, top-N path ranking, lagInFrame) is handled internally; pass parameters via `WHERE`
+- **Don't write JOINs**: PickedQL injects them automatically when you reference dimension columns
+- **Group by any dimension**: Add dimension columns to `SELECT` and `GROUP BY` freely — required joins are handled for you
+

package/dist/docs/pickedql/schema.md

@@ -0,0 +1,123 @@
+---
+layout: docs
+---
+
+# Schema
+
+Column reference for each PickedQL data source.
+
+## `metrics`
+
+Pre-aggregated daily data. One row per unique combination of dimensions per day.
+
+| Column | Type | Description |
+|---|---|---|
+| `project_id` | String | Project identifier (required in `WHERE`) |
+| `project_local_date` | Date | Date in project timezone |
+| `experience_id` | String | Experience identifier |
+| `step_id` | String | Step identifier |
+| `event_type` | String | Event type (e.g., `page_view`, `click`) |
+| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
+| `variant_type` | String | `Control`, `Variant`, or `Unknown` |
+| `device_category` | String | Device category (e.g., `Desktop`, `Mobile`) |
+| `country_code` | String | ISO country code |
+| `utm_source` | String | UTM source |
+| `utm_medium` | String | UTM medium |
+| `product_name` | String | Product name |
+| `product_category` | String | Product category |
+| `landing_page_url` | String | Landing page URL |
+
+:::note
+Aggregate columns (`users`, `sessions`, `events`, etc.) are not queried directly — use [virtual functions](./virtual-functions) instead.
+:::
+
+## `events`
+
+User-level event data. One row per event per user. Dimension columns are joined automatically when referenced.
+
+### Native columns
+
+| Column | Type | Description |
+|---|---|---|
+| `project_id` | String | Project identifier (required in `WHERE`) |
+| `event_id` | String | Unique event identifier |
+| `user_canonical_id` | String | Canonical user identifier |
+| `session_id` | String | Session identifier |
+| `experience_id` | String | Experience identifier |
+| `step_id` | String | Step identifier |
+| `event_type` | String | Event type (e.g., `page_view`, `click`) |
+| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
+| `client_local_date` | Date | Date in client timezone |
+| `is_purchase` | UInt8 | `1` if checkout complete event |
+| `is_cart_add` | UInt8 | `1` if cart add event |
+| `is_first_session` | UInt8 | `1` if first session for this user |
+| `landing_page_url` | String | Landing page URL |
+| `features` | Map(String, String) | Feature flag assignments |
+| `feature_keys` | Map(String, String) | Feature key assignments |
+| `event_meta` | String | Event metadata |
+
+### Dimension columns (auto-joined)
+
+These columns are joined automatically when referenced — no `JOIN` syntax needed.
+
+| Column | Source | Description |
+|---|---|---|
+| `variant_type` | dim_variant | `Control`, `Variant`, or `Unknown` |
+| `ab_feature_name` | dim_variant | A/B feature name |
+| `ab_feature_value` | dim_variant | A/B feature value |
+| `device_category` | dim_device | Device category |
+| `browser_name` | dim_device | Browser name |
+| `browser_version` | dim_device | Browser version |
+| `os_name` | dim_device | Operating system name |
+| `os_version` | dim_device | Operating system version |
+| `platform` | dim_device | Platform |
+| `country_code` | dim_geo | ISO country code |
+| `country_name` | dim_geo | Country name |
+| `region` | dim_geo | Region |
+| `city` | dim_geo | City |
+| `utm_source` | dim_utm | UTM source |
+| `utm_medium` | dim_utm | UTM medium |
+| `utm_campaign` | dim_utm | UTM campaign |
+| `utm_term` | dim_utm | UTM term |
+| `utm_content` | dim_utm | UTM content |
+| `product_name` | dim_product | Product name |
+| `product_category` | dim_product | Product category |
+| `product_page` | dim_product | Product page |
+
+## `features`
+
+The `features` table provides [parameterized virtual functions](./virtual-functions#feature-functions-features--events) for querying feature flag assignments:
+
+| 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 |
+
+## `experience_journey`
+
+Aggregated step-transition edges for sankey / funnel charts. Parameters are supplied via the outer `WHERE` clause (PickedQL extracts them and substitutes into the underlying scaffold).
+
+### Columns
+
+| Column | Type | Description |
+|---|---|---|
+| `source` | String | Edge start, formatted as `NN. step_id` (e.g., `01. welcome`). |
+| `target` | String | Edge end, formatted as `NN. step_id`. |
+| `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
+
+### Parameters (via `WHERE`)
+
+| Key | Type | Required | Purpose |
+|---|---|---|---|
+| `project_id` | String | ✓ | Tenant filter. |
+| `experience_id` | String |  | Restrict to one `fact_events.experience_id`. |
+| `starting_step` | String |  | Anchor edges at first occurrence of this `step_id`. Defaults to each user's first step. |
+| `targeting_step` | String |  | Trim each user's window at their first occurrence of this `step_id`. Non-reachers still contribute their pre-cut journey. |
+| `num_nodes_after_start` | Integer |  | Forward window from start: keep steps where `seq_pos < start_seq + N` (card 4129 semantics). |
+| `num_nodes_before_target` | Integer |  | Backward window from target: keep steps where `seq_pos >= target_seq - N` (card 2740 semantics). Requires `targeting_step`. |
+| `top_n_path` | Integer |  | Keep only the top-N most-walked paths by user count. Defaults to no limit. |
+
+When both window params are set, both predicates apply (intersection).
+
+See [data sources → experience_journey](./data-sources#experience_journey--sankey-ready-step-transitions) for usage examples.

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

@@ -0,0 +1,121 @@
+---
+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/B test metrics
+
+| Function | Description |
+|---|---|
+| `control_users()` | Unique users in the Control group |
+| `variant_users()` | Unique users in the Variant group |
+| `all_users()` | All unique users |
+| `control_sessions()` | Unique sessions in the Control group |
+| `variant_sessions()` | Unique sessions in the Variant group |
+| `all_sessions()` | All unique sessions |
+
+## Conversion metrics
+
+| Function | Description |
+|---|---|
+| `total_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) |
+| `total_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
+| `total_purchase_orders()` | Unique order count (`metrics` only) |
+| `total_cart_add_users()` | Users who added to cart |
+
+## Conversion rates
+
+| 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 |
+
+### Custom conditions on `events`
+
+On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
+
+Each argument is a condition expression using `column=value` with `AND`/`OR` operators and parentheses for grouping.
+
+```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
+
+-- AND/OR in conditions
+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
+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
+
+-- Uplift with named args
+SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
+```
+
+:::note
+Custom conditions are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
+:::
+
+## 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
+Funnel metrics are being continuously updated. Check back for new functions.
+:::
+
+| Function | Description |
+|---|---|
+| `step_enter_users()` | Users who entered a funnel step |
+| `step_enter_sessions()` | Sessions that entered a funnel step |
+
+## Feature functions (`features` / `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) |

package/dist/docs/projects.md

@@ -0,0 +1,30 @@
+---
+layout: docs
+---
+
+# 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.
+
+## Create a project
+
+You need an organization first. If you don't 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 contains one or more [Workspaces](/workspaces) for configuring and previewing experiences before publishing.
+
+## 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.
+
+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.
+
+## 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.

package/dist/docs/reference/index.md

@@ -0,0 +1,11 @@
+---
+layout: docs
+---
+
+# Reference
+
+Typedoc Reference
+
+## Getting Started
+
+Coming soon

package/dist/docs/reports.md

@@ -0,0 +1,11 @@
+---
+layout: docs
+---
+
+# Reports
+
+Reports show analytics data for your project. Track how visitors interact with your experiences and features.
+
+## View report data
+
+Open a report to see its analytics. Data updates as new visitor interactions are recorded.

package/dist/docs/sdk/actions.md

@@ -0,0 +1,37 @@
+---
+layout: docs
+---
+
+# Actions
+
+Register action handlers on the Picked client so the SDK can invoke them when an experience flow reaches an action node.
+
+## Registering actions
+
+Register actions when creating the Picked client. Each key in the `actions` object must match an action key defined in the dashboard:
+
+```ts
+import { createClient } from '@picked/client'
+
+const picked = createClient({
+  organizationId: 'your-org-id',
+  projectId: 'your-project-id',
+  actions: {
+    'track-signup': () => {
+      analytics.track('signup_completed')
+    },
+    'notify': (params) => {
+      sendNotification(params)
+    },
+  },
+})
+```
+
+Each action is a function that receives optional parameters and returns nothing. When the flow reaches an action node, the SDK calls the matching function.
+
+## 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. Actions execute synchronously within the flow — the SDK continues to the next node after the function returns
+4. **Non-blocking**: Actions don't interrupt the visitor's experience. The flow continues to the next connected node automatically