@picked/client 0.0.55 → 0.0.56-next.2

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

package/dist/docs/sdk/index.md

@@ -0,0 +1,74 @@
+---
+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({
+  organizationId: 'your-organization-id',
+  projectId: 'your-project-id',
+  plugins: [windowObjectPlugin(), singlePageAppPlugin()],
+})
+
+picked.init()
+```
+
+```ts [Server]
+Coming Soon...
+```
+
+:::
+
+:::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/create-experience.md

@@ -0,0 +1,133 @@
+---
+layout: docs
+---
+
+# Create Experience Plugin
+
+A plugin to register an array of experiences to the Picked client.
+
+## Setup Plugin
+
+:::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({
+  organizationId: 'your-org-id',
+  projectId: 'your-project-id',
+  plugins: createExperiencePlugin({
+    experiences: [funnelExperience, widgetExperience],
+  }),
+})
+```
+
+:::
+
+## Defining Steps
+
+Steps are defined using `createStep()`. They are added directly to an experience using `experience.addStep()`.
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+
+// Define standalone steps
+const welcomeStep = createStep({
+  id: 'welcome',
+  name: 'Welcome',
+})
+
+const contactStep = createStep({
+  id: 'contact',
+  name: 'Contact Details',
+})
+
+// Define the experience and add steps to build the flow
+const onboardingExperience = createExperience({
+  id: 'onboarding',
+  name: 'User Onboarding',
+  targets: [{ selector: 'body', placement: 'after' }],
+})
+
+onboardingExperience.addStep(welcomeStep)
+onboardingExperience.addStep(contactStep)
+```
+
+Each step requires a `name` that identifies it in analytics events. An `id` is optional — one will be generated automatically if omitted.
+
+Steps can be used on multiple experiences.
+
+### Adding Fields to Steps
+
+Fields are defined with `createField()`.
+
+```ts
+import { createStep, createField } from '@picked/client/plugins/create-experience'
+
+const emailField = createField({
+  id: 'email-address',
+  name: 'email-address',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  placeholder: 'you@example.com',
+})
+```
+
+Fields are added to a step with `step.addField()`, or an array of `fieldIds` when creating a step:
+
+```ts
+const contactStep = createStep({
+  id: 'contact',
+  label: 'Contact Details',
+})
+
+contactStep.addField(emailField)
+
+//Or
+
+const contactStep = createStep({
+  id: 'contact',
+  label: 'Contact Details',
+  fieldIds: [contactStep.id],
+})
+```
+
+## Using conditions in an experience
+
+[Conditions](../conditions) are used to define when an experience will become active for the user.
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+
+const productPageFunnel = createExperience({
+  id: 'product-page-funnel',
+  name: 'Product Page Funnel',
+  condition: {
+    and: [
+      {
+        '==': [
+          {
+            var: 'location.pathname',
+          },
+          '/product/:id',
+        ],
+      },
+      {
+        var: 'actions.isSaleActive',
+      },
+    ],
+  },
+  targets: [{ selector: 'body', placement: 'after' }],
+})
+```
+
+Navigation between steps is handled with [conditions](../conditions). Use the `create`
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+```

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

@@ -0,0 +1,59 @@
+---
+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({
+  organizationId: 'your-org-id',
+  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](/tooling/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](/tooling/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

@@ -0,0 +1,9 @@
+---
+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/plugins/window-object.md

@@ -0,0 +1,20 @@
+---
+layout: docs
+---
+
+# Window Object
+
+A plugin to add the Picked client to the window object
+
+## Setup Plugin
+
+```ts
+import { createClient } from '@picked/client'
+import { windowObjectPlugin } from '@picked/client/plugins/window-object'
+
+const client = createClient({
+  organizationId: 'your-org-id',
+  projectId: 'your-project-id',
+  plugins: [windowObjectPlugin()],
+})
+```

package/dist/docs/sdk/predicates.md

@@ -0,0 +1,113 @@
+---
+layout: docs
+---
+
+# Predicates
+
+Predicates enable reusable condition logic based on current application state. Each predicate is a pure function that receives a state snapshot containing responses, fields, browser context, and optional arguments.
+
+## Defining Predicates
+
+Define predicates when creating the Picked client by passing a `predicates` object. Each predicate requires a unique identifier and a function that receives a state snapshot:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  organizationId: 'your-org-id',
+  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
+
+When a predicate is registered and used in conditions, the SDK follows this execution flow:
+
+1. **Registration**: Predicates are registered to the Picked client during initialization
+2. **State Snapshot Creation**: When invoked, predicates receive a frozen state snapshot containing current responses, fields, and browser context
+3. **Condition Evaluation**: Experience conditions invoke predicates with a fresh snapshot whenever called
+4. **Return Flexibility**: Predicates can return boolean, string, string array, undefined, or promises that resolve to these types
+
+## Using Predicates in Conditions
+
+Predicates are most commonly used within condition logic via the `invoke` operator:
+
+```ts
+const myExperience = createExperience({
+  // ... other config
+  condition: {
+    and: [
+      {
+        '==': [
+          {
+            invoke: {
+              var: 'predicates.is-example-page', // Reference predicate that calls user endpoint
+            },
+          },
+          true, // Check if return value is true
+        ],
+      },
+      {
+        '==': [
+          {
+            invoke: {
+              var: 'predicates.account-tier',
+            },
+          },
+          '/trial', // If string matches, evaluate to true
+        ],
+      },
+    ],
+  },
+})
+```
+
+:::tip
+Predicates can also be used in `validation` logic
+:::
+
+## Using the State Snapshot
+
+Each predicate receives a `StateSnapshot` object with the following properties:
+
+```ts
+interface StateSnapshot {
+  client: Picked // The Picked client instance
+  responses?: Array<{
+    // All user responses
+    fieldId: string
+    value: FieldValue | undefined
+  }>
+  args?: unknown[]
+  fields?: Field[] // All registered fields
+  location?: Location // Browser location (URL, pathname, search, etc.)
+  document?: Document // Browser document object
+  sessionStorage?: Storage // Browser sessionStorage API
+  localStorage?: Storage // Browser localStorage API
+}
+```
+
+:::warning
+In server-side rendering or non-browser environments, `location`, `document`, `sessionStorage`,
+and `localStorage` will be `undefined`.
+:::
+
+## Best Practices
+
+- **Keep predicates pure**: Predicates should be deterministic and side-effect free. Given the same snapshot, they should always return the same result
+- **Handle missing data gracefully**: Always check if responses or fields exist before accessing their values. Return `undefined` when data is unavailable rather than throwing errors
+- **Avoid heavy computations**: Predicates may be invoked frequently. Keep logic lightweight and fast
+- **Use async sparingly**: While async predicates are supported, they can delay experience rendering. Prefer synchronous logic when possible
+- **Return consistent types**: Don't mix return types (e.g., sometimes boolean, sometimes string) for the same predicate
+- **Use meaningful names**: Predicate IDs should clearly describe what they evaluate (e.g., `is-premium-user`, `has-items-in-cart`)
+- **Consider caching expensive operations**: If a predicate needs to perform expensive operations, consider caching the result in `localStorage` or `sessionStorage` within the predicate logic
+- **Don't mutate the snapshot**: The state snapshot is frozen. Any attempt to modify it will throw an error in strict mode