@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/sdk/features.md

@@ -1,212 +0,0 @@
----
-layout: docs
----
-
-# Features
-
-Define feature flags with a `decide` function that resolves to a bucket value, access results through framework hooks, and invalidate cached decisions by bumping the version.
-
-## 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({
-  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

@@ -1,263 +0,0 @@
----
-layout: docs
----
-
-# Fields
-
-Define fields in code with `createField()`, validate input with JSON Logic, and read submitted values through step context.
-
-## 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 browser storage
-  },
-})
-```
-
-**Privacy policies**:
-
-- `doNotTrackValue`: Excludes field value from analytics events (only field ID is tracked)
-- `doNotStoreValue`: Prevents field value from being persisted to browser 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

package/dist/docs/sdk/index.md

@@ -1,83 +0,0 @@
----
-layout: docs
----
-
-# Picked SDK
-
-The Picked SDK enables you to add dynamic, personalized experiences to your web applications with minimal code.
-
-:::tip
-The SDK is framework-agnostic and works with React, Svelte, Vue, and vanilla 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 server-only helpers, such as `serialize()`, that produce an SSR snapshot. It is a separate entry point so browser bundles never include it. See [Server-Side Rendering](/sdk/ssr).
-
-:::tip
-If you’re running Picked in a browser environment, access the Picked client in the console with `window.Picked`
-:::
-
-## Precondition & Condition
-
-| Category     | Question               | Description                                                                                   |
-| ------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
-| Precondition | Should Picked start?   | Use for environment checks, page filtering, or feature flags that completely disable the SDK. |
-| Condition    | Is this user eligible? | Use for user segmentation, A/B test enrollment, or targeting specific user groups.            |
-
-```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',
-    },
-  },
-  // rest of picked config
-})
-```
-
-See [conditions](./conditions.md) for more detail

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

@@ -1,58 +0,0 @@
----
-layout: docs
----
-
-# Dynamic Experiences Plugin
-
-A plugin that fetches your project configuration from the Picked API at runtime, letting you manage experiences, features, steps, fields, and conditions entirely from the [dashboard](/experiences).
-
-## Setup Plugin
-
-:::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
-Unlike [createExperiencePlugin](./create-experience.md), you do not define experiences, steps, or fields in code. All configuration is managed from the [Picked dashboard](/experiences).
-:::
-
-## How It Works
-
-When the client starts, the plugin resolves your project configuration using a three-tier strategy:
-
-1. **Preview mode** — When you [enter preview mode from the dashboard](/workspaces#preview), the plugin fetches fresh config from the API. Feature decisions use session storage so they are not persisted beyond the current tab.
-
-2. **Build-time config** — If `projectConfig` was passed as a plugin option, or the [Vite Plugin](/vite-plugin) injected config at build time, the plugin uses that config with no network request.
-
-3. **Runtime fetch** — Otherwise, the plugin fetches config from the API when the client starts.
-
-Once resolved, the plugin registers all features, conditions, fields, steps, and experiences with the client. Experiences then initialize according to their [conditions](/sdk/conditions) and [target selectors](/sdk/experiences).
-
-:::note
-The [Vite Plugin](/vite-plugin) eliminates the runtime API request in production by embedding your project config at build time. This is the recommended setup for Vite-based applications.
-:::
-
-## Feature Allocation
-
-Each [feature](/sdk/features) in your project has an `enabled` state and a `weight` (0–100) that controls the percentage of traffic allocated to it. The plugin uses a deterministic hash of the user's session ID to produce a stable allocation value. A user whose value falls below the feature weight is allocated to that feature — the same user always gets the same result.
-
-Feature decisions are cached in `localStorage` by default, or `sessionStorage` when in [preview mode](#preview-mode).
-
-## Preview Mode
-
-When you [enter preview mode from the dashboard](/workspaces#preview), the SDK receives a preview token and activates preview mode:
-
-- The plugin fetches fresh config from the API using the token, bypassing any build-time or cached config
-- Feature decisions use session storage, so closing the tab resets them

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.