@picked/client 0.0.1-dev.1786675074931 → 0.0.1-dev.1787537193674

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

@@ -7,8 +7,6 @@ layout: docs
 
 Picked can generate TypeScript types from your workspace schema so field values, feature keys, content models, and step layouts are typed in your app.
 
-The generated file augments the `PickedSchemaRegistry` interface of `@picked/client`. Your IDE reads the types as soon as the declaration file is part of your TypeScript project.
-
 ## Quick start
 
 ### 1. Add `picked.config.ts`
@@ -16,40 +14,48 @@ The generated file augments the `PickedSchemaRegistry` interface of `@picked/cli
 Create a `picked.config.ts` in your project root:
 
 ```typescript
-import { defineConfig } from '@picked/config'
+import { defineConfig } from 'picked/config'
 
 export default defineConfig({
   projectId: 'your-project-id',
-  apiUrl: 'https://api.picked.app',
   typesOutput: './src/picked-env.d.ts',
-  source: 'published',
 })
 ```
 
 | Option | Description |
 | --- | --- |
 | `projectId` | **Required.** Your Picked project id. |
-| `apiUrl` | API origin (defaults to `https://api.picked.app`). |
 | `typesOutput` | Path for generated types (defaults to `./src/picked-env.d.ts`). |
 | `source` | Schema surface to type against: `'published'` (default) or `'preview'`. |
 | `previewToken` | Workspace preview token. Required when `source` is `'preview'`, and read only then. |
 
 The `source` value matches the `x-picked-source` field on the [workspace schema](/reference/delivery-api/workspace-schema) document — it controls whether tooling fetches the published or preview workspace shape.
 
-A preview token is a long-lived, unexpiring, workspace-scoped secret. Keep it out of
-version control by reading it from wherever your project holds secrets:
+A preview token reads one workspace, and it does not expire. Leave both `source` and
+`previewToken` out of the committed file, and pick a workspace instead:
+
+```bash
+picked login
+picked workspace use
+```
+
+That writes the choice, and that workspace's token, to `.picked/settings.json`, which is
+per-developer and which Git ignores. Each developer points at their own workspace, and the
+committed file holds no token.
+
+You can also set the values here. Every developer then reads the same workspace:
 
 ```typescript
 export default defineConfig({
   projectId: 'your-project-id',
   source: 'preview',
-  previewToken: process.env.PICKED_PREVIEW_TOKEN,
+  previewToken: 'the-workspace-preview-token',
 })
 ```
 
-Tooling resolves the token from the first source that supplies one: the
-`PICKED_PREVIEW_TOKEN` environment variable, then the workspace chosen with
-[`picked workspace use`](/reference/tools/cli), then this `previewToken` option.
+Three places can give the token. Tooling reads the first of them that has one: the
+`PICKED_PREVIEW_TOKEN` environment variable, then the workspace that
+[`picked workspace use`](/reference/tools/cli) chose, then this `previewToken` option.
 
 ### 2. Enable the Vite plugin (recommended)
 
@@ -59,30 +65,47 @@ 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()],
 })
 ```
 
-Project identity (`projectId`, `apiUrl`) comes from `picked.config.ts` — the plugin only accepts Vite-specific options:
-
-| Option | Default | Description |
-| --- | --- | --- |
-| `generateTypes` | `true` | Read the workspace schema and write types, in development and in a build. |
-| `disableLauncher` | `false` | Turn off the HTML page of the dev launcher. |
-
-Set `generateTypes: false` in a nested Vite build that must not regenerate types, such as a build for one more entry point.
+The project id comes from `picked.config.ts`. A failure stops the
+run. See [the plugin reference](/reference/tools/vite-plugin) for `generateTypes` and every
+other option.
 
 ### 3. Or use the CLI
 
-Install `@picked/cli` and run:
+Install [`picked`](/reference/tools/cli) and run:
 
 ```bash
 picked generate types
 ```
 
-In CI, `--check` writes no file and fails when the types are stale. See the [CLI reference](/reference/tools/cli) for each command.
+## Keep the types current
+
+Commit `picked-env.d.ts`. A workspace changes after you commit it, so the file goes stale,
+and stale types describe fields your workspace no longer has.
+
+Run this check in CI, next to your other checks:
+
+```bash
+picked generate types --check
+```
+
+`--check` writes no file. It reads the live workspace schema and compares it with the
+committed file. A match gives status `0`. A difference gives status `1` and names the file:
+
+```
+Types are out of date: /home/runner/work/your-app/src/picked-env.d.ts
+```
+
+To clear it, run `picked generate types` and commit the result. The check reads no cached
+schema, so an API it cannot reach fails the check.
+
+:::note
+`--check` reads the workspace that the resolved configuration names. A CI run that has no
+`.picked/settings.json` reads the workspace your committed `picked.config.ts` names.
+:::
 
 ## Workspace selection
 
@@ -101,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 {
@@ -109,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

@@ -5,18 +5,24 @@ layout: docs
 
 # CLI
 
-`@picked/cli` is the command-line tool for local Picked development. It generates
-TypeScript types from your workspace schema and lets you switch which project or workspace
-your local tooling loads — without hand-editing `picked.config.ts`.
+`picked` is the command-line tool for local Picked development. It generates TypeScript
+types from your workspace schema and lets you switch which project or workspace your local
+tooling loads — without hand-editing `picked.config.ts`.
 
 ## Installation
 
-`@picked/cli` installs as a dev dependency and gives you the binary `picked`. It reads
-`picked.config.ts` from the current directory, so it runs from your project root. See
-[How to authenticate the CLI](/how-to/authenticate-the-cli) to install it and sign in.
+The [`picked`](/reference/sdk) package holds this command, the client, and the
+`picked.config` helpers:
 
-The `picked` package holds this command too, so a project that installs `picked` has it
-already.
+```bash
+npm install picked
+```
+
+The command reads `picked.config.ts` from the current directory, so run it from your
+project root. See [How to authenticate the CLI](/how-to/authenticate-the-cli) to sign in.
+
+`@picked/cli` holds the command on its own, for a project that wants no other part of the
+package.
 
 ## Commands
 
@@ -24,7 +30,7 @@ already.
 | --- | --- |
 | `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`. |
@@ -101,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
@@ -114,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`. |
 
