@picked/client 0.0.101-next.2 → 0.0.101

package/dist/docs/reference/management-api/pagination.md

@@ -1,192 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Pagination
-
-The Picked API paginates every list field that can return a large result. It uses a
-cursor, in the Relay-style pattern. This guide covers the connection pattern and
-shows how to move through a result.
-
-## Connection pattern
-
-A paginated field returns a **connection** object with this shape:
-
-```graphql
-type ExampleConnection {
-  edges: [ExampleEdge!]!
-  pageInfo: PageInfo!
-  totalCount: Int!
-}
-
-type ExampleEdge {
-  cursor: String!
-  node: Example!
-}
-
-type PageInfo {
-  hasNextPage: Boolean!
-  hasPreviousPage: Boolean!
-  startCursor: String
-  endCursor: String
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
-| `pageInfo.hasNextPage` | `true` when more results come after the last edge |
-| `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
-| `pageInfo.startCursor` | The cursor of the first edge on the current page |
-| `pageInfo.endCursor` | The cursor of the last edge on the current page |
-| `totalCount` | The number of items on every page together |
-
-## Forward pagination with `first` and `after`
-
-To move forward through the results, use two arguments. The `first` argument gives
-the page size. The `after` argument gives the cursor to start after.
-
-### First page
-
-Leave the `after` argument out to read the first page:
-
-```graphql
-query {
-  organizations(input: { first: 10 }) {
-    edges {
-      cursor
-      node {
-        id
-        name
-      }
-    }
-    pageInfo {
-      hasNextPage
-      endCursor
-    }
-    totalCount
-  }
-}
-```
-
-### Next page
-
-Pass the `endCursor` from the previous response as the `after` argument:
-
-```graphql
-query {
-  organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
-    edges {
-      cursor
-      node {
-        id
-        name
-      }
-    }
-    pageInfo {
-      hasNextPage
-      endCursor
-    }
-    totalCount
-  }
-}
-```
-
-## Check for more pages
-
-Read the `hasNextPage` field before you ask for the next page:
-
-- `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
-  argument of the next request.
-- `hasNextPage: false` — you read every result. Stop here.
-
-## Full paginated query example
-
-This example reads every member of an organization, one page at a time:
-
-```graphql
-# Page 1
-query {
-  organization(input: { slug: "my-company" }) {
-    members(first: 20) {
-      edges {
-        cursor
-        node {
-          id
-          userEmail
-          role
-          joinedAt
-        }
-      }
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-      totalCount
-    }
-  }
-}
-```
-
-If `pageInfo.hasNextPage` is `true`, fetch the next page:
-
-```graphql
-# Page 2
-query {
-  organization(input: { slug: "my-company" }) {
-    members(first: 20, after: "cursor_from_page_1") {
-      edges {
-        cursor
-        node {
-          id
-          userEmail
-          role
-          joinedAt
-        }
-      }
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-      totalCount
-    }
-  }
-}
-```
-
-Continue until `hasNextPage` returns `false`.
-
-## Paginated fields
-
-These fields in the schema return a connection type. They all take the `first` and
-`after` arguments:
-
-| Parent Type | Field | Connection Type |
-|------------|-------|----------------|
-| `Query` | `organizations` | `OrganizationConnection` |
-| `User` | `organizations` | `OrganizationConnection` |
-| `User` | `invitations` | `ViewerInvitationConnection` |
-| `Organization` | `members` | `OrganizationMemberConnection` |
-| `Organization` | `invitations` | `OrganizationInvitationConnection` |
-| `Organization` | `projects` | `ProjectConnection` |
-| `Project` | `reports` | `ProjectReportConnection` |
-
-All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
-
-## Tips
-
-- **The default page size** — the API applies a default limit when you leave `first`
-  out. Set `first` yourself to make sure that each page has the size you expect.
-- **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
-  build it, or change it. Pass it back exactly as the API gave it.
-- **The order is stable** — a connection returns its results in a stable order. The
-  same cursor always points at the same position in the result.
-- **Use them with other fields** — you can use the pagination arguments together with
-  other query fields. One request that reads an organization and the first page of
-  its members is common, and it is efficient.
-
-## Related
-
-- [Your first API call](/tutorials/first-api-call)
-- [Authorization and scopes](/reference/management-api/authorization-and-scopes)

package/dist/docs/reference/pickedql/data-sources.md

@@ -1,174 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Data sources
-
-PickedQL gives you four virtual tables. Each table is fast for one kind of work. It also gives you three reference tables, and those hold the options of your
-Picked project.
-
-## `metrics` — data that PickedQL aggregates each day
-
-Use it for a dashboard and to study a trend. There is one row for each unique set of
-dimensions on each day. The dimension columns are there directly, and they need no
-join. Examples are `device_category`, `country_code`, and `utm_source`.
-
-```sql
-SELECT device_category, control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-GROUP BY device_category
-```
-
-## `events` — one row for each event of each user
-
-Use it for a deep study, for a funnel, and for a breakdown of your own. There is one
-row for each event of each user. PickedQL joins a dimension column, such as
-`device_category` or `country_code`, when you point at it.
-
-```sql
-SELECT user_canonical_id, device_category
-FROM events
-WHERE project_id = 'your-project-id'
-  AND variant_type = 'Control'
-```
-
-## `features` — one row for each feature flag
-
-Use it to count the users, the sessions, and the events for each feature flag and
-bucket. It uses parameterized functions.
-
-```sql
-SELECT feature_users('homepage_test', 'control')
-FROM features
-WHERE project_id = 'your-project-id'
-```
-
-## `experience_journey` — step transitions for a sankey chart
-
-It returns one `source, target, users` row for each edge. You can put those rows
-directly into a sankey chart or a funnel chart. It holds the eight common table
-expressions that a card carried before. Those call `lagInFrame`, remove a duplicate
-between two steps that follow each other, and rank the top paths.
-
-Every filter goes in the **outer `WHERE`** clause. PickedQL reads each one as a
-parameter and puts it into the query below. Only `project_id` is necessary. The rest
-are optional, and each has a sensible default.
-
-| Parameter, as a WHERE key | What it does |
-|---|---|
-| `project_id` | The tenant filter. It is necessary. |
-| `experience_id` | Limits the rows to one `fact_events.experience_id`. |
-| `starting_step` | Anchors each edge at the first time that a user reaches this `step_id`. With no value, it anchors at the first `step_enter` event of that user. |
-| `targeting_step` | Trims the window of each user at the first time that the user reaches this `step_id`. A user who never reaches it still gives a journey, up to `num_nodes_after_start`. |
-| `num_nodes_after_start` | The size of the forward window from the start step. |
-| `num_nodes_before_target` | The size of the backward window from the target step. It needs `targeting_step`. |
-| `top_n_path` | Keeps the paths with the most users, and drops the rest. |
-| `user_cohort_event` | Limits the rows to a user with at least one `fact_events` row of this `event_type`, such as `'lead_capture'`. Use it for the paths of the users who reached a goal. |
-| `client_local_date` | A filter on the date. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. PickedQL puts it into the `fact_events` read below. |
-| `event_timestamp` | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
-
-When you set both `num_nodes_after_start` and `num_nodes_before_target`, both tests
-apply. The result is the intersection of the two.
-
-```sql
--- The "overall user journey" sankey.
--- It uses a forward window. The target step is optional.
-SELECT source, target, users FROM experience_journey
-WHERE project_id           = 'your-project-id'
-  AND starting_step        = 'step-start'
-  AND targeting_step       = 'step-target'
-  AND num_nodes_after_start = 10
-  AND client_local_date   >= '2026-04-01'    -- An optional range of dates.
-  AND client_local_date   <= '2026-04-30'
-```
-
-```sql
--- The "paths to a target" sankey.
--- It uses a backward window and it ranks the top paths.
-SELECT source, target, users FROM experience_journey
-WHERE project_id             = 'your-project-id'
-  AND experience_id          = 'exp-123'
-  AND starting_step          = 'step-start'
-  AND targeting_step         = 'step-target'
-  AND num_nodes_before_target = 5
-  AND top_n_path             = 10
-```
-
-```sql
--- The "drop-off" sankey. Leave the target step out.
-SELECT source, target, users FROM experience_journey
-WHERE project_id           = 'your-project-id'
-  AND experience_id        = 'exp-123'
-  AND starting_step        = 'step-start'
-  AND num_nodes_after_start = 10
-```
-
-```sql
--- A cohort sankey. It holds the users who reached the goal only.
-SELECT source, target, users FROM experience_journey
-WHERE project_id           = 'your-project-id'
-  AND starting_step        = 'step-start'
-  AND targeting_step       = 'step-target'
-  AND num_nodes_after_start = 10
-  AND user_cohort_event    = 'lead_capture'   -- Users with one or more of these events.
-```
-
-The columns that it returns:
-
-| Column | Type | Description |
-|---|---|---|
-| `source` | String | The start of the edge, in the form `NN. <step title>`, such as `001. Welcome screen`. PickedQL joins `steps` to find the title. |
-| `target` | String | The end of the edge, in the form `NN. <step title>`. |
-| `users` | `UInt64` | The number of different `user_canonical_id` values that went along this edge. |
-
-:::note
-`experience_journey` returns data that PickedQL aggregates first. It does **not**
-support a dimension filter such as `variant_type`, `device_category`, or
-`country_code`. To use one of those, query
-[`events`](#events--one-row-for-each-event-of-each-user) directly and build the
-transitions yourself.
-:::
-
-## Reference tables — `steps`, `experiences`, `projects`
-
-These reference tables hold the configuration of your Picked project. They have two uses:
-
-- **PickedQL joins them onto `events`** when you point at one of their analyst
-  columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
-- **You can read them directly.** Each one then needs its own tenant filter, so that
-  you see only the rows of a project that you can reach.
-
-| Source | The tenant filter that it needs |
-|---|---|
-| `steps` | `WHERE project_id = '<project_id>'` |
-| `experiences` | `WHERE project_id = '<project_id>'` |
-| `projects` | `WHERE id = '<project_id>'` |
-
-```sql
--- A direct query that reads the experiences of a project.
-SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
-
--- A direct query that reads the metadata of one project.
-SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
-```
-
-```sql
--- Pointed at from events. PickedQL adds each LEFT JOIN for you.
--- The reference tables need no separate tenant filter, because
--- the event table already limits the join.
-SELECT experience_title, step_title, count(*)
-FROM events
-WHERE project_id = 'your-project-id'
-GROUP BY experience_title, step_title
-```
-
-See [Schema, reference tables](/reference/pickedql/schema#steps-experiences-projects) for the full
-column list and the join keys.
-
-## Related
-
-- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
-- [Schema](/reference/pickedql/schema)
-- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/dimensions.md

@@ -1,103 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Dimension columns
-
-Every data source has dimension columns. The `metrics` table holds them directly. On
-`events` and on `features`, PickedQL adds the `LEFT JOIN` that it needs when you
-point at one. You write no join.
-
-## The dimensions
-
-| Source | Columns |
-|---|---|
-| `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
-| `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
-| `dim_geo` | `country_code`, `country_name`, `region`, `city` |
-| `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
-| `dim_product` | `product_name`, `product_category`, `product_page` |
-| `steps` | `step_title` |
-| `experiences` | `experience_title` |
-| `projects` | `project_name`, `project_timezone` |
-
-:::warning
-`dim_variant` describes whether the visitor is a known user. It does **not** hold the variants
-of your feature flags. To count the visitors in one variant, use
-[`feature_users`](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
-:::
-
-The `steps`, `experiences`, and `projects` sources are reference tables, and they come
-from the operational database. PickedQL joins them onto `events` and `fact_events`
-when you point at one of their analyst-facing columns. Each one **also** needs its own
-tenant filter when you query it directly:
-
-| Source | The tenant filter that it needs |
-|---|---|
-| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
-| `projects` | `WHERE id = '<project_id>'`, because the `id` of the row is the project ID |
-
-PickedQL also puts a tenant equality in the `ON` clause of each join that it adds.
-Examples are `AND st.project_id = '<project_id>'` and `AND pr.id = '<project_id>'`.
-ClickHouse then reads part of the dimension table and not all of it. PickedQL puts
-the test in `ON` and not in `WHERE`, because a test in `WHERE` would change a
-`LEFT JOIN` into an inner join.
-
-Each analyst-facing column name carries a prefix, such as `step_title` and
-`project_name`. The prefix stops a collision between two sources. Both `steps.title`
-and `experiences.title` are there, and you point at them as `step_title` and
-`experience_title`.
-
-```sql
--- Group the events by experience and by step name.
--- PickedQL joins both `experiences` and `steps` for you.
-SELECT experience_title, step_title, count(*)
-FROM events
-WHERE project_id = 'your-project-id'
-GROUP BY experience_title, step_title
-```
-
-An automatic join also works inside a subquery and inside a common table expression.
-Point at a dimension column where you need it, and PickedQL adds the `LEFT JOIN` at
-that level:
-
-```sql
--- Dimension columns inside a common table expression.
-WITH per_step AS (
-  SELECT step_title, count(*) AS n
-  FROM events
-  WHERE project_id = 'your-project-id'
-  GROUP BY step_title
-)
-SELECT * FROM per_step ORDER BY n DESC
-
--- Dimension columns inside a nested query.
-SELECT step_title, n FROM (
-  SELECT step_title, count(*) AS n FROM events
-  WHERE project_id = 'your-project-id'
-  GROUP BY step_title
-) sub
-```
-
-## Native event columns
-
-These columns are on `events` directly, and they need no join:
-
-`event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.
-
-Two of them take a name from the SDK. A filter on a name that does not exist gives an
-empty result set and not an error:
-
-| Column | The values that it holds |
-|---|---|
-| `event_type` | The name of the event, such as `step_enter` or `cart_add`. [Analytics events](/reference/sdk/analytics-events) names every one, together with the name of each custom event of your own. |
-| `interaction_type` | The label of the element behind the event. It falls back to `event_type` when the event has no element, so it is **not** the list of interaction types. [Analytics events](/reference/sdk/analytics-events) describes both. |
-
-## Related
-
-- [About PickedQL](/explanation/how-pickedql-works) — why you write no join.
-- [Data sources](/reference/pickedql/data-sources)
-- [Analytics events](/reference/sdk/analytics-events) — every `event_type` value, and the
-  contexts behind these columns.
-- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/filtering.md

@@ -1,64 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Filters
-
-Add a `WHERE` clause in the usual way. Every query must hold a `project_id` filter.
-PickedQL reads that filter and checks that you have permission for the project.
-PickedQL rejects a query with no `project_id` filter.
-
-```sql
--- A range of dates.
-SELECT control_users() FROM metrics
-WHERE project_id = 'your-project-id'
-  AND project_local_date BETWEEN '2026-03-01' AND '2026-03-31'
-
--- By experience.
-SELECT step_enter_users() FROM events
-WHERE project_id = 'your-project-id'
-  AND experience_id = 'my-experience'
-GROUP BY step_id
-
--- Combined filters
-SELECT control_users(), variant_users() FROM metrics
-WHERE project_id = 'your-project-id'
-  AND project_local_date >= '2026-03-01'
-  AND experience_id = 'my-experience'
-  AND device_category = 'Mobile'
-```
-
-:::warning
-Each query can only filter on a single `project_id`. Queries that reference multiple projects will be rejected.
-:::
-
-## Reference tables, each with its own tenant filter
-
-A query against a reference table needs its own tenant filter. The reference tables
-are `steps`, `experiences`, and `projects`. The filter makes sure that you see only
-the rows of a project that you can reach:
-
-| Source | Tenant filter |
-|---|---|
-| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
-| `projects` | `WHERE id = '<project_id>'` (the row's `id` IS the project id) |
-
-```sql
--- All experiences for one project
-SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
-
--- All steps for one project
-SELECT id, title FROM steps WHERE project_id = 'your-project-id'
-
--- Metadata for one project
-SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
-```
-
-The small lookup tables (`dim_variant`, `dim_device`, `dim_geo`, `dim_utm`, `dim_product`) are still exempt — they contain no tenant data.
-
-## Related
-
-- [Virtual functions](/reference/pickedql/virtual-functions) — the functions that take a
-  filter.
-- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/index.md

@@ -1,18 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# PickedQL
-
-PickedQL is a SQL query language for your Picked analytics data. Write short SQL with
-a virtual table and a virtual function. PickedQL expands them into a full query, and
-it adds the joins and the A/B test aggregations for you.
-
-## Related
-
-- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands, and why a
-  tenant filter is required.
-- [Analytics queries](/how-to/analytics) — worked examples.
-- [Data sources](/reference/pickedql/data-sources) — every table.
-- [Filters](/reference/pickedql/filtering) — the filter string a virtual function takes.