@picked/client 0.0.56-next.1 → 0.0.56-next.2

package/dist/docs/flow-builder/keyboard-shortcuts.md

@@ -0,0 +1,66 @@
+---
+layout: docs
+---
+
+# Keyboard shortcuts
+
+These shortcuts are available when the flow builder canvas is focused.
+
+## Canvas tools
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `V` | `V` | Select tool |
+| `H` | `H` | Hand tool (pan) |
+| `Space` (hold) | `Space` (hold) | Temporary hand tool |
+
+## Layout
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Shift+L` | `Shift+L` | Auto-layout |
+
+## Selection
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+A` | `Ctrl+A` | Select all nodes |
+| `Escape` | `Escape` | Deselect all |
+
+## Editing
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+D` | `Ctrl+D` | Duplicate selected nodes |
+| `Delete` / `Backspace` | `Delete` / `Backspace` | Delete selected nodes |
+| `Cmd+Z` | `Ctrl+Z` | Undo |
+| `Cmd+Shift+Z` | `Ctrl+Shift+Z` | Redo |
+
+## Movement
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Arrow keys | Arrow keys | Nudge selected nodes |
+| `Shift`+Arrow keys | `Shift`+Arrow keys | Large nudge |
+
+## Zoom
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Scroll | Scroll | Zoom in/out |
+| Pinch | Pinch | Zoom in/out (trackpad) |
+| `Cmd+=` | `Ctrl+=` | Zoom in |
+| `Cmd+-` | `Ctrl+-` | Zoom out |
+| `Shift+1` | `Shift+1` | Fit view |
+| `Shift+0` | `Shift+0` | Zoom to 100% |
+
+## Panels
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+\` | `Ctrl+\` | Toggle both side panels |
+| `?` | `?` | Toggle shortcuts |
+
+---
+
+[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · [Building Flows](/flow-builder/building-flows) · **Keyboard Shortcuts** · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/flow-builder/nodes.md

@@ -0,0 +1,43 @@
+---
+layout: docs
+---
+
+# Nodes
+
+Nodes are the building blocks of a flow. Each node represents a block in your experience. There are four node types.
+
+## Origin
+
+Every flow starts with an origin node. It's a gray circle on the left side of the canvas. It has one output handle on its right side.
+
+You can't move, delete, or duplicate the origin. It's always present.
+
+## Step
+
+A step node represents a screen shown to visitors. It appears as a blue rectangle on the canvas.
+
+Steps hold fields. Drag a field from the entity browser onto a step node to assign it. The node subtitle shows how many fields are assigned.
+
+Each step has a `layoutName` that tells the SDK which visual layout to use when rendering this step. Configure the layout name in the inspector.
+
+## Action
+
+An action node represents a side effect — something that happens behind the scenes. It appears as a green rectangle.
+
+Actions trigger when the flow reaches them. Use actions for tasks like tracking events, sending data, or triggering integrations.
+
+## Condition
+
+A condition node represents a branching point. It appears as an amber rectangle.
+
+Condition nodes have two output handles instead of one. The green handle (top-right) connects to the path taken when the condition is true. The red handle (bottom-right) connects to the path taken when it's false.
+
+Define the condition logic in the inspector using the visual condition builder. See [Conditions](/conditions) for details.
+
+## Handles
+
+Handles are the connection points on nodes. Input handles sit on the left. Output handles sit on the right. Drag from an output handle to an input handle to connect two nodes.
+
+---
+
+[Overview](/flow-builder/overview) · **Nodes** · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/flow-builder/overview.md

@@ -0,0 +1,43 @@
+---
+layout: docs
+---
+
+# Flow builder
+
+The flow builder is a visual editor for designing experience flows. You drag blocks onto a canvas, connect them with arrows, and configure each node in an inspector panel.
+
+## Layout
+
+The flow builder has three panels arranged left to right.
+
+**Entity browser** (left): Lists all steps, actions, conditions, and fields in your project. Drag items from here onto the canvas.
+
+**Canvas** (center): The workspace where you build your flow. Nodes represent blocks. Arrows represent connections between them.
+
+**Inspector** (right): Shows configuration for the selected node. When nothing is selected, it shows experience-level settings.
+
+## Panel controls
+
+Drag the dividers between panels to resize them. Press `Cmd/Ctrl+\` to toggle both side panels. Press `Cmd/Ctrl+Shift+\` to toggle just the inspector.
+
+## Navigating the canvas
+
+**Zoom**: Scroll to zoom in and out.
+
+**Pan**: Select the hand tool (press `H`) and drag. Or hold `Space` while dragging. Middle-click drag also pans.
+
+**Select tool**: Press `V` to switch back to the select tool. This is the default — click to select nodes, drag on empty space to marquee-select.
+
+## Auto-layout
+
+Click the auto-layout button in the toolbar to automatically arrange all nodes in a clean hierarchy. Useful after adding many nodes or when the canvas gets messy.
+
+## Saving
+
+Click **Save** in the toolbar to save your flow. The button is enabled when you have unsaved changes.
+
+The flow builder also auto-saves after a period of inactivity. A dot indicator appears on the save button when there are unsaved changes.
+
+---
+
+**Flow Builder** · [Nodes](/flow-builder/nodes) · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/index.md

@@ -0,0 +1,79 @@
+---
+layout: docs
+---
+
+# Getting Started
+
+Picked lets you build personalized UI flows in a visual editor and deliver them to visitors on your site with a lightweight SDK.
+
+## How it works
+
+You design experiences in the dashboard using a drag-and-drop flow builder. The SDK fetches your published experiences and renders them on your site.
+
+## Quick start
+
+### 1. Create a project
+
+Sign in to the dashboard and create a project. A project represents one website or app.
+
+See [Projects](/projects) for details.
+
+### 2. Install the SDK
+
+Add the SDK to your site and initialize the client. Copy the snippet from your project home page.
+
+```typescript
+import { createClient } from '@picked/client'
+
+const picked = createClient({
+  organizationId: 'your-organization-id',
+  projectId: 'your-project-id',
+  plugins: [],
+})
+
+picked.start()
+```
+
+See [SDK Installation](/sdk) for full setup options.
+
+### 3. Register a component
+
+Register components when creating the client. Each key in the `components` object must match a component name you set in the dashboard.
+
+```typescript
+import { createClient } from '@picked/client'
+
+const picked = createClient({
+  organizationId: 'your-organization-id',
+  projectId: 'your-project-id',
+  components: {
+    'welcome-survey': YourComponent,
+  },
+})
+
+picked.start()
+```
+
+See [SDK Experiences](/sdk/experiences) for targeting, conditions, and component adapters.
+
+### 4. Create an experience
+
+In the dashboard, open your project and click **Experiences** > **New Experience**. Enter a name and set the component name to match your registered component (e.g., `welcome-survey`).
+
+See [Experiences](/experiences) for configuration options.
+
+### 5. Build the flow
+
+Open the flow builder and drag steps, actions, and conditions onto the canvas. Connect nodes to define the visitor's path through the experience.
+
+See [Flow Builder](/flow-builder/overview) for a full walkthrough.
+
+### 6. Save and publish
+
+Click **Save** in the flow builder toolbar. The SDK picks up the published experience and renders it to matching visitors on your site.
+
+## Next steps
+
+- [Flow Builder](/flow-builder/overview) — Build experience flows visually
+- [Steps](/steps), [Fields](/fields), [Actions](/actions), [Conditions](/conditions) — Configure the building blocks of experiences
+- [SDK Installation](/sdk) — Full SDK setup and configuration

package/dist/docs/pickedql/data-sources.md

@@ -0,0 +1,39 @@
+---
+layout: docs
+---
+
+# Data sources
+
+PickedQL provides three virtual tables, each optimized for different query patterns.
+
+## `metrics` — Pre-aggregated daily data
+
+Best for dashboards and trend analysis. One row per unique combination of dimensions per day. Dimension columns (like `device_category`, `country_code`, `utm_source`) are available directly — no joins needed.
+
+```sql
+SELECT device_category, control_users(), variant_users()
+FROM metrics
+WHERE project_id = 'your-project-id'
+GROUP BY device_category
+```
+
+## `events` — User-level event data
+
+Best for deep analysis, funnels, and custom breakdowns. One row per event per user. Dimension columns (like `device_category` or `country_code`) are joined automatically when referenced.
+
+```sql
+SELECT user_canonical_id, device_category
+FROM events
+WHERE project_id = 'your-project-id'
+  AND variant_type = 'Control'
+```
+
+## `features` — Feature flag analysis
+
+Best for querying user, session, and event counts per feature flag and bucket. Uses parameterized functions.
+
+```sql
+SELECT feature_users('homepage_test', 'control')
+FROM features
+WHERE project_id = 'your-project-id'
+```

package/dist/docs/pickedql/dimensions.md

@@ -0,0 +1,23 @@
+---
+layout: docs
+---
+
+# Dimension columns
+
+Dimension columns are available on all data sources. On `metrics`, they are included directly in the table. On `events` and `features`, the required `LEFT JOIN` is added automatically when you reference them — you never write joins yourself.
+
+## Available dimensions
+
+| Source | Columns |
+|---|---|
+| `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
+| `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
+| `dim_geo` | `country_code`, `country_name`, `region`, `city` |
+| `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
+| `dim_product` | `product_name`, `product_category`, `product_page` |
+
+## Native event columns
+
+These columns are available directly on `events` and require no join:
+
+`event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.

package/dist/docs/pickedql/examples.md

@@ -0,0 +1,165 @@
+---
+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       |
+
+## 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     |
+
+
+## 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,34 @@
+---
+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
+- **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,95 @@
+---
+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 |