@@ -124,7 +128,8 @@ Tooling — `picked generate types` and the
 [Vite plugin](/reference/tools/vite-plugin) — resolves the configuration in this order. Each
 layer supersedes the layer before it:
 
-1. **`picked.config.ts`** — the committed default, `projectId` and `source`.
+1. **`picked.config.ts`** — the committed default: `projectId`, `source`, and
+   `previewToken`.
 2. **`.picked/settings.json`** — the per-developer active selection that
    `picked workspace use` writes. It supersedes `projectId` and `source`, and Git ignores it.
 3. **Environment variables** — `PICKED_PROJECT_ID` and `PICKED_PREVIEW_TOKEN` supersede

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

@@ -106,12 +106,34 @@ After the dev server starts, the launcher URL appears next to the Vite output:
 
 ## Options
 
-| Option           | Type                  | Default                  | Description                                               |
-| ---------------- | --------------------- | ------------------------ | --------------------------------------------------------- |
-| `projectId`      | `string`              | —                        | **Required.** The ID of your Picked project.              |
-| `apiUrl`         | `string`              | `https://api.picked.app` | Your own API URL, for a self-hosted or local API.         |
-| `disableLauncher`| `boolean`             | `false`                  | Turns the launcher page off in both dev and build output. |
-| `mode`           | `'bundle' \| 'api'`   | `'bundle'`               | Whether the build carries your project data.              |
+Project identity belongs in [`picked.config.ts`](/reference/sdk/type-generation). The two
+options that carry it are deprecated, and the table marks them.
+
+| Option           | Type                  | Default                  | Description                                                |
+| ---------------- | --------------------- | ------------------------ | ---------------------------------------------------------- |
+| `disableLauncher`| `boolean`             | `false`                  | Turns the launcher page off in both dev and build output.  |
+| `generateTypes`  | `boolean`             | `true`                   | Whether the plugin writes types from the workspace schema. |
+| `mode`           | `'bundle' \| 'api'`   | `'bundle'`               | Whether the build carries your project data.               |
+| `projectId`      | `string`              | —                        | **Deprecated.** Use `picked.config.ts`.                    |
+| `apiUrl`         | `string`              | —                        | **Deprecated.** Use `picked.config.ts`.                    |
+
+### projectId and apiUrl
+
+These two options moved to [`picked.config.ts`](/reference/sdk/type-generation), which the
+`picked` command and type generation also read. A later release removes them.
+
+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.
+
+### generateTypes
+
+The plugin reads the workspace schema and writes `picked-env.d.ts`, on `vite dev` and on
+`vite build`. [Type generation](/reference/sdk/type-generation) describes the output and
+the `picked.config.ts` options that control it.
+
+A failure stops the run. Set `generateTypes: false` for a build that must not write types,
+such as a build for one more entry point.
 
 ### mode
 

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/client @picked/react effector effector-react
+npm install picked @picked/react
 ```
 
 ```bash [Svelte]
-npm install @picked/client @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}>
@@ -177,7 +176,7 @@ match the component name that you entered in step 4.
 :::code-group
 
 ```tsx [React]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 import { adaptReactComponent } from '@picked/react'
 import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
@@ -195,7 +194,7 @@ picked.start()
 ```
 
 ```ts [Svelte]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 import { adaptSvelteComponent } from '@picked/svelte'
 import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'

package/dist/docs/tutorials/first-server-rendered-page.mdx

@@ -76,7 +76,7 @@ a snapshot as plain JSON.
 Make one client for each request, in `server.ts`:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { serialize } from '@picked/client/server'
 
 const client = createClient(options)
@@ -107,7 +107,7 @@ Register the component under the same name that the page uses. Here it is `CMSPa
 :::code-group
 
 ```tsx [React]
-import type { CreateClientOptions } from '@picked/client'
+import type { CreateClientOptions } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
 import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
@@ -136,7 +136,7 @@ export function Page({ snapshot }) {
 
 ```svelte [Svelte]
 <script lang="ts">
-  import type { CreateClientOptions } from '@picked/client'
+  import type { CreateClientOptions } from 'picked'
   import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
   import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
   import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'

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 };