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

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

@@ -0,0 +1,84 @@
+---
+layout: docs
+---
+
+# Virtual functions
+
+Virtual functions are shorthand for aggregate expressions. They are **table-aware** — the same function expands differently on `metrics` (pre-aggregated) vs `events` (user-level).
+
+## A/B test metrics
+
+| Function | Description |
+|---|---|
+| `control_users()` | Unique users in the Control group |
+| `variant_users()` | Unique users in the Variant group |
+| `all_users()` | All unique users |
+| `control_sessions()` | Unique sessions in the Control group |
+| `variant_sessions()` | Unique sessions in the Variant group |
+| `all_sessions()` | All unique sessions |
+
+## Conversion metrics
+
+| Function | Description |
+|---|---|
+| `total_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) |
+| `total_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
+| `total_purchase_orders()` | Unique order count (`metrics` only) |
+| `total_cart_add_users()` | Users who added to cart |
+
+## Conversion rates
+
+| Function | Description |
+|---|---|
+| `control_conversion_rate()` | Purchase conversion rate for Control (purchase users / total users) |
+| `variant_conversion_rate()` | Purchase conversion rate for Variant |
+| `conversion_rate_uplift()` | Relative improvement: `(variant CR - control CR) / control CR` |
+
+## 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
+Funnel metrics are being continuously updated. Check back for new functions.
+:::
+
+| Function | Description |
+|---|---|
+| `step_enter_users()` | Users who entered a funnel step |
+| `step_enter_sessions()` | Sessions that entered a funnel step |
+
+## Feature functions (`features` / `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 |
+
+```sql
+-- Compare feature buckets
+SELECT
+  feature_users('homepage_test', 'control') AS control,
+  feature_users('homepage_test', 'variant') AS variant
+FROM features
+
+-- With feature key filter
+SELECT feature_users('homepage_test', 'control', 'v1') FROM features
+```
+
+## Other (`metrics` only)
+
+| Function | Description |
+|---|---|
+| `event_count()` | Total event count (from pre-aggregation) |

package/dist/docs/projects.md

@@ -0,0 +1,30 @@
+---
+layout: docs
+---
+
+# Projects
+
+A project represents one website or app you want to instrument with Picked. Each project has its own set of experiences, entities, and configuration.
+
+## Create a project
+
+You need an organization first. If you don't have one, create it when you sign up.
+
+1. Open your organization.
+2. Click **New Project**.
+3. Enter a name.
+4. Click **Create**.
+
+## Workspaces
+
+Each project contains one or more [Workspaces](/workspaces) for configuring and previewing experiences before publishing.
+
+## Project home
+
+When you open a project, you land on the project home page. It shows your SDK installation snippet and a getting-started checklist.
+
+Copy the snippet and add it to your site. This connects your site to the project and enables experience delivery. See [SDK Installation](/sdk) for setup details.
+
+## Project navigation
+
+The sidebar shows all sections available in your project: **Experiences**, **Fields**, **Steps**, **Actions**, **Conditions**, and more. Some sections appear only when enabled for your account.

package/dist/docs/reference/index.md

@@ -0,0 +1,11 @@
+---
+layout: docs
+---
+
+# Reference
+
+Typedoc Reference
+
+## Getting Started
+
+Coming soon

package/dist/docs/reports.md

@@ -0,0 +1,11 @@
+---
+layout: docs
+---
+
+# Reports
+
+Reports show analytics data for your project. Track how visitors interact with your experiences and features.
+
+## View report data
+
+Open a report to see its analytics. Data updates as new visitor interactions are recorded.

package/dist/docs/sdk/actions.md

@@ -0,0 +1,7 @@
+---
+layout: docs
+---
+
+# Actions
+
+Coming Soon...

package/dist/docs/sdk/conditions.md

