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

package/dist/docs/api/authentication.md

@@ -1,403 +0,0 @@
----
-layout: docs
----
-
-# Authentication
-
-The Picked API supports four ways to authenticate. They are a session from an email
-address and a password, an OAuth provider, a magic link, and an API key. This guide
-covers each one. It also covers how to control a session and how to use multi-factor
-authentication (MFA).
-
-## Sign in with an email address and a password
-
-The `sessionCreate` mutation authenticates a user from an email address and a
-password. It returns a session.
-
-```graphql
-mutation {
-  sessionCreate(input: {
-    email: "user@example.com"
-    password: "secure-password"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-      user {
-        id
-        email
-      }
-      aal
-    }
-    requiresMfa
-    mfaFactors {
-      id
-      factorType
-      status
-    }
-  }
-}
-```
-
-When the user has MFA on, the response sets `requiresMfa` to `true` and returns the
-`mfaFactors` of that user. The caller must then complete an MFA challenge before it
-receives a full session. See [MFA](#multi-factor-authentication-mfa) below.
-
-When MFA is off, the response holds a `session` with an `accessToken`, a
-`refreshToken`, and an `expiresAt` timestamp.
-
-## Create an account
-
-The `accountCreate` mutation creates a new account:
-
-```graphql
-mutation {
-  accountCreate(input: {
-    email: "newuser@example.com"
-    password: "secure-password"
-    metadata: { firstName: "Jane", lastName: "Doe" }
-  }) {
-    user {
-      id
-      email
-    }
-    session {
-      accessToken
-      refreshToken
-    }
-  }
-}
-```
-
-The `metadata` field is optional. It takes any JSON, and you can hold profile
-information in it. When the account needs email verification, the session in the
-response is `null` until the user verifies the email address.
-
-## Verify an email address
-
-After you create the account, the user receives a verification email with a token.
-The `accountVerifyEmail` mutation completes the verification:
-
-```graphql
-mutation {
-  accountVerifyEmail(input: {
-    email: "newuser@example.com"
-    token: "verification-token-from-email"
-  }) {
-    session {
-      accessToken
-      refreshToken
-    }
-  }
-}
-```
-
-To send the verification email again:
-
-```graphql
-mutation {
-  accountResendVerification(input: {
-    email: "newuser@example.com"
-  }) {
-    success
-  }
-}
-```
-
-## The OAuth flow with Google
-
-The API supports Google as an OAuth provider. The flow has two steps.
-
-### Step 1: get the authorization URL
-
-```graphql
-mutation {
-  oauthAuthorize(input: {
-    provider: GOOGLE
-    redirectUrl: "https://app.example.com/auth/callback"
-    scopes: ["openid", "email", "profile"]
-  }) {
-    url
-  }
-}
-```
-
-The caller sends the user to the `url` in the response. The user authenticates with
-Google. Google then sends the user back to a URL on the same dashboard deployment,
-with a `code` parameter. The caller exchanges that code for a session.
-
-### Step 2: exchange the code for a session
-
-```graphql
-mutation {
-  oauthCallback(input: {
-    provider: GOOGLE
-    code: "auth-code-from-google"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-    }
-  }
-}
-```
-
-## Magic links
-
-A magic link authenticates a user through an email address, with no password.
-
-### Send a magic link
-
-```graphql
-mutation {
-  magicLinkSend(input: {
-    email: "user@example.com"
-    redirectUrl: "https://app.example.com/auth/verify"
-  }) {
-    success
-  }
-}
-```
-
-The user receives an email with a link, and the link holds a token.
-
-### Verify the magic link
-
-```graphql
-mutation {
-  magicLinkVerify(input: {
-    email: "user@example.com"
-    token: "token-from-magic-link"
-  }) {
-    session {
-      accessToken
-      refreshToken
-    }
-  }
-}
-```
-
-## Passwords
-
-### Reset a password
-
-Send an email to reset the password:
-
-```graphql
-mutation {
-  passwordResetSend(input: {
-    email: "user@example.com"
-    redirectUrl: "https://app.example.com/reset-password"
-  }) {
-    success
-  }
-}
-```
-
-Complete the reset with the token from that email:
-
-```graphql
-mutation {
-  passwordReset(input: {
-    email: "user@example.com"
-    token: "reset-token-from-email"
-    newPassword: "new-secure-password"
-  }) {
-    session {
-      accessToken
-      refreshToken
-    }
-  }
-}
-```
-
-### Change a password
-
-This mutation needs authentication:
-
-```graphql
-mutation {
-  passwordUpdate(input: {
-    currentPassword: "old-password"
-    newPassword: "new-secure-password"
-  }) {
-    success
-  }
-}
-```
-
-## Multi-factor authentication (MFA)
-
-MFA adds a second layer of security, and it uses a telephone to verify the user. The
-API can add an MFA factor, send a challenge, verify a challenge, and remove a factor.
-Every MFA mutation needs authentication.
-
-### Add a factor
-
-```graphql
-mutation {
-  mfaFactorEnroll(input: {
-    factorType: PHONE
-    phone: "+15551234567"
-    friendlyName: "My Phone"
-  }) {
-    factor {
-      id
-      factorType
-      status
-    }
-  }
-}
-```
-
-A new factor has the status `UNVERIFIED` until a challenge confirms it.
-
-### Send a challenge
-
-```graphql
-mutation {
-  mfaChallengeSend(input: {
-    factorId: "factor-id"
-  }) {
-    challengeId
-  }
-}
-```
-
-This sends a verification code to the telephone number of the factor.
-
-### Verify the challenge
-
-```graphql
-mutation {
-  mfaChallengeVerify(input: {
-    factorId: "factor-id"
-    challengeId: "challenge-id"
-    code: "123456"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      aal
-    }
-  }
-}
-```
-
-On success, the session moves to Authenticator Assurance Level `AAL2`. The status of
-the factor changes to `VERIFIED`.
-
-### Remove a factor
-
-```graphql
-mutation {
-  mfaFactorUnenroll(input: {
-    factorId: "factor-id"
-  }) {
-    success
-  }
-}
-```
-
-## Use a session
-
-After the caller has a session, it puts the access token in the `Authorization`
-header of every request that needs authentication:
-
-```
-Authorization: Bearer <accessToken>
-```
-
-The `expiresAt` field of the session gives the time at which the access token
-expires. The caller must refresh the session before that time.
-
-### Authenticator assurance levels
-
-The session holds an `aal` field, and it gives the strength of the authentication:
-
-| Level | Meaning |
-|-------|---------|
-| `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
-| `AAL2` | More than one factor: the user completed an MFA challenge |
-
-Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
-returns an authorization error.
-
-## Refresh a session
-
-An access token has a short life. The `sessionRefresh` mutation exchanges a refresh
-token for a new session:
-
-```graphql
-mutation {
-  sessionRefresh(input: {
-    refreshToken: "v1.refresh-token..."
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-    }
-  }
-}
-```
-
-The response holds a new `accessToken` and a new `refreshToken`. The API invalidates
-the earlier refresh token. This mutation needs no `Authorization` header.
-
-## API key authentication
-
-An API key gives access to the API for a long time, inside a set of scopes. Most
-callers use an API key for a server-to-server integration or for an automated
-workflow.
-
-To authenticate with an API key, include it in the `x-api-key` header:
-
-```
-x-api-key: pk_live_abc123...
-```
-
-An API key belongs to an organization, and it can also belong to one project. It
-carries a set of [authorization scopes](./authorization-and-scopes.md), and those
-scopes decide which operations the key can do.
-
-See [API Keys](/api-keys) for how to control a key from the dashboard.
-
-### Create an API key
-
-The `apiKeyCreate` mutation creates a new API key. Only a user with a session can
-call it. Another API key cannot:
-
-```graphql
-mutation {
-  apiKeyCreate(input: {
-    organizationId: "org-id"
-    name: "CI/CD Pipeline Key"
-    projectId: "project-id"
-    scopes: [ORGANIZATION_READ, ORGANIZATION_PROJECTS_READ]
-  }) {
-    apiKey
-  }
-}
-```
-
-The response holds the full API key string one time only. Keep it in a secure place, because
-you cannot read it again.
-
-The scopes that you ask for must all be scopes of the user who creates the key. See
-[Authorization and Scopes](./authorization-and-scopes.md) for more detail.
-
-### Revoke an API key
-
-```graphql
-mutation {
-  apiKeyRevoke(input: {
-    keyId: "key-id"
-    organizationId: "org-id"
-  })
-}
-```
-
-The API invalidates a revoked key immediately. No later request can use it.

package/dist/docs/chrome-extension.md

@@ -1,68 +0,0 @@
----
-layout: docs
----
-
-# Chrome Extension
-
-The extension for the Picked Developer Tools adds a Picked panel to Chrome DevTools.
-Use the panel to check and debug your Picked integration on any page that runs the
-SDK.
-
-![Picked Developer Tools](/chrome-extension-screenshot.jpg)
-
-## Installation
-
-Install the extension from the
-[Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
-
-## Setup
-
-Add the `svelteDevtoolsPlugin` to your Picked client. The extension then connects 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 tools for one project. They appear
-under a **Custom Tools** tab.
-
-Each tool is a framework-adapted component. Write it with the same
-`adaptReactComponent` or `adaptSvelteComponent` helper that you already use. You can
-therefore build the tool in the framework of your application.
-
-The tool receives the live Picked client, exactly as an experience component does. In
-React, use `usePicked()`. In Svelte, use `getPicked()`. A tool can 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) }],
-    }),
-  ],
-})
-```
-
-Svelte renders the Developer Tools shell, so you must also register the framework of
-your tool on the client. A React application needs `reactFrameworkPlugin` for the
-tool, together with the Svelte framework and `svelteDevtoolsPlugin` for the shell.
-When the framework of a tool is not registered, the tab of that tool shows a warning
-and no content.

package/dist/docs/conditions.mdx

@@ -1,72 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Conditions
-
-A condition evaluates a rule and splits the flow into two paths. One path is for a
-true result, the other for a false result.
-
-<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 a key.
-5. Click **Create**.
-
-## Set up a condition
-
-**Name**: The name that the dashboard shows. Your visitors do not see it.
-
-**Key**: The identifier for your application. You set it once and you cannot change
-it. Your visitors do not see it.
-
-## Define the rule
-
-Choose a condition node in the flow builder to open its inspector. The **Logic**
-section holds a visual [condition builder](/flow-builder/condition-builder).
-
-The condition builder lets you write a rule with AND groups and OR groups. Each rule
-compares a data source against an operator and a value.
-
-### Data sources
-
-**Responses** — the values that your visitors send through form fields. An example is
-a check of whether a visitor entered one email domain, or chose one option.
-
-**Actions** — the actions that ran during the flow.
-
-**Feature flags** — the state of each feature flag in your project. Branch on whether
-Picked allocates a visitor to a flag.
-
-**Location** — the parts of the current page URL of the visitor. These are the
-pathname, the search parameters, the hostname, and the hash. An example is content
-that changes with the page that the visitor is on.
-
-### Example
-
-To take a branch on the country that a visitor chooses:
-
-1. Add a rule: **Responses → country** equals `US`.
-2. The green path, for a true result, handles a visitor in the US. The red path, for
-   a false result, handles every other visitor.
-
-To join more than one rule, create an AND group or an OR group and add the rules
-inside it.
-
-## Branches
-
-In the flow builder, a condition node has two output handles. The green handle, for a
-true result, leads to the path for a match. The red handle, for a false result, leads
-to the other path.
-
-You can chain conditions. Connect the output of one condition to the input of another
-to build a decision tree.

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

@@ -1,124 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Asset Library
-
-The Asset Library holds the files that your content points at. These are images,
-video, documents, and HTML.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/assets"
-  alt="The asset library on the Picked dashboard"
-/>
-
-## Upload and control your assets
-
-The Asset Library is a project-level store. Upload a file, then point at it from any
-Content Entry in the project.
-
-- **Size limit:** 50 MB for each file.
-- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
-  or WebM. A common document format. HTML, as `text/html`.
-
-Picked rejects a file of another type. It also rejects a file above the size limit.
-
-## Reference an asset from a field
-
-Two field types point at an item in the library:
-
-- An **Asset** field points at an image, a video, or a document.
-- An **HTML asset** field takes a `.html` file from your library.
-
-Add the field to a [layout](/content/layouts). Then choose an item from the library
-when you fill in the [Content Entry](/content/content-entries).
-
-## Pick an asset
-
-Every Asset field opens the same picker. Click **Choose file** to open it. On a field
-with a value already, click **Replace**. The modal has two tabs: **Library**, where
-you browse the assets that are there, and **Upload**, where you 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, with the Library tab, its search box, its type filter, and its Sort by menu"
-  renderWidth={1072}
-  renderHeight={790}
-/>
-
-### Search, filter, and sort
-
-The Library tab has three controls that make a large asset list smaller. The server
-applies each one across the whole library, and not only across the assets that it
-loaded already:
-
-- **Search:** narrows the list by file name while you type.
-- **Type filter:** narrows the list to one media type. The choices are All types,
-  Images, Video, Audio, Documents, and Archive files.
-- **Sort by:** orders the list by the Name or by the Date uploaded, each one
-  ascending or descending.
-
-:::note
-The results come one page at a time. Click **Load more** at the bottom of the list to
-read the next page.
-:::
-
-### Choose one asset or several
-
-The picker changes with the number of assets that the field takes:
-
-- A field that holds one asset shows a **radio** indicator next to each row. The
-  Asset field of a layout and the guidance file of a design system both do this. A
-  new choice replaces the current asset.
-- A place that takes several assets at once shows a **checkbox** indicator. The
-  detail panel then also shows a count of what you chose. The Files tab of a
-  workbench does this.
-
-The detail panel on the right shows the kind, the dimensions, the size, and the
-upload date of the asset that you chose.
-
-### Open an asset in a new tab
-
-Each row has an **Open in new tab** control, and so does the detail panel of the
-asset that you chose. It links to the full detail page of the asset, and your choice
-in the picker stays as it is.
-
-:::tip
-Use this to check an asset again before you choose it. You can see the full-size
-preview and every version that somebody uploaded.
-:::
-
-## HTML assets
-
-Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
-the file. The scan is advisory: it helps you, and it never stops you. It
-reports findings about speed, about search rank, and about accessibility, so that you
-can improve the file before you publish it:
-
-- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
-- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
-- **Image dimensions:** an image with no width and no height. Such an image can move
-  the content around it while the page loads.
-- **Lazy load:** an image with no `loading="lazy"` attribute.
-- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
-- **Link search rank:** an external link with no `rel="nofollow"`.
-- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
-  contrast, and more.
-
-Every finding is advisory. You can always upload the file as it is.
-
-## How assets are served
-
-Picked serves each asset from a sandboxed storage origin. That origin is separate
-from the trusted origin of your application. HTML therefore comes from its own
-origin, so a document that you upload runs in isolation and cannot reach the page
-that holds it.
-
-An [Experience Content](/delivery-api/experience-content) response can hold an HTML
-asset. The response then carries the content of that asset, and the SDK renders it
-with no second request to storage.