@picked/client 0.0.1-dev.1787019239195 → 0.0.1-dev.1787543060859

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

@@ -22,8 +22,8 @@ decision.
 | --- | --- | --- |
 | `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 |
+| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** setting | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` property | 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
@@ -32,6 +32,9 @@ function they return after the data arrives.
 
 ## 2. Read the bucket
 
+The bucket is what your site receives. A Boolean feature flag gives `true` or `false`. A
+Text feature flag gives the value of one variant, or `false` for the control group.
+
 :::code-group
 
 ```tsx [React]
@@ -39,12 +42,13 @@ import { useFeatureResult } from '@picked/react/hooks'
 
 function MyComponent() {
   // { id, bucket }, or undefined until the feature flag resolves.
-  const result = useFeatureResult('my-feature')
+  const result = useFeatureResult('hero')
 
   return (
     <div>
-      {result?.bucket === 'control' && <p>Control</p>}
-      {result?.bucket === 'variant-a' && <p>Variant A</p>}
+      {result?.bucket === false && <p>Control</p>}
+      {result?.bucket === 'hero-a' && <p>Hero A</p>}
+      {result?.bucket === 'hero-b' && <p>Hero B</p>}
     </div>
   )
 }
@@ -55,13 +59,15 @@ function MyComponent() {
   import { getFeatureResult } from '@picked/svelte/hooks'
 
   // A store that holds { id, bucket }, or undefined until the feature flag resolves.
-  const result = getFeatureResult('my-feature')
+  const result = getFeatureResult('hero')
 </script>
 
-{#if $result?.bucket === 'control'}
+{#if $result?.bucket === false}
   <p>Control</p>
-{:else if $result?.bucket === 'variant-a'}
-  <p>Variant A</p>
+{:else if $result?.bucket === 'hero-a'}
+  <p>Hero A</p>
+{:else if $result?.bucket === 'hero-b'}
+  <p>Hero B</p>
 {/if}
 ```
 
@@ -72,6 +78,12 @@ function MyComponent() {
 renders, and they commit the visitor to a bucket at that moment.
 :::
 
+:::tip
+Run [type generation](/reference/sdk/type-generation) and `bucket` narrows to the values
+that this Text feature flag declares. Your editor then shows each value, and it reports a
+comparison against a value that the feature flag cannot serve.
+:::
+
 ## 3. Read it without a framework
 
 The event bus works with any framework, and with none:
@@ -85,7 +97,7 @@ const client = createClient({
 
 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' }
+    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'hero-a' }
   }
 })
 ```

package/dist/docs/how-to/read-a-referenced-entry.md

@@ -20,12 +20,11 @@ Pass the raw field value to `useReference()` in React, or to `getReference()` in
 :::code-group
 
 ```tsx [React]
-import { useUnit } from 'effector-react'
-import { useReference, useStepContent } from '@picked/react/hooks'
+import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
 export function ProductCategory() {
   const content = useStepContent()
-  const category = useUnit(useReference(content?.category))
+  const category = useStoreGlobal(useReference(content?.category))
 
   if (!category) return null
 
@@ -58,12 +57,11 @@ Use `useReferences()` or `getReferences()`. They give a list in field order.
 :::code-group
 
 ```tsx [React]
-import { useUnit } from 'effector-react'
-import { useReferences, useStepContent } from '@picked/react/hooks'
+import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
 export function ProductCategories() {
   const content = useStepContent()
-  const categories = useUnit(useReferences(content?.categories))
+  const categories = useStoreGlobal(useReferences(content?.categories))
 
   return (
     <ul>

package/dist/docs/how-to/render-a-step-form.md

@@ -59,13 +59,12 @@ Bind `form.props` to your `<form>` element and map over the fields.
 :::code-group
 
 ```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useUnit } from 'effector-react'
