picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/analytics-session.md

@@ -0,0 +1,363 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Analytics session schema
+
+The operations and types that `analytics-session.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Types
+
+### `AnalyticsSession`
+
+```graphql
+"""
+One visit by a visitor: the analytics events one person produced on a site, from
+their first event until 30 minutes passed without another. A lead's `session` is
+the visit during which the lead was captured.
+"""
+type AnalyticsSession {
+  """The identity resolver's session identifier."""
+  id: ID!
+  """
+  What the visit adds up to, each event counted once: when it started and ended,
+  how the visitor arrived, and on what device from where. Requires scope:
+  `ORGANIZATION_LEADS_READ`.
+  """
+  summary: AnalyticsSessionSummary! @auth
+  """
+  The visit's timeline: the events that read as the visitor's path, each once,
+  oldest first. Without a cursor, `last` ends the page with the capture event and
+  `first` starts it there; with neither, the page is the 20 events ending with the
+  capture. A page holds at most 100 events. The newest events can take a few
+  minutes to arrive. Requires scope: `ORGANIZATION_LEADS_READ`.
+  """
+  events(first: Int, after: String, last: Int, before: String): AnalyticsEventConnection! @auth
+  """
+  The lead captured during the visit, or null when it captured none. A session
+  listed by `Project.analyticsSessions` that captured several gives the latest; one
+  reached through `Lead.session` gives that lead. Requires scope:
+  `ORGANIZATION_LEADS_READ`.
+  """
+  lead: Lead @auth
+  """
+  The Session reports on the visit, in order: the overview, the
+  journey through the experience's steps, and the full event log. Each is a
+  signed guest embed URL with the session's project and the session locked,
+  read from the project's analytics warehouse. Requires scope:
+  `ORGANIZATION_LEADS_READ`.
+  """
+  reports: [AnalyticsSessionReport!]! @auth
+}
+```
+
+### `AnalyticsSessionReport`
+
+```graphql
+"""
+A report on one analytics session, embedded with the session's
+project and the session locked, so the embed shows that visit and no other.
+"""
+type AnalyticsSessionReport {
+  """Which of the Session reports this is."""
+  kind: AnalyticsSessionReportKind!
+  """
+  URL of a signed embed of the report, for an iframe. The
+  signature expires 3 hours after the field is read.
+  """
+  embedUrl: String!
+}
+```
+
+### `AnalyticsSessionReportKind`
+
+```graphql
+"""The Session reports."""
+enum AnalyticsSessionReportKind {
+  """
+  How the visit ended, who the visitor was, when they were active and their other visits.
+  """
+  OVERVIEW
+  """
+  Every step entry in order, with time on step, submit outcomes, errors and clicks.
+  """
+  JOURNEY
+  """Every event the visit recorded, in order, in the visitor's clock."""
+  EVENT_LOG
+}
+```
+
+### `AnalyticsSessionsReport`
+
+```graphql
+"""
+One of the project's Sessions reports: a Metabase dashboard over all of its
+sessions, signed for embedding with the project locked, so the embed shows that
+project's sessions and no other. Its date range is an editable filter inside the
+embed.
+"""
+type AnalyticsSessionsReport {
+  """Which of the Sessions reports this is."""
+  kind: AnalyticsSessionsReportKind!
+  """
+  URL of a signed embed of the report, for an iframe. The
+  signature expires 3 hours after the field is read.
+  """
+  embedUrl: String!
+}
+```
+
+### `AnalyticsSessionsReportKind`
+
+```graphql
+"""The Sessions reports."""
+enum AnalyticsSessionsReportKind {
+  """
+  How sessions arrive: volume, channel, referrer, campaign, landing page, device, place and time of arrival.
+  """
+  ACQUISITION
+  """
+  The journeys sessions take: length, pages, returning visits, experiences, step paths and where they leave.
+  """
+  JOURNEYS
+  """
+  Which sessions convert: the funnel, the conversion rate by week and by segment.
+  """
+  CONVERSION
+}
+```
+
+### `AnalyticsSessionConnection`
+
+```graphql
+"""
+Relay-style connection of analytics sessions, with both an `edges` list and a flat `nodes` accessor.
+"""
+type AnalyticsSessionConnection {
+  """List of analytics-session edges."""
+  edges: [AnalyticsSessionEdge!]!
+  """
+  Flat list of analytics sessions, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [AnalyticsSession!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """
+  Metrics over every session the connection's `window` holds, across all pages.
+  Pass `first: 0` on `Project.analyticsSessions` to read metrics without fetching a page.
+  """
+  metrics: AnalyticsSessionMetrics!
+}
+```
+
+### `AnalyticsSessionMetrics`
+
+```graphql
+"""
+Metrics over the sessions an `AnalyticsSessionConnection` holds. Every metric
+ignores the connection's page.
+"""
+type AnalyticsSessionMetrics {
+  """
+  Sessions by when each started. A session is its events inside the window, so
+  a visit that began before the window counts from its first event inside it.
+  
+  `groupBy` splits the count; `CONVERTED` into `converted` and `not_converted`.
+  """
+  count(groupBy: AnalyticsSessionCountGroupBy): CountMetric!
+}
+```
+
+### `AnalyticsSessionCountGroupBy`
+
+```graphql
+"""What a session count can be split by."""
+enum AnalyticsSessionCountGroupBy {
+  """
+  Whether the session converted: one of its events inside the window captured a
+  lead, a `lead_created` or `lead_capture`.
+  """
+  CONVERTED
+}
+```
+
+### `AnalyticsSessionEdge`
+
+```graphql
+"""Edge type for `AnalyticsSessionConnection`."""
+type AnalyticsSessionEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The analytics session."""
+  node: AnalyticsSession!
+}
+```
+
+### `AnalyticsSessionSummary`
+
+```graphql
+"""What an analytics session adds up to."""
+type AnalyticsSessionSummary {
+  """
+  When the session's first event happened, by the visitor's device clock.
+  """
+  startedAt: DateTime!
+  """When the session's last event happened, by the visitor's device clock."""
+  endedAt: DateTime!
+  """How many events the session's `events` timeline lists."""
+  eventCount: Int!
+  """How many pages the visitor viewed."""
+  pageViewCount: Int!
+  """Full URL of the first page the session's events happened on."""
+  landingPageUrl: String
+  """
+  Where the visitor came from, as the tracker classified the landing page's referrer.
+  """
+  referrer: AnalyticsReferrer
+  """The UTM campaign the landing page's URL carried."""
+  campaign: AnalyticsCampaign
+  """The visitor's device, as parsed from their user agent."""
+  device: AnalyticsDevice
+  """Where the visitor was, as looked up from their IP address."""
+  location: AnalyticsLocation
+  """
+  The visitor's Google Analytics client ID, from the session's first event to carry one.
+  """
+  gaid: String
+  """
+  The visitor's Picked ID: the canonical id identity resolution gave them, from the session's
+  first event to carry one.
+  """
+  visitorId: String
+}
+```
+
+### `AnalyticsReferrer`
+
+```graphql
+"""The site that referred a visitor, as the tracker classified its URL."""
+type AnalyticsReferrer {
+  """The referrer's name, in lowercase, such as `google` or `facebook`."""
+  source: String
+  """
+  The kind of referrer, such as `search`, `social`, `email` or `internal`.
+  """
+  medium: String
+}
+```
+
+### `AnalyticsCampaign`
+
+```graphql
+"""A visit's UTM campaign parameters."""
+type AnalyticsCampaign {
+  """`utm_source`."""
+  source: String
+  """`utm_medium`."""
+  medium: String
+  """`utm_campaign`."""
+  name: String
+}
+```
+
+### `AnalyticsDevice`
+
+```graphql
+"""A visitor's device, as parsed from their user agent."""
+type AnalyticsDevice {
+  """The class of device, such as `Desktop`, `Phone` or `Tablet`."""
+  category: String
+  """The browser's name, such as `Chrome`."""
+  browser: String
+  """The browser's major version."""
+  browserVersion: String
+  """The operating system's name, such as `Mac OS` or `Android`."""
+  operatingSystem: String
+  """The operating system's version."""
+  operatingSystemVersion: String
+}
+```
+
+### `AnalyticsLocation`
+
+```graphql
+"""Where a visitor was, as looked up from their IP address."""
+type AnalyticsLocation {
+  """The city's English name."""
+  city: String
+  """The ISO 3166-2 code of the region within the country, such as `NSW`."""
+  region: String
+  """The country's English name."""
+  country: String
+  """The country's ISO 3166-1 alpha-2 code."""
+  countryCode: String
+}
+```
+
+### `AnalyticsEvent`
+
+```graphql
+"""
+One analytics event in a visitor's session: a page viewed, a step entered or
+submitted, a product added to the cart, a lead captured. Together, a session's
+events read as the visitor's path through the site.
+"""
+type AnalyticsEvent {
+  """Unique event identifier."""
+  id: ID!
+  """
+  The event type, such as `page_view`, `step_enter`, `cart_add` or `lead_created`.
+  """
+  type: String!
+  """When the event happened, by the visitor's device clock."""
+  occurredAt: DateTime!
+  """Full URL of the page the event happened on."""
+  pageUrl: String
+  """Path of the page the event happened on."""
+  pagePath: String
+  """Title of the experience the event happened in."""
+  experienceTitle: String
+  """Title of the step the event concerns."""
+  stepTitle: String
+  """Title of the form the event concerns."""
+  formTitle: String
+  """Title of the modal the event concerns."""
+  modalTitle: String
+  """
+  The name of a product the event concerns: one of them, when it concerns several.
+  """
+  productTitle: String
+}
+```
+
+### `AnalyticsEventConnection`
+
+```graphql
+"""
+Relay-style connection of analytics events, with both an `edges` list and a flat `nodes` accessor.
+"""
+type AnalyticsEventConnection {
+  """List of analytics-event edges."""
+  edges: [AnalyticsEventEdge!]!
+  """
+  Flat list of analytics events, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [AnalyticsEvent!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+}
+```
+
+### `AnalyticsEventEdge`
+
+```graphql
+"""Edge type for `AnalyticsEventConnection`."""
+type AnalyticsEventEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The analytics event."""
+  node: AnalyticsEvent!
+}
+```

package/docs/reference/management-api/schema/analytics.md

@@ -0,0 +1,73 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Analytics schema
+
+The operations and types that `analytics.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `pickedqlQuery`
+
+Execute a PickedQL query scoped to the caller's authorised projects.
+
+```graphql
+pickedqlQuery(input: PickedqlQueryInput!): PickedqlQueryResult! @auth
+```
+
+## Types
+
+### `PickedqlQueryInput`
+
+```graphql
+"""Input for `pickedqlQuery` — execute a PickedQL statement."""
+input PickedqlQueryInput {
+  """
+  The SQL query to execute. Must include a tenant filter (e.g. `WHERE project_id = '…'`).
+  """
+  sql: String!
+}
+```
+
+### `PickedqlTableDataColumn`
+
+```graphql
+"""Column metadata for a PickedQL query result."""
+type PickedqlTableDataColumn {
+  """The column identifier."""
+  name: String!
+  """The data type (e.g. `String`, `UInt64`, `DateTime`)."""
+  dataType: String!
+  """Human-readable column label."""
+  displayName: String!
+}
+```
+
+### `PickedqlTableData`
+
+```graphql
+"""Structured table data from a PickedQL query."""
+type PickedqlTableData {
+  """Column definitions with name, type, and display name."""
+  columns: [PickedqlTableDataColumn!]!
+  """
+  Rows of cell values. Each row is a list of stringified cell values aligned with the `columns` array.
+  """
+  rowData: [[String]!]!
+}
+```
+
+### `PickedqlQueryResult`
+
+```graphql
+"""Result of a PickedQL query (ShopifyQL-style structured shape)."""
+type PickedqlQueryResult {
+  """Structured table data, null if the query failed to parse or validate."""
+  tableData: PickedqlTableData
+  """Parse or validation errors, empty if the query succeeded."""
+  parseErrors: [String!]!
+}
+```

