@picked/client 0.0.56-next.1 → 0.0.56

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

package/dist/docs/sdk/fields.md

@@ -0,0 +1,263 @@
+---
+layout: docs
+---
+
+# Fields
+
+Fields are used to store data for a Picked instance. Fields can be added to steps or forms and rendered as inputs, or have their values directly set.
+
+## Defining Fields
+
+Define fields using `createField()` from the `@picked/client/plugins/create-experience` package. Each field requires a unique identifier, name, type, label, and cardinality:
+
+```ts
+import { createField } from '@picked/client/plugins/create-experience'
+
+// Required text input
+export const emailField = createField({
+  id: 'email-address',
+  name: 'email-address',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  placeholder: 'you@example.com',
+})
+
+// Multi-select dropdown with static options
+export const communicationMethods = createField({
+  id: 'communication-methods',
+  name: 'communication-methods',
+  type: 'text',
+  label: 'Preferred contact methods',
+  multiple: true,
+  required: true,
+  options: [
+    {
+      id: 'email',
+      label: 'Email',
+      value: 'email',
+    },
+    {
+      id: 'phone',
+      label: 'Phone',
+      value: 'phone',
+    },
+    {
+      id: 'sms',
+      label: 'SMS',
+      value: 'sms',
+    },
+  ],
+})
+```
+
+## How Fields Work
+
+When a field is registered and used in an experience:
+
+1. **Registration**: Fields are registered to the experience during step creation via `.addField()`
+2. **Condition Evaluation**: If the field has a `condition`, it's evaluated against the current context to determine visibility
+3. **Rendering**: Visible fields are rendered in the experience UI with their label, placeholder, and options
+4. **User Input**: User enters or selects a value, triggering client-side validation if specified
+5. **Storage**: Valid responses are stored in the experience state under `responses[field.name]`
+6. **Reference**: Field values can be referenced in subsequent field conditions, step conditions, or experience logic via `{ var: 'responses.field-name' }`
+
+## Field Types
+
+Fields support four primitive types, `text`, `number`, `boolean` and `object`:
+
+```ts
+// Single text input
+const nameField = createField({
+  type: 'text',
+  multiple: false,
+  // ...
+})
+```
+
+Provide an `options` array to allow multiple select:
+
+```ts
+const nameField = createField({
+  type: 'text',
+  multiple: true,
+  options: [
+    {
+      id: 'option-one',
+      label: 'Option One',
+      value: 'product-id-one',
+    },
+    {
+      id: 'option-two',
+      label: 'Option Two',
+      value: 'product-id-two',
+    },
+    {
+      id: 'option-three',
+      label: 'Option Three',
+      value: 'product-id-three',
+    },
+  ],
+})
+```
+
+## Conditions
+
+Fields and field options are compatible with condition logic:
+
+```ts
+const conditionalField = createField({
+  id: 'conditional-field',
+  type: 'text',
+  condition: {
+    invoke: {
+      var: 'responses.has-answered-question',
+    },
+  },
+  options: [
+    {
+      id: 'conditional-option',
+      label: 'Conditional Label',
+      condition: {
+        invoke: {
+          var: 'responses.eligible-for-option',
+        },
+      },
+    },
+  ],
+})
+```
+
+## Field Validation
+
+Validate user input using JSON Logic rules. The `$input` variable contains the current field value:
+
+```ts
+const quantityField = createField({
+  id: 'quantity',
+  name: 'quantity',
+  type: 'number',
+  label: 'Quantity',
+  multiple: false,
+  required: true,
+  validation: {
+    catch: {
+      or: [
+        {
+          and: [
+            {
+              // Input value is above 0
+              '>': [
+                {
+                  var: '$input',
+                },
+                0,
+              ],
+            },
+            {
+              // Input value is equal or below 999
+              '<=': [
+                {
+                  var: '$input',
+                },
+                999,
+              ],
+            },
+          ],
+        },
+        {
+          throw: 'Please enter a value between 1 and 999',
+        },
+      ],
+    },
+  },
+})
+```
+
+:::tip
+The `catch`/`throw` pattern in JSON Logic validates that the condition evaluates to `true`. If it doesn't, the `throw` message is displayed to the user.
+:::
+
+## Field Policies
+
+Control how field data is tracked and stored using privacy policies:
+
+```ts
+const sensitiveField = createField({
+  id: 'ssn',
+  name: 'ssn',
+  type: 'text',
+  label: 'Social Security Number',
+  multiple: false,
+  required: true,
+  policies: {
+    doNotTrackValue: true, // Don't send value to analytics
+    doNotStoreValue: true, // Don't persist value to backend
+  },
+})
+```
+
+**Privacy policies**:
+
+- `doNotTrackValue`: Excludes field value from analytics events (only field ID is tracked)
+- `doNotStoreValue`: Prevents field value from being persisted to backend storage
+
+Use these policies for sensitive data like SSNs, credit cards, or passwords that should only exist client-side.
+
+## Field Metadata
+
+Enhance user experience with additional descriptive text:
+
+```ts
+const passwordField = createField({
+  id: 'password',
+  name: 'password',
+  type: 'text',
+  label: 'Password',
+  multiple: false,
+  required: true,
+  placeholder: 'Enter a strong password',
+  description: 'Your password must be at least 8 characters',
+  helpText: 'Use a mix of letters, numbers, and symbols for better security',
+})
+```
+
+**Metadata fields**:
+
+- `placeholder`: Hint text displayed in empty input fields
+- `description`: Brief explanation shown below the label
+- `helpText`: Additional guidance or requirements displayed near the field
+
+## Accessing Field Values
+
+Field responses are stored in the experience state and can be accessed via the `responses` object:
+
+:::code-group
+
+```ts [In Conditions]
+// Reference in subsequent field conditions
+const sensitiveField = createField({
+  condition: {
+    '==': [
+      {
+        var: 'responses.field-name',
+      },
+      'expected-value',
+    ],
+  },
+})
+```
+
+:::
+
+## Best Practices
+
+- **Use semantic IDs and names**: Name fields descriptively (e.g., `email-address` not `field1`) for easier debugging and analytics
+- **Match type to data**: Use `number` for numeric values, not `text`, to enable proper validation and comparison
+- **Set appropriate `required` flags**: Only mark fields as required when truly necessary to reduce form abandonment
+- **Keep validation messages clear**: Error messages should tell users exactly how to fix the input
+- **Use conditional fields for progressive disclosure**: Show fields only when relevant based on prior responses
+- **Apply privacy policies to sensitive data**: Use `doNotTrackValue` and `doNotStoreValue` for PII, passwords, or financial data
+- **Provide helpful metadata**: Add `placeholder` and `description` to guide users, especially for complex or formatted inputs
+- **Keep option lists scannable**: For more than 5 options, consider providing search/filter functionality or breaking into multiple steps