picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,248 @@
+---
+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 |
+
+The bucket is what the SDK sent to the site of the visitor. A Boolean feature flag gives
+`'true'` or `'false'`. A Text feature flag gives the value of one variant, or `'false'` for
+the control group. The key is the version of the feature flag, such as `'v1'`.
+
+```sql
+-- Compare the two buckets of a Boolean feature flag.
+SELECT
+  feature_users('homepage_test', 'false') AS control,
+  feature_users('homepage_test', 'true') AS variant
+FROM features
+
+-- Compare the variants of a Text feature flag.
+SELECT
+  feature_users('hero', 'false') AS control,
+  feature_users('hero', 'hero-a') AS hero_a,
+  feature_users('hero', 'hero-b') AS hero_b
+FROM features
+
+-- Count one version of the feature flag alone.
+SELECT feature_users('homepage_test', 'false', '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/docs/reference/sdk/actions.md

@@ -0,0 +1,154 @@
+---
+type: reference
+layout: docs
+---
+
+# Actions
+
+An action is a function that the SDK runs by its key. An action comes from one of two
+places:
+
+- **Your application** registers a handler in `createClient({ actions })`.
+- **Your project** publishes the action. Its handler sends the visitor's answers to Picked,
+  and the workflow of the action runs there.
+
+A handler from your application replaces a published action that has the same key. The
+workflow then does not start.
+
+## Response
+
+The value that a handler returns is the response of the action. A handler can return any
+value, or a promise of any value.
+
+The response of a published action is the payload of the **Action response** node in its
+workflow. A workflow that has no **Action response** node gives `undefined`.
+
+## 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. While the action runs, the flow ignores a request to go to the next step
+or to a specified step. The outcome of the action then chooses the branch. If your visitor
+goes back before the action completes, the flow stays on that step. The signal that the
+handler receives then stops.
+
+## Published actions
+
+A published action waits for the response of its workflow. It stops after 30 seconds.
+
+| Cause | The action rejects with |
+| --- | --- |
+| Picked refuses the request | An `Error` that names the HTTP status |
+| Picked does not accept the request in 25 seconds | A `TimeoutError` |
+| Picked accepts the request, but gives no run to wait for | An `Error` that says that no run is available |
+| The workflow fails before it sends a response | `ActionRunFailedError` |
+| Picked refuses a request for the response with a `4xx` status | An `Error` that names the HTTP status |
+| No response in 30 seconds | `ActionResponseTimeoutError` |
+| Your code stops the wait with a signal | The reason of the signal |
+
+A request for the response can fail because of a network error, a timeout, a `5xx` status or
+a body that the SDK cannot read. The SDK then sends the request again. It waits 1 second after
+the first failure, and two times longer after each failure that follows. If the requests
+continue to fail, the 30-second limit stops the wait with `ActionResponseTimeoutError`.
+
+To identify `ActionRunFailedError` and `ActionResponseTimeoutError` with `instanceof`, import
+them from `@picked/client/plugins/dynamic-experiences`. The `name` of each error is the same
+as the name that you import.
+
+## Run an action from code
+
+| API | Returns | Rejects |
+| --- | --- | --- |
+| `client.actions.run(key, options)` | A promise of the response | Yes, with the error of the action |
+| `useAction(key, options)` (React) | For an action that starts a workflow: `{ run, status, response, error }`. For other actions: the action as a function. | `run`: No. The function: it returns or throws what the action returns or throws. |
+| `getAction(key, options)` (Svelte) | A store of the same value | The same as `useAction` |
+| `useActionResult(key, options)` (React) | The last result of your own action | No |
+| `getActionResult(key, options)` (Svelte) | A store of the last result of your own action | No |
+| `client.actions.getActionBinding(key, options)` | A store of the value that `useAction` and `getAction` give | The same as `useAction` |
+| `client.actions.getActionResult(key, options)` | A store of the last result of your own action, which `useActionResult` and `getActionResult` read | No |
+
+Type generation names the actions that start a workflow (`WorkflowActionKeys`). Without generated
+types, `useAction` and `getAction` give the action as a function. For each key, the value also
+includes `run`, `status`, `response` and `error`.
+
+The handler receives the arguments of a call to the function in `args`. It also receives the
+arguments of `run(...args)` in `args`.
+
+`status` is `idle`, `running`, `succeeded` or `failed`, for the last run. When a run starts,
+`response` and `error` are `undefined`. `run(...args)` resolves to
+`{ status: 'succeeded', response }` or to `{ status: 'failed', error }`.
+
+The SDK keeps one run state for each key and experience. All the components that use the
+same key and the same experience share that run state, and they show the same last run. When
+one of them calls `run`, all of them show that run.
+
+`useActionResult` and `getActionResult` run your own action again when a response, a field or
+the handler of the action changes. They also run it when a component that reads the result
+starts. In React, the action runs when the component mounts, and when an `<Activity>` shows the
+component again. In Svelte, it runs each time a component calls `getActionResult`. A change that
+occurs outside Picked, for example a login, then shows in a component that starts after the
+change.
+
+The components that read the same key and the same experience share one result. The action
+runs one time for each change. It also runs one time for the components that React renders
+together. React can stop while it renders and continue later, for example in a transition. Then
+the components that React renders after it continues run the action again.
+
+The result is always from the run that started last. If that run throws, the result is
+`undefined`. For a published action they give `undefined` and do not send a request. The types
+refuse the key of an action that starts a workflow.
+
+A result for an experience follows the changes only while `client.experienceInstances`
+contains that experience. When `client.experienceInstances` adds the experience, the action
+runs if a response, a field or the handler changed after the last run.
+
+The options of `client.actions.run`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `args` | `unknown[]` | The values that the handler receives in `args`. |
+| `experience` | `ExperienceInstance` | The experience that the handler receives as `context.experience`. |
+| `signal` | `AbortSignal` | Stops the wait. The handler receives a signal that stops too. |
+| `timeoutMs` | `number` | Stops the wait after this many milliseconds, with a `TimeoutError`. |
+
+`useAction` and `getAction` take `experience` only.
+
+## Other methods of `client.actions`
+
+| Method | Description |
+| --- | --- |
+| `refreshActionResult(key, options)` | Runs your own action again for the result that `getActionResult` gives. It does nothing until a component or your code reads that result. The calls in one task start one run. |
+| `isPublished(key)` | Returns `true` when the handler of the key is a published action. |
+| `unregister(key)` | Removes the handler of the key. If the key has no handler, nothing changes. |
+
+`refreshActionResult` and `getActionResult` take `experience` only.
+
+## Rule logic
+
+A rule reads the response of an action with `{ "invoke": [{ "var": "actions.<key>" }] }`. A
+response that is a string, a number, a Boolean, `null`, or an array or object of these
+reaches the rule. A different response reaches the rule as `undefined`.
+
+A rule runs the action each time the SDK evaluates the rule.
+
+A condition node can have a rule that runs an action. While the condition node waits for that
+rule, the flow ignores a request to go to the next step or to a specified step. The result of
+the rule then chooses the branch. If your visitor goes back before the rule has a result, the
+flow ignores the result.
+
+## Related
+
+- [How to wait for the response of an action](/how-to/wait-for-an-action-response) — show
+  the response in a component.
+- [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.