@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

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

@@ -0,0 +1,228 @@
+---
+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](/reference/management-api/authentication#api-key-authentication) 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

@@ -0,0 +1,143 @@
+---
+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.

package/dist/docs/tutorials/first-experience.mdx

@@ -0,0 +1,255 @@
+---
+type: tutorial
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# Add Picked to your application
+
+In this tutorial we make a color survey and put it on a page. We build the flow in the
+Picked dashboard, connect the SDK to it, and see the survey in a browser.
+
+At the end you have one experience, one step, one field, and a page that shows them.
+
+## Before you start
+
+- A Picked account, and an organization in it.
+- Node 20 or later.
+- A web application that runs React or Svelte. A new Vite application is enough.
+
+## 1. Make a project
+
+A project is one site or one application.
+
+1. Sign in to the dashboard.
+2. Open your organization.
+3. Click **New Project**.
+4. Enter the name `Tutorial`.
+5. Click **Create**.
+
+The project home page opens. It shows a project ID near the top. Copy that ID. Every step
+after this one needs it.
+
+## 2. Make a field
+
+A field collects one answer from your visitor.
+
+1. Click **Fields** in the sidebar.
+2. Click **New field**.
+3. Enter the name `Color`. The dashboard fills in the label and the key for you.
+4. Change the label to `Which color do you like most?`.
+5. Leave the key as `color`.
+6. Choose the type **Text**.
+7. Click **Create field**.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
+  alt="The fields list for a workspace on the Picked dashboard"
+/>
+
+The field now appears in the fields list.
+
+## 3. 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.
+5. Open **Advanced**.
+6. Enter the component name `ColorSurvey`.
+7. Click **Create flow**.
+
+The flow builder opens with an empty canvas. One gray circle is on the left. That circle
+is the origin, and every flow starts there.
+
+## 4. 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.
+
+## 5. Build the flow
+
+1. Find your `Question` step in the library on the left.
+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.
+
+The subtitle of the step node now reads one field. Your flow is one step long, and it
+starts at the origin.
+
+## 6. Publish the workspace
+
+Your visitors see nothing until you publish.
+
+1. Click **Publish** in the workspace toolbar.
+2. Read the change preview.
+3. Click **Publish** to confirm.
+
+## 7. Connect the SDK
+
+Install the client and the adapter for your framework.
+
+:::code-group
+
+```bash [React]
+npm install @picked/client @picked/react effector effector-react
+```
+
+```bash [Svelte]
+npm install @picked/client @picked/svelte effector
+```
+
+:::
+
+Now write the component that renders the step. Put it in `ColorSurvey.tsx`, or in
+`ColorSurvey.svelte`. It reads the fields of the active step and
+puts each one in a form.
+
+:::code-group
+
+```tsx [React]
+import { useStep } from '@picked/react/hooks'
+import { useUnit } from 'effector-react'
+
+export function ColorSurvey() {
+  const { fields, form } = useStep()
+  const currentFields = useUnit(fields)
+
+  return (
+    <form {...form.props}>
+      {currentFields.map((field) => (
+        <div key={field.id}>
+          <label htmlFor={field.id}>{field.label}</label>
+          <input
+            id={field.id}
+            name={field.id}
+            value={field.value ?? ''}
+            onChange={field.onChange}
+            onBlur={field.onBlur}
+          />
+        </div>
+      ))}
+      <button type="submit">Continue</button>
+    </form>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { fields, form } = getStep()
+</script>
+
+<form {...form.props}>
+  {#each $fields as field}
+    <div>
+      <label for={field.id}>{field.label}</label>
+      <input
+        id={field.id}
+        name={field.id}
+        value={field.value ?? ''}
+        onchange={field.onChange}
+        onblur={field.onBlur}
+      />
+    </div>
+  {/each}
+  <button type="submit">Continue</button>
+</form>
+```
+
+:::
+
+Then start the client from `picked.ts`. Put your project ID in `projectId`. The key in `components` must
+match the component name that you entered in step 4.
+
+:::code-group
+
+```tsx [React]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { adaptReactComponent } from '@picked/react'
+import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
+import { ColorSurvey } from './ColorSurvey'
+
+export const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    ColorSurvey: adaptReactComponent(ColorSurvey),
+  },
+  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+})
+
+picked.start()
+```
+
+```ts [Svelte]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { adaptSvelteComponent } from '@picked/svelte'
+import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
+import ColorSurvey from './ColorSurvey.svelte'
+
+export const picked = createClient({
+  projectId: 'your-project-id',
+  components: {
+    ColorSurvey: adaptSvelteComponent(ColorSurvey),
+  },
+  plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+})
+
+picked.start()
+```
+
+:::
+
+`dynamicExperiencesPlugin` reads the published configuration of your project. It registers your
+experience, your step, and your field. You declare none of them in code.
+
+## 8. See it
+
+Start your application and open it in a browser.
+
+Your survey appears. It shows the label `Which color do you like most?` and one text
+input. Both come from the dashboard, and neither is in your code.
+
+## 9. Change it without a deployment
+
+This step shows you what the dashboard controls.
+
+1. Go back to the dashboard.
+2. Open your `Color` field.
+3. Change the label to `Which color do you like least?`.
+4. Click **Save**.
+5. Publish the workspace again.
+6. Open the page in your browser again.
+
+The question changes. You edited no code and you deployed nothing.
+
+## What you built
+
+You have an experience that you control from the dashboard and render in your own
+application. The dashboard holds the flow, the step, and the field. Your code holds only
+the component and the client.
+
+To change the label, the field type, or the order of the steps, edit the workspace and
+publish again. You deploy no code.
+
+## Where to go next
+
+- [Your first server-rendered page](/tutorials/first-server-rendered-page) — a page that
+  a search engine can read.
+- [How to build a flow](/how-to/build-a-flow) — branches, actions, and conditions.
+- [About how Picked works](/explanation/how-picked-works) — what happens between publish
+  and render.