@@ -0,0 +1,131 @@
+---
+layout: docs
+---
+
+# Conditions
+
+Conditions evaluate of the current state of the Picked client to decide outcomes as defined by the user. Conditions are `JsonLogic`, which will always return the same result given the same input.
+
+## Conditions in Experiences
+
+A common method of navigating a Funnel Experiences is using conditions between steps. The condition will evaludate values from the Picked state, and navigation the user based on a boolean value
+
+```ts
+const questionaireFunnel = createExperience({
+  id: 'mini-funnel',
+  // experience config
+})
+
+const userInformationStep = funnel.addStep({
+  fields: ['email-address-field', 'sign-up-for-newsletter-field'],
+})
+const signUserUpToNewsletter = funnel.addStep({
+  // step config
+})
+const userDoesNotWantNewsletter = funnel.addStep({
+  // step config
+})
+
+const isSigningUpForNewsletter = funnel.addConditional({
+  condition: {
+    '==': [
+      {
+        var: 'responses.sign-up-for-newsletter-field', // check if response value for the field is true
+      },
+      true,
+    ],
+  },
+})
+
+userInformationStep.nextConditional(isSigningUpForNewsletter)
+
+isSigningUpForNewsletter.addTrue(signUserUpToNewsletter)
+isSigningUpForNewsletter.addFalse(userDoesNotWantNewsletter)
+```
+
+## Conditional Fields
+
+Fields can be shown or hidden based on previous responses or predicates using JSON Logic conditions:
+
+```ts
+// Show email field only if user selected "email" as a contact method
+export const emailField = createField({
+  id: 'email-input',
+  name: 'email-input',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  condition: {
+    in: [
+      'email',
+      {
+        var: 'responses.communication-methods', // Reference previous field
+      },
+    ],
+  },
+})
+
+// Show field based on predicate
+export const mailingAddressField = createField({
+  id: 'mailing-address',
+  name: 'mailing-address',
+  type: 'text',
+  label: 'Mailing Address',
+  multiple: false,
+  required: true,
+  condition: {
+    '==': [
+      {
+        invoke: {
+          var: 'predicates.user-allows-mail',
+        },
+      },
+      true,
+    ],
+  },
+})
+```
+
+## Field Options with Conditions
+
+Individual options within a field can also have conditional visibility:
+
+```ts
+export const contactMethodsField = createField({
+  id: 'contact-methods',
+  name: 'contact-methods',
+  type: 'text',
+  label: 'How should we contact you?',
+  multiple: true,
+  required: true,
+  options: [
+    {
+      id: 'email',
+      label: 'Email',
+      value: 'email',
+    },
+    {
+      id: 'phone',
+      label: 'Phone',
+      value: 'phone',
+    },
+    {
+      id: 'mail',
+      label: 'Postal Mail',
+      value: 'mail',
+      // Only show this option if user has a verified address
+      condition: {
+        '==': [
+          {
+            invoke: {
+              var: 'predicates.has-verified-address',
+            },
+          },
+          true,
+        ],
+      },
+    },
+  ],
+})
+```

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

@@ -0,0 +1,31 @@
+---
+layout: docs
+---
+
+# Content Security Policy
+
+The Picked SDK makes outbound HTTPS requests to the following domains. Add them to your `connect-src` directive.
+
+## Required domains
+
+| Domain | Purpose |
+| --- | --- |
+| `api.picked.app` | API requests — project configuration, experiences, session tracking |
+| `evnts.pckd.dev` | Analytics event collection (Snowplow) |
+
+## Configuration
+
+As an HTTP header:
+
+```
+Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev;
+```
+
+Or as a `<meta>` tag:
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev;"
+/>
+```

package/dist/docs/sdk/experiences.md

@@ -0,0 +1,41 @@
+---
+layout: docs
+---
+
+# Experiences
+
+Experiences enable you to conditionally show UI components in your application based on custom logic. Each experience defines a component to render, where to inject it in the DOM, and an optional condition that controls when it appears. Experiences support multi-step flows with fields and branching logic, making them ideal for onboarding, surveys, and interactive product tours
+
+## Creating Experiences
+
+```ts
+import { createExperience } from '@picked/client/plugins/create-experience'
+
+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],
+  }),
+})
+```
+
+## How Experiences Work
+
+When an experience is registered, the SDK follows this execution flow:
+
+1. **Registration**: Experiences are registered to the Picked client using [createExperiencePlugin](./plugins/create-experience.md) for code-defined experiences, or [dynamicExperiencesPlugin](./plugins/dynamic-experiences.md) for dashboard-managed experiences
+2. **Condition Evaluation**: The SDK evaluates the experience's `condition` using the logic engine to determine if it should be shown
+3. **Target Resolution**: The SDK searches the DOM for elements matching the `targets` selectors (e.g., `body`, `.product-page`, `#checkout`)
+4. **Initialization**: If the condition evaluates to `true` and at least one target element exists, the experience is initialized
+5. **Component Rendering**: The experience's component is rendered and injected into the DOM at the specified target location and placement (before, after, append, prepend, or replace)
+6. **Flow Execution**: If the experience contains steps, fields, and conditionals, users can progress through the multi-step flow with validation and branching logic

