@picked/client 0.0.56-next.1 → 0.0.56

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