picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ generated: true
 
 # Lead schema
 
-The operations and types that `lead.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `lead`
 
-Get a lead by ID. Requires scope: `ORGANIZATION_LEADS_READ`.
+Reads a lead.
+Scope: `ORGANIZATION_LEADS_READ`.
 
 ```graphql
 lead(input: LeadInput!): Lead @auth
@@ -22,7 +23,8 @@ lead(input: LeadInput!): Lead @auth
 
 ### `leadDelete`
 
-Permanently delete a lead and its labels. Requires scope: `ORGANIZATION_LEADS_DELETE`.
+Deletes a lead and its labels. This cannot be undone.
+Scope: `ORGANIZATION_LEADS_DELETE`.
 
 ```graphql
 leadDelete(input: LeadDeleteInput!): LeadDeletePayload! @auth
@@ -34,68 +36,56 @@ leadDelete(input: LeadDeleteInput!): LeadDeletePayload! @auth
 
 ```graphql
 """
-A captured lead. Project-scoped, and the only place a visitor's responses are
-readable.
-
-`responses` is resolved against the field schema of `workspaceVersion`, so each
-one carries the label and type an author gave the field. When a workspace
-preview captured the lead there is no version to resolve against, and the
-responses fall back to their raw keys.
+One set of answers that a visitor gave to a flow. It belongs to the project and stays after a new
+version is published.
 """
 type Lead {
-  """Unique lead identifier."""
+  """The ID of the lead."""
   id: ID!
-  """ID of the project that captured this lead."""
+  """The ID of the project that captured the lead."""
   projectId: ID!
-  """
-  The visitor the SDK identified. Anonymous: a capture is not an account.
-  """
+  """The ID the SDK gave the visitor."""
   userId: String!
   """
-  The published version whose schema names the response keys, or null when a workspace preview captured the lead.
+  The ID of the version that captured the lead. Null when a workspace preview captured it.
   """
   workspaceVersionId: ID
   """
-  The version this lead was captured against, or null for a preview capture.
+  The version that captured the lead. Null when a workspace preview captured it.
   """
   workspaceVersion: WorkspaceVersion
   """
-  The visitor's answers, each resolved to the label and type its field declares.
+  The answers, each with the label and type of its field in the capturing version. For a preview
+  capture, each label is the key and each type is `TEXT`.
   """
   responses: [LeadResponse!]!
-  """Annotations on this lead, ordered by namespace then key."""
+  """The labels on the lead, ordered by namespace, then key."""
   labels: [Label!]!
   """
-  What was done to this lead and by whom, latest first: its capture, and each
-  later change, including a change to its labels, whether a workflow task, a
-  person or an integration made it.
-  Pass `reverse: false` for the capture first. Requires scope: `ORGANIZATION_LEADS_READ`.
+  The changes to the lead, newest first: its capture, and each later change, its labels included.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   operations(first: Int, after: String, sortKey: OperationSortKeys = OCCURRED_AT, reverse: Boolean = true): LeadOperationConnection! @auth
   """
-  The workflow runs that created or changed this lead, each once, latest first.
-  Pass `reverse: false` for the earliest first. Requires scopes:
-  `ORGANIZATION_LEADS_READ` and `ORGANIZATION_PROJECTS_READ`.
+  The workflow runs that created or changed the lead, each once, newest first.
+  Scope: `ORGANIZATION_LEADS_READ` and `ORGANIZATION_PROJECTS_READ`.
   """
   workflowRuns(first: Int, after: String, last: Int, before: String, reverse: Boolean = true): WorkflowRunConnection! @auth
   """
-  Every lead captured under this lead's SDK session id (`userId`), this lead
-  included, newest first unless `reverse` is false. A visitor who passes several
-  capture points in one flow leaves a lead at each, so this is how a lead that
-  `Project.leads(collapse: SESSION)` stands for reaches the others.
-  `matchCount` counts them, and `metrics` counts over them. Requires scope:
-  `ORGANIZATION_LEADS_READ`.
+  Every lead with the same `userId`, this lead included, newest first. A visitor who passes
+  several capture points in one flow leaves a lead at each.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   sessionLeads(first: Int, after: String, last: Int, before: String, reverse: Boolean = true): LeadConnection! @auth
   """
-  The visitor session in which this lead was captured. Null when the lead has no
-  capture event, or analytics holds none for it: the event has yet to arrive, or was
-  captured outside production. Requires scope: `ORGANIZATION_LEADS_READ`.
+  The visit in which the visitor gave the lead. Null when the lead has no capture event, or when
+  analytics holds no event for it yet or the capture happened outside production.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   session: AnalyticsSession @auth
-  """When this lead was captured."""
+  """When the lead was captured."""
   createdAt: DateTime!
-  """When this lead was last changed."""
+  """When the lead last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -104,23 +94,22 @@ type Lead {
 
 ```graphql
 """
-One entry in a lead's log: something done to the lead, by a workflow run task,
-a person or an integration. `lead` is null once the lead has been deleted.
+A change to a lead, made by a workflow run task, a person or an integration.
 """
 type LeadOperation implements Operation {
-  """Unique operation identifier."""
+  """The ID of the operation."""
   id: ID!
-  """What was done to the lead."""
+  """What the operation did to the lead."""
   type: OperationType!
   """When the operation happened."""
   occurredAt: DateTime!
   """
-  The workflow run task that performed the operation, or null when it was not a workflow.
+  The workflow run task that made the change. Null when a workflow did not make it.
   """
   task: WorkflowTask
-  """ID of the lead, present after the lead is deleted."""
+  """The ID of the lead, which stays after the lead is deleted."""
   leadId: ID!
-  """The lead, or null once it has been deleted."""
+  """The lead. Null when the lead was deleted."""
   lead: Lead
 }
 ```
@@ -128,17 +117,15 @@ type LeadOperation implements Operation {
 ### `LeadOperationConnection`
 
 ```graphql
-"""Relay-style connection of a lead's operations, in the order asked."""
+"""A page of lead operations."""
 type LeadOperationConnection {
-  """List of operation edges."""
+  """The edges in this page."""
   edges: [LeadOperationEdge!]!
-  """
-  Flat list of operations, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The operations in this page."""
   nodes: [LeadOperation!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of operations on the lead."""
+  """The total number of operations on the lead."""
   totalCount: Int!
 }
 ```
@@ -146,9 +133,9 @@ type LeadOperationConnection {
 ### `LeadOperationEdge`
 
 ```graphql
-"""Edge type for `LeadOperationConnection`."""
+"""A lead operation in a page of results."""
 type LeadOperationEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The operation."""
   node: LeadOperation!
@@ -159,20 +146,16 @@ type LeadOperationEdge {
 
 ```graphql
 """
-One answer a visitor gave, joined to the field that requested it.
-
-`label` and `type` come from the capturing version's field schema. For a
-preview capture, `label` repeats `key` and `type` is `TEXT`, because there is no
-schema to resolve against.
+One answer in a lead, held under the key of the field that asked for it.
 """
 type LeadResponse {
-  """The field key this answer was stored under."""
+  """The key of the field."""
   key: String!
-  """The human-readable label the field declares."""
+  """The label of the field. For a preview capture, the key."""
   label: String!
-  """The kind of value the field captures."""
+  """The type of the field. For a preview capture, `TEXT`."""
   type: FieldType!
-  """The answer itself. Shape follows `type`."""
+  """The answer, shaped by `type`."""
   value: JSON
 }
 ```
@@ -180,30 +163,24 @@ type LeadResponse {
 ### `LeadConnection`
 
 ```graphql
-"""
-Relay-style connection of leads, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of leads."""
 type LeadConnection {
-  """List of lead edges."""
+  """The edges in this page."""
   edges: [LeadEdge!]!
-  """
-  Flat list of leads, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The leads in this page."""
   nodes: [Lead!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
   """
-  Total number of leads matching the query. A query with a `session.` clause
-  has no total, and this field fails for one.
+  The total number of leads the query matches. Fails for a query with a `session.` clause.
   """
   totalCount: Int! @deprecated(reason: "Use matchCount, which is null for a query with a session. clause.")
   """
-  The number of leads the query matches across every page; null when the query has a `session.` clause.
+  The number of leads the query matches across all pages. Null when the query has a `session.`
+  clause.
   """
   matchCount: Int
-  """
-  Metrics over every lead the connection's `query` matches, across all pages.
-  """
+  """Metrics over every lead the query matches, across all pages."""
   metrics: LeadMetrics!
 }
 ```
@@ -212,20 +189,17 @@ type LeadConnection {
 
 ```graphql
 """
-Metrics over the leads a `LeadConnection` matches. Every metric counts under
-the connection's `query` and ignores its page window and `sort`, so pass
-`first: 0` on `Project.leads` to read metrics without fetching a page.
+Metrics over the leads a `LeadConnection` matches. They ignore the page window and `sort`, so
+`first: 0` reads them without a page.
 """
 type LeadMetrics {
   """
-  Matching leads by capture time.
+  The number of matching leads by capture time.
   
-  `groupBy` splits the count by a path in the lead query grammar: a label
-  (`labels.aia.status`, or `aia.status`) or a response (`responses.state`, or
-  `state`). Leads with no value at the path group under an empty key.
-  
-  Under a `session.` clause the count reads the session of each capture event
-  of the leads created in the window.
+  `groupBy` splits the count by a path in the lead query language: a label (`labels.aia.status`
+  or `aia.status`) or a response (`responses.state` or `state`). Leads with no value at the path
+  group under an empty key. Under a `session.` clause, the count reads the visit of each capture
+  event.
   """
   count(groupBy: String): CountMetric!
 }
@@ -234,22 +208,13 @@ type LeadMetrics {
 ### `LeadCollapse`
 
 ```graphql
-"""
-How `Project.leads` reads the leads captured under one SDK session id
-(`Lead.userId`).
-
-A visitor who passes several capture points in one flow, such as a short form and
-then a longer one, leaves one lead at each. `SESSION` reads each session as its
-newest lead the query matches, and `Lead.sessionLeads` on that lead reaches the
-rest.
-"""
+"""How `Project.leads` treats several leads with the same `Lead.userId`."""
 enum LeadCollapse {
   """Every lead the query matches."""
   NONE
   """
-  One lead per SDK session id: the newest lead the query matches. `matchCount`
-  counts sessions, and `metrics` count each session once, at its newest lead in
-  the measured window. A query with a `session.` clause takes no collapse.
+  One lead per `userId`: the newest the query matches, which `matchCount` and `metrics` count once.
+  Not allowed with a `session.` clause.
   """
   SESSION
 }
@@ -258,9 +223,9 @@ enum LeadCollapse {
 ### `LeadEdge`
 
 ```graphql
-"""Edge type for `LeadConnection`."""
+"""A lead in a page of results."""
 type LeadEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The lead."""
   node: Lead!
@@ -270,9 +235,9 @@ type LeadEdge {
 ### `LeadInput`
 
 ```graphql
-"""Input for the top-level `lead` query."""
+"""The input of `lead`."""
 input LeadInput {
-  """ID of the lead to fetch."""
+  """The ID of the lead."""
   id: ID!
 }
 ```
@@ -280,9 +245,9 @@ input LeadInput {
 ### `LeadDeleteInput`
 
 ```graphql
-"""Input for `leadDelete`."""
+"""The input of `leadDelete`."""
 input LeadDeleteInput {
-  """ID of the lead to delete."""
+  """The ID of the lead."""
   id: ID!
 }
 ```
@@ -290,12 +255,9 @@ input LeadDeleteInput {
 ### `LeadDeletePayload`
 
 ```graphql
-"""
-Payload returned by `leadDelete`. The delete is permanent and takes the lead's
-labels with it, because deleting the row is how an erasure request is honoured.
-"""
+"""The result of `leadDelete`."""
 type LeadDeletePayload {
-  """ID of the deleted lead."""
+  """The ID of the deleted lead."""
   deletedLeadId: ID
 }
 ```
@@ -304,16 +266,15 @@ type LeadDeletePayload {
 
 ```graphql
 """
-A report on a project's leads, embedded with the project locked,
-so the embed shows that project's leads and no other. Its date range is an
-editable filter inside the embed.
+An embedded analytics report on the leads of one project. Its date range is a filter inside the
+embed.
 """
 type LeadReport {
-  """Which of the Leads reports this is."""
+  """The kind of report."""
   kind: LeadReportKind!
   """
-  URL of a signed embed of the report, for an iframe. The
-  signature expires 3 hours after the field is read.
+  The URL of a signed embed of the report, for an iframe. The signature expires 3 hours after the
+  field is read.
   """
   embedUrl: String!
 }
@@ -322,18 +283,18 @@ type LeadReport {
 ### `LeadReportKind`
 
 ```graphql
-"""The Leads reports."""
+"""The kinds of lead report."""
 enum LeadReportKind {
   """
-  How leads are acquired: volume, channel, referrer, campaign, landing page, device, place and time of arrival.
+  How leads arrive: volume, channel, referrer, campaign, landing page, device, place and time.
   """
   ACQUISITION
   """
-  The paths behind leads: first touch to lead, step sequences, visits and time to capture.
+  The paths to leads: first touch, step sequences, visits and time to capture.
   """
   JOURNEYS
   """
-  How visits convert to leads: the funnel, the lead rate by week and by segment, and what leads did that others did not.
+  How visits convert to leads: the funnel, the lead rate by week and segment, and what leads did.
   """
   CONVERSION
 }