@picked/client 0.0.71-next.1 → 0.0.71-next.3

package/dist/docs/{pickedql → reference/pickedql}/virtual-functions.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -228,3 +229,9 @@ SELECT feature_users('homepage_test', 'control', 'v1') FROM features
 | 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,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -50,7 +51,7 @@ isSigningUpForNewsletter.addFalse(userDoesNotWantNewsletter)
 ## Conditional fields
 
 A JSON Logic condition can show or hide a field. The condition can read an earlier
-response or a [predicate](./predicates):
+response or a [predicate](/reference/sdk/predicates):
 
 ```ts
 import { createField } from '@picked/client/plugins/create-experience'
@@ -138,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/{sdk → reference/sdk}/features.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -11,7 +12,7 @@ rules.
 ## Where feature flags come from
 
 You control most feature flags from the dashboard. The
-[dynamic experiences plugin](/sdk/plugins/dynamic-experiences) reads the options of
+[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.
 
@@ -24,7 +25,7 @@ For a feature flag that you control from the dashboard, the SDK makes the defini
 | `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](/sdk/feature-allocation#preview-mode) |
+| `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
@@ -80,26 +81,6 @@ features: {
 }
 ```
 
-## How feature flags work
-
-After you register a feature flag, the SDK follows this order:
-
-1. **Registration** — the client registers each feature flag at startup. A registration
-   allocates nobody.
-2. **Cache check** — the SDK looks in browser storage for a decision from an earlier
-   visit. The cache key holds the feature flag `id` and `key`. When an entry is there, the
-   feature flag starts in a resolved state. This is why Picked allocates a visitor who
-   returns before anything reads the feature flag.
-3. **Lazy evaluation** — with no cached decision, `decide` runs the first time that
-   something reads the bucket.
-4. **Storage** — the SDK writes the resolved bucket to browser storage.
-5. **Event emission** — the SDK sends a `feature_decide` event, but only for a
-   decision that it makes during this page view. A decision that step 2 restores
-   sends nothing.
-
-See [Allocation and exposure](/sdk/feature-allocation) for what this means when you
-track an exposure.
-
 ## Overrides in the URL
 
 You can override a feature flag decision from the URL search parameters, for a test:
@@ -120,84 +101,6 @@ This is useful for QA, because you can test one bucket value and change no code.
 SDK keeps the override value in session storage. The browser clears it when you close
 the tab.
 
-## Read a feature flag
-
-After you define your feature flags, your application code can read the resolved
-bucket value of each one. The SDK gives you a hook for each framework, and an event
-bus that works with any framework.
-
-:::code-group
-
-```ts [Vanilla JS]
-import { createClient } from '@picked/client'
-
-const client = createClient({
-  /* Put your client options here. */
-})
-
-client.eventBus.watch((event) => {
-  if (event.type === 'feature_decide' && event.feature.id === 'my-feature') {
-    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'control' }
-  }
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getFeatureResult } from '@picked/svelte/hooks'
-
-  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
-  const result = getFeatureResult('my-feature')
-</script>
-
-{#if $result?.bucket === 'control'}
-  <p>Control</p>
-{:else if $result?.bucket === 'variant-a'}
-  <p>Variant A</p>
-{/if}
-```
-
-```tsx [React]
-import { useFeatureResult } from '@picked/react/hooks'
-
-function MyComponent() {
-  // { id, bucket }, or undefined until the feature flag resolves.
-  const result = useFeatureResult('my-feature')
-
-  return (
-    <div>
-      {result?.bucket === 'control' && <p>Control</p>}
-      {result?.bucket === 'variant-a' && <p>Variant A</p>}
-    </div>
-  )
-}
-```
-
-:::
-
-### Choose an accessor
-
-Each accessor returns a different value. They also differ in whether a read resolves
-the feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports
-the decision. See [Allocation and exposure](/sdk/feature-allocation).
-
-| API | Returns | Does a read resolve the feature flag? |
-| --- | --- | --- |
-| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
-| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
-| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** toggle | No |
-| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | No |
-| `client.features.getById(id)` | A store that holds one feature flag | No |
-
-:::warning
-`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
-renders. They commit the visitor to a bucket at that moment.
-
-Some decisions must wait for data that you do not have yet, such as a cart, a quote,
-or a profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call
-the function that they return after the data arrives.
-:::
-
 ## Use a feature flag in an experience condition
 
 You can use a feature flag in an experience condition through JSON logic:
@@ -248,17 +151,32 @@ client.eventBus.watch((event) => {
 })
 ```
 
+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.
 
-:::warning
-The SDK does not yet restore a string bucket value, such as `'variant-a'`, correctly
-from storage. It treats the visitor as unallocated on the next page load. A boolean
-bucket value is correct, and that includes every feature flag that you control from the
-dashboard. See PICK-1574.
+:::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
@@ -306,15 +224,10 @@ features: {
 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.
 
-## Best practices
-
-- **Use `session` storage for a short test**: set `storage: 'session'` for an
-  experiment that must not stay across browser sessions.
-- **Keep each `decide` function fast**: everything that waits for the feature flag waits for
-  `decide` to finish. This includes an experience condition and a component that
-  reads the result. Do not make a slow network call inside it.
-- **Allocate when the decision matters**: read a feature flag only after the data that it
-  needs arrives. Do not read every feature flag at startup. See
-  [Allocation and exposure](/sdk/feature-allocation).
-- **Return one type**: do not return a boolean from a feature flag one time and a string the
-  next. Choose one type and keep it.
+## 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.
+

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

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -55,24 +56,6 @@ export const communicationMethods = createField({
 })
 ```
 
-## How fields work
-
-After you register a field and an experience uses it:
-
-1. **Registration**: you register a field on the experience while you create the
-   step, with `.addField()`.
-2. **Condition evaluation**: when the field has a `condition`, the SDK evaluates it
-   against the current context. The result decides whether the field is visible.
-3. **Rendering**: the SDK renders each visible field in the experience UI, with its
-   label, its placeholder, and its options.
-4. **User input**: the user enters or chooses a value. Validation then runs in the
-   browser, when you set a rule.
-5. **Storage**: the SDK stores a valid response in the experience state, under
-   `responses[field.name]`.
-6. **Reference**: a later condition can point at the value with
-   `{ var: 'responses.field-name' }`. This works in a field condition, in a step
-   condition, and in the logic of an experience.
-
 ## Field types
 
 A field has one of four basic types: `text`, `number`, `boolean`, or `object`.
@@ -139,58 +122,6 @@ const conditionalField = createField({
 })
 ```
 
-## Field validation
-
-Check the input of a user with a JSON Logic rule. The `$input` variable holds the
-current value of the field:
-
-```ts
-const quantityField = createField({
-  id: 'quantity',
-  name: 'quantity',
-  type: 'number',
-  label: 'Quantity',
-  multiple: false,
-  required: true,
-  validation: {
-    catch: {
-      or: [
-        {
-          and: [
-            {
-              // The input value is above 0.
-              '>': [
-                {
-                  var: '$input',
-                },
-                0,
-              ],
-            },
-            {
-              // The input value is 999 or below.
-              '<=': [
-                {
-                  var: '$input',
-                },
-                999,
-              ],
-            },
-          ],
-        },
-        {
-          throw: 'Please enter a value between 1 and 999',
-        },
-      ],
-    },
-  },
-})
-```
-
-:::tip
-The `catch` and `throw` pattern in JSON Logic checks that the condition gives `true`.
-When it does not, the SDK shows the `throw` message to the user.
-:::
-
 ## Field policies
 
 Use a privacy policy to control how Picked tracks and stores the data of a field:
@@ -220,6 +151,11 @@ const sensitiveField = createField({
 Use these policies for sensitive data such as a tax number, a credit card number, or
 a password. That data must stay in the browser.
 
+Neither policy stops the flow from the use of the value inside the page. A field with both
+policies set still holds its value there, for step validation and for the conditions after
+the step. The policies control what leaves the page: your analytics, and browser
+storage.
+
 ## Field metadata
 
 Add more text to help the user:
@@ -267,21 +203,7 @@ const sensitiveField = createField({
 
 :::
 
-## Best practices
-
-- **Give each field a name that says what it holds**: use `email-address` and not
-  `field1`. It is then easier to debug the flow and to read your analytics.
-- **Match the type to the data**: use `number` for a numeric value, and not `text`.
-  The SDK can then check and compare the value correctly.
-- **Mark a field as required only when it is**: fewer required fields means fewer
-  users who leave the form.
-- **Keep each validation message clear**: an error message must tell the user exactly
-  how to correct the input.
-- **Show a field only when it is relevant**: use a condition on the field, and decide
-  it from the earlier responses.
-- **Apply a privacy policy to sensitive data**: use `doNotTrackValue` and
-  `doNotStoreValue` for personal information, a password, or financial data.
-- **Give helpful metadata**: add a `placeholder` and a `description` to help the
-  user, above all for an input with a format.
-- **Keep an option list easy to read**: for more than 5 options, add a search or
-  break the field into more than one step.
+## Related
+
+- [How to validate a field](/how-to/validate-a-field)
+- [Fields](/reference/dashboard/fields) — the dashboard privacy controls.

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

@@ -0,0 +1,68 @@
+---
+type: reference
+layout: docs
+---
+
+# Picked SDK
+
+The Picked SDK lets you add a dynamic, personalized experience to your web
+application with very little code.
+
+:::tip
+The SDK is framework-agnostic. It works with React, Svelte, Vue, and plain
+JavaScript.
+:::
+
+## Precondition and condition
+
+| Category     | Question               | Description                                                                                   |
+| ------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
+| Precondition | Must Picked start?     | Use it to check the environment, to filter by page, or for a feature flag that turns the SDK off completely. |
+| Condition    | Is this user eligible? | Use it to divide your users into groups, to enter a user into an A/B test, or to reach one group of users. |
+
+```ts
+const picked = createClient({
+  precondition: {
+    and: [
+      {
+        or: [
+          {
+            invoke: {
+              var: 'features.aa-test',
+            },
+          },
+          true,
+        ],
+      },
+      { invoke: { var: 'predicates.shopify-is-product-page' } },
+    ],
+  },
+  condition: {
+    invoke: {
+      var: 'features.convincely-enabled',
+    },
+  },
+  // The rest of the Picked options go here.
+})
+```
+
+:::warning
+A precondition or a condition that points at a feature flag reads the bucket of that
+feature flag. That read allocates the visitor at that moment.
+
+A precondition runs at startup. Picked therefore allocates every visitor to a feature
+flag that a precondition points at, before anything else happens. This includes a
+visitor who never reaches the experience that the feature flag controls.
+
+See [Allocation and exposure](/explanation/feature-flag-allocation) before you point a
+precondition at a flag.
+:::
+
+See [conditions](/reference/sdk/conditions) for more detail.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk)
+- [How to register a component](/how-to/register-a-component)
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what the difference is between a precondition and a condition.

package/dist/docs/{sdk → reference/sdk}/plugins/create-experience.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -6,26 +7,6 @@ layout: docs
 
 This plugin registers an array of experiences on the Picked client.
 
-## Set the plugin up
-
-:::code-group
-
-```ts [app.ts]
-import { createClient } from '@picked/client'
-import { createExperiencePlugin } from '@picked/client/plugins/create-experience'
-import { funnelExperience } from '../experiences/funnel-experience'
-import { widgetExperience } from '../experiences/widget-experience'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  plugins: createExperiencePlugin({
-    experiences: [funnelExperience, widgetExperience],
-  }),
-})
-```
-
-:::
-
 ## Define a step
 
 Define a step with `createStep()`. Add it directly to an experience with
@@ -101,7 +82,7 @@ const contactStep = createStep({
 
 ## Use a condition in an experience
 
-A [condition](../conditions) defines when an experience becomes active for the user.
+A [condition](/reference/sdk/conditions) defines when an experience becomes active for the user.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
@@ -128,8 +109,15 @@ const productPageFunnel = createExperience({
 })
 ```
 
-A [condition](../conditions) also controls the move from one step to the next.
+A [condition](/reference/sdk/conditions) also controls the move from one step to the next.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
 ```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [SDK experiences](/reference/sdk/experiences)
+- [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) — the dashboard-driven
+  alternative.

package/dist/docs/reference/sdk/plugins/dynamic-experiences.md

@@ -0,0 +1,26 @@
+---
+type: reference
+layout: docs
+---
+
+# Dynamic Experiences Plugin
+
+This plugin reads the configuration of your project from the Picked API at runtime. You can
+therefore control your experiences, feature flags, steps, fields, and conditions from
+the [dashboard](/reference/dashboard/experiences) alone.
+
+## Preview mode
+
+After you [enter preview mode from the dashboard](/reference/dashboard/workspaces#preview), the SDK
+receives a preview token and starts preview mode:
+
+- The plugin reads fresh options from the API with that token. It bypasses the
+  build-time configuration and the cached options.
+- A feature flag decision uses session storage. The decision resets when you close
+  the tab.
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — how the plugin resolves your
+  options at startup.
+- [About feature flag allocation](/explanation/feature-flag-allocation)

package/dist/docs/reference/sdk/plugins/index.md

@@ -0,0 +1,29 @@
+---
+type: reference
+layout: docs
+---
+
+# Plugins
+
+A plugin adds behaviour to the Picked client. Pass one to the `plugins` array of
+`createClient()`.
+
+| Plugin | Import | What it does |
+| --- | --- | --- |
+| [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) | `@picked/client/plugins/dynamic-experiences` | Reads the published configuration of your project at runtime and registers every experience, step, field, condition, and feature flag. |
+| [Create Experience](/reference/sdk/plugins/create-experience) | `@picked/client/plugins/create-experience` | Registers an experience, a step, and a field that you define in code. |
+| [Window Object](/reference/sdk/plugins/window-object) | `@picked/client/plugins/window-object` | Puts the client on `window.Picked`, which helps when you debug. |
+| Single Page App | `@picked/client/plugins/single-page-app` | Starts the client again on a history event. |
+| React framework | `@picked/react/plugins/framework` | Lets the client render a React component. |
+| Svelte framework | `@picked/svelte/plugins/framework` | Lets the client render a Svelte component. |
+| Devtools | `@picked/svelte/plugins/devtools` | Connects the client to the Chrome extension. |
+
+Most applications need a framework plugin and **one** of Dynamic Experiences or Create
+Experience. Dynamic Experiences puts your options in the dashboard; Create Experience
+puts them in code.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk) — where the plugins go.
+- [SDK installation](/reference/sdk) — every client option.
+- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)

package/dist/docs/{sdk → reference/sdk}/plugins/window-object.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -17,3 +18,8 @@ const client = createClient({
   plugins: [windowObjectPlugin()],
 })
 ```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [How to install the SDK](/how-to/install-the-sdk)