@picked/client 0.0.101-next.2 → 0.0.101

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,235 +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
-      aal
-      user {
-        mfa { required enrolled }
-      }
-    }
-  }
-}
-```
-
-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",
-        "aal": "AAL1",
-        "user": {
-          "mfa": { "required": false, "enrolled": false }
-        }
-      }
-    }
-  }
-}
-```
-
-When `required` is `true`, the token can only read `user` and call the MFA mutations
-until you verify a code from an authenticator app. See
-[How to set up MFA](/how-to/set-up-mfa).
-
-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.

package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx

@@ -1,143 +0,0 @@
----
-type: tutorial
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Build your first experience
-
-In this tutorial we build a survey and show it to your visitors. We do all of it in the
-Picked dashboard.
-
-At the end you have one experience, one step, one field, and a preview of the survey on
-your own site.
-
-## You will need
-
-**A Picked account, in an organization.** An organization holds your projects and the
-people who work on them. If you have an invitation, accept it and sign in. If nobody made
-an organization yet, make one from the dashboard home page.
-
-**A project.** A project is one site or one application. See
-[How to create a project](/how-to/create-a-project). Keep the project home page open,
-because it shows the SDK snippet that the next item needs.
-
-**The URL of your site**, such as `https://www.example.com`. Step 5 opens it to show you
-the survey. It can be a test site.
-
-## What a developer must do first
-
-The SDK must be on your site before step 1. This happens one time, and after it you need
-no developer again. Send them these four tasks:
-
-1. Add the SDK to the site. The snippet and the project ID are on the project home page.
-   See [How to install the SDK](/how-to/install-the-sdk).
-2. Make a component that renders a step form.
-3. [Register that component](/how-to/register-a-component) under the name `ColorSurvey`.
-   Step 3 enters the same name in the dashboard, and the two names must match.
-4. Tell you which site the SDK runs on, so you can open a preview against it.
-
-[Add Picked to your application](/tutorials/first-experience) walks a developer through
-all of it.
-
-## 1. Make a field
-
-A field collects one answer from your visitor.
-
-1. Open your project.
-2. Click **Fields** in the sidebar.
-3. Click **New field**.
-4. Enter the name `Color`. The dashboard fills in the label and the key for you.
-5. Change the label to `Which color do you like most?`. Your visitors read the label, and
-   they never see the name or the key.
-6. Leave the key as `color`. You cannot change it later.
-7. Choose the type **Text**.
-8. Click **Create field**.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields/new"
-  alt="The new field form, with a name, a label, and a key entered"
-  fill={{ 'input[name="name"]': 'Color', 'input[name="label"]': 'Which color do you like most?' }}
-/>
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
-  alt="The fields list for a workspace on the Picked dashboard"
-/>
-
-Your field appears in the fields list.
-
-## 2. Make the experience
-
-1. Click **Flows** in the sidebar. The experiences list opens.
-2. Click **New experience**.
-3. Enter the name `Color survey`.
-4. Leave **Type** on the **Flow** option. A flow is the interactive kind, and it is what
-   this tutorial builds. See [About pages and flows](/explanation/pages-and-flows) for the
-   other kind.
-5. Open **Advanced**.
-6. Enter the component name `ColorSurvey`. This is the name your developer registered.
-7. Click **Create flow**.
-
-The flow builder opens with an empty canvas. One gray circle sits on the left. That
-circle is the origin, and every flow starts there.
-
-## 3. Make a step
-
-A step is one screen that your visitor sees. It holds your field. You make one from the
-library, on the left of the flow builder.
-
-1. Find the **Steps** section in the library.
-2. Click the **+** next to it.
-3. Enter the name `Question`. The key fills in as `question`.
-4. Click **Create step**.
-
-The flow builder opens again, and your step is in the library.
-
-## 4. Build the flow
-
-1. Find your `Question` step under **Steps** in the library.
-2. Drag it onto the canvas.
-3. Drag from the output handle of the origin to the input handle of your step. An arrow
-   joins them.
-4. Drag your `Color` field from the library onto the step node.
-5. Click **Save** in the toolbar.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences/{experienceId}"
-  alt="The flow builder with the library, canvas, and inspector panels"
-/>
-
-The subtitle of the step node now reads one field. Your flow is one step long, and it
-starts at the origin.
-
-## 5. Preview it
-
-A preview opens your own site with this workspace applied. Your visitors see no change.
-
-1. Click **Preview** in the workspace toolbar.
-2. Enter the URL of your site.
-3. Click **Open preview**.
-
-Your site opens in a new tab, and your survey is on it. Enter a color and continue.
-
-## 6. Publish it
-
-1. Click **Publish** in the workspace toolbar.
-2. Read the change preview. It lists what your visitors get.
-3. Click **Publish** to confirm.
-
-Your survey is live.
-
-## What you built
-
-You have an experience that your visitors see. The dashboard holds the flow, the step, and
-the field, so you change any of them and publish again without a deployment.
-
-## Where to go next
-
-- [How to build a flow](/how-to/build-a-flow) — branches, actions, and conditions.
-- [How to run an A/B test](/how-to/run-an-ab-test) — show a change to some visitors.
-- [About how Picked works](/explanation/how-picked-works) — what happens when you
-  publish.