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

package/dist/docs/sdk/actions.md

@@ -1,82 +0,0 @@
----
-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.
-
-## Register an action
-
-Register your actions when you create the Picked client. Each key in the `actions`
-object must match an action key from the dashboard:
-
-```ts
-import { createClient } from '@picked/client'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  actions: {
-    'track-signup': () => {
-      analytics.track('signup_completed')
-    },
-    'notify': (params) => {
-      sendNotification(params)
-    },
-  },
-})
-```
-
-Each action is a function. It takes optional parameters and it usually runs a side
-effect. When the flow reaches an action node, the SDK calls the function that
-matches. The SDK then takes a branch, which depends on whether the function succeeds
-or throws. See [Success and failure branches](#success-and-failure-branches).
-
-## How actions work
-
-1. **Registration**: you register each action on the Picked client at startup.
-2. **Flow traversal**: the SDK walks the experience flow. When it reaches an action
-   node, it finds the action by its key.
-3. **Execution**: the SDK calls the function that matches and awaits it. The outcome
-   then decides which node comes next.
-4. **No block**: an action does not interrupt your visitor. The current step
-   stays on the screen while an async action runs.
-
-## Success and failure branches
-
-An action node can have a **success** branch and a **failure** branch. The SDK
-chooses the branch from the outcome of the action:
-
-- **Failure** — the action throws, or its promise rejects. The flow takes the failure
-  branch, `onFail`.
-- **Success** — the action resolves to any value: `void`, `true`, `false`, or a
-  string. A resolved `false` is a valid response and not a failure. The flow takes
-  the success branch, `onSuccess`.
-
-Keep the failure branch for a true error. Throw on the failure case, because a
-returned value never takes the `onFail` branch:
-
-```ts
-'check-eligibility': async () => {
-  const response = await fetch('/api/eligibility')
-  // Throw only when the request itself fails. That takes the failure branch.
-  if (!response.ok) throw new Error('Eligibility request failed')
-}
-```
-
-A valid negative result is not a failure. An API can return `200` with a "no", for
-example `{ serviced: false }`. Record that value as a response and branch on it with
-a condition. Do not throw:
-
-```ts
-'check-serviced-area': async ({ client, responses }) => {
-  const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
-  const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
-  // Store the outcome as a response. A later condition then takes the branch.
-  client.responses.register('is-serviced', serviced)
-}
-```
-
-An action node can also have one plain connection, with no success or failure branch.
-The flow then continues through it on either outcome.

package/dist/docs/sdk/content-security-policy.md

@@ -1,33 +0,0 @@
----
-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 options, 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](../image-optimisation-service.md) serves |
-
-## Configuration
-
-As an HTTP header:
-
-```
-Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
-```
-
-Or as a `<meta>` tag:
-
-```html
-<meta
-  http-equiv="Content-Security-Policy"
-  content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
-/>
-```

package/dist/docs/sdk/experiences.md

@@ -1,64 +0,0 @@
----
-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](./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](/sdk/ssr) and
-[Slots and Placements](/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](./plugins/create-experience). To read an experience from
-the dashboard at runtime and control it there, use the
-[Dynamic Experiences Plugin](./plugins/dynamic-experiences).
-
-## How experiences work
-
-After you register an experience, the SDK follows this flow:
-
-1. **Registration**: You register the experience on the Picked client. Use
-   `createExperiencePlugin` for an experience that you define in code. Use
-   `dynamicExperiencesPlugin` for one that you control from the dashboard.
-2. **Condition evaluation**: The SDK evaluates the `condition` of the experience with
-   the logic engine. The result decides whether a visitor sees it.
-3. **Target resolution**: The SDK searches the DOM for an element that matches a
-   selector in `targets`. Examples are `body`, `.product-page`, and `#checkout`.
-4. **Initialization**: The SDK starts the experience when the condition is `true` and
-   at least one target element is there.
-5. **Component rendering**: The SDK renders the component of the experience. It puts
-   the component into the DOM at the target and the placement that you set. A
-   placement is `before`, `after`, `append`, `prepend`, or `replace`.
-6. **Flow execution**: An experience can hold steps, fields, and conditions. A user
-   then moves through the flow. The flow checks each answer and takes a branch.

package/dist/docs/sdk/feature-allocation.md

