@picked/client 0.0.73 → 0.0.74

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

@@ -13,21 +13,41 @@ ID from the dashboard.
 :::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
 ```
 
 :::
 
-## 2. Create and start the client
+`picked` gives you the client, the `picked.config` helpers, and the `picked` command. Your
+package manager adds `@picked/client` with it, which carries the runtime and holds the
+generated types.
+
+## 2. Add `picked.config.ts`
+
+Create this file in the root of your project. The `picked` command and the
+[Vite plugin](/reference/tools/vite-plugin) read your project identity from it:
+
+```typescript
+import { defineConfig } from 'picked/config'
+
+export default defineConfig({
+  projectId: 'your-project-id',
+})
+```
+
+[Type generation](/reference/sdk/type-generation) reads this file, and gives your fields,
+features and steps the types the workspace declares.
+
+## 3. Create and start the client
 
 :::code-group
 
 ```tsx [React]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
 
@@ -40,7 +60,7 @@ picked.start()
 ```
 
 ```ts [Svelte]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
 
@@ -54,9 +74,13 @@ picked.start()
 
 :::
 
+`picked` carries the client's root entry. Each deeper import path, such as
+`@picked/client/plugins/dynamic-experiences` and `@picked/client/server`, keeps its own
+name.
+
 `start()` is idempotent. A second call changes nothing on a client that started already.
 
-## 3. Add the optional plugins
+## 4. 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.
@@ -65,4 +89,5 @@ picked.start()
 
 - [Add Picked to your application](/tutorials/first-experience) — the whole path.
 - [SDK installation](/reference/sdk) — every client option.
+- [Type generation](/reference/sdk/type-generation) — types from your workspace.
 - [How to register a component](/how-to/register-a-component).

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

@@ -13,37 +13,49 @@ API request at runtime.
 :::code-group
 
 ```bash [npm]
-npm install @picked/vite-plugin-picked
+npm install @picked/vite-plugin-picked picked
 ```
 
 ```bash [pnpm]
-pnpm add @picked/vite-plugin-picked
+pnpm add @picked/vite-plugin-picked picked
 ```
 
 ```bash [yarn]
-yarn add @picked/vite-plugin-picked
+yarn add @picked/vite-plugin-picked picked
 ```
 
 :::
 
-## 2. Add it to your config
+## 2. Name your project
+
+Create `picked.config.ts` in the root of your project. The plugin reads your project
+identity from this file:
+
+```typescript
+import { defineConfig } from 'picked/config'
+
+export default defineConfig({
+  projectId: 'your-project-id',
+})
+```
+
+## 3. Add the plugin to your Vite config
 
 ```typescript
 import { defineConfig } from 'vite'
 import { picked } from '@picked/vite-plugin-picked'
 
 export default defineConfig({
-  plugins: [
-    picked({
-      projectId: 'your-project-id',
-    }),
-  ],
+  plugins: [picked()],
 })
 ```
 
 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.
 
+The plugin also writes `picked-env.d.ts`, which types your fields, features and steps
+against the workspace. See [Type generation](/reference/sdk/type-generation).
+
 :::note
 When a preview token is there at runtime, the SDK ignores the embedded configuration and reads
 fresh data from the API.
@@ -52,5 +64,6 @@ fresh data from the API.
 ## Related
 
 - [Vite plugin](/reference/tools/vite-plugin) — every option.
+- [Type generation](/reference/sdk/type-generation) — the `picked.config.ts` options.
 - [About how Picked works](/explanation/how-picked-works) — where build-time configuration sit
   in the startup order.

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