package/dist/docs/sdk/features.md

@@ -0,0 +1,213 @@
+---
+layout: docs
+---
+
+# Features
+
+Features enable A/B testing and feature flagging in your application. Each feature defines decision logic that resolves to a `bucket` as either a boolean value (`true`/`false`) or a string value (like `"control"`, `"variant-a"`, or `"variant-b"`). Once a feature is decided, the result is cached in browser storage to ensure consistent user experiences across sessions.
+
+## Defining Features
+
+Define features when creating the Picked client by passing a `features` object. Each feature requires a unique identifier, a versioning key, a human-readable name, and a `decide` function:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  organizationId: 'your-org-id',
+  projectId: 'your-project-id',
+  features: {
+    'summer-sale': {
+      key: 'summer-sale-v1', // Version key - change to invalidate cache
+      name: 'Summer Sale Experiment', // Human-readable name for analytics
+      decide: async () => {
+        // Your decision logic here
+        const isEligible = await checkUserEligibility()
+        return isEligible // Returns boolean
+      },
+      storage: 'local', // Optional: 'local' (default) or 'session'
+    },
+    'homepage-variant': {
+      key: 'homepage-test-v2',
+      name: 'Homepage A/B Test',
+      decide: async () => {
+        // Return string for multi-variant tests
+        return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
+      },
+    },
+  },
+})
+```
+
+Features can also be defined as factory functions for lazy initialization:
+
+```ts
+features: {
+  'my-feature': () => ({
+    key: 'my-feature-v1',
+    name: 'My Feature',
+    decide: async () => true,
+  }),
+}
+```
+
+## How Features Work
+
+When a feature is registered, the SDK follows this execution order:
+
+1. **Registration**: Features are registered to the Picked client during initialization
+2. **Cache Check**: The SDK checks browser storage (localStorage or sessionStorage) for a previously resolved value using the feature `id` and `key`
+3. **Lazy Evaluation**: If no cached value exists, the `decide` function will be called the first time the feature is accessed
+4. **Storage**: Once resolved, the bucket value is persisted to browser storage for consistency across page loads
+5. **Event Emission**: A `feature_decide` event is fired on the event bus when a feature is resolved for the first time
+
+## URL-Based Overrides
+
+You can override feature decisions via URL search parameters for testing purposes:
+
+```
+https://example.com?picked-feature=my-feature:true
+```
+
+Multiple overrides can be specified:
+
+```
+https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
+```
+
+The format is `?picked-feature=<feature-id>:<bucket-value>`.
+
+This is useful for QA testing specific feature variants without modifying code. The override is persisted in session storage and will be cleared when the browser tab is closed.
+
+## Accessing Features
+
+Once features are defined, you can access their resolved bucket values in your application code. The SDK provides framework-specific hooks and a framework-agnostic event bus for subscribing to feature decisions.
+
+:::code-group
+
+```ts [Vanilla JS]
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  /* Create client options here */
+})
+
+client.eventBus.subscribe('feature_decide', ({ feature }) => {
+  if (feature.id === 'my-feature') {
+    console.log(feature) // { id: 'my-feature', bucket: 'control' }
+  }
+})
+```
+
+```ts [Svelte]
+<script lang="ts">
+  import { getFeature } from '@picked/svelte/hooks'
+  // Returns an Effector store containing the feature resolver
+  const myFeature = getFeature('my-feature')
+</script>
+<!-- $myFeature is a reactive Effector store (see Effector docs for details) -->
+{#if $myFeature()}
+  <p>My feature is enabled</p>
+{:else}
+  <p>My feature is disabled</p>
+{/if}
+```
+
+```ts [React]
+import { useFeature } from '@picked/react/hooks'
+
+function MyComponent() {
+  // Returns the resolved bucket value for 'my-feature'
+  const myFeature = useFeature('my-feature')
+
+  return (
+    <div>
+      {myFeature === 'control' && <p>Control variant</p>}
+      {myFeature === 'variant-a' && <p>Variant A</p>}
+    </div>
+  )
+}
+
+```
+
+:::
+
+## Using Features in Experience Conditions
+
+Features can be used with experience conditions via JSON logic:
+
+```ts
+const myExperience = createExperience({
+  // ... other config
+  condition: {
+    and: [
+      {
+        '==': [
+          {
+            invoke: {
+              var: 'features.summer-sale', // Reference feature by ID
+            },
+          },
+          true, // Check if bucket equals true
+        ],
+      },
+    ],
+  },
+})
+```
+
+## Listening to Feature Decisions
+
+Subscribe to the `feature_decide` event to track when features are resolved:
+
+```ts
+client.eventBus.subscribe('feature_decide', ({ feature }) => {
+  console.log(`Feature "${feature.id}" resolved to bucket:`, feature.bucket)
+  // Example output: Feature "summer-sale" resolved to bucket: true
+
+  // Send to analytics
+  analytics.track('Feature Decision', {
+    featureId: feature.id,
+    bucket: feature.bucket,
+  })
+})
+```
+
+## Versioning and cache invalidation
+
+Feature decisions are cached in browser storage (localStorage or sessionStorage) using a key derived from the feature ID and version. This ensures visitors see a consistent experience across page loads.
+
+### How versioning works
+
+When you create a feature in the dashboard, it starts at version 1. The SDK uses the version to build the cache key — for example, a feature at version 3 uses the key `v3`. This version is also included in the allocation hash, so it directly affects which variant a visitor is assigned to.
+
+### What happens when the version is incremented
+
+When you increment a feature's version in the dashboard:
+
+1. **Cache keys change.** The old cache entry (e.g., `v3`) no longer matches the new key (`v4`), so the SDK treats the feature as undecided.
+2. **All visitors are re-allocated.** The allocation hash includes the version, so every visitor gets a new hash value and may be assigned to a different variant.
+3. **The `decide` function runs again.** On the next page load, the SDK calls `decide()` fresh and caches the new result.
+
+> **Warning:** Incrementing the version re-allocates all visitors, not just new ones. This is irreversible. Only increment when you intentionally want to reset all assignments — for example, after changing traffic allocation weights.
+
+### SDK `key` vs dashboard version
+
+If you define features statically in the SDK (not loaded from the dashboard), use the `key` field for manual versioning:
+
+```ts
+features: {
+  'summer-sale': {
+    key: 'summer-sale-v2', // Change to invalidate cache
+    // ...
+  },
+}
+```
+
+For features managed through the dashboard, versioning is handled automatically — the dashboard appends the version number to the cache key used by the SDK.
+
+## Best Practices
+
+- **Use `session` storage for temporary tests**: Set `storage: 'session'` for short-lived experiments that shouldn't persist across browser sessions
+- **Keep `decide` functions fast**: The function blocks experience rendering, so avoid heavy computations or slow network calls
+- **Return consistent types**: Don't mix boolean and string returns for the same feature - pick one type and stick with it