@@ -1,161 +0,0 @@
----
-layout: docs
----
-
-# Allocation and exposure
-
-A read of the bucket of a feature flag is what allocates a visitor to that feature flag. This
-page covers when that happens and how to watch it. It also covers how to be sure that
-Picked allocates a visitor before you report on that visitor.
-
-## A registration is not a decision
-
-The SDK loads every feature flag in your project at startup, but it allocates no visitor
-then. A feature flag stays undecided until something reads its bucket. The first read runs the
-`decide` function, stores the result, and reports the decision.
-
-You therefore choose when Picked commits a visitor to a feature flag. You choose it by the
-point at which you read the feature flag.
-
-## A read of a bucket records an exposure
-
-The first read is the decision, so a read of a bucket is the moment when the visitor
-enters the test. If you read every feature flag at startup, every visitor counts as exposed
-to every test. This includes a test that the visitor never reached.
-
-:::warning
-Do not loop over every feature flag at startup to read its bucket. That commits every visitor
-to every test immediately. You then have no way to wait for the data that a decision
-needs.
-:::
-
-Read a feature flag at the point where the decision matters. That is after the cart loads,
-after the quote returns, or after you know who the visitor is.
-
-## Check a feature flag without a decision
-
-`client.features.listStore` holds every registered feature flag. Each entry reports whether
-the feature flag is decided yet, so you can check a feature flag and commit nobody:
-
-```ts
-for (const feature flag of client.features.listStore.getState()) {
-  console.log(feature flag.id, feature flag.isResolved)
-}
-```
-
-`getBucket()` behaves differently for each state:
-
-- **Resolved** — it returns `{ id, bucket }` at once. The read changes nothing.
-- **Not resolved** — it returns a promise. An `await` runs `decide` and commits the
-  visitor.
-
-`await` works for both states, so you can treat them the same way when you do intend
-to decide.
-
-## When `feature_decide` fires
-
-The SDK sends a `feature_decide` event the first time that it decides a feature flag for a
-visitor, and only then.
-
-:::warning
-On a later page load the SDK restores the decision from browser storage, and it
-sends **no event**. A visitor who returns produces no `feature_decide` event at all,
-although Picked still allocates that visitor.
-
-An integration that reads only `feature_decide` therefore reports nothing for a
-visitor who returns.
-:::
-
-Use the correct source for your question:
-
-| Question | Use |
-| --- | --- |
-| What is this visitor allocated to now? | `client.features.listStore` |
-| Did the SDK make a new decision? | `feature_decide` on `client.eventBus` |
-| Which decisions happened before I subscribed? | `client.events` |
-
-## Watch for decisions
-
-`listStore` updates each time that a feature flag resolves. It does this whether the SDK
-restored the feature flag from storage or decided it now. A watch on `listStore` therefore
-always gives you the current state:
-
-```ts
-const buckets = new Map<string, string | boolean>()
-
-client.features.listStore.watch((feature flags) => {
-  for (const feature flag of feature flags) {
-    if (!feature flag.isResolved) continue
-    buckets.set(feature flag.id, feature flag.getBucket().bucket)
-  }
-})
-```
-
-Use `feature_decide` when you need to know that the SDK *made* a decision, and not
-what the current value is. An example is your own exposure event:
-
-```ts
-client.eventBus.watch((event) => {
-  if (event.type !== 'feature_decide') return
-  analytics.track('Experiment exposure', {
-    feature flag: event.feature.id,
-    bucket: event.feature.bucket,
-  })
-})
-```
-
-An earlier event is still available when you subscribe after startup. `client.events`
-holds every event since the client started:
-
-```ts
-const earlier = client.events
-  .getState()
-  .filter((entry) => entry.payload.type === 'feature_decide')
-```
-
-## Decide before you report
-
-To be sure that the SDK decides a feature flag before a later event fires, `await` the feature flag
-first:
-
-```ts
-const feature flag = client.features.getById('quote-experiment').getState()
-
-if (feature flag) {
-  const { bucket } = await feature flag.getBucket()
-  trackViewQuote({ experiment: bucket })
-}
-```
-
-An `await` on `getBucket()` resolves the feature flag when it is undecided, and returns the
-stored value when it is decided. In both cases the bucket is known before the next
-line runs.
-
-## What Picked reports for you
-
-Read this before you build a report of your own.
-
-Every Picked analytics event carries a `feature_list` context. The context describes
-each feature flag that this visitor resolved:
-
-| Field | Description |
-| --- | --- |
-| `ab_feature` | The feature flag ID |
-| `ab_name` | The feature flag name |
-| `ab_key` | The version key, such as `v3` |
-| `ab_bucket` | The resolved bucket |
-
-Only a resolved feature flag appears there. The context therefore shows what the visitor was
-exposed to at the time when the event fired.
-
-The [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) is optional. When
-it is installed, each decision also tags the Sentry scope as
-`picked.feature.<feature flag-id>`, with the bucket as the value. You can then filter your
-errors by the variant.
-
-## Preview mode
-
-In [preview mode](/workspaces#preview) the SDK stores a decision in session storage
-and not in local storage. The decision does not stay after you close the tab, and
-Picked can allocate a preview visitor differently from a production visitor. Treat a
-preview allocation as disposable.

package/dist/docs/sdk/index.md

@@ -1,98 +0,0 @@
----
-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.
-:::
-
-## Quick start
-
-:::code-group
-
-```typescript [Browser]
-import { createClient } from '@picked/client'
-import { windowObjectPlugin } from '@picked/client/plugins/window-object'
-import { singlePageAppPlugin } from '@picked/client/plugins/single-page-app'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [windowObjectPlugin(), singlePageAppPlugin()],
-})
-
-picked.init()
-```
-
-```ts [Server]
-import { createClient } from '@picked/client'
-import { serialize } from '@picked/client/server'
-
-const client = createClient({ projectId: 'your-project-id' })
-
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-})
-```
-
-:::
-
-The `@picked/client/server` entry holds the helpers that run only on a server, such
-as `serialize()`. Those helpers make an SSR snapshot. It is a separate entry point,
-so a browser bundle never holds it. See [Server-Side Rendering](/sdk/ssr).
-
-:::tip
-In a browser, you can reach the Picked client from the console with `window.Picked`.
-:::
-
-## 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 flag reads the bucket of that flag,
-and that allocates the visitor at that moment. A precondition runs at startup.
-Picked therefore allocates every visitor to a flag that a precondition points at,
-before anything else happens. This includes a visitor who never reaches the
-experience that the flag controls.
-
-See [Allocation and exposure](/sdk/feature-allocation) before you point a
-precondition at a flag.
-:::
-
-See [conditions](./conditions.md) for more detail.

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

@@ -1,84 +0,0 @@
----
-layout: docs
----
-
-# Dynamic Experiences Plugin
-
-This plugin reads the options of your project from the Picked API at runtime. You can
-therefore control your experiences, feature flags, steps, fields, and conditions from
-the [dashboard](/experiences) alone.
-
-## Set the plugin up
-
-:::code-group
-
-```ts [app.ts]
-import { createClient } from '@picked/client'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  plugins: [dynamicExperiencesPlugin()],
-})
-
-client.start()
-```
-
-:::
-
-:::tip
-With [`createExperiencePlugin`](./create-experience.md) you define an experience, a
-step, and a field in code. With this plugin you do not. You control every option from
-the [Picked dashboard](/experiences).
-:::
-
-## How it works
-
-When the client starts, the plugin resolves the options of your project. It tries
-three sources, in this order:
-
-1. **Preview mode** — after you [enter preview mode from the dashboard](/workspaces#preview),
-   the plugin reads fresh options from the API. A feature flag decision then uses
-   session storage, so it does not stay after you close the tab.
-
-2. **Build-time options** — the plugin uses the options that it has already, and
-   makes no network request. This applies in two cases. You pass `projectConfig` as a
-   plugin option, or the [Vite Plugin](/vite-plugin) injects the options at build
-   time.
-
-3. **Runtime read** — in every other case, the plugin reads the options from the API
-   when the client starts.
-
-After the options resolve, the plugin registers every feature flag, condition, field,
-step, and experience on the client. Each experience then starts, and its
-[conditions](/sdk/conditions) and [target selectors](/sdk/experiences) decide
-whether it does.
-
-:::note
-The [Vite Plugin](/vite-plugin) embeds the options of your project at build time. In
-production there is therefore no API request at runtime. This is the recommended
-setup for an application that uses Vite.
-:::
-
-## Feature flag allocation
-
-Each [feature flag](/sdk/features) in your project has an `enabled` state and a
-`weight` from 0 to 100. The weight controls what percentage of your traffic Picked
-allocates to the flag.
-
-The plugin makes a deterministic hash from the session ID of the user, and that gives
-a stable allocation value. Picked allocates a user whose value is below the weight of
-the flag. The same user always gets the same result.
-
-The plugin caches a feature flag decision in `localStorage` by default. In
-[preview mode](#preview-mode) it uses `sessionStorage`.
-
-## Preview mode
-
-After you [enter preview mode from the 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 options and the cached options.
-- A feature flag decision uses session storage. The decision resets when you close
-  the tab.

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

@@ -1,9 +0,0 @@
----
-layout: docs
----
-
-# Plugins
-
-[Create Experience](./create-experience.md) — Define experiences, steps, and fields in code.
-
-[Dynamic Experiences](./dynamic-experiences.md) — Fetch and register experiences from the Picked API at runtime.

package/dist/docs/sdk/predicates.md

@@ -1,128 +0,0 @@
----
-layout: docs
----
-
-# Predicates
-
-A predicate holds reusable condition logic that reads the current state of your
-application. Each predicate is a pure function. It takes a state snapshot, and that
-snapshot holds the responses, the fields, the browser context, and optional
-arguments.
-
-## Define a predicate
-
-Define your predicates when you create the Picked client. Pass a `predicates` object.
-Each predicate needs a unique identifier and a function that takes a state snapshot:
-
-```ts
-import { createClient } from '@picked/client'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  predicates: {
-    'is-example-page': ({ location }) => {
-      return location?.pathname === '/example'
-    },
-    'get-account-tier': async () => {
-      const data = await fetch('/api/get-account-tier').then((r) => r.json())
-      return data.result // Returns "trial".
-    },
-  },
-})
-```
-
-## How predicates work
-
-After you register a predicate and a condition uses it, the SDK follows this flow:
-
-1. **Registration**: you register each predicate on the Picked client at startup.
-2. **State snapshot**: the SDK gives the predicate a frozen state snapshot. The
-   snapshot holds the current responses, the fields, and the browser context.
-3. **Condition evaluation**: an experience condition invokes the predicate with a
-   fresh snapshot on each call.
-4. **Return types**: a predicate can return a boolean, a string, an array of
-   strings, or `undefined`. It can also return a promise that resolves to one of
-   those.
-
-## Use a predicate in a condition
-
-Most predicates are used inside condition logic, through the `invoke` operator:
-
-```ts
-const myExperience = createExperience({
-  // ... other config
-  condition: {
-    and: [
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.is-example-page', // Points at a predicate that calls your endpoint.
-            },
-          },
-          true, // Check that the return value is true.
-        ],
-      },
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.account-tier',
-            },
-          },
-          '/trial', // The condition is true when the string matches.
-        ],
-      },
-    ],
-  },
-})
-```
-
-:::tip
-You can also use a predicate in `validation` logic.
-:::
-
-## Use the state snapshot
-
-Each predicate takes a `StateSnapshot` object with these properties:
-
-```ts
-interface StateSnapshot {
-  client: Picked // The Picked client.
-  responses?: Array<{
-    // Every response from the user.
-    fieldId: string
-    value: FieldValue | undefined
-  }>
-  args?: unknown[]
-  fields?: Field[] // Every registered field.
-  location?: Location // The browser location: URL, pathname, search, and more.
-  document?: Document // The browser document object.
-  sessionStorage?: Storage // The browser sessionStorage API.
-  localStorage?: Storage // The browser localStorage API.
-}
-```
-
-:::warning
-In server-side rendering, and in any environment that is not a browser, `location`,
-`document`, `sessionStorage`, and `localStorage` are `undefined`.
-:::
-
-## Best practices
-
-- **Keep each predicate pure**: a predicate must be deterministic and free of side
-  effects. The same snapshot must always give the same result.
-- **Handle missing data**: check that a response or a field is there before you read
-  its value. Return `undefined` when the data is not available. Do not throw.
-- **Do not do heavy work**: the SDK can invoke a predicate many times. Keep the logic
-  small and fast.
-- **Use an async predicate only when you must**: the SDK supports one, but it can
-  make the experience slow to appear. Use synchronous logic where you can.
-- **Return one type**: do not return a boolean from a predicate one time and a string
-  the next.
-- **Use a meaningful name**: a predicate ID must say what the predicate evaluates,
-  such as `is-premium-user` or `has-items-in-cart`.
-- **Keep the result of expensive work**: when a predicate must do expensive work, put
-  the result in `localStorage` or `sessionStorage` inside the predicate.
-- **Do not change the snapshot**: the state snapshot is frozen. A change to it throws
-  an error in strict mode.