@picked/client 0.0.101-next.2 → 0.0.101

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

@@ -1,292 +0,0 @@
----
-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 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 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/dist/docs/reference/tools/image-optimisation-service.md

@@ -1,104 +0,0 @@
----
-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/dist/docs/reference/tools/mcp.md

@@ -1,136 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# MCP server
-
-Control your Picked workspace from an AI tool that writes code, with the Model
-Context Protocol (MCP).
-
-## Tools
-
-### Discovery
-
-| Tool                     | Description                                                    |
-| ------------------------ | -------------------------------------------------------------- |
-| `list_projects`          | Lists your organizations and projects                          |
-| `list_workspaces`        | Lists the workspaces in a project                              |
-| `get_workspace_overview` | Reads the live version and the workspace draft                 |
-| `get_schema_info`        | Reads the documentation for Picked concepts and the data model |
-| `list_picked_docs`       | Lists every Picked documentation page with its URL             |
-| `read_picked_doc`        | Reads one documentation page, or one section of it             |
-
-### Experiences
-
-| Tool                     | Description                                                                                        |
-| ------------------------ | -------------------------------------------------------------------------------------------------- |
-| `create_experience`      | Creates an experience                                                                              |
-| `get_experience`         | Reads an experience, with its flow graph                                                           |
-| `list_experiences`       | Lists your experiences                                                                             |
-| `update_experience_flow` | Creates, updates, or deletes steps, conditions, actions, fields, nodes, and edges as one operation |
-
-### Steps, fields, conditions, and actions
-
-| Tool                                | Description                                                      |
-| ----------------------------------- | ---------------------------------------------------------------- |
-| `get_step` / `list_steps`           | Read steps                                                       |
-| `update_step`                       | Renames a step, or binds it to the content entry that it renders |
-| `get_field` / `list_fields`         | Read fields                                                      |
-| `get_condition` / `list_conditions` | Read conditions                                                  |
-| `get_action` / `list_actions`       | Read actions                                                     |
-
-### Feature flags
-
-| Tool             | Description                                     |
-| ---------------- | ----------------------------------------------- |
-| `create_feature` | Creates a feature flag                          |
-| `get_feature`    | Reads a feature flag                            |
-| `list_features`  | Lists your feature flags                        |
-| `update_feature` | Updates the name, description, state, or weight |
-
-### Workflows
-
-A workflow runs a graph of nodes when its trigger occurs. The trigger is a domain
-event or one action.
-
-| Tool                      | Description                                                                           |
-| ------------------------- | ------------------------------------------------------------------------------------- |
-| `list_workflows`          | Lists the workflows in a workspace, with search and sort                              |
-| `get_workflow`            | Reads a workflow, with its trigger, graph, warnings, and the paths that its nodes use |
-| `list_workflow_tools`     | Lists the tools that a tool node can run, with the arguments of each tool             |
-| `create_workflow`         | Creates a workflow with its trigger. You cannot change the trigger after this step    |
-| `update_workflow`         | Renames a workflow, and sets its visit cap                                            |
-| `update_workflow_graph`   | Creates, updates, or deletes nodes and edges as one operation                         |
-| `guide_delete_workflow`   | Gives the link to the workflow in the dashboard, where you delete it                  |
-| `list_workflow_runs`      | Lists the runs of a workflow, with the newest run first                               |
-| `get_workflow_run`        | Reads the status of a run and the reason for a failure                                |
-| `list_workflow_run_tasks` | Lists the nodes that a run started, and the leads and labels that each node changed   |
-| `test_run_workflow`       | Runs the draft of a workflow one time as a test, and shows what each node did         |
-
-If `update_workflow_graph` refuses a change, it saves nothing. The result names each
-node or edge that has a problem. If the origin node does not connect to a node, the
-change is saved, and the result gives a warning for that node.
-
-A workflow run uses the published version of the workflow. Publish the workspace to
-apply a change.
-
-`test_run_workflow` runs the draft, so you can test a change before you publish it. Give
-the `responses` of the action, or the `entity_id` of the event. The result shows the
-input, the output, the status, and the branch of each node.
-
-A tool that reads, such as `search_leads` or an `http` `GET`, runs. A tool that writes
-does not run: the result shows what it would send. A wait node does not wait. The test
-run saves nothing. You must have each scope that the workflow uses.
-
-### Analytics
-
-| Tool             | Description                                                     |
-| ---------------- | --------------------------------------------------------------- |
-| `query_pickedql` | Runs a PickedQL analytics query and returns the rows as a table |
-
-Call `get_schema_info` with the topic `pickedql` to see the tables, the virtual
-functions, and the dimension columns before you write a query.
-
-### Publish
-
-| Tool                         | Description                                                            |
-| ---------------------------- | ---------------------------------------------------------------------- |
-| `get_preview_url`            | Makes a preview URL for your unpublished work                          |
-| `guide_publish_workspace`    | Gives the link to publish the workspace in the dashboard               |
-| `list_workspace_versions`    | Lists the published versions of a project, and shows the live one      |
-| `compare_workspace_versions` | Shows the differences between the live version, a version, and a draft |
-
-The `list_*` and `get_*` tools read the workspace draft. The draft can be
-different from the live version that visitors see. Use
-`compare_workspace_versions` to see what is live and what changes when you publish.
-
-## Example prompts
-
-- "List my Picked projects and show me the options on each one"
-- "Create a feature flag called 'new-checkout' at 50% traffic"
-- "Create an experience with a step that collects an email address"
-- "Show me control and variant users by the device type for the last 30 days"
-- "Make a preview URL for my workspace on `https://example.com`"
-- "Create a workflow that adds the label `plan.pro` to each lead from the sign-up action"
-- "Show me why the last run of my workflow failed"
-- "Test my sign-up workflow with the email `a@example.com` and show me what each node does"
-
-## Tips
-
-- Ask your agent for a list of your projects first. Then ask it to read your
-  workspace and report the options on each record.
-- For a large experience, ask your agent about flow graphs and JSON Logic. The agent
-  can read the documentation for you.
-- An update to an experience flow is atomic. Your agent can create steps, fields,
-  nodes, and edges in one operation.
-- See a preview of your work on your site before you publish, to check that each page
-  is correct.
-- The `create_workflow` prompt tells your agent how to build a workflow. The resource
-  `picked://workflow/{workflowId}/graph` gives the graph of a workflow as JSON.
-- Ask your agent to run a PickedQL query on your analytics data. The agent can read
-  the schema, write the SQL, and explain the rows.
-
-## Related
-
-- [How to connect the MCP server](/how-to/connect-the-mcp-server)