@picked/client 0.0.101-next.2 → 0.0.101-next.3

package/dist/docs/how-to/analytics/index.md

@@ -1,316 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run an analytics query
-
-This guide gives you a query for each common analytics question. Copy one, put your own
-project ID in the `WHERE` clause, and run it.
-
-Every query must carry a tenant filter. See
-[About PickedQL](/explanation/how-pickedql-works) for why, and
-[Data sources](/reference/pickedql/data-sources) for every table.
-
-## Daily A/B test trend
-
-```sql
-SELECT
-  project_local_date,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-**Result:**
-
-| project_local_date | control | variant |
-| ----------------- | ------- | ------- |
-| 2026-04-11        | 4361    | 101     |
-| 2026-04-12        | 4178    | 126     |
-| 2026-04-13        | 5008    | 176     |
-
-## Conversion rate uplift by date
-
-```sql
-SELECT
-  project_local_date,
-  control_conversion_rate()        AS control_conversion_rate,
-  variant_conversion_rate()        AS variant_conversion_rate,
-  conversion_rate_uplift()         AS conversion_rate_uplift_pct
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-**Result:**
-
-| project_local_date | control_conversion_rate | variant_conversion_rate | conversion_rate_uplift_pct |
-| ----------------- | ----------------------- | ----------------------- | -------------------------- |
-| 2026-04-01        | 0.0322     | 0.0349     | 0.0349        |
-| 2026-04-02        | 0.0398     | 0.0416     | 0.0416        |
-| 2026-04-03        | 0.0462     | 0          | -0.0001       |
-
-## Custom conversion rate definition
-
-Override the default conversion, which counts a `purchase` event, with your own
-numerator and denominator. Use this when a form submission, a lead capture, or
-another event of your own defines a conversion.
-
-```sql
--- Lead capture conversion: form submissions / lead-capture step entries
-SELECT
-  project_local_date,
-  control_conversion_rate(
-    numerator='event_type=form_submit_success',
-    denominator='step_id=lead-capture-step'
-  ) AS control_lead_cr,
-  variant_conversion_rate(
-    numerator='event_type=form_submit_success',
-    denominator='step_id=lead-capture-step'
-  ) AS variant_lead_cr
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-GROUP BY project_local_date
-ORDER BY project_local_date
-```
-
-You can also combine multiple events with `OR` and group with parentheses:
-
-```sql
--- A `checkout_complete` event or an `order_create` event counts as a conversion.
-SELECT
-  control_conversion_rate(
-    'event_type=checkout_complete OR event_type=order_create'
-  ) AS control_cr,
-  variant_conversion_rate(
-    'event_type=checkout_complete OR event_type=order_create'
-  ) AS variant_cr
-FROM events
-WHERE project_id = '{{ your project ID }}'
-```
-
-## Your own segment with `control_users` and `variant_users`
-
-On `events`, four functions take an optional filter string: `control_users`,
-`variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
-user or a session that matches your expression. It applies together with the
-`variant_type` filter that PickedQL adds.
-
-```sql
--- The control users who fired an `app_initialize` event, by step.
-SELECT
-  step_id,
-  control_users('event_type=app_initialize')                      AS control_initialized,
-  variant_users('event_type=app_initialize')                      AS variant_initialized
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-GROUP BY step_id
-ORDER BY control_initialized DESC
-```
-
-The named form (`filter=`) is also supported:
-
-```sql
-SELECT control_users(filter='event_type=form_submit AND step_id=lead-capture') FROM events
-WHERE project_id = '{{ your project ID }}'
-```
-
-## Conversion rate from nested virtual functions
-
-The numerator and the denominator can come from different segments. An example is the
-control users who fired an event of your own, divided by **all** users and not by the
-control users alone. For that, pass a virtual function call directly as an argument
-of the conversion rate:
-
-```sql
--- The control users who fired `app_initialize`, over all users of every variant.
-SELECT
-  control_conversion_rate(
-    control_users('event_type=app_initialize'),
-    all_users()
-  ) AS control_initialize_rate
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND client_local_date >= '2026-04-01'
-```
-
-## A/B test by device
-
-```sql
-SELECT
-  device_category,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-GROUP BY device_category
-```
-
-**Result:**
-
-| device_category | control | variant |
-| --------------- | ------- | ------- |
-| Phone           | 193430  | 1723    |
-| Desktop         | 23423   | 309     |
-| Tablet          | 13294   | 65      |
-
-## Daily A/B test trend by device
-
-Combine date and device dimensions to spot device-specific trends:
-
-```sql
-SELECT
-  project_local_date,
-  device_category,
-  control_users()                  AS control,
-  variant_users()                  AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY project_local_date, device_category
-ORDER BY project_local_date, device_category
-```
-
-**Result:**
-
-| project_local_date | device_category | control | variant |
-| ----------------- | --------------- | ------- | ------- |
-| 2026-04-13        | Tablet          | 175     | 2       |
-| 2026-04-14        | Desktop         | 37      | 1       |
-| 2026-04-14        | Phone           | 244     | 1       |
-
-## Purchase by UTM source
-
-```sql
-SELECT
-  utm_source,
-  all_users()                      AS users,
-  all_purchase_users()             AS purchasers
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-GROUP BY utm_source
-```
-
-**Result:**
-
-| utm_source | users  | purchasers |
-| ---------- | ------ | ---------- |
-| `meta`       | 12031  | 101        |
-| `fb`         | 3656   | 31         |
-| `an`         | 100366 | 299        |
-
-## Step funnel for variant users
-
-Count unique variant users per step to understand the conversion funnel:
-
-```sql
-SELECT
-  step_id,
-  variant_users()                    AS variant
-FROM metrics
-WHERE project_id = '{{ your project ID }}'
-  AND project_local_date >= '2026-04-01'
-GROUP BY step_id
-ORDER BY variant DESC
-```
-
-**Result:**
-
-| step_id                        | variant |
-| ------------------------------ | ------- |
-| `who-are-you-protecting-step`    | 1093    |
-| `about-yourself-step`            | 533     |
-| `date-of-birth-step`             | 435     |
-| `employment-status-step`         | 408     |
-| `nicotine-usage-step`            | 407     |
-| `coverage-motivation-step`       | 405     |
-| `lead-capture-step`              | 398     |
-
-
-## Sankey — overall user journey
-
-A forward window from the starting step. A user who never reaches `targeting_step`
-still gives edges, up to `num_nodes_after_start`.
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id            = '{{ your project ID }}'
-  AND starting_step         = '{{ starting step ID }}'
-  AND targeting_step        = '{{ target step ID }}'
-  AND num_nodes_after_start = 10
-```
-
-**Result:**
-
-| source                    | target                    | users |
-| ------------------------- | ------------------------- | ----- |
-| `001. step-start`           | `002. step-questionnaire-1` | 182   |
-| `002. step-questionnaire-1` | `003. step-quote`           | 144   |
-| `003. step-quote`           | `004. step-target`          | 121   |
-
-## Sankey — the top paths to a target step
-
-A backward window anchored at the target. It also ranks the paths and keeps the ones
-with the most users.
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id              = '{{ your project ID }}'
-  AND experience_id           = '{{ experience ID }}'
-  AND starting_step           = '{{ starting step ID }}'
-  AND targeting_step          = '{{ target step ID }}'
-  AND num_nodes_before_target = 5
-  AND top_n_path              = 10
-```
-
-## Sankey — drop-off view
-
-Starts at `starting_step` and emits every consecutive transition until `num_nodes_after_start` steps later (no target).
-
-```sql
-SELECT source, target, users FROM experience_journey
-WHERE project_id            = '{{ your project ID }}'
-  AND experience_id         = '{{ experience ID }}'
-  AND starting_step         = '{{ starting step ID }}'
-  AND num_nodes_after_start = 10
-```
-
-## List all control users for mobile (user-level)
-
-Use `events` when you need data at the individual user level:
-
-```sql
-SELECT
-  device_category,
-  user_canonical_id
-FROM events
-WHERE project_id = '{{ your project ID }}'
-  AND device_category = 'Mobile'
-  AND variant_type = 'Control'
-```
-
-**Result:**
-
-| device_category | user_canonical_id                    |
-| --------------- | ------------------------------------ |
-| Mobile          | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
-| Mobile          | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
-| Mobile          | `019cc80f-503c-7181-b2c6-986b1f76d496` |
-
-## Related
-
-- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
-- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
-- [Dimensions](/reference/pickedql/dimensions) — every dimension column.
-- [Analytics events](/reference/sdk/analytics-events) — every `event_type` value that a
-  filter can use.
-- [Reports](/reference/dashboard/reports) — the same data as an embedded dashboard.

package/dist/docs/how-to/archive-or-delete-a-workspace.md

@@ -1,46 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to archive or delete a workspace
-
-This guide shows you how to take a draft workspace out of use. Archive it when you want
-to keep it. Delete it only when you are certain, because you cannot reverse a delete.
-
-You cannot archive or delete a live workspace. Make a different workspace live first.
-
-## Archive a workspace
-
-1. Open the workspace settings page.
-2. Click **Archive workspace** in the page header.
-3. Confirm in the modal.
-
-The workspace leaves the default list. It stays editable.
-
-## Unarchive a workspace
-
-1. Open the workspace settings page.
-2. Click **Unarchive workspace** in the page header.
-
-## Delete a workspace
-
-1. Open the workspace settings page.
-2. Click **Delete workspace**.
-3. Confirm in the modal.
-
-Picked removes the workspace, and everything in it, permanently.
-
-## Rename a workspace
-
-1. Open the workspace settings page.
-2. Change the **Workspace name** field.
-3. Click **Save changes**.
-
-A name is unique inside a project. The dashboard rejects a duplicate name.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why Picked keeps
-  these two operations separate.
-- [Workspaces](/reference/dashboard/workspaces) — the settings reference.

package/dist/docs/how-to/authenticate-the-cli.md

@@ -1,101 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to authenticate the CLI
-
-This guide shows you how to install the `picked` command and sign it in. Commands that read
-your organizations, projects, and workspaces then know who you are. It expects a Picked
-account and a project directory to work in.
-
-## 1. Install the CLI
-
-:::code-group
-
-```bash [npm]
-npm install picked
-```
-
-```bash [pnpm]
-pnpm add picked
-```
-
-```bash [yarn]
-yarn add picked
-```
-
-:::
-
-The binary is `picked`. Run it from the directory that holds your `picked.config.ts`, so it
-reads your configuration and writes your selection next to it.
-
-## 2. Sign in
-
-```bash
-picked login
-```
-
-The command opens your browser for a one-time sign-in and prints your identity:
-
-```
-Opening your browser to sign in...
-https://api.picked.app/…/oauth/authorize?…
-Logged in as you@example.com (https://api.picked.app)
-```
-
-If your account must use MFA, the browser asks for the code from your authenticator app
-before it signs the CLI in. Picked staff, and members of an organization that requires
-MFA, must use it.
-
-The CLI stores the session in `~/.picked/auth/<origin>.json`. It refreshes the session as it nears expiry.
-
-## 3. Confirm the session
-
-```bash
-picked whoami
-```
-
-```
-you@example.com (https://api.picked.app)
-```
-
-Each command acts on the API origin your current directory resolves to, and on no other. To
-end the session for that origin:
-
-```bash
-picked logout
-```
-
-```
-Logged out of https://api.picked.app.
-```
-
-## Run the CLI in CI
-
-`picked generate types` reads the workspace schema, not your account, so CI needs no
-session for it. A workspace you read with `source: 'preview'` needs that workspace's token.
-Run `picked workspace use` once on your machine, then give CI the two values it wrote:
-
-```bash
-PICKED_PROJECT_ID=your-project-id \
-PICKED_PREVIEW_TOKEN=$YOUR_CI_SECRET \
-picked generate types --check
-```
-
-`picked workspace list` and `picked workspace use` read your organizations and projects, so
-those two do need a session. Run them on your machine, where a browser can sign you in.
-
-:::note
-This is a developer session for local tooling. It is not the same as an
-[API key](/reference/dashboard/api-keys), which authenticates server-to-server delivery and
-management calls, or [dashboard sign-in](/reference/management-api/authentication). Use an
-API key for an application; use `picked login` for the CLI on your machine.
-:::
-
-## Related
-
-- [CLI](/reference/tools/cli) — every command, flag, and environment variable.
-- [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
-- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — credentials
-  for applications.

package/dist/docs/how-to/authenticate-with-a-magic-link.md

@@ -1,47 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to authenticate with a magic link
-
-This guide shows you how to sign a user in through an email address, with no password.
-
-## 1. Send the email
-
-```graphql
-mutation {
-  magicLinkSend(input: {
-    email: "user@example.com"
-    redirectUrl: "https://app.example.com/auth/verify"
-  }) {
-    success
-  }
-}
-```
-
-The user receives an email with a six-digit code and a sign-in link. The mutation does not
-create an account. For an address with no account, it returns `success: true` and sends no
-email.
-
-If you send a second request for the same address soon after the first, the mutation
-returns `success: true` and sends no new email. The code in the first email stays valid.
-
-## 2. Verify the code
-
-```graphql
-mutation {
-  magicLinkVerify(input: {
-    email: "user@example.com"
-    token: "123456"
-  }) {
-    session { accessToken refreshToken }
-  }
-}
-```
-
-Put the six-digit code from the email in `token`.
-
-## Related
-
-- [Authentication](/reference/management-api/authentication) — every mutation.

package/dist/docs/how-to/authenticate-with-a-password.md

@@ -1,59 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to authenticate with a password
-
-This guide shows you how to get an access token from an email address and a password.
-
-## 1. Create a session
-
-```graphql
-mutation {
-  sessionCreate(input: {
-    email: "user@example.com"
-    password: "secure-password"
-  }) {
-    session {
-      accessToken
-      refreshToken
-      expiresAt
-      aal
-      user {
-        mfa { required enrolled }
-      }
-    }
-  }
-}
-```
-
-The session is at `AAL1`. When `user.mfa.required` is `true`, verify a code from an
-authenticator app before you call other operations. See
-[How to set up MFA](/how-to/set-up-mfa).
-
-## 2. Send the token
-
-```
-Authorization: Bearer <accessToken>
-```
-
-## 3. Refresh before it expires
-
-The `expiresAt` field gives the time at which the access token expires.
-
-```graphql
-mutation {
-  sessionRefresh(input: { refreshToken: "v1.refresh-token..." }) {
-    session { accessToken refreshToken expiresAt }
-  }
-}
-```
-
-The API invalidates the earlier refresh token. This mutation needs no `Authorization`
-header.
-
-## Related
-
-- [Authentication](/reference/management-api/authentication) — every mutation.
-- [Your first API call](/tutorials/first-api-call).

package/dist/docs/how-to/authenticate-with-an-api-key.md

@@ -1,51 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to authenticate with an API key
-
-This guide shows you how to authenticate a server-to-server integration. An API key gives
-access for a long time, inside a set of scopes.
-
-## 1. Create the key
-
-Only a user with a session can create a key. 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 key one time only. Keep it in a secure place.
-
-The scopes that you ask for must all be scopes of the user who creates the key.
-
-## 2. Send the key
-
-```
-x-api-key: pk_live_abc123...
-```
-
-## 3. Revoke the key
-
-```graphql
-mutation {
-  apiKeyRevoke(input: { keyId: "key-id", organizationId: "org-id" })
-}
-```
-
-## Related
-
-- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — every
-  scope.
-- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — the
-  dashboard path.

package/dist/docs/how-to/authenticate-with-oauth.md

@@ -1,40 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to authenticate with OAuth
-
-This guide shows you how to sign a user in through Google.
-
-## 1. Get the authorization URL
-
-```graphql
-mutation {
-  oauthAuthorize(input: {
-    provider: GOOGLE
-    redirectUrl: "https://app.example.com/auth/callback"
-    scopes: ["openid", "email", "profile"]
-  }) {
-    url
-  }
-}
-```
-
-## 2. Send the user to that URL
-
-Google authenticates the user and sends them back with a `code` parameter.
-
-## 3. Exchange the code
-
-```graphql
-mutation {
-  oauthCallback(input: { provider: GOOGLE, code: "auth-code-from-google" }) {
-    session { accessToken refreshToken expiresAt }
-  }
-}
-```
-
-## Related
-
-- [Authentication](/reference/management-api/authentication) — every mutation.