@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.2

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,90 +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 full workspace state                               |
-| `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      |
-| `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      |
-
-### 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  |
-| `publish_workspace` | Publishes the workspace                        |
-
-## 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`"
-
-## 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.
-- 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)

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

@@ -1,163 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Vite Plugin
-
-`@picked/vite-plugin-picked` adds Picked to your Vite project. It reads the options
-of your project at build time. It then puts them in a module that gives them to the
-SDK, so the SDK makes no API request at runtime. In development it also serves a
-launcher page. On that page you can see a preview of an experience with your own
-feature flag values.
-
-## How it works
-
-### Build-time config injection
-
-When Vite starts, in both `dev` and `build`, the plugin does this:
-
-1. It reads the configuration of your project from the Picked API.
-2. It embeds those options in your bundle.
-3. The module gives the options to the SDK as the browser loads it.
-4. The SDK reads the embedded configuration at runtime and makes no network request.
-
-Step 3 is a function call. The module gives the options to the SDK as it loads, and does
-not wait for the SDK to ask.
-
-When a preview token is there at runtime, the SDK ignores the embedded configuration and
-reads fresh data from the API.
-
-### Preload of the data file
-
-Vite puts the options of your project in their own JavaScript file. For each HTML page
-in your build, the plugin adds a `<link rel="modulepreload">` for that file. The
-browser then gets it while it reads the page, and not later when the SDK starts.
-
-The CMS content of an experience stays in its own file and gets no preload. The
-browser gets it only when an experience needs it.
-
-Some applications make their HTML from the code, and not from an HTML file in your
-project. React Router in server mode is one of these. Such a build has no page for the
-plugin to add the link to. Add this line to the code that runs in the browser instead:
-
-:::code-group
-
-```ts [entry.client.ts]
-import 'virtual:picked/data'
-```
-
-:::
-
-Your framework then sees the file in its own list and adds the preload for you.
-
-The line reads no value from the module. It is there for the work the module does as it
-loads. A bundler removes a module that only declares values, and removes the line with
-it. This module gives your project options to the SDK, which is work, so the bundler
-keeps both.
-
-Your application is correct without this line. The SDK gets the same data later, as it
-starts. The line moves that work earlier.
-
-### Types for the data file
-
-The plugin makes `virtual:picked/data` at build time. Because the module is not a file in
-your project, TypeScript cannot find its types. The plugin gives you a type file for the
-module. Point your project at that type file to import from the module:
-
-:::code-group
-
-```json [tsconfig.json]
-{
-  "compilerOptions": {
-    "types": ["@picked/vite-plugin-picked/client"]
-  }
-}
-```
-
-```ts [picked-data.ts]
-/// <reference types="@picked/vite-plugin-picked/client" />
-```
-
-:::
-
-Use one of the two. The `types` option applies to all files in your project. The
-`reference` comment applies to one file.
-
-The module gives three values: `projectConfig`, `experienceContent` and
-`manifestMetadata`. You do not give these values to the SDK. The module gives them to
-the SDK itself as the browser loads it.
-
-### Dev launcher
-
-In development, the plugin serves an HTML page at `/`. On that page you can:
-
-- see every feature flag in your project with its current state;
-- turn a feature flag on or off for a local test;
-- see a preview of an experience with your own feature flag values.
-
-After the dev server starts, the launcher URL appears next to the Vite output:
-
-```
-  ➜  Picked:  http://localhost:5173/
-  ➜  Local:   http://localhost:5173/
-  ➜  Network: use --host to expose
-```
-
-## Options
-
-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
-
-`'bundle'` reads your project options at build time and puts them in your bundle.
-
-`'api'` does not read them. Your build then makes no request to the Picked API, and
-writes no `.picked` directory. The SDK reads your project options from the API at
-runtime instead. Use this when your build must not depend on the Picked API.
-
-The SDK has no equivalent option. It uses the data your build gives it, and the API when
-your build gives none.
-
-## Build output
-
-For a production build, `vite build`, the plugin writes an `index.html` file that
-holds the launcher page. Set `disableLauncher` to stop this. The file lets you deploy
-the launcher next to your application, so that a stakeholder can see a preview.
-
-The plugin writes that file only when your build made no `index.html` of its own. An
-application that has an HTML entry keeps its own page at the root of the output.
-
-The plugin also writes a `.picked` directory next to your Vite `root`. It holds the
-options of your project and the CMS content of each experience.
-
-## Related
-
-- [How to install the Vite plugin](/how-to/install-the-vite-plugin)

package/dist/docs/tutorials/first-api-call.md

