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

package/dist/docs/flow-builder/building-flows.md

@@ -0,0 +1,61 @@
+---
+layout: docs
+---
+
+# Building flows
+
+Build flows by dragging blocks onto the canvas, connecting nodes with arrows, and configuring each node in the inspector.
+
+## Add nodes
+
+Drag a step, action, or condition from the entity browser onto the canvas. A new node appears where you drop it.
+
+You can also drop a block directly onto an existing arrow. The node inserts inline — the original arrow splits into two arrows with the new node in between. A **+** indicator appears when you hover over a valid arrow.
+
+## Connect nodes
+
+Click and drag from a node's output handle (right side) to another node's input handle (left side). An arrow appears connecting them.
+
+The flow follows arrows from left to right, starting at the origin. Every node downstream of the origin is part of the experience flow.
+
+## Branch with conditions
+
+Connect the origin (or any node) to a condition node. The condition evaluates its logic and routes the flow down one of two paths.
+
+Connect the green (true) handle to the nodes that should run when the condition passes. Connect the red (false) handle to the alternative path. Either path can lead to more steps, actions, or further conditions.
+
+## Assign fields to steps
+
+Drag a field from the entity browser and drop it onto a step node. The field is now assigned to that step.
+
+You can assign multiple fields to a single step. The step node shows a count of assigned fields. To see which fields are assigned, select the step and check the **Assigned Fields** section in the inspector.
+
+## Select nodes
+
+Click a node to select it. Its inspector opens in the right panel.
+
+Drag on empty canvas to marquee-select multiple nodes. Press `Cmd/Ctrl+A` to select all nodes.
+
+When multiple nodes are selected, the inspector shows a count and grouped list. Click any item in the list to navigate to its inspector.
+
+## Move nodes
+
+Drag a selected node to reposition it. Nodes snap to the grid automatically.
+
+Use arrow keys to nudge selected nodes. Hold `Shift` for larger nudges.
+
+## Delete nodes
+
+Select one or more nodes and press `Delete` or `Backspace`. The nodes and their connected arrows are removed.
+
+## Duplicate nodes
+
+Select one or more nodes and press `Cmd/Ctrl+D`. Copies appear offset from the originals.
+
+## Undo and redo
+
+Press `Cmd/Ctrl+Z` to undo. Press `Cmd/Ctrl+Shift+Z` to redo. The undo stack tracks node additions, deletions, connections, and position changes.
+
+---
+
+[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · **Building Flows** · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

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

@@ -0,0 +1,54 @@
+---
+layout: docs
+---
+
+# Condition builder
+
+The condition builder is a visual rule editor used across the dashboard. It lets you define logic without writing code.
+
+## Where it appears
+
+The condition builder is used in several places:
+
+- **Condition nodes** — define branching logic in the [flow builder](/flow-builder/overview)
+- **Experience conditions** — control when an experience activates for a visitor
+- **Initialize open conditions** — control when an experience opens automatically on page load
+- **Field option conditions** — show or hide individual options based on visitor state
+
+## Rule structure
+
+Rules are organized into groups. Each group uses either **AND** (all rules must match) or **OR** (any rule must match).
+
+A single rule has three parts:
+
+1. **Field** — the data source to evaluate
+2. **Operator** — how to compare (equals, not equals, greater than, contains, etc.)
+3. **Value** — the target value to compare against
+
+You can nest groups inside other groups to create complex logic. For example, an AND group containing two OR groups.
+
+## Available data sources
+
+When building rules, you can reference these data sources:
+
+**Responses** — values visitors have submitted through form fields in the current experience. Each field you create in your project appears here by its name.
+
+**Actions** — references to actions that have been triggered during the flow.
+
+**Features** — the state of feature flags in your project. Use this to branch based on which variant a visitor is assigned to.
+
+**Location** — properties of the visitor's current page URL, including pathname, search parameters, hostname, and hash.
+
+## Example
+
+To show a step only to visitors on a specific page who opted into marketing:
+
+1. Create an AND group.
+2. Add a rule: **Location → pathname** equals `/pricing`.
+3. Add a rule: **Responses → marketing_opt_in** equals `true`.
+
+Both conditions must be true for the rule group to match.
+
+---
+
+[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · **Condition Builder**

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,98 @@
+---
+layout: docs
+---
+
+# Data sources
+
+PickedQL provides four 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'
+```
+
+## `experience_journey` — Sankey-ready step transitions
+
+Returns per-edge `source, target, users` rows ready to feed a sankey or funnel chart. Wraps the 8-CTE step-transition scaffold (lagInFrame, consecutive-step dedup, top-N path ranking) that cards used to carry inline.
+
+All filters pass through the **outer `WHERE`** — PickedQL extracts them as parameters and substitutes them into the underlying scaffold. Only `project_id` is required; the rest are optional and default sensibly.
+
+| Param (WHERE key) | Purpose |
+|---|---|
+| `project_id` | Required tenant filter. |
+| `experience_id` | Restrict to one `fact_events.experience_id`. |
+| `starting_step` | Anchor edges at each user's first occurrence of this `step_id`. Absent → anchor at user's first step_enter event. |
+| `targeting_step` | Trim each user's window at their first occurrence of this `step_id`. Users who never reach it still contribute their journey up to `num_nodes_after_start`. |
+| `num_nodes_after_start` | Forward window size from the starting step (card 4129 semantics). |
+| `num_nodes_before_target` | Backward window size from the targeting step (card 2740 semantics). Requires `targeting_step`. |
+| `top_n_path` | Keep only the top-N distinct paths by user count. |
+
+When `num_nodes_after_start` and `num_nodes_before_target` are both set, both predicates apply (intersection).
+
+```sql
+-- "Overall user journey" sankey (card 4129 pattern) — forward window, target optional
+SELECT source, target, users FROM experience_journey
+WHERE project_id           = 'your-project-id'
+  AND starting_step        = 'step-start'
+  AND targeting_step       = 'step-target'
+  AND num_nodes_after_start = 10
+```
+
+```sql
+-- "Paths leading to target" sankey (card 2740 pattern) — backward window + top-N ranking
+SELECT source, target, users FROM experience_journey
+WHERE project_id             = 'your-project-id'
+  AND experience_id          = 'exp-123'
+  AND starting_step          = 'step-start'
+  AND targeting_step         = 'step-target'
+  AND num_nodes_before_target = 5
+  AND top_n_path             = 10
+```
+
+```sql
+-- "Drop-off" sankey (card 2744 pattern) — omit targeting_step
+SELECT source, target, users FROM experience_journey
+WHERE project_id           = 'your-project-id'
+  AND experience_id        = 'exp-123'
+  AND starting_step        = 'step-start'
+  AND num_nodes_after_start = 10
+```
+
+Columns returned:
+
+| 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. |
+
+:::note
+`experience_journey` is aggregated output. Dimension filters (`variant_type`, `device_category`, `country_code`, …) are **not** supported — if you need those, query [`events`](#events--user-level-event-data) directly and build the transitions yourself.
+:::

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`.