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

package/dist/docs/api/error-handling.md

@@ -1,211 +0,0 @@
----
-layout: docs
----
-
-# Error handling
-
-The Picked API returns errors using the standard GraphQL error format. This guide covers the error response shape, all error codes, and practical strategies for handling errors.
-
-## Error response shape
-
-When an operation fails, the API returns an `errors` array in the response body. Each error object contains:
-
-```json
-{
-  "data": null,
-  "errors": [
-    {
-      "message": "A human-readable description of the error",
-      "path": ["mutationName"],
-      "extensions": {
-        "code": "ERROR_CODE"
-      }
-    }
-  ]
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `message` | A human-readable error description. Suitable for logging but not for programmatic handling. |
-| `path` | The path to the field in the query that caused the error. |
-| `extensions.code` | A machine-readable error code. Use this for programmatic error handling. |
-
-Multiple errors may appear in a single response. The `data` field may be `null` if the entire operation failed, or it may contain partial data if only some fields failed.
-
-## Authentication error codes
-
-These errors relate to session creation, account management, OAuth, magic links, password operations, and MFA. They map to the `AuthErrorCode` enum in the schema.
-
-| Code | Description |
-|------|-------------|
-| `INVALID_CREDENTIALS` | The email/password combination is incorrect. |
-| `EMAIL_NOT_CONFIRMED` | The account exists but the email address has not been verified. See [Authentication](/api/authentication#email-verification). |
-| `USER_NOT_FOUND` | No account exists with the provided email address. |
-| `USER_ALREADY_EXISTS` | An account with this email already exists. Returned during account creation. |
-| `WEAK_PASSWORD` | The provided password does not meet strength requirements. |
-| `INVALID_TOKEN` | The token (verification, reset, or magic link) is invalid or malformed. |
-| `TOKEN_EXPIRED` | The token has expired. The caller should request a new one. |
-| `MFA_CHALLENGE_FAILED` | The MFA verification code is incorrect. |
-| `MFA_FACTOR_NOT_FOUND` | The specified MFA factor does not exist or does not belong to the caller. |
-| `OAUTH_PROVIDER_ERROR` | An error occurred communicating with the OAuth provider (e.g., Google). |
-| `RATE_LIMITED` | Too many requests in a short period. The caller should wait and retry. |
-
-### Example: invalid credentials
-
-```json
-{
-  "data": {
-    "sessionCreate": {
-      "session": null,
-      "requiresMfa": false,
-      "mfaFactors": null
-    }
-  },
-  "errors": [
-    {
-      "message": "Invalid credentials",
-      "path": ["sessionCreate"],
-      "extensions": {
-        "code": "INVALID_CREDENTIALS"
-      }
-    }
-  ]
-}
-```
-
-## Authorization error codes
-
-Authorization errors occur when the caller lacks the required [scope](./authorization-and-scopes.md) for an operation.
-
-| Code | Description |
-|------|-------------|
-| `UNAUTHORIZED` | No valid authentication was provided. The request is missing the `Authorization` header or the `x-api-key` header, or the token/key is invalid. |
-| `FORBIDDEN` | The caller is authenticated but does not have the required scope for the operation. |
-
-### Example: insufficient scope
-
-A caller with only `organization/read` attempting to delete an organization receives:
-
-```json
-{
-  "data": {
-    "organizationDelete": null
-  },
-  "errors": [
-    {
-      "message": "Insufficient permissions",
-      "path": ["organizationDelete"],
-      "extensions": {
-        "code": "FORBIDDEN"
-      }
-    }
-  ]
-}
-```
-
-## Organization, member, and invitation error codes
-
-These errors relate to organization management, member operations, and invitation workflows. They map to the `ErrorCode` enum in the schema.
-
-### Organization errors
-
-| Code | Description |
-|------|-------------|
-| `ORGANIZATION_NOT_FOUND` | The specified organization does not exist or the caller does not have access to it. |
-| `ORGANIZATION_ALREADY_EXISTS` | An organization with this name already exists. |
-| `SLUG_ALREADY_EXISTS` | The requested slug is already in use by another organization. |
-| `INVALID_SLUG` | The slug contains invalid characters. Slugs must be lowercase alphanumeric with hyphens. |
-
-### Member errors
-
-| Code | Description |
-|------|-------------|
-| `MEMBER_NOT_FOUND` | The specified user is not a member of the organization. |
-| `MEMBER_ALREADY_EXISTS` | The user is already a member of the organization. |
-| `CANNOT_REMOVE_PRIMARY_OWNER` | The primary owner of an organization cannot be removed. |
-| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change their own role. Another owner must perform this action. |
-
-### Invitation errors
-
-| Code | Description |
-|------|-------------|
-| `INVITATION_NOT_FOUND` | The specified invitation does not exist. |
-| `INVITATION_EXPIRED` | The invitation has expired and can no longer be accepted. |
-| `INVITATION_ALREADY_ACCEPTED` | The invitation has already been accepted. |
-
-### Project errors
-
-| Code | Description |
-|------|-------------|
-| `PROJECT_NOT_FOUND` | The specified project does not exist or the caller does not have access. |
-
-### General errors
-
-| Code | Description |
-|------|-------------|
-| `VALIDATION_ERROR` | The input failed validation. Check the `message` field for details about which field is invalid. |
-| `INTERNAL_ERROR` | An unexpected server error occurred. Retry the request or contact support if the issue persists. |
-
-## Handling errors in practice
-
-### Check for errors first
-
-Every response should be checked for the presence of an `errors` array before processing `data`:
-
-```javascript
-const response = await fetch('/graphql', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${accessToken}`,
-  },
-  body: JSON.stringify({ query, variables }),
-});
-
-const result = await response.json();
-
-if (result.errors) {
-  for (const error of result.errors) {
-    const code = error.extensions?.code;
-
-    switch (code) {
-      case 'UNAUTHORIZED':
-        // Redirect to login
-        break;
-      case 'FORBIDDEN':
-        // Show a permissions error
-        break;
-      case 'RATE_LIMITED':
-        // Wait and retry
-        break;
-      default:
-        // Log or display the error message
-        console.error(error.message);
-    }
-  }
-}
-```
-
-### Refresh expired tokens
-
-If a request returns `UNAUTHORIZED` and the caller has a refresh token, attempt a [session refresh](/api/authentication#session-refresh) before treating it as a login failure:
-
-```javascript
-if (code === 'UNAUTHORIZED' && refreshToken) {
-  const refreshResult = await sessionRefresh(refreshToken);
-  if (refreshResult.session) {
-    // Retry the original request with the new access token
-  } else {
-    // Redirect to login
-  }
-}
-```
-
-### Handle partial data
-
-GraphQL can return partial data alongside errors. For example, a query that fetches an organization and its members might succeed for the organization but fail for the members if the caller lacks `organization_members/read`. In this case, the response contains both `data` (with the organization) and `errors` (for the members field). Always check both.
-
-### Retry transient failures
-
-`INTERNAL_ERROR` and `RATE_LIMITED` are transient. For `RATE_LIMITED`, implement exponential backoff before retrying. For `INTERNAL_ERROR`, a single retry is usually sufficient.

package/dist/docs/api/index.md

@@ -1,197 +0,0 @@
----
-layout: docs
----
-
-# Getting started
-
-This guide walks you through your first interactions with the Picked GraphQL API, from sending a simple ping to making authenticated queries and mutations.
-
-:::note
-This reference covers the authenticated GraphQL management API. To serve your published config and page content to your app, use the public, read-only [Delivery API](/delivery-api) instead.
-:::
-
-## Playground
-
-Explore the API and run queries interactively 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 with a JSON body containing a `query` field and an optional `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
-
-Verify that the API is reachable with the `ping` query. This query does not require authentication.
-
-```graphql
-query {
-  ping
-}
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "ping": "pong"
-  }
-}
-```
-
-If you receive this response, the API is up and ready.
-
-## Authenticate
-
-Most operations require an access token. You obtain one by creating a session with your email and password.
-
-```graphql
-mutation {
-  sessionCreate(input: {
-    email: "you@example.com"
-    password: "your-password"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-    }
-    requiresMfa
-  }
-}
-```
-
-A successful response returns a `Session` containing an `accessToken` and a `refreshToken`:
-
-```json
-{
-  "data": {
-    "sessionCreate": {
-      "session": {
-        "accessToken": "eyJhbGciOiJIUzI1NiIs...",
-        "refreshToken": "v1.refresh-token...",
-        "expiresAt": "2025-01-15T12:00:00Z"
-      },
-      "requiresMfa": false
-    }
-  }
-}
-```
-
-If `requiresMfa` is `true`, you need to complete the MFA challenge before receiving a session. See the [Authentication](./authentication.md) guide for details.
-
-For server-to-server integrations, prefer [API key authentication](/api/authentication#api-key-authentication) over session tokens.
-
-## Make an authenticated query
-
-Pass the access token in the `Authorization` header as a Bearer token:
-
-```
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-```
-
-Now you can query resources that require authentication. For example, fetch your user profile:
-
-```graphql
-query {
-  user {
-    id
-    email
-    createdAt
-    organizations(first: 5) {
-      edges {
-        node {
-          id
-          name
-        }
-      }
-    }
-  }
-}
-```
-
-## Make a mutation
-
-Mutations follow the same pattern: send a `POST` request with the `Authorization` header. For example, create 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 accepts an `input` argument and returns a payload object. The payload contains the created or updated resource on success, or errors in the top-level `errors` array on failure.
-
-## Error handling basics
-
-When something goes wrong, the API returns errors in the standard GraphQL `errors` array:
-
-```json
-{
-  "data": null,
-  "errors": [
-    {
-      "message": "Invalid credentials",
-      "extensions": {
-        "code": "INVALID_CREDENTIALS"
-      }
-    }
-  ]
-}
-```
-
-Check the `extensions.code` field for a machine-readable error code you can use to handle specific failures programmatically. See the [Error Handling](./error-handling.md) guide for the full list of error codes.
-
-## Next steps
-
-Now that you can authenticate and make requests, explore these guides to go deeper:
-
-- [Authentication](./authentication.md) — email/password, OAuth, magic links, MFA, API keys, and session management
-- [Authorization and Scopes](./authorization-and-scopes.md) — understand what each role can access and how scopes control permissions
-- [Pagination](./pagination.md) — navigate large result sets with cursor-based pagination
-- [Error Handling](./error-handling.md) — handle every error code the API can return

package/dist/docs/api-keys.mdx

@@ -1,40 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# API keys
-
-API keys let you access Picked's API programmatically. Use them for server-side integrations or CI/CD workflows.
-
-<Screenshot
-  route="/{orgSlug}/api-keys"
-  alt="The API keys list for an organization on the Picked dashboard"
-/>
-
-## Create an API key
-
-1. Open your organization.
-2. Click **API Keys**.
-3. Click **Create Key**.
-4. Enter a description.
-5. Click **Create**.
-
-Copy the key immediately — it won't be shown again.
-
-## Using an API key
-
-Include your API key in the `Authorization` header when making requests to the [Picked API](/api).
-
-```
-Authorization: Bearer your-api-key
-```
-
-## Scopes
-
-API keys can be scoped to limit what they can access. When creating a key, select the scopes that match your integration's needs. A key can only perform actions allowed by its assigned scopes.
-
-## Revoke a key
-
-Revoke a key at any time from the API keys list. Click the revoke button next to the key you want to disable. Revoked keys stop working immediately.

package/dist/docs/chrome-extension.md

@@ -1,51 +0,0 @@
----
-layout: docs
----
-
-# Chrome Extension
-
-The Picked Developer Tools extension adds a Picked panel to Chrome DevTools for inspecting and debugging your Picked integration on any page running the SDK.
-
-![Picked Developer Tools](/chrome-extension-screenshot.jpg)
-
-## Installation
-
-Install from the [Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
-
-## Setup
-
-Add the `svelteDevtoolsPlugin` to your Picked client so the extension can connect to the SDK.
-
-```typescript
-import { createPicked } from '@picked/client'
-import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
-
-const picked = createPicked({
-  projectId: 'your-project-id',
-  plugins: [
-    svelteDevtoolsPlugin(),
-  ],
-})
-```
-
-## Custom Tools
-
-You can extend the Developer Tools with your own project-specific tools, surfaced under a **Custom Tools** tab. Each tool is a framework-adapted component — authored with the same `adaptReactComponent` / `adaptSvelteComponent` helpers you already use — so you can build it in your app's framework and it receives the live Picked client exactly like an experience component does (React: `usePicked()`; Svelte: `getPicked()`). Tools can both read client state and call client methods.
-
-```typescript
-import { createPicked } from '@picked/client'
-import { adaptReactComponent } from '@picked/react'
-import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
-import MyTool from './MyTool'
-
-const picked = createPicked({
-  projectId: 'your-project-id',
-  plugins: [
-    svelteDevtoolsPlugin({
-      customTools: [{ id: 'my-tool', label: 'My Tool', component: adaptReactComponent(MyTool) }],
-    }),
-  ],
-})
-```
-
-The Developer Tools shell is rendered with Svelte, so a tool's framework must also be registered on the client. A React app needs `reactFrameworkPlugin` (for the tool) alongside the Svelte framework and `svelteDevtoolsPlugin` (for the shell). If a tool's framework isn't registered, its tab shows a warning instead of rendering.

package/dist/docs/conditions.mdx

@@ -1,59 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Conditions
-
-A condition evaluates logic and branches the flow into two paths — one for when the condition is true, another for when it's false.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
-  alt="The conditions list for a workspace on the Picked dashboard"
-/>
-
-## Create a condition
-
-1. Open your project.
-2. Click **Conditions** in the sidebar.
-3. Click **New Condition**.
-4. Enter a name and key.
-5. Click **Create**.
-
-## Configure a condition
-
-**Name**: The display name shown in the dashboard. Not visible to visitors.
-
-**Key**: The programmatic identifier. Set once, can't change. Not visible to visitors.
-
-## Define logic
-
-Select a condition node in the flow builder to open its inspector. The **Logic** section contains a visual [condition builder](/flow-builder/condition-builder).
-
-The condition builder lets you create rules using AND/OR groups. Each rule compares a data source against an operator and a target value.
-
-### Available data sources
-
-**Responses** — values visitors have submitted through form fields. For example, check if a visitor entered a specific email domain or selected a particular option.
-
-**Actions** — references to actions that have been triggered during the flow.
-
-**Features** — the state of feature flags in your project. Branch based on which variant a visitor is assigned to.
-
-**Location** — properties of the visitor's current page URL, including pathname, search parameters, hostname, and hash. For example, show different content based on which page the visitor is on.
-
-### Example
-
-To branch based on a visitor's country selection:
-
-1. Add a rule: **Responses → country** equals `US`.
-2. The green (true) path handles US visitors. The red (false) path handles everyone else.
-
-To combine multiple conditions, create an AND or OR group and add rules within it.
-
-## Branching
-
-In the flow builder, condition nodes have two output handles. The green handle (true) leads to the path taken when the condition matches. The red handle (false) leads to the alternative path.
-
-You can chain conditions. Connect the output of one condition to the input of another to create complex decision trees.

package/dist/docs/content/asset-library.mdx

@@ -1,93 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Asset Library
-
-The Asset Library stores the files your content references: images, video, documents, and HTML.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/assets"
-  alt="The asset library on the Picked dashboard"
-/>
-
-## Upload and manage assets
-
-The Asset Library is a project-level store. Upload a file, then reference it from any Content Entry in the project.
-
-- **Size limit:** 50 MB per file.
-- **Allowed types:** images (PNG, JPEG, WebP, AVIF, GIF, SVG), video (MP4, WebM), common document formats, and HTML (`text/html`).
-
-Uploads outside the allowed types or over the size limit are rejected at upload time.
-
-## Reference an asset from a field
-
-Two field types point at library items:
-
-- An **Asset** field references an image, video, or document.
-- An **HTML asset** field references an uploaded `.html` file.
-
-Add the field to a [layout](/content/layouts), then pick a library item when filling in the [Content Entry](/content/content-entries).
-
-## Pick an asset
-
-Every Asset field opens the same picker: click **Choose file** (or **Replace** on a field that already has a value) to open a modal with two tabs, **Library** (browse existing assets) and **Upload** (add a new file).
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/design-systems/new"
-  wait='button:has-text("Upload file")'
-  click='button:has-text("Upload file")'
-  selector="[role=dialog]"
-  alt="The asset picker modal on the Picked dashboard, showing the Library tab with its search box, type filter, and Sort by menu"
-  renderWidth={1072}
-  renderHeight={790}
-/>
-
-### Search, filter, and sort
-
-The Library tab has three controls for narrowing a large asset list, all applied on the server across the whole library, not just the assets already loaded:
-
-- **Search:** filters by file name as you type.
-- **Type filter:** narrows to a media-type bucket (All types, Images, Video, Audio, Documents, or Archives).
-- **Sort by:** orders by Name or Date uploaded, each ascending or descending.
-
-:::note
-Results are paginated. Use **Load more** at the bottom of the list to fetch the next page.
-:::
-
-### Select one or several assets
-
-The picker adapts to how many assets the field accepts:
-
-- A field that holds a single asset (a layout's Asset field, or a design system's guidance file) shows a **radio** indicator next to each row. Picking a new asset replaces the current one.
-- A surface that accepts several assets at once (for example, a workbench's Files tab) shows a **checkbox** indicator and a running selection count in the detail panel.
-
-The detail panel on the right shows the selected asset's kind, dimensions, size, and upload date.
-
-### Open an asset in a new tab
-
-Each row, and the detail panel for the currently selected asset, has an **Open in new tab** control. It links to the asset's full detail page without losing your current selection in the picker.
-
-:::tip
-Use this to double-check an asset (its full-size preview, every uploaded version) before committing to it.
-:::
-
-## HTML assets
-
-Upload a `.html` file and reference it from an **HTML asset** field. On upload, Picked runs an advisory scan that guides you but never blocks the upload. It surfaces performance, SEO, and accessibility findings so you can improve the file before publishing:
-
-- **File size:** a warning at 100 KB and a stronger one at 250 KB.
-- **Inline images:** a note when inline base64 image data adds roughly 50 KB or more.
-- **Image dimensions:** images missing an explicit width or height, which risk layout shift.
-- **Lazy loading:** images without `loading="lazy"`.
-- **Link safety:** external links with `target="_blank"` but no `rel="noopener"`.
-- **Link SEO:** external links without `rel="nofollow"`.
-- **Accessibility:** an axe-core pass covering alt text, heading order, contrast, and more.
-
-Every finding is advisory. You can always upload the file as is.
-
-## How assets are served
-
-Assets are served from a sandboxed storage origin, separate from your app's trusted origin. Serving HTML from its own origin means an uploaded document executes in isolation and cannot reach the page that embeds it. When an [Experience Content](/delivery-api/experience-content) response includes an HTML asset, its content is inlined into the response, so the SDK renders it without a second storage fetch.

package/dist/docs/content/content-entries.mdx

@@ -1,30 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Content Entries
-
-A Content Entry is an instance of a layout filled with real data. A Page renders one entry; a Flow Step can render one too.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/content"
-  alt="The content entries list on the Picked dashboard"
-/>
-
-## What a content entry is
-
-A Content Entry is an instance of a layout's schema. The [layout](/content/layouts) defines the fields; the entry holds the actual values. One layout can back many entries, each with its own data.
-
-## How entries bind to pages and steps
-
-A [Page](/content/pages) has a single Step, and that Step links to its entry through the layout content link. A Flow [Step](/steps) backed by a Step Layout binds an entry the same way. When the SDK renders the Page or Step, it resolves the linked entry and hands its data to your component.
-
-## Edit entry data
-
-The entry editor renders a form driven by the layout schema: one input per field, in the order the schema defines. Repeatable fields appear as sortable lists you can add to and reorder. Group fields nest their inputs under a single heading.
-
-## Validation
-
-Invalid data surfaces as per-field errors using a JSON-path style that points at the exact location in the entry, for example `sections[0].data.title`. Fix every error before publishing: the published surface only serves valid content.