package/docs/reference/management-api/schema/api-key.md

@@ -0,0 +1,170 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Api key schema
+
+The operations and types that `api-key.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `apiKeys`
+
+List API keys for an organisation. Requires authentication.
+
+```graphql
+apiKeys(input: ApiKeysInput!): [ApiKey!]! @auth
+```
+
+## Mutations
+
+### `apiKeyCreate`
+
+Create a new API key. Requires scope: `ORGANIZATION_API_KEYS_CREATE`. User authentication only (not API key).
+
+```graphql
+apiKeyCreate(input: ApiKeyCreateInput!): ApiKeyCreatePayload! @auth(only: USER)
+```
+
+### `apiKeyRevoke`
+
+Revoke an API key. Requires scope: `ORGANIZATION_API_KEYS_DELETE`.
+
+```graphql
+apiKeyRevoke(input: ApiKeyRevokeInput!): Boolean! @auth
+```
+
+## Types
+
+### `ApiKey`
+
+```graphql
+"""
+An API key for programmatic access. Scoped to one organisation; may
+additionally be scoped to a single project. Carries a static list of
+authorisation scopes that gate every API operation the key performs.
+
+`keyPrefix` is the first few characters of the secret — used as a
+human-readable identifier in the dashboard and audit logs. The full
+secret is only returned once at creation time (see `ApiKeyCreatePayload`).
+"""
+type ApiKey {
+  """Unique identifier for the API key."""
+  id: ID!
+  """Display name of the API key."""
+  name: String!
+  """
+  Prefix of the key for identification (e.g. `pk_abc12…`). Safe to log and display.
+  """
+  keyPrefix: String!
+  """
+  ID of the project this key is scoped to, or null when the key is org-wide.
+  """
+  projectId: String
+  """Name of the project this key is scoped to (denormalised for display)."""
+  projectName: String
+  """ID of the user who created this key."""
+  createdBy: ID!
+  """Email of the user who created this key (denormalised for display)."""
+  createdByEmail: String!
+  """When this key was created."""
+  createdAt: String!
+  """
+  Scopes this API key has access to. Must be a subset of the creator's scopes at creation time.
+  """
+  scopes: [Scope!]!
+}
+```
+
+### `ApiKeyEdge`
+
+```graphql
+"""Edge type for `ApiKeyConnection`."""
+type ApiKeyEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The API key."""
+  node: ApiKey!
+}
+```
+
+### `ApiKeyConnection`
+
+```graphql
+"""Relay-style connection of API keys."""
+type ApiKeyConnection {
+  """List of API key edges."""
+  edges: [ApiKeyEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of API keys."""
+  totalCount: Int!
+}
+```
+
+### `ApiKeyCreatePayload`
+
+```graphql
+"""
+Payload returned by `apiKeyCreate`. WARNING: `apiKey` is the only place
+the full secret is exposed; subsequent reads return only the prefix.
+Show it to the user once and discard.
+"""
+type ApiKeyCreatePayload {
+  """
+  The full API key — shown only once at creation time. Treat as sensitive.
+  """
+  apiKey: String!
+}
+```
+
+### `ApiKeysInput`
+
+```graphql
+"""Input for listing API keys."""
+input ApiKeysInput {
+  """ID of the organisation to list keys for."""
+  organizationId: ID!
+}
+```
+
+### `ApiKeyCreateInput`
+
+```graphql
+"""
+Input for `apiKeyCreate`. Scopes must be a subset of the creator's
+scopes — granting a scope the caller does not hold is rejected with
+`FORBIDDEN`.
+"""
+input ApiKeyCreateInput {
+  """ID of the organisation to create the key in."""
+  organizationId: ID!
+  """Display name for the API key."""
+  name: String!
+  """
+  Optional project ID to scope the key to. When null, the key is org-wide. A
+  project-scoped key is refused on any operation outside that project, including
+  organization-level ones.
+  """
+  projectId: ID
+  """
+  Required scopes for this API key. Must be a subset of the creator's scopes, and
+  of the project-level scopes when `projectId` is set.
+  """
+  scopes: [Scope!]!
+}
+```
+
+### `ApiKeyRevokeInput`
+
+```graphql
+"""Input for `apiKeyRevoke` — invalidates the key immediately."""
+input ApiKeyRevokeInput {
+  """ID of the API key to revoke."""
+  keyId: ID!
+  """ID of the organisation the key belongs to."""
+  organizationId: ID!
+}
+```