@@ -77,7 +77,7 @@ renders, and they commit the visitor to a bucket at that moment.
 The event bus works with any framework, and with none:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 
 const client = createClient({
   /* Put your client options here. */

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/register-a-component.md

@@ -17,7 +17,7 @@ the dashboard.
 :::code-group
 
 ```tsx [React]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { adaptReactComponent } from '@picked/react'
 import { MyWidget } from './MyWidget'
 
@@ -30,7 +30,7 @@ const picked = createClient({
 ```
 
 ```ts [Svelte]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { adaptSvelteComponent } from '@picked/svelte'
 import MyWidget from './MyWidget.svelte'
 

package/dist/docs/how-to/register-an-action-handler.md

@@ -15,7 +15,7 @@ Pass an `actions` object to `createClient()`. Each key must match an action key
 dashboard:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 
 const picked = createClient({
   projectId: 'your-project-id',

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/server-render-a-page.md

@@ -13,7 +13,7 @@ browser. You need a published Page and a server that renders React or Svelte.
 Create one client for each request, then call `serialize()`:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { serialize } from '@picked/client/server'
 
 const client = createClient(options)

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

@@ -0,0 +1,122 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to switch workspaces
+
+This guide shows you how to point your local tooling at a different project or workspace.
+Your application then renders that workspace's content and types on your machine. It expects
+a `picked.config.ts` and the [CLI](/reference/tools/cli).
+
+Your tooling reads the project and surface named in the committed `picked.config.ts`. The
+CLI writes your choice to `.picked/settings.json` instead. That file is per-developer and
+Git ignores it, so the committed default stays as it is and one command puts it back.
+
+See [Workspaces](/reference/dashboard/workspaces) for what Live, Draft, and Archived mean.
+
+## 1. Sign in
+
+```bash
+picked login
+```
+
+This opens your browser for a one-time OAuth sign-in and stores a session under
+`~/.picked/`. Confirm it with `picked whoami`. See
+[CLI authentication](/how-to/authenticate-the-cli).
+
+## 2. Find a workspace
+
+```bash
+picked workspace list
+```
+
+```
+Acme Corp. (acme-corporation)
+  Storefront [proj_a1b2]
+    Default Storefront [LIVE] (live)
+    Checkout rework [DRAFT]
+```
+
+Note the **project id** (`proj_a1b2`) and the name or the id of the workspace you want.
+
+## 3. Switch to the draft
+
+```bash
+picked workspace use --project proj_a1b2 --workspace ws_draft
+```
+
+```
+Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
+Generated types at /app/src/picked-env.d.ts
+```
+
+A command that names **one specific workspace** (draft, live, or archived):
+
+- writes the selection (and its [preview token](/reference/delivery-api/preview-caching-crawling)) to
+  `.picked/settings.json`,
+- switches the resolved `source` to `preview` for that project, and
+- regenerates `picked-env.d.ts` from that workspace's schema (skip with `--no-generate`).
+
+To browse instead, run `picked workspace use` with no flags. The interactive picker lists
+every project, with **Published (live version)** and each of its workspaces.
+
+## 4. See the draft in your app
+
+Both readers of the selection use `.picked/settings.json` with no change to your
+configuration:
+
+- **Type generation** now reads the draft schema. Rerun `picked generate types` after more
+  edits.
+- The **[Vite plugin](/reference/tools/vite-plugin)** reads the draft's configuration and
+  content in development and in a build. It sends the preview token to the
+  [Delivery API](/reference/delivery-api). Restart the dev server to apply a switch.
+
+Your application renders the unpublished draft on your machine, with types.
+
+## 5. Switch back to live
+
+```bash
+picked workspace use --project proj_a1b2
+```
+
+A command that names a project with no `--workspace`, or **Published (live version)** in the
+picker, discards the preview token and returns `source` to `published`. To confirm what is
+active:
+
+```bash
+picked status
+```
+
+```
+Config default: project proj_a1b2 (source: published)
+Active selection: none (using the config default).
+```
+
+## CI and headless runs
+
+`.picked/settings.json` is a local, per-developer file. Do not commit it. To choose one
+workspace in CI with no selection file, set the environment directly:
+
+```bash
+PICKED_PROJECT_ID=proj_a1b2 \
+PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
+  picked generate types --check
+```
+
+`PICKED_PREVIEW_TOKEN` applies only when the resolved `source` is `preview`. See the
+[CLI environment variables](/reference/tools/cli#environment-variables) for the full
+precedence order.
+
+:::note
+A preview token is a long-lived credential for one workspace. Keep it out of the version
+control system, as you do with each other credential. Git ignores `.picked/settings.json`
+for this reason, because `picked workspace use` writes a token there.
+:::
+
+## Related
+
+- [CLI](/reference/tools/cli) — every command and flag.
+- [Workspaces](/reference/dashboard/workspaces) — Live, Draft, and Archived states.
+- [Type generation](/reference/sdk/type-generation) — how the schema becomes types.
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — preview tokens on the Delivery API.

package/dist/docs/how-to/write-a-predicate.md

@@ -13,7 +13,7 @@ such as a cart total or an account level.
 Pass a `predicates` object to `createClient()`:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 
 const client = createClient({
   projectId: 'your-project-id',

package/dist/docs/reference/dashboard/api-keys.mdx

@@ -7,8 +7,9 @@ import { Screenshot } from '../../../../components/Screenshot'
 
 # API keys
 
-An API key lets your code reach the Picked API. Use one for a server-side integration
-or for a CI/CD workflow.
+An API key lets your code reach the Picked API. Use one where your own code calls the API,
+such as a server-side integration. It does not sign the
+[CLI](/reference/tools/cli) in.
 
 <Screenshot
   route="/{orgSlug}/api-keys"
@@ -17,11 +18,11 @@ or for a CI/CD workflow.
 
 ## Use an API key
 
-Put your API key in the `Authorization` header of each request to the
+Put your API key in the `x-api-key` header of each request to the
 [Picked API](/tutorials/first-api-call).
 
 ```
-Authorization: Bearer your-api-key
+x-api-key: your-api-key
 ```
 
 ## Scopes

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

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Workspace Schema Endpoint
+
+A JSON Schema document for the structure of your project: content models, fields, feature keys, experience keys, and step keys. Tooling reads this endpoint to generate TypeScript types for your application.
+
+## Request
+
+```
+GET /api/v1/projects/:projectId/schema
+```
+
+| Parameter | In | Description |
+| --- | --- | --- |
+| `projectId` | path | The project whose schema to fetch. |
+| `preview_token` | query | Optional. Returns the preview (unpublished) schema when you send it. |
+
+## Response
+
+The response is a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/schema) document with Picked-specific extension fields:
+
+| Field | Description |
+| --- | --- |
+| `x-picked-schema-version` | Schema document version (currently `1`). |
+| `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. |
+| `$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. |
+| `$defs.featureKeys` | String enum of feature keys. |
+| `$defs.experienceKeys` | String enum of experience keys. |
+| `$defs.stepKeys` | String enum of step keys. |
+
+## Published and preview
+
+On the published surface, the schema reflects your last published workspace. On the preview surface (`?preview_token=...`), the schema reflects the current draft workspace. See [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
+
+When no published schema exists, the published endpoint returns `404` and tells you to publish the workspace.
+
+## Example
+
+```bash
+curl https://api.picked.app/api/v1/projects/proj_123/schema
+```
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "picked:project/proj_123/schema",
+  "x-picked-schema-version": 1,
+  "x-picked-source": "published",
+  "x-picked-version-id": "ver_456",
+  "x-picked-step-content-models": {
+    "intro": "welcome-page"
+  },
+  "$defs": {
+    "contentModels": {},
+    "contentBlocks": {},
+    "fields": { "type": "object", "additionalProperties": false, "properties": {} },
+    "featureKeys": { "type": "string", "enum": ["default"] },
+    "experienceKeys": { "type": "string", "enum": ["welcome-survey"] },
+    "stepKeys": { "type": "string", "enum": ["intro"] }
+  }
+}
+```
+
+## Related
+
+- [Type generation](/reference/sdk/type-generation) — Generate TypeScript types from this schema in your app.
+- [Project Config](/reference/delivery-api/project-config) — Runtime project configuration for the SDK.

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>
@@ -201,7 +198,7 @@ React and Svelte.
 | `deriveReferences(contents, value)` | `Store<Content[]>` | The store behind `useReferences` and `getReferences`. |
 
 ```ts
-import { createClient, readReferenceIds } from '@picked/client'
+import { createClient, readReferenceIds } from 'picked'
 
 const client = createClient({ projectId: 'proj_123' })
 const content = client.contents.getById('entry_789').getState()

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

@@ -41,7 +41,7 @@ unique identifier, a version key, a name that a person can read, and a `decide`
 function:
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 
 const client = createClient({
   projectId: 'your-project-id',

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

@@ -32,7 +32,7 @@ content the same version.
 :::code-group
 
 ```ts [app.ts]
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
 
 const client = createClient({

package/dist/docs/reference/sdk/plugins/window-object.md

@@ -10,7 +10,7 @@ A plugin to add the Picked client to the window object
 ## Setup Plugin
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { windowObjectPlugin } from '@picked/client/plugins/window-object'
 
 const client = createClient({

package/dist/docs/reference/sdk/ssr/serialize.md

@@ -12,7 +12,7 @@ client.
 ## The `serialize(client, params)` function
 
 ```ts
-import { createClient } from '@picked/client'
+import { createClient } from 'picked'
 import { serialize } from '@picked/client/server'
 
 const client = createClient(options)

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 (
     <>