picked 0.0.101-next.2 → 0.0.101

package/docs/reference/tools/cli.md

@@ -0,0 +1,319 @@
+---
+type: reference
+layout: docs
+---
+
+# CLI
+
+`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`. It also copies the content of a
+workspace from one project to a different project.
+
+## Installation
+
+The [`picked`](/reference/sdk) package holds this command, the client, and the
+`picked.config` helpers:
+
+```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
+
+| Command | Description |
+| --- | --- |
+| `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. |
+| `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`. |
+| `picked workspace export` | Write a workspace, or the published version of a project, to a bundle directory. |
+| `picked workspace import` | Create a new draft workspace in a project from a bundle directory. `--publish` also publishes it. |
+| `picked generate types` | Read the workspace schema and write `picked-env.d.ts`. `--check` verifies and writes nothing. |
+| `picked docs list` | List the documentation pages. Words after `list` filter the list. `--type` and `--json` are available. |
+| `picked docs read` | Print one documentation page as Markdown. |
+
+### `picked generate types`
+
+Writes the typed schema declaration. See [Type generation](/reference/sdk/type-generation)
+for the `picked.config.ts` reference and the generated output.
+
+```bash
+picked generate types
+```
+
+In CI, `--check` writes nothing and fails when the committed types are stale:
+
+```bash
+picked generate types --check
+# → "Types are up to date (`…/src/picked-env.d.ts`)."  (status 0)
+# → "Types are out of date: `…/src/picked-env.d.ts`"   (status 1)
+```
+
+### `picked docs list` and `picked docs read`
+
+These commands print this documentation. They read the copy in the `picked` package, at
+`node_modules/picked/docs`. When that copy is not there, they read the index of
+`docs.picked.app`.
+
+```bash
+picked docs list
+picked docs list feature flag
+picked docs list --type how-to --json
+picked docs read /how-to/install-the-sdk
+```
+
+`picked docs list` prints one page on each line: the path, a tab, and the title.
+
+| Option | Description |
+| --- | --- |
+| `--type <type>` | Keeps one content type: `tutorial`, `how-to`, `reference` or `explanation`. |
+| `--json` | Gives the path, title, type, description and file of each page. |
+
+`picked docs read` accepts a page path, a `docs.picked.app` URL, or a file path below
+`node_modules/picked/docs`. The command `picked docs <path>` does the same thing. The first
+line of the output is a comment with the URL of the page. If no page has that path, the
+command names the closest pages and returns status 1.
+
+### `picked workspace list`
+
+```bash
+picked workspace list
+```
+
+```
+Acme Corp. (acme-corporation)
+  Storefront [proj_a1b2]
+    Default Storefront [LIVE] (live)
+    Checkout rework [DRAFT]
+```
+
+`--json` gives a machine-readable tree. Each prompt and heading goes to `stderr`, so the
+`stdout` of `--json` stays clean when you send it to another command.
+
+### `picked workspace use`
+
+Sets the active selection, then regenerates types. See
+[How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
+
+```bash
+picked workspace use                                  # interactive picker
+picked workspace use --project proj_a1b2              # the project's published (live) version
+picked workspace use --project proj_a1b2 --workspace ws_id      # preview a specific workspace via its token
+```
+
+```
+Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
+Generated types at /app/src/picked-env.d.ts
+```
+
+`--no-generate` sets the selection and leaves the types as they are.
+
+:::warning
+`picked workspace use` regenerates types by default. Types that no longer match the
+workspace give no error, and a developer can fail to see the problem for a long time. Use
+`--no-generate` only when you regenerate the types yourself.
+:::
+
+### `picked workspace export`
+
+Writes one workspace of a project to a bundle directory. The bundle holds every part of the
+workspace: features, steps, fields, actions, conditions, experiences, workflows, page
+layouts, sections, and content entries. It also holds a copy of each asset that the content
+entries use.
+
+```bash
+picked workspace export --project proj_a1b2 --live --out ./bundle
+picked workspace export --project proj_a1b2 --workspace ws_id --out ./bundle
+```
+
+```
+Exported workspace "Snapshot of Default Storefront" with 12 assets to /app/bundle
+```
+
+| Flag | Description |
+| --- | --- |
+| `--project <id>` | The project that holds the workspace. Required. |
+| `--live` | Write the version that the project serves now. The bundle does not include draft changes that you made after you published that version. |
+| `--workspace <id>` | Write this workspace, with its draft changes. The command stops with status 1 when you use `--live` and `--workspace` together. |
+| `--out <dir>` | The bundle directory. It must be in the current directory, and be empty or not exist. Required. |
+
+The command stops with status 1 when:
+
+- `--live` is used and the project has no published version.
+- The workspace is not in `--project`.
+- The API rejects the request. The message shows the error code and one line for each
+  problem.
+- The size of a downloaded asset, or its `sha256` hash, is different from the value in the
+  bundle manifest.
+
+The error code `UNRESOLVED_REFERENCE` shows that a part of the workspace refers to a part that
+the workspace does not have. For example, a content entry uses a deleted section, a flow
+goes to a deleted experience, or a workflow starts from a deleted action. Each line names the
+part, its key or name if it has one, the location of the reference in the part, and the
+missing id:
+
+```
+Export of workspace ws_id failed:
+  UNRESOLVED_REFERENCE: Cannot export experience 'exp_1' (key 'home'): flow node references experience 'exp_gone', which does not belong to the workspace, at flow_json.nodes.1.targetExperienceId (workspaceId)
+```
+
+Remove or change each reference, then run the command again.
+
+The credential needs the `organization_workspace/read` scope on the project. With `--live`,
+it also needs the `organization_projects/read` scope.
+
+#### Bundle directory
+
+| Path | Contents |
+| --- | --- |
+| `bundle.json` | The workspace. `formatVersion` is `1`. `assets` lists each asset version with its `fileName`, `mimeType`, `sizeBytes`, and `sha256` hash. |
+| `assets/<sha256>` | The bytes of one asset. The file name is the `sha256` hash of the bytes, in lowercase. |
+
+The command writes the bundle into a temporary directory next to `--out`, and writes
+`bundle.json` last. When the bundle is complete, the command moves it to `--out`. When the
+command fails, it removes the temporary directory, and you can run the same command again.
+
+Each request body and response body of the Picked API can be at most 4.5 MB. For a very
+large workspace, `picked workspace export` and `picked workspace import` fail when its
+`bundle.json` is larger than this limit. Asset files do not count, because the command
+downloads and uploads them directly.
+
+### `picked workspace import`
+
+Creates a new draft workspace in a project from a bundle directory, then prints the id of
+the new workspace. The command does not change the other workspaces of the project. It
+changes the published version only when you use `--publish`.
+
+```bash
+picked workspace import --project proj_c3d4 --in ./bundle --name "Copy of storefront" --publish
+```
+
+```
+Imported workspace "Copy of storefront" as ws_new into project proj_c3d4 (assets: 12 uploaded, 0 already in the project).
+Published workspace ws_new.
+```
+
+| Flag | Description |
+| --- | --- |
+| `--project <id>` | The project to import into. It can be in a different organization or a different API deployment. Required. |
+| `--in <dir>` | The bundle directory that `picked workspace export` wrote. It must be in the current directory. Required. |
+| `--name <name>` | The name of the new workspace. The default is the workspace name in the bundle. |
+| `--publish` | Publish the new workspace after the command creates it. |
+
+The command sends the `sha256` hash of each asset to the API before it uploads the asset.
+When the project already has an asset with the same bytes, the new workspace uses that
+asset. The command does not upload the bytes again. When you import the same bundle into
+the same project two times, the second command uploads no assets. Each command creates a
+new workspace.
+
+Every part of the workspace gets a new id in the target project. The key of an experience
+does not change. The nodes of a workflow keep their ids, and a workflow that starts from an
+action starts from the new copy of that action.
+
+The API calculates the scopes of each workflow from the tools that the workflow uses. For
+each tool scope that a workflow does not get by default, the credential must have that
+scope. If it does not, the API rejects the bundle with the error code
+`WORKFLOW_SCOPES_NOT_HELD`, and the message names the workflow, the tool and the scope.
+
+The command stops with status 1 when:
+
+- An asset file does not exist, or its size or `sha256` hash is different from the bundle
+  manifest. The command makes no API request in this case.
+- An asset upload fails.
+- The API rejects the bundle. The message shows the error code, for example
+  `UNSUPPORTED_FORMAT_VERSION`, `UNRESOLVED_REFERENCE` or `WORKFLOW_SCOPES_NOT_HELD`.
+- The API rejects the import request with a GraphQL error, for example because the
+  credential does not have the necessary scopes.
+- The import request fails on the API with a different GraphQL error, for example
+  `INFRASTRUCTURE_ERROR`.
+- The import request gets no GraphQL answer from the API, for example because of a network
+  failure, a timeout or an HTTP error. The import request has a longer timeout than the
+  other requests.
+- `--publish` is used and the API does not publish the workspace. The message shows the id
+  of the new draft workspace.
+
+When the API rejects the import request, the GraphQL error code is `FORBIDDEN`,
+`UNAUTHENTICATED`, `BAD_USER_INPUT` or `GRAPHQL_VALIDATION_FAILED`. When an asset upload
+fails or the API rejects the bundle or the import request, the API does not create a
+workspace. The command deletes the assets that it uploaded, and the message names them.
+Assets that were already in the project stay.
+
+When the import request fails with a different GraphQL error or gets no GraphQL answer,
+the new workspace can exist in the project. The command keeps the assets that it uploaded,
+and the message names them. When the project has no new workspace, no workspace uses these
+assets.
+
+The credential needs the `organization_projects/read`, `organization_projects/update` and
+`organization_workspace/update` scopes on the project. For a bundle with workflows, it also
+needs the scopes of their tools, as described above.
+
+## Authentication
+
+`picked login` signs in through the browser. It uses an authorization-code flow with PKCE
+against the Picked OAuth server. `picked whoami` prints the identity for the current origin.
+`picked logout` clears it.
+
+The CLI holds one auth config file for each API origin, outside each repository. Every
+command reads and writes only the origin that the current directory resolves to, and never
+a session for another API.
+
+| File | Contents |
+| --- | --- |
+| `~/.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. |
+
+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
+[dashboard sign-in](/reference/management-api/authentication).
+
+### API key
+
+When `PICKED_API_KEY` is set, each command that calls the API sends the key in the
+`X-API-Key` header. The CLI does not read the stored session. An
+[API key](/reference/dashboard/api-keys) lets a run that has no browser, for example a CI
+job, call the API. An API key for one project can read and write only that project.
+
+An API key does not identify a user. When `PICKED_API_KEY` is set, `picked login`,
+`picked whoami`, and `picked workspace list` stop with status 1.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `PICKED_API_URL` | The API origin that the CLI reads. Supersedes `picked.config` `apiUrl` and the `https://api.picked.app` default. |
+| `PICKED_API_KEY` | An API key. When set, the CLI sends it as `X-API-Key` in place of the stored session. |
+| `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`. |
+
+### How the selection resolves
+
+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`, `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
+   both, for a CI or headless run.
+
+`picked status` prints the resolved result.
+
+## Related
+
+- [How to authenticate the CLI](/how-to/authenticate-the-cli) — install and sign in.
+- [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
+- [Type generation](/reference/sdk/type-generation) — `picked.config.ts` and the generated types.
+- [Vite plugin](/reference/tools/vite-plugin) — reads the same selection in development and in a build.
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how a preview token behaves.

package/docs/reference/tools/delivery-api-client.md

@@ -0,0 +1,60 @@
+---
+type: reference
+layout: docs
+---
+
+# Delivery API client
+
+`@picked/delivery-api-client` gives typed functions for the
+[Delivery API](/reference/delivery-api). The Picked SDK uses it, and you can use it on a
+server or in a script.
+
+```ts
+import { fetchExperienceContent, fetchProject, fetchSchema } from '@picked/delivery-api-client'
+
+const config = await fetchProject('https://api.picked.app', 'your-project-id')
+const content = await fetchExperienceContent(
+  'https://api.picked.app',
+  'your-project-id',
+  'your-experience-id',
+)
+const schema = await fetchSchema('https://api.picked.app', 'your-project-id')
+```
+
+## Functions
+
+| Function | Endpoint | Returns |
+| --- | --- | --- |
+| `fetchProject(apiUrl, projectId, options?)` | [Project config](/reference/delivery-api/project-config) | `Promise<ProjectConfig \| null>` |
+| `fetchExperienceContent(apiUrl, projectId, experienceId, options?)` | [Experience content](/reference/delivery-api/experience-content) | `Promise<ExperienceContentResponse \| null>` |
+| `fetchSchema(apiUrl, projectId, options?)` | [Workspace schema](/reference/delivery-api/workspace-schema) | `Promise<WorkspaceSchema \| null>` |
+| `runAction(apiUrl, payload, options?)` | `POST /api/v1/action/<key>/run` | `Promise<RunActionResult>` |
+| `createClientHeaders(name, version)` | none | The `Picked-Client` and `Picked-Version` headers. |
+
+`apiUrl` is the origin of the API, for example `https://api.picked.app`.
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `previewToken` | `string` | Reads the draft of a workspace. See [Preview](/how-to/preview-a-workspace). |
+| `headers` | `Record<string, string>` | More request headers. |
+| `signal` | `AbortSignal` | Stops the request. |
+| `onWarn` | `(message: string, error?: unknown) => void` | Receives each failure of a fetch function. |
+| `onResponse` | `(status: number) => void` | Receives the HTTP status of `fetchProject` and `fetchExperienceContent`. |
+
+`runAction` takes only `previewToken`, `headers` and `signal`.
+
+## Errors
+
+Each request stops after 10 seconds.
+
+| Function | On failure |
+| --- | --- |
+| `fetchProject`, `fetchExperienceContent`, `fetchSchema` | Returns `null` and calls `onWarn`. A failure is a network error, a status that is not `ok`, a body that is not JSON, or a body with the wrong shape. |
+| `runAction` | Throws an `Error` for a status that is not `ok`. |
+
+## Related
+
+- [Delivery API](/reference/delivery-api)
+- [About the two APIs](/explanation/the-two-apis)

package/docs/reference/tools/image-optimisation-service.md

@@ -0,0 +1,104 @@
+---
+type: reference
+layout: docs
+---
+
+# Image optimisation service
+
+The Picked service for image optimisation is a hosted endpoint at
+`https://img.picked-content.com`. It reads an image from an allowed source domain and
+resizes it. It then encodes the image again to a modern format, WebP or AVIF, and
+caches the result.
+
+## Endpoint
+
+```
+GET https://img.picked-content.com/_next/image?url={source}&w={width}&q={quality}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `url` | The URL of the source image, URL-encoded. It must point at an allowed source domain. See below. |
+| `w` | The width in pixels. It must be one of the supported widths. |
+| `q` | The quality: `25`, `50`, `75`, or `100`. |
+
+The service chooses the response format. When the browser advertises `image/avif` or
+`image/webp` in its `Accept` header, the response uses that format. If it does not,
+the response uses the source format.
+
+## Allowed source domains
+
+The service reads only from these hostnames:
+
+- `**.picked.app`
+
+A request with a `url` parameter for any other hostname returns `400 Bad Request`.
+
+## Supported widths
+
+Device sizes, for a responsive image that spans the width of the viewport:
+
+```
+640, 750, 828, 1080, 1200, 1920, 2048, 3840
+```
+
+Image sizes, for a UI element of fixed size such as an icon, an avatar, or a
+thumbnail:
+
+```
+16, 32, 48, 64, 96, 128, 256, 384
+```
+
+A request with any other width returns `400 Bad Request`. Choose the smallest width
+that covers the size you render at the device pixel ratio of the visitor.
+
+## Supported qualities
+
+```
+25, 50, 75, 100
+```
+
+A lower value reduces the bandwidth by a large amount. `75` is a good default for
+most images. Use `25` or `50` for a thumbnail on a slow network.
+
+## Responsive images
+
+Use the endpoint together with the standard `srcset` attribute. The browser then
+picks the correct width for each viewport:
+
+```html
+<img
+  src="https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75"
+  srcset="
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=640&q=75 640w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75 1080w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1920&q=75 1920w
+  "
+  sizes="(max-width: 768px) 100vw, 720px"
+  alt="..."
+/>
+```
+
+## Cache
+
+The upstream CDN caches each optimised response. The smallest cache TTL is 60
+seconds. The real lifetime depends on the eviction policy of the CDN. When you change
+the source image at the same URL, the optimised copy stays in the cache for at least
+that time.
+
+## Security
+
+- The service does not optimise an SVG source. A request for an SVG returns the
+  original bytes when the source is allowed. The service never runs an embedded
+  script.
+- Each optimised response carries a strict `Content-Security-Policy`
+  (`default-src *; script-src 'none'; sandbox;`). A compromised source therefore
+  cannot run a script in the browser that shows the image.
+- The response uses `Content-Disposition: inline`, and never `attachment`.
+
+## Related
+
+- [Asset library](/reference/dashboard/content/asset-library) — where the images come
+  from.
+- [Content Security Policy](/reference/sdk/content-security-policy) — the `img-src`
+  entry this service needs.

package/docs/reference/tools/mcp-run.md

@@ -0,0 +1,121 @@
+---
+type: reference
+layout: docs
+---
+
+# MCP run tool
+
+`picked_run` is a tool of the [MCP server](/reference/tools/mcp). It runs JavaScript that
+you write against the Picked API. Each MCP tool is a function on the `tools` object. Only
+the value that your code returns goes back to your agent.
+
+Use `picked_run` when a task needs many tool calls, for example to read each experience in
+a workspace. For one call, use the tool directly.
+
+## Arguments
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` | `string` | None | The body of a JavaScript function. Use `return` to send back a result. |
+| `allow_writes` | `boolean` | `false` | Lets the code call the tools that change data. Without it, the code can only read. |
+
+## Call a tool
+
+Call a tool with `await` and one object of arguments. The arguments have the same names as
+the arguments of the MCP tool.
+
+```js
+const { experiences } = await tools.list_experiences({ workspace_id: 'YOUR_WORKSPACE_ID' })
+
+return experiences.map(({ id, name, status }) => ({ id, name, status }))
+```
+
+Many how-to guides end with an `## API and MCP` section. Its Run column shows the call for
+each task, for example `tools.update_step({ step_id, layout_content_entry_id })`. Each name
+in the call is an argument. Give a value to each one.
+
+## Find a tool
+
+- `picked_search_api` finds the tools that match the words you give, for example
+  `content entry update`.
+- `picked_describe_api` gives the arguments and the result of each tool that you name. With
+  no names, it lists each tool on one line.
+
+## Do many calls
+
+Use `Promise.all` to start many calls together. The run does a maximum of eight calls at
+the same time. Each other call waits until a call is complete.
+
+```js
+const { experiences } = await tools.list_experiences({ workspace_id: 'YOUR_WORKSPACE_ID' })
+const results = await Promise.all(
+  experiences.map(({ id }) => tools.get_experience({ experience_id: id })),
+)
+
+return results.map(({ experience }) => ({
+  name: experience.name,
+  nodes: experience.flow_json.nodes.length,
+}))
+```
+
+:::warning
+Do not change one entity with two calls at the same time. The two calls read the same data,
+and the call that completes last removes the change of the other call. The two calls both
+report success. Use `await` on each change to an entity before you start the next change to
+it.
+:::
+
+## Get each page of a list
+
+A list tool gives a maximum of 100 rows for each call. To get the next page, give the value
+of `pageInfo.endCursor` as `after`. Stop when `pageInfo.hasNextPage` is `false`.
+
+```js
+const drafts = []
+let after
+
+do {
+  const page = await tools.list_experiences({ workspace_id: 'YOUR_WORKSPACE_ID', after })
+  for (const experience of page.experiences) {
+    if (experience.status === 'draft') drafts.push(experience.name)
+  }
+  after = page.pageInfo.hasNextPage ? (page.pageInfo.endCursor ?? undefined) : undefined
+} while (after)
+
+return drafts
+```
+
+## Errors
+
+If a tool call fails, its promise rejects. `error.message` gives the reason, and
+`error.code` gives a code that does not change. Put `try` and `catch` around a call, and
+the run continues after an item that fails. If you do not have permission for a call, the run stops.
+
+## Result
+
+The result of a run shows these items:
+
+- The value that the code returns.
+- The text that the code writes with `console.log`. This text is also there when the run
+  fails.
+- Each tool that the code called, with the number of calls, the time that they took, and
+  the calls that failed.
+
+Return only the data that you need. A full tool result costs more than the same result
+from a direct call to the tool, because a direct call gives a short text.
+
+## Limits
+
+- A run stops after 20 seconds.
+- The code has no network access, no file system, and no `eval`.
+- The code can use `JSON`, `Math`, `Date`, `Map`, `Set`, `Promise` and `RegExp`.
+- The code cannot use `fetch`, `crypto`, `Buffer`, `URL`, `Intl`, `structuredClone` or
+  `setTimeout`.
+- Each tool call uses your permissions. A tool that you cannot use from the MCP server is
+  not available in a run.
+
+## Related
+
+- [MCP server](/reference/tools/mcp)
+- [How to connect the MCP server](/how-to/connect-the-mcp-server)
+- [Management API schema](/reference/management-api/schema)