@@ -1,228 +0,0 @@
----
-type: tutorial
-layout: docs
----
-
-# Your first API call
-
-In this tutorial we make your first calls to the Picked management API. We start with a
-ping, then authenticate, then read your user and make an organization.
-
-At the end you have an access token and two answers from the API.
-
-## Before you start
-
-- A Picked account, with an email address and a password.
-- `curl`, or any HTTP client.
-
-:::note
-This tutorial covers the GraphQL management API, which needs authentication. To serve
-published configuration and page content to your application, use the read-only
-[Delivery API](/reference/delivery-api) instead.
-:::
-
-## Playground
-
-Read the API and run a query in the
-[GraphQL Playground](https://api.picked.app/api/graphql).
-
-## API endpoint
-
-All requests go to a single endpoint:
-
-```
-POST https://api.picked.app/api/graphql
-```
-
-Every request must use the `POST` method. The JSON body must hold a `query` field,
-and it can also hold a `variables` field:
-
-```json
-{
-  "query": "query { ... }",
-  "variables": { }
-}
-```
-
-Set the `Content-Type` header to `application/json` on every request.
-
-```bash
-curl -X POST https://api.picked.app/api/graphql \
-  -H "Content-Type: application/json" \
-  -d '{"query": "{ ping }"}'
-```
-
-## Ping the API
-
-Check that the API is reachable with the `ping` query. This query needs no
-authentication.
-
-```graphql
-query {
-  ping
-}
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "ping": "pong"
-  }
-}
-```
-
-This response means that the API is ready.
-
-## Authenticate
-
-Most operations need an access token. To get one, create a session with your email
-address and your password.
-
-```graphql
-mutation {
-  sessionCreate(input: {
-    email: "you@example.com"
-    password: "your-password"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-    }
-    requiresMfa
-  }
-}
-```
-
-A successful response returns a `Session` with an `accessToken` and a
-`refreshToken`:
-
-```json
-{
-  "data": {
-    "sessionCreate": {
-      "session": {
-        "accessToken": "eyJhbGciOiJIUzI1NiIs...",
-        "refreshToken": "v1.refresh-token...",
-        "expiresAt": "2025-01-15T12:00:00Z"
-      },
-      "requiresMfa": false
-    }
-  }
-}
-```
-
-When `requiresMfa` is `true`, you must complete the MFA challenge before you receive
-a session. See the [Authentication](/reference/management-api/authentication) guide.
-
-For a server-to-server integration, use
-[API key authentication](/how-to/authenticate-with-an-api-key) and not a
-session token.
-
-## Make an authenticated query
-
-Pass the access token in the `Authorization` header as a Bearer token:
-
-```
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-```
-
-You can now query a resource that needs authentication. This example reads your user
-profile:
-
-```graphql
-query {
-  user {
-    id
-    email
-    createdAt
-    organizations(first: 5) {
-      edges {
-        node {
-          id
-          name
-        }
-      }
-    }
-  }
-}
-```
-
-## Make a mutation
-
-A mutation follows the same pattern. Send a `POST` request with the `Authorization`
-header. This example creates an organization:
-
-```graphql
-mutation {
-  organizationCreate(input: {
-    name: "My Company"
-    slug: "my-company"
-  }) {
-    organization {
-      id
-      name
-      slug
-    }
-  }
-}
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "organizationCreate": {
-      "organization": {
-        "id": "org_abc123",
-        "name": "My Company",
-        "slug": "my-company"
-      }
-    }
-  }
-}
-```
-
-Every mutation takes an `input` argument and returns a payload object. On success the
-payload holds the resource that the mutation created or updated. On failure the
-`errors` array at the top level holds the errors.
-
-## Errors
-
-When something goes wrong, the API returns the errors in the standard GraphQL
-`errors` array:
-
-```json
-{
-  "data": null,
-  "errors": [
-    {
-      "message": "Invalid credentials",
-      "extensions": {
-        "code": "INVALID_CREDENTIALS"
-      }
-    }
-  ]
-}
-```
-
-Read the `extensions.code` field. It holds an error code that your code can act on.
-See the [Errors](/reference/management-api/error-handling) guide for the full list of codes.
-
-## What you built
-
-You authenticated against the management API, read your own user, and created an
-organization. Every other operation follows the same shape: a `POST` to one endpoint,
-with your token in the `Authorization` header.
-
-## Where to go next
-
-- [Authentication](/reference/management-api/authentication) — an email address and a password, OAuth,
-  magic links, MFA, API keys, and how to control a session.
-- [Authorization and Scopes](/reference/management-api/authorization-and-scopes) — what each role can
-  reach, and how a scope controls a permission.
-- [Pagination](/reference/management-api/pagination) — how to move through a large result with a cursor.
-- [Errors](/reference/management-api/error-handling) — every error code that the API can return.