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

package/dist/docs/how-to/create-an-experience.md

@@ -0,0 +1,42 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create an experience
+
+An experience is a Flow or a Page. This guide adds a **Flow**: the interactive kind, of
+more than one step, which the browser renders. A **Page** is the standalone kind that your
+server renders for a search engine, and
+[How to fill and publish a page](/how-to/fill-and-publish-a-page) covers it.
+
+[About pages and flows](/explanation/pages-and-flows) sets out the difference, and which
+kind a piece of work needs.
+
+## Steps
+
+1. Open your project.
+2. Click **Flows** in the sidebar. The experiences list opens.
+3. Click **New experience**.
+4. Enter a name.
+5. Leave **Type** on the **Flow** option.
+6. Open **Advanced**.
+7. Enter a component name. It must match a component that you register in your
+   application.
+8. Click **Create flow**.
+
+The flow editor opens with an empty canvas.
+
+## Set the options
+
+Click the canvas background to open the experience inspector.
+
+- **Condition** — the experience starts only for a visitor who matches it. Keep it blank
+  to start for every visitor.
+- **Initialize Open** — the experience opens by itself when the page loads.
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow) — add your first node.
+- [About pages and flows](/explanation/pages-and-flows) — Page or Flow.
+- [Experiences](/reference/dashboard/experiences) — every option.

package/dist/docs/how-to/create-and-revoke-an-api-key.md

@@ -0,0 +1,37 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create and revoke an API key
+
+This guide shows you how to give your code access to the Picked API. Use a key for a
+server-side integration or for a CI/CD workflow.
+
+## Create a key
+
+1. Open your organization.
+2. Click **API Keys**.
+3. Click **Create API Key**.
+4. Enter a **Name**, such as `Production key`.
+5. Set **Project** to one project. The default, **All projects**, gives the key every
+   project.
+6. Choose the **Permissions** that your integration needs.
+7. Click **Create API Key**.
+
+:::warning
+Copy the key immediately. The dashboard does not show it again.
+:::
+
+## Revoke a key
+
+1. Open the API keys list.
+2. Click **Revoke** next to the key.
+3. Click **Revoke Key** to confirm.
+
+Picked invalidates the key immediately. No later request can use it.
+
+## Related
+
+- [API keys](/reference/dashboard/api-keys) — the scopes.
+- [Authentication](/reference/management-api/authentication) — how to send the key.

package/dist/docs/how-to/debug-with-the-chrome-extension.md