+import { useStep, useStoreGlobal } from '@picked/react/hooks'
 
 function StepForm() {
   const { fields, form } = useStep()
-  const currentFields = useUnit(fields)
-  const isSubmitting = useUnit(form.submitting)
+  const currentFields = useStoreGlobal(fields)
+  const isSubmitting = useStoreGlobal(form.submitting)
 
   return (
     <form {...form.props}>

package/dist/docs/how-to/switch-workspaces.md

@@ -22,7 +22,7 @@ picked login
 ```
 
 This opens your browser for a one-time OAuth sign-in and stores a session under
-`~/.picked/`. Confirm it with `picked whoami`. For CI, set `PICKED_TOKEN` instead — see
+`~/.picked/`. Confirm it with `picked whoami`. See
 [CLI authentication](/how-to/authenticate-the-cli).
 
 ## 2. Find a workspace
@@ -99,7 +99,6 @@ Active selection: none (using the config default).
 workspace in CI with no selection file, set the environment directly:
 
 ```bash
-PICKED_TOKEN="$TOKEN" \
 PICKED_PROJECT_ID=proj_a1b2 \
 PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
   picked generate types --check

package/dist/docs/reference/dashboard/features.mdx

@@ -21,6 +21,19 @@ Each feature flag has a unique key. Your application uses this key to check whet
 Picked allocates a visitor to the feature flag. You set the key when you create the
 feature flag, and you cannot change it later.
 
+## Types
+
+Each feature flag has a type. You set the type when you create the feature flag, and you
+cannot change it later.
+
+| Type | What your site receives | Groups |
+| --- | --- | --- |
+| **Boolean** | `true` or `false` | Two |
+| **Text** | A string that you write, or `false` for the control group | Two or more |
+
+Choose **Boolean** for one change against no change. Choose **Text** when you must test
+several changes at the same time, and each change needs its own group.
+
 ## Set the allocation
 
 Set the allocation from the detail page of the feature flag:
@@ -28,19 +41,46 @@ Set the allocation from the detail page of the feature flag:
 | Control | What it does |
 | --- | --- |
 | **Enabled** | Whether Picked allocates a visitor to the feature flag. A disabled feature flag allocates nobody, and it records nothing. See [Disable a feature flag](#disable-a-feature-flag). |
-| **Weight** | The percentage of visitors that Picked allocates to the feature flag, from 0 to 100. |
+| **Weight** | The percentage of visitors that Picked allocates to a Boolean feature flag, from 0 to 100. |
+| **Variants** | The groups of a Text feature flag, and the traffic that each one receives. See [Variants](#variants). |
 | **Description** | An internal note about what the feature flag tests. |
 
-A feature flag has one weight. For each visitor it gives one of two outcomes:
+A Boolean feature flag has one weight. For each visitor it gives one of two outcomes:
 allocated, or not allocated. A weight of 30 allocates 30% of your visitors. The other
 70% stay unallocated. A weight of 0 allocates nobody. A weight of 100 allocates
 everybody.
 
+## Variants
+
+A Text feature flag has a table of variants. Each row is one group of visitors:
+
+| Column | What it does |
+| --- | --- |
+| **Name** | A label for the variant. It appears in your reports. You can change it at any time. |
+| **Value** | The string that your site receives for a visitor in this variant. |
+| **Weight** | The share of traffic for this variant, against the other rows. |
+
+The first row is **Control**. Picked always sends `false` to a visitor in the control
+group, and you cannot remove the row, move it, or change its value. It takes a weight like
+any other row.
+
+The weights are shares, and not percentages. Picked reduces them to their smallest whole
+numbers, so `10 : 10 : 20` and `1 : 1 : 2` are the same split. The percentage beside each
+row shows the traffic that the variant receives.
+
+Choose **Even split** to give every variant the same weight.
+
+:::info
+The order of the rows is the order that you read them in. It has no effect on the
+allocation, so you can move a row and no visitor changes group.
+:::
+
 ## How Picked allocates a visitor
 
-The allocation is deterministic. It derives from the visitor ID, the ID of the feature
-flag, and the weight. Each feature flag gets its own value, so tests that run at the
-same time are independent. See
+The allocation is deterministic. It derives from the visitor ID and from the ID of the
+feature flag. A Boolean feature flag then compares that value against the weight, and a
+Text feature flag compares it against the range of each variant. Each feature flag gets its
+own value, so tests that run at the same time are independent. See
 [About feature flag allocation](/explanation/feature-flag-allocation).
 
 ## Disable a feature flag

package/dist/docs/reference/delivery-api/workspace-schema.md

@@ -28,6 +28,7 @@ The response is a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020
 | `x-picked-source` | `"published"` or `"preview"` — mirrors the surface you requested. |
 | `x-picked-version-id` | Published workspace version id, or `null` on preview. |
 | `x-picked-step-content-models` | Map of step key → content model key, which gives each layout its type. |
+| `x-picked-feature-values` | Map of feature key → the values that the feature can serve. Picked adds this field only when the workspace has a Text feature flag. |
 | `$defs.contentModels` | JSON Schema definitions for each content model. |
 | `$defs.contentBlocks` | JSON Schema definitions for reusable content blocks. |
 | `$defs.fields` | Object schema for project field values. |
@@ -41,6 +42,13 @@ On the published surface, the schema reflects your last published workspace. On
 
 When no published schema exists, the published endpoint returns `404` and tells you to publish the workspace.
 
+A Boolean feature flag serves `true` or `false`, and it contributes no entry to
+`x-picked-feature-values`. A workspace of Boolean feature flags therefore omits the field.
+A schema that Picked published before Text feature flags existed also omits it.
+
+Picked sorts the values of each Text feature flag by the key of the variant. The document
+therefore does not change when you rename a variant or move a row.
+
 ## Example
 
 ```bash
@@ -57,11 +65,14 @@ curl https://api.picked.app/api/v1/projects/proj_123/schema
   "x-picked-step-content-models": {
     "intro": "welcome-page"
   },
+  "x-picked-feature-values": {
+    "hero": [false, "hero-a", "hero-b"]
+  },
   "$defs": {
     "contentModels": {},
     "contentBlocks": {},
     "fields": { "type": "object", "additionalProperties": false, "properties": {} },
-    "featureKeys": { "type": "string", "enum": ["default"] },
+    "featureKeys": { "type": "string", "enum": ["default", "hero"] },
     "experienceKeys": { "type": "string", "enum": ["welcome-survey"] },
     "stepKeys": { "type": "string", "enum": ["intro"] }
   }

package/dist/docs/reference/pickedql/dimensions.md

@@ -22,6 +22,12 @@ point at one. You write no join.
 | `experiences` | `experience_title` |
 | `projects` | `project_name`, `project_timezone` |
 
+:::warning
+`dim_variant` describes whether the visitor is a known user. It does **not** hold the variants
+of your feature flags. To count the visitors in one variant, use
+[`feature_users`](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
+:::
+
 The `steps`, `experiences`, and `projects` sources are reference tables, and they come
 from the operational database. PickedQL joins them onto `events` and `fact_events`
 when you point at one of their analyst-facing columns. Each one **also** needs its own

package/dist/docs/reference/pickedql/virtual-functions.md

@@ -213,15 +213,26 @@ Parameterized functions that accept the feature name, bucket, and an optional fe
 | `feature_sessions('name', 'bucket' [, 'key'])` | Unique sessions in a feature bucket |
 | `feature_events('name', 'bucket' [, 'key'])` | Unique events in a feature bucket |
 
+The bucket is what the SDK sent to the site of the visitor. A Boolean feature flag gives
+`'true'` or `'false'`. A Text feature flag gives the value of one variant, or `'false'` for
+the control group. The key is the version of the feature flag, such as `'v1'`.
+
 ```sql
--- Compare feature buckets
+-- Compare the two buckets of a Boolean feature flag.
+SELECT
+  feature_users('homepage_test', 'false') AS control,
+  feature_users('homepage_test', 'true') AS variant
+FROM features
+
+-- Compare the variants of a Text feature flag.
 SELECT
-  feature_users('homepage_test', 'control') AS control,
-  feature_users('homepage_test', 'variant') AS variant
+  feature_users('hero', 'false') AS control,
+  feature_users('hero', 'hero-a') AS hero_a,
+  feature_users('hero', 'hero-b') AS hero_b
 FROM features
 
--- With feature key filter
-SELECT feature_users('homepage_test', 'control', 'v1') FROM features
+-- Count one version of the feature flag alone.
+SELECT feature_users('homepage_test', 'false', 'v1') FROM features
 ```
 
 ## Other (`metrics` only)

package/dist/docs/reference/sdk/content.md

@@ -68,11 +68,10 @@ changes. `getStepContent()` returns a store, which you read with the `$` prefix.
 :::code-group
 
 ```tsx [React]
-import { useUnit } from 'effector-react'
-import { useContent } from '@picked/react/hooks'
+import { useContent, useStoreGlobal } from '@picked/react/hooks'
 
 export function Banner() {
-  const banner = useUnit(useContent('entry_42'))
+  const banner = useStoreGlobal(useContent('entry_42'))
 
   return <h1>{String(banner?.data.headline ?? '')}</h1>
 }
@@ -99,12 +98,11 @@ index.
 :::code-group
 
 ```tsx [React]
-import { useUnit } from 'effector-react'
-import { useReference, useStepContent } from '@picked/react/hooks'
+import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
 export function ProductCategory() {
   const content = useStepContent()
-  const category = useUnit(useReference(content?.category))
+  const category = useStoreGlobal(useReference(content?.category))
 
   return <span>{String(category?.data.name ?? '')}</span>
 }
@@ -129,12 +127,11 @@ a list in field order.
 :::code-group
 
 ```tsx [React]
-import { useUnit } from 'effector-react'
-import { useReferences, useStepContent } from '@picked/react/hooks'
+import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
 export function ProductCategories() {
   const content = useStepContent()
-  const categories = useUnit(useReferences(content?.categories))
+  const categories = useStoreGlobal(useReferences(content?.categories))
 
   return (
     <ul>

package/dist/docs/reference/sdk/features.md

@@ -26,12 +26,22 @@ For a feature flag that you control from the dashboard, the SDK makes the defini
 | `enabled` | The dashboard **Enabled** toggle |
 | `weight` | The dashboard **Weight**, 0 to 100 |
 | `storage` | `local`, or `session` in [preview mode](/explanation/feature-flag-allocation#preview-mode) |
-| `decide` | Made by the SDK. It compares the stable value of the visitor for this feature flag against `weight`. |
+| `decide` | Made by the SDK. See the two routes below. |
 
-The `decide` function that the SDK makes derives from the visitor ID, the ID of the
-feature flag, and the weight. A feature flag that you control from the dashboard
-therefore cannot use the data of your application. Define the feature flag in SDK code
-when you need that.
+The `decide` function that the SDK makes derives from the visitor ID and from the ID of
+the feature flag. A feature flag that you control from the dashboard therefore cannot use
+the data of your application. Define the feature flag in SDK code when you need that.
+
+Which route `decide` takes depends on the type of the feature flag:
+
+| Dashboard type | The bucket | How the SDK decides |
+| --- | --- | --- |
+| Boolean | `true` or `false` | It compares the stable value of the visitor against `weight`. |
+| Text | The value of one variant, or `false` | It compares the stable value of the visitor against the range that Picked gives to each variant. |
+
+The SDK sorts the variants by their key before it allocates, so the order of the payload
+has no effect. See
+[More than two groups](/explanation/feature-flag-allocation#more-than-two-groups).
 
 ## Define a feature flag in SDK code
 
@@ -95,7 +105,15 @@ You can give more than one override value:
 https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
 ```
 
-The format is `?picked-feature=<feature-id>:<bucket-value>`.
+The format is `?picked-feature=<feature-id>:<bucket-value>`. For a Text feature flag,
+give the value that the variant serves.
+
+A feature ID contains only lowercase letters, numbers, and hyphens. Therefore the SDK divides
+the parameter at the first colon. The bucket value can contain more colons:
+
+```
+https://example.com?picked-feature=opening-hours:09:00-17:00
+```
 
 This is useful for QA, because you can test one bucket value and change no code. The
 SDK keeps the override value in session storage. The browser clears it when you close

package/dist/docs/reference/sdk/steps.md

@@ -16,13 +16,12 @@ Inside a `Step` component, or inside any component that a `Step` renders, call
 :::code-group
 
 ```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useUnit } from 'effector-react'
+import { useStep, useStoreGlobal } from '@picked/react/hooks'
 
 function ContactForm() {
   const { step, fields } = useStep()
-  const currentStep = useUnit(step)
-  const currentFields = useUnit(fields)
+  const currentStep = useStoreGlobal(step)
+  const currentFields = useStoreGlobal(fields)
 
   return (
     <>

package/dist/docs/reference/sdk/type-generation.md

@@ -65,9 +65,7 @@ If you use Vite, add `@picked/vite-plugin-picked`. Type generation runs automati
 import { picked } from '@picked/vite-plugin-picked'
 
 export default defineConfig({
-  plugins: [
-    picked({ disableLauncher: true }),
-  ],
+  plugins: [picked()],
 })
 ```
 
@@ -126,7 +124,7 @@ The generated `picked-env.d.ts` file looks like:
 
 export interface WelcomePage { /* ... */ }
 export interface FieldValues { /* ... */ }
-export type FeatureKey = 'default' | 'winter-sale'
+export type FeatureKey = 'default' | 'hero' | 'winter-sale'
 
 declare module '@picked/client' {
   interface PickedSchemaRegistry {
@@ -134,12 +132,28 @@ declare module '@picked/client' {
     stepContentModels: { intro: 'welcome-page' }
     fieldValues: FieldValues
     featureKeys: FeatureKey
+    featureValues: { hero: false | 'hero-a' | 'hero-b' }
   }
 }
 ```
 
 Commit this file to the version control system, or regenerate it in CI after you publish a workspace change.
 
+### Feature flag values
+
+A Text feature flag declares the values that it can serve, so `useFeatureResult` narrows
+the bucket to those values:
+
+```typescript
+const result = useFeatureResult('hero')
+```
+
+The `bucket` property then has the type `false | 'hero-a' | 'hero-b'`.
+
+`featureValues` holds the Text feature flags alone. A Boolean feature flag, and a feature
+flag that your application defines, both keep the general `boolean | string` type. The
+`FeatureValueFor<'hero'>` type gives the same union on its own.
+
 ## Keys the application defines
 
 An application can define a feature, an action, a field, a step, or an experience of its

package/dist/docs/reference/tools/cli.md

@@ -30,7 +30,7 @@ package.
 | --- | --- |
 | `picked login` | Sign in with your browser (OAuth) to the API origin of the current directory. Stores a session under `~/.picked/auth/`. |
 | `picked logout` | Clear the stored session for the current directory's API origin. |
-| `picked whoami` | Print the identity signed in to the API origin of the current directory, or report that `PICKED_TOKEN` is in use. |
+| `picked whoami` | Print the identity signed in to the API origin of the current directory. |
 | `picked status` | Print the resolved selection and the committed `picked.config` default. |
 | `picked workspace list` | List each org, project, and workspace that you can read. Alias `ls`. `--json` gives machine output. |
 | `picked workspace use` | Set the active project or workspace. Alias `picked use`. Interactive, or `--project` and `--workspace`. |
@@ -107,9 +107,8 @@ a session for another API.
 | --- | --- |
 | `~/.picked/auth/<origin>.json` | The OAuth session for one API origin — access token, refresh token, expiry — with the CLI's registered client id for that origin. File mode `600`. Refreshed as it nears expiry. |
 
-`PICKED_TOKEN` supersedes each stored session and needs no browser, which is what a CI run
-uses. An API deployment with no OAuth client registration rejects `picked login`, and has
-no other flow.
+An API deployment with no OAuth client registration rejects `picked login`, and has no
+other flow.
 
 A CLI session is a developer credential. It is not an
 [API key](/reference/dashboard/api-keys), which authenticates server-to-server calls, and
@@ -120,7 +119,6 @@ not [dashboard sign-in](/reference/management-api/authentication).
 | Variable | Effect |
 | --- | --- |
 | `PICKED_API_URL` | The API origin that the CLI reads. Supersedes `picked.config` `apiUrl` and the `https://api.picked.app` default. |
-| `PICKED_TOKEN` | An access token in place of the stored session, for a CI or headless run. `picked login` is then not needed. |
 | `PICKED_PROJECT_ID` | Supersedes the resolved project id, above the active selection and the committed configuration. |
 | `PICKED_PREVIEW_TOKEN` | Supersedes the preview token. Applies only when the resolved source is `preview`. |
 

package/dist/docs/reference/tools/vite-plugin.md

@@ -124,11 +124,7 @@ These two options moved to [`picked.config.ts`](/reference/sdk/type-generation),
 
 The plugin still reads an option for a field that `picked.config.ts` leaves out, so a
 project that has yet to move needs no change. It stops when the two values are different,
-rather than choose one for you:
-
-```
-picked plugin option `projectId` is "option-proj", and picked.config says "file-proj".
-```
+rather than choose one for you.
 
 ### generateTypes
 

package/dist/docs/tutorials/first-experience.mdx

@@ -102,11 +102,11 @@ Install the client and the adapter for your framework.
 :::code-group
 
 ```bash [React]
-npm install picked @picked/react effector effector-react
+npm install picked @picked/react
 ```
 
 ```bash [Svelte]
-npm install picked @picked/svelte effector
+npm install picked @picked/svelte
 ```
 
 :::
@@ -118,12 +118,11 @@ puts each one in a form.
 :::code-group
 
 ```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useUnit } from 'effector-react'
+import { useStep, useStoreGlobal } from '@picked/react/hooks'
 
 export function ColorSurvey() {
   const { fields, form } = useStep()
-  const currentFields = useUnit(fields)
+  const currentFields = useStoreGlobal(fields)
 
   return (
     <form {...form.props}>

package/dist/emit-D-tLiWL1.cjs

@@ -0,0 +1 @@
+let e=require("@picked/telemetry");async function t(t,n,r){let i=(0,e.createTelemetryEmitter)({endpoint:t,resource:n,headers:{"Picked-Telemetry":`sdk`},maxBatchSize:r.length||1});for(let e of r)i.record(e);await i.flush()}exports.flushSpans=t;

package/dist/emit-Ds2EG7CB.js

@@ -0,0 +1,14 @@
+import { createTelemetryEmitter as e } from "@picked/telemetry";
+//#region src/plugins/telemetry/emit.ts
+async function t(t, n, r) {
+	let i = e({
+		endpoint: t,
+		resource: n,
+		headers: { "Picked-Telemetry": "sdk" },
+		maxBatchSize: r.length || 1
+	});
+	for (let e of r) i.record(e);
+	await i.flush();
+}
+//#endregion
+export { t as flushSpans };