@picked/client 0.0.70 → 0.0.71-next.2

package/dist/docs/actions.mdx

@@ -1,98 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Actions
-
-An action is a side effect that starts when the flow reaches it. Use an action to
-track an event, to send data to an external service, or to call a webhook.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/actions"
-  alt="The actions list for a workspace on the Picked dashboard"
-/>
-
-## Create an action
-
-1. Open your project.
-2. Click **Actions** in the sidebar.
-3. Click **New Action**.
-4. Enter a name and a key.
-5. Click **Create**.
-
-The key is a unique identifier for your application. You set it once, and you cannot
-change it later.
-
-## Set up an action
-
-**Name**: The name that the dashboard shows. Your visitors do not see it.
-
-**Key**: The identifier that your application uses for this action. Your visitors do
-not see it.
-
-## Register in your application
-
-Register your actions when you create the Picked client. Pass an `actions` object.
-Each key in it must match an action key from the dashboard:
-
-```typescript
-import { createClient } from '@picked/client'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  actions: {
-    'track-signup': () => {
-      analytics.track('signup_completed')
-    },
-    'notify': (params) => {
-      sendNotification(params)
-    },
-    'check-eligibility': async () => {
-      const response = await fetch('/api/eligibility')
-      // Throw only when the request itself fails. That takes the failure branch.
-      if (!response.ok) throw new Error('Eligibility request failed')
-    },
-  },
-})
-```
-
-Each action is a function. It takes optional parameters and it usually runs a side
-effect. When the flow reaches an action node, the SDK calls the function that
-matches. The SDK then takes a branch, which depends on whether the function succeeds
-or throws. See [Success and failure branches](#success-and-failure-branches).
-
-See [SDK Actions](/sdk/actions) for more detail.
-
-## Use actions in flows
-
-In the flow builder, drag an action from the entity browser onto the canvas. Connect
-it to the point in the flow where you want it to start.
-
-An action runs when the flow reaches its node. It does not interrupt your visitor. By
-default the flow continues to the next connected node.
-
-### Success and failure branches
-
-An action node can have two outgoing branches: **success** and **failure**. The SDK
-chooses the branch from the outcome of the action:
-
-- **Failure** — the action throws, or its promise rejects. The flow takes the failure
-  branch.
-- **Success** — the action resolves to any value: nothing, `true`, `false`, or a
-  string. A returned `false` is a valid response and not a failure. The flow takes
-  the success branch.
-
-Keep the failure branch for a true error. Throw on the failure case, for example
-`if (!response.ok) throw new Error(...)`. A valid negative result is _not_ a failure.
-An API that returns `200` with `{ serviced: false }` must record that value as a
-response. Branch on it with a condition instead of a throw.
-
-An action node can also have one plain connection, with no success or failure branch.
-The flow then continues through it on either outcome.
-
-## Reuse actions
-
-An action is a project-level entity. Use the same action in more than one experience
-flow. A change to the options of an action applies at every place that uses it.

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.