@@ -0,0 +1,57 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to debug with the Chrome extension
+
+This guide shows you how to add a Picked panel to Chrome DevTools and check your
+integration on any page that runs the SDK.
+
+## 1. Install the extension
+
+Install it from the
+[Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
+
+## 2. Add the devtools plugin
+
+```typescript
+import { createClient } from '@picked/client'
+import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [svelteDevtoolsPlugin()],
+})
+```
+
+The extension then connects to the SDK.
+
+## 3. Add a tool of your own
+
+A custom tool is a framework-adapted component, and it receives the live Picked client
+exactly as an experience component does.
+
+```typescript
+import { adaptReactComponent } from '@picked/react'
+import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
+import MyTool from './MyTool'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [
+    svelteDevtoolsPlugin({
+      customTools: [
+        { id: 'my-tool', label: 'My Tool', component: adaptReactComponent(MyTool) },
+      ],
+    }),
+  ],
+})
+```
+
+Your tools appear under a **Custom Tools** tab. In React use `usePicked()`, and in Svelte
+use `getPicked()`.
+
+## Related
+
+- [Chrome extension](/reference/tools/chrome-extension) — the panel reference.

package/dist/docs/how-to/define-a-page-layout.md

@@ -0,0 +1,39 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to define a page layout
+
+This guide shows you how to define the shape of a page. A layout sets which fields a page
+can hold, and it holds no data itself.
+
+## Steps
+
+1. Open your workspace.
+2. Click **Pages** in the sidebar, then **Page Layouts**.
+3. Click **New model**.
+4. Set **Category** to **Page layout**.
+5. Enter a **Name** and a **Key**. The key is stable, and your SDK code and your API
+   calls both use it.
+6. Add your fields. Choose a type for each one.
+7. Click **Create model**.
+
+The category is fixed when you create the layout. You cannot change it later.
+
+## Make a field repeatable
+
+Turn on **repeatable** on any field. It then renders as a sortable list of values. Use it
+for a gallery, or for a list of features.
+
+## Group related fields
+
+Add a **Group** field to hold a set of fields under one key. Make the group repeatable to
+describe a list of objects, such as a list of feature cards.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why the schema and the data
+  are separate.
+- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
+- [How to reuse a section](/how-to/reuse-a-section).

package/dist/docs/how-to/fill-and-publish-a-page.md

@@ -0,0 +1,50 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to fill and publish a page
+
+This guide shows you how to make a server-rendered Page and put content in it. You need a
+page layout first. See [How to define a page layout](/how-to/define-a-page-layout).
+
+## 1. Create the page
+
+1. Open your project.
+2. Choose a workspace.
+3. Click **Pages** in the sidebar.
+4. Click **New experience**.
+5. Choose the **Page** type.
+6. Choose a page layout.
+7. Click **Create page**.
+
+Picked makes a content entry and links it to the page on the first save.
+
+## 2. Fill in the content
+
+1. Open the **Properties** tab.
+2. Fill in each field. The inspector on the right edits the field that you choose.
+3. Watch the preview panel as the page fills in.
+
+## 3. Correct every error
+
+An invalid field shows an error next to it while you edit. Correct each one before you
+publish. Picked serves valid content only.
+
+## 4. Publish
+
+Publish the workspace to make the page live. See
+[How to publish a workspace](/how-to/publish-a-workspace).
+
+## Change the layout later
+
+Use the change-layout control on the **Settings** tab. When you unlink a layout, Picked
+separates the content entry from the page. It deletes no entry, but the page then has no
+content to render.
+
+## Related
+
+- [About pages and flows](/explanation/pages-and-flows) — when to choose a Page.
+- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
+  path, with the SDK.
+- [Pages](/reference/dashboard/content/pages) — the editor reference.

package/dist/docs/how-to/install-the-gtm-template.md

@@ -0,0 +1,84 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to install the GTM template
+
+This guide shows you how to track an ecommerce event in Google Tag Manager and send it to
+Picked. You need a GTM container and your Picked Tag ID.
+
+## Automatic installation
+
+Install the template from the GTM Community Gallery:
+
+1. In Tag Manager, click **Templates**.
+2. In the **Tag Templates** section, click **Search Gallery**.
+3. Search for `Picked Ecommerce`.
+4. Click the Picked Ecommerce template to read its detail.
+5. Click the **Add to workspace** button.
+6. Read the permissions that it needs.
+7. Click **Add**.
+
+![The Picked Ecommerce template in the GTM Community Gallery](/gtm/picked-ecommerce-gtm.png)
+
+## Manual installation
+
+To import the template file yourself:
+
+1. Download the
+   [template file](https://github.com/picked-app/gtm-template/blob/main/template.tpl)
+   from GitHub with the download icon.
+2. In Google Tag Manager, go to **Templates**.
+3. Click **New**.
+4. Open the three-dot menu.
+5. Click **Import**.
+6. Choose the file that you downloaded.
+7. Click **Save**.
+
+## Setup
+
+### 1. Create a Tag ID variable
+
+Sign in to the [Picked Dashboard](https://dashboard.picked.app) and copy the Tag ID of
+your project. Save it as a constant variable in GTM, for example `Picked Tag ID`.
+
+![How to create a variable in GTM for the Picked Tag ID](/gtm/gtm-variable.png)
+
+### 2. Create an ecommerce data variable
+
+Create a **Data Layer Variable** with the variable name `ecommerce`. It captures what
+GA4 Enhanced Ecommerce writes to the data layer.
+
+![The variable for the data layer of GA4 Enhanced Ecommerce](/gtm/gtm-ecommerce-variable.png)
+
+### 3. Create event triggers
+
+Add a trigger for each ecommerce event that you want to track, for example
+`add_to_cart`, `purchase`, or `view_item`.
+
+![The event triggers that record an ecommerce event](/gtm/gtm-triggers.png)
+
+### 4. Create tags
+
+Create a new tag for each event. Choose the tag template called **Picked Ecommerce**. Assign
+the trigger that matches. Then set the options below.
+
+![The tags that use the Picked Ecommerce template](/gtm/gtm-tags.png)
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| **Tag ID** | The Tag ID of your Picked project. Find it in the [Picked Dashboard](https://dashboard.picked.app). |
+| **Event** | The ecommerce event to track, for example `add_to_cart` or `purchase`. |
+| **Send ecommerce data** | Turn this on to send the data from GA4 Enhanced Ecommerce to Picked. Turn it on for every ecommerce event. |
+| **GA4 Enhanced Ecommerce Data** | The GTM variable that holds the data from GA4 Enhanced Ecommerce. Use the data layer variable from step 2. |
+| **Additional data** | An optional GTM variable, for more metadata with the event. |
+
+![The options on a Picked Ecommerce tag](/gtm/gtm-tag.png)
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — what Picked does with the
+  event.

package/dist/docs/how-to/install-the-sdk.md

@@ -0,0 +1,68 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to install the SDK
+
+This guide shows you how to add the Picked client to a web application. You need a project
+ID from the dashboard.
+
+## 1. Install the packages
+
+:::code-group
+
+```bash [React]
+npm install @picked/client @picked/react effector effector-react
+```
+
+```bash [Svelte]
+npm install @picked/client @picked/svelte effector
+```
+
+:::
+
+## 2. Create and start the client
+
+:::code-group
+
+```tsx [React]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
+
+export const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+})
+
+picked.start()
+```
+
+```ts [Svelte]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
+
+export const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+})
+
+picked.start()
+```
+
+:::
+
+`start()` is idempotent. A second call changes nothing on a client that started already.
+
+## 3. Add the optional plugins
+
+- `windowObjectPlugin()` puts the client on `window.Picked`, which helps when you debug.
+- `singlePageAppPlugin()` starts the client again on a history event.
+
+## Related
+
+- [Add Picked to your application](/tutorials/first-experience) — the whole path.
+- [SDK installation](/reference/sdk) — every client option.
+- [How to register a component](/how-to/register-a-component).

package/dist/docs/how-to/install-the-vite-plugin.md

@@ -0,0 +1,56 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to install the Vite plugin
+
+This guide shows you how to embed your project configuration at build time, so the SDK makes no
+API request at runtime.
+
+## 1. Install
+
+:::code-group
+
+```bash [npm]
+npm install @picked/vite-plugin-picked
+```
+
+```bash [pnpm]
+pnpm add @picked/vite-plugin-picked
+```
+
+```bash [yarn]
+yarn add @picked/vite-plugin-picked
+```
+
+:::
+
+## 2. Add it to your config
+
+```typescript
+import { defineConfig } from 'vite'
+import { picked } from '@picked/vite-plugin-picked'
+
+export default defineConfig({
+  plugins: [
+    picked({
+      projectId: 'your-project-id',
+    }),
+  ],
+})
+```
+
+When Vite starts, the plugin reads your project configuration and embeds them in your bundle.
+The SDK then reads the embedded configuration and makes no network request.
+
+:::note
+When a preview token is there at runtime, the SDK ignores the embedded configuration and reads
+fresh data from the API.
+:::
+
+## Related
+
+- [Vite plugin](/reference/tools/vite-plugin) — every option.
+- [About how Picked works](/explanation/how-picked-works) — where build-time configuration sit
+  in the startup order.

package/dist/docs/how-to/invite-and-remove-members.md

@@ -0,0 +1,34 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to invite and remove members
+
+This guide shows you how to control who reaches your organization.
+
+## Invite a member
+
+1. Open your organization.
+2. Click **Members**.
+3. Click **Invite member**.
+4. Enter an email address.
+5. Choose a role. Give the smallest role that the work needs.
+6. Click **Send invitation**.
+
+The person receives an email with a link to join. A person with no Picked account must
+create one first.
+
+## Remove a member
+
+1. Open your organization.
+2. Click **Members**.
+3. Find the member.
+4. Click **Remove** next to the name.
+5. Confirm.
+
+The member loses access to every project in the organization immediately.
+
+## Related
+
+- [Team management](/reference/dashboard/team-management) — the roles.

package/dist/docs/how-to/preview-a-workspace.md

@@ -0,0 +1,28 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to see a preview of a workspace
+
+This guide shows you how to see an unpublished change on your own site before your
+visitors get it. You need a draft workspace with at least one change in it.
+
+## Steps
+
+1. Click **Preview** in the workspace toolbar.
+2. Enter the URL of your site.
+3. Set each feature flag to the **Default** value, to **On**, or to **Off**. This step
+   is optional.
+4. Click **Open preview**.
+
+Your site opens in a new tab with the unpublished workspace applied.
+
+The preview sends the workspace state to the SDK in the query parameters. The visitors on
+your live site therefore see no change.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why a preview
+  cannot reach production.
+- [Workspaces](/reference/dashboard/workspaces) — the workspace states.

package/dist/docs/how-to/publish-a-workspace.md

@@ -0,0 +1,30 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to publish a workspace
+
+This guide shows you how to make the changes in a workspace live. You need a draft
+workspace with at least one unpublished change.
+
+The **Publish** button is active only when the workspace holds an unpublished change. A
+badge in the toolbar shows the current state.
+
+## Steps
+
+1. Click **Publish** in the workspace toolbar.
+2. Read the change preview in the publish modal.
+3. Expand any modified row to see which properties changed.
+4. Read the banner above the diff, if one is there. It reports a change that breaks
+   another record.
+5. Click **Publish** to confirm.
+
+Picked makes an immutable snapshot of your workspace, and the SDK serves it to your
+visitors.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why the modal
+  shows a diff.
+- [How to roll back a published version](/how-to/roll-back-a-published-version).

package/dist/docs/how-to/read-a-feature-flag.md

@@ -0,0 +1,101 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to read a feature flag
+
+This guide shows you how to read the resolved bucket of a feature flag in your
+application. You need a feature flag in your project first, either from the dashboard or
+[defined in SDK code](/reference/sdk/features#define-a-feature-flag-in-sdk-code).
+
+Which accessor you pick decides *when* the visitor enters the test, so read
+[About feature flag allocation](/explanation/feature-flag-allocation) before you choose.
+
+## 1. Choose an accessor
+
+Each accessor returns a different value, and they differ in whether a read resolves the
+feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports the
+decision.
+
+| API | Returns | Does a read resolve the feature flag? |
+| --- | --- | --- |
+| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
+| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
+| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** feature flag | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | No |
+| `client.features.getById(id)` | A store that holds one feature flag | No |
+
+Some decisions must wait for data that you do not have yet, such as a cart, a quote, or
+the profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call the
+function they return after the data arrives.
+
+## 2. Read the bucket
+
+:::code-group
+
+```tsx [React]
+import { useFeatureResult } from '@picked/react/hooks'
+
+function MyComponent() {
+  // { id, bucket }, or undefined until the feature flag resolves.
+  const result = useFeatureResult('my-feature')
+
+  return (
+    <div>
+      {result?.bucket === 'control' && <p>Control</p>}
+      {result?.bucket === 'variant-a' && <p>Variant A</p>}
+    </div>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getFeatureResult } from '@picked/svelte/hooks'
+
+  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
+  const result = getFeatureResult('my-feature')
+</script>
+
+{#if $result?.bucket === 'control'}
+  <p>Control</p>
+{:else if $result?.bucket === 'variant-a'}
+  <p>Variant A</p>
+{/if}
+```
+
+:::
+
+:::warning
+`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
+renders, and they commit the visitor to a bucket at that moment.
+:::
+
+## 3. Read it without a framework
+
+The event bus works with any framework, and with none:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  /* Put your client options here. */
+})
+
+client.eventBus.watch((event) => {
+  if (event.type === 'feature_decide' && event.feature.id === 'my-feature') {
+    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'control' }
+  }
+})
+```
+
+`feature_decide` fires only when the SDK makes a new decision. A visitor who returns
+restores the decision from storage and fires nothing, so watch
+`client.features.listStore` when you need the current state instead.
+
+## Related
+
+- [About feature flag allocation](/explanation/feature-flag-allocation) — when the
+  visitor enters the test.
+- [SDK feature flags](/reference/sdk/features) — the definition shape and the overrides.

package/dist/docs/how-to/register-a-component.md

@@ -0,0 +1,55 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to register a component
+
+This guide shows you how to connect a component in your application to an experience in
+the dashboard.
+
+## Steps
+
+1. Wrap your component with the adapter for your framework.
+2. Pass it in the `components` object of `createClient()`.
+3. Use the same key as the component name of the experience.
+
+:::code-group
+
+```tsx [React]
+import { createClient } from '@picked/client'
+import { adaptReactComponent } from '@picked/react'
+import { MyWidget } from './MyWidget'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    MyWidget: adaptReactComponent(MyWidget),
+  },
+})
+```
+
+```ts [Svelte]
+import { createClient } from '@picked/client'
+import { adaptSvelteComponent } from '@picked/svelte'
+import MyWidget from './MyWidget.svelte'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    MyWidget: adaptSvelteComponent(MyWidget),
+  },
+})
+```
+
+:::
+
+:::warning
+`components` takes an adapted component. A plain React or Svelte component does not work
+without `adaptReactComponent` or `adaptSvelteComponent`.
+:::
+
+## Related
+
+- [SDK experiences](/reference/sdk/experiences) — the experience shape.
+- [How to install the SDK](/how-to/install-the-sdk).