picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,349 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Label schema
+
+The operations and types that `label.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Mutations
+
+### `labelsSet`
+
+Create or replace labels on an owner. Requires scope:
+`ORGANIZATION_LEADS_UPDATE` on the lead's project for a `LEAD` owner, and
+`ORGANIZATION_PROJECTS_UPDATE` on the project for a `PROJECT` or
+`WORKFLOW_RUN` owner.
+
+```graphql
+labelsSet(input: LabelsSetInput!): LabelsSetPayload! @auth
+```
+
+### `labelsDelete`
+
+Remove labels from an owner. Requires scope: `ORGANIZATION_LEADS_UPDATE` on
+the lead's project for a `LEAD` owner, and `ORGANIZATION_PROJECTS_UPDATE` on
+the project for a `PROJECT` or `WORKFLOW_RUN` owner.
+
+```graphql
+labelsDelete(input: LabelsDeleteInput!): LabelsDeletePayload! @auth
+```
+
+## Types
+
+### `LabelType`
+
+```graphql
+"""How to read a label's `value`."""
+enum LabelType {
+  """A plain string."""
+  TEXT
+  """A number, serialised as a string."""
+  NUMBER
+  """A boolean, serialised as `true` or `false`."""
+  BOOLEAN
+  """A JSON document, serialised as a string."""
+  JSON
+}
+```
+
+### `LabelOwnerType`
+
+```graphql
+"""
+The kind of entity a label is attached to. Each kind is read under its own
+scope and written under another:
+
+| Owner type | Read scope | Write scope |
+| --- | --- | --- |
+| `LEAD` | `ORGANIZATION_LEADS_READ` | `ORGANIZATION_LEADS_UPDATE` |
+| `PROJECT` | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE` |
+| `WORKFLOW_RUN` | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE` |
+
+A workflow run reads and writes its own labels without either scope.
+"""
+enum LabelOwnerType {
+  """A captured lead. Its labels are deleted with it."""
+  LEAD
+  """A project, whose id is the owner id. Its labels outlive every lead."""
+  PROJECT
+  """A workflow run. Its labels outlive every lead."""
+  WORKFLOW_RUN
+}
+```
+
+### `Label`
+
+```graphql
+"""
+An annotation on an owner. Unique per owner, namespace and key, so setting one
+that already exists replaces its value and type.
+
+A label written with `expiresIn` expires that many seconds after the write.
+Once it has expired it reads as absent: it leaves its owner's `labels`, matches
+no lead query clause, and a later write to it creates a new label with a new id.
+"""
+type Label {
+  """Unique label identifier."""
+  id: ID!
+  """Grouping for related keys, rendered as a section heading."""
+  namespace: String!
+  """Name of this label within its namespace."""
+  key: String!
+  """How to read `value`."""
+  type: LabelType!
+  """The value, always a string. Interpret it through `type`."""
+  value: String!
+  """When this label was first set."""
+  createdAt: DateTime!
+  """When this label was last changed."""
+  updatedAt: DateTime!
+  """When this label expires, or null when it does not expire."""
+  expiresAt: DateTime
+  """The owner this label annotates."""
+  owner: LabelOwner!
+}
+```
+
+### `LabelOwner`
+
+```graphql
+"""The resource a label annotates: a lead, a project or a workflow run."""
+union LabelOwner = Lead | Project | WorkflowRun
+```
+
+### `LabelOperation`
+
+```graphql
+"""
+One entry in a label's log: something done to the label, by a workflow run
+task, a person or an integration. `label` is null once the label has been
+removed or has expired.
+"""
+type LabelOperation implements Operation {
+  """Unique operation identifier."""
+  id: ID!
+  """What was done to the label."""
+  type: OperationType!
+  """When the operation happened."""
+  occurredAt: DateTime!
+  """
+  The workflow run task that performed the operation, or null when it was not a workflow.
+  """
+  task: WorkflowTask
+  """The label, or null once it has been removed or has expired."""
+  label: Label
+}
+```
+
+### `LabelInput`
+
+```graphql
+"""
+One label to set. Namespace and key must be 1-64 characters of lowercase
+letters, digits, underscore or hyphen; a dot is rejected, because the leads
+search query language splits `labels.<namespace>.<key>` on it.
+
+Exactly one of `value` and `increment` is required; a label carrying both, or
+neither, is refused with `LABEL_WRITE_INVALID`.
+
+Example, a lock that holds the caller's id for an hour unless another caller
+holds it already:
+
+    { namespace: "cms", key: "request-callback", type: TEXT, value: "wkrun_abc",
+      onlyIfAbsent: true, expiresIn: 3600 }
+
+Example, a counter:
+
+    { namespace: "cms", key: "sent-today", type: NUMBER, increment: 1, expiresIn: 86400 }
+"""
+input LabelInput {
+  """Grouping for related keys."""
+  namespace: String!
+  """Name of this label within its namespace."""
+  key: String!
+  """How to read `value`. Must be `NUMBER` with `increment`."""
+  type: LabelType!
+  """
+  The value, as a string. Must parse as `type`. A write with `value` and no
+  `expiresIn` makes the label permanent, clearing any expiry it had.
+  """
+  value: String
+  """
+  A finite number to add to the label's current value, in place of `value`; a
+  negative number subtracts.
+  An absent or expired label reads as 0. The label must be of type `NUMBER`:
+  an increment of a label of another type is refused with
+  `VALUE_INVALID_FOR_TYPE`, and the label is unchanged. Concurrent increments
+  all count. An increment keeps a live label's expiry, so its `expiresIn`
+  applies only when the increment creates the label. Each increment records an
+  operation, and cannot be combined with `onlyIfAbsent`.
+  """
+  increment: Float
+  """
+  Seconds from the write until the label expires: a whole number from 1 to
+  31536000 (365 days). An expired label reads as absent everywhere.
+  """
+  expiresIn: Int
+  """
+  Writes the label only when the owner holds no unexpired label under this
+  namespace and key. The check and the write are one atomic step, so of
+  several concurrent writes to an absent label exactly one takes effect.
+  
+  A live label that already holds this write's type and value counts as taken,
+  is left unchanged (its expiry included) and records no operation, so a
+  retried write reads the same result. A live label holding anything else is
+  left unchanged, is not taken, and is listed in `LabelsSetPayload.skipped`. A
+  lock's value should therefore be unique to its holder, such as a run id.
+  """
+  onlyIfAbsent: Boolean
+}
+```
+
+### `LabelIdentifierInput`
+
+```graphql
+"""Names one label without its value, for deletion."""
+input LabelIdentifierInput {
+  """Grouping for related keys."""
+  namespace: String!
+  """Name of this label within its namespace."""
+  key: String!
+  """
+  Removes the label only when it has not expired and its stored value equals
+  this. The check and the removal are one atomic step. A label holding another
+  value is left unchanged, records no operation, and is not counted as
+  removed: a holder releases its lock and never another holder's.
+  """
+  ifValue: String
+}
+```
+
+### `LabelsSetInput`
+
+```graphql
+"""
+Input for `labelsSet`. Creates or replaces each named label and leaves every
+other label on the owner untouched, so a partial save cannot discard work
+another writer did.
+
+The labels are taken in (namespace, key) order, so two concurrent calls naming
+the same labels cannot deadlock.
+"""
+input LabelsSetInput {
+  """The kind of entity being annotated."""
+  ownerType: LabelOwnerType!
+  """ID of the entity being annotated."""
+  ownerId: ID!
+  """
+  Labels to create or replace, one per namespace and key. A label naming the
+  namespace and key of an earlier one is refused with `LABEL_WRITE_INVALID`.
+  """
+  labels: [LabelInput!]!
+  """
+  Takes every label or none. When any `onlyIfAbsent` label is skipped, the call
+  writes nothing, records no operation, returns no `labels`, and lists in
+  `skipped` the existing labels that blocked it. Of two concurrent
+  `atomic` calls that both write some label with `onlyIfAbsent`, each
+  with a value unique to its caller, at most one takes effect. Defaults to
+  false.
+  """
+  atomic: Boolean
+}
+```
+
+### `LabelsSetPayload`
+
+```graphql
+"""Payload returned by `labelsSet`."""
+type LabelsSetPayload {
+  """
+  The labels the call took, as they now stand: those it wrote, and those an
+  `onlyIfAbsent` label found already holding its own type and value. Empty when
+  input failed validation.
+  """
+  labels: [Label!]!
+  """
+  The existing labels an `onlyIfAbsent` label left in place, because they held
+  another type or value.
+  """
+  skipped: [Label!]!
+  """Per-label validation errors. Empty array indicates success."""
+  userErrors: [LabelUserError!]!
+}
+```
+
+### `LabelsDeleteInput`
+
+```graphql
+"""
+Input for `labelsDelete`. Deleting a label that is not set is a no-op success.
+An expired label is deleted without being counted as removed.
+"""
+input LabelsDeleteInput {
+  """The kind of entity being annotated."""
+  ownerType: LabelOwnerType!
+  """ID of the entity being annotated."""
+  ownerId: ID!
+  """Labels to remove."""
+  labels: [LabelIdentifierInput!]!
+}
+```
+
+### `LabelsDeletePayload`
+
+```graphql
+"""Payload returned by `labelsDelete`."""
+type LabelsDeletePayload {
+  """
+  IDs of the labels that were removed. A label `ifValue` spared is not listed.
+  """
+  deletedLabelIds: [ID!]!
+  """Per-label validation errors. Empty array indicates success."""
+  userErrors: [LabelUserError!]!
+}
+```
+
+### `LabelUserErrorCode`
+
+```graphql
+"""Machine-readable error codes for the label mutations."""
+enum LabelUserErrorCode {
+  """The namespace is outside the accepted character set."""
+  NAMESPACE_INVALID
+  """The key is outside the accepted character set."""
+  KEY_INVALID
+  """The value does not parse as the declared type."""
+  VALUE_INVALID_FOR_TYPE
+  """
+  No owner of that type exists with that id, or the id carries another owner
+  type's prefix.
+  """
+  OWNER_NOT_FOUND
+  """
+  The write is malformed: it carries both `value` and `increment` or neither,
+  an `increment` with `onlyIfAbsent` or with a type other than `NUMBER`, an
+  `expiresIn` outside 1 to 31536000 seconds, or the namespace and key of an
+  earlier label in the same call.
+  """
+  LABEL_WRITE_INVALID
+}
+```
+
+### `LabelUserError`
+
+```graphql
+"""A user error from `labelsSet` or `labelsDelete`."""
+type LabelUserError {
+  """
+  Path to the input field that caused the error, e.g. `['labels', '0', 'namespace']`.
+  """
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: LabelUserErrorCode!
+}
+```

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

@@ -0,0 +1,340 @@
+---
+type: reference
+layout: docs
+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.
+
+## Queries
+
+### `lead`
+
+Get a lead by ID. Requires scope: `ORGANIZATION_LEADS_READ`.
+
+```graphql
+lead(input: LeadInput!): Lead @auth
+```
+
+## Mutations
+
+### `leadDelete`
+
+Permanently delete a lead and its labels. Requires scope: `ORGANIZATION_LEADS_DELETE`.
+
+```graphql
+leadDelete(input: LeadDeleteInput!): LeadDeletePayload! @auth
+```
+
+## Types
+
+### `Lead`
+
+```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.
+"""
+type Lead {
+  """Unique lead identifier."""
+  id: ID!
+  """ID of the project that captured this lead."""
+  projectId: ID!
+  """
+  The visitor the SDK identified. Anonymous: a capture is not an account.
+  """
+  userId: String!
+  """
+  The published version whose schema names the response keys, or null when a workspace preview captured the lead.
+  """
+  workspaceVersionId: ID
+  """
+  The version this lead was captured against, or null for a preview capture.
+  """
+  workspaceVersion: WorkspaceVersion
+  """
+  The visitor's answers, each resolved to the label and type its field declares.
+  """
+  responses: [LeadResponse!]!
+  """Annotations on this 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`.
+  """
+  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`.
+  """
+  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`.
+  """
+  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`.
+  """
+  session: AnalyticsSession @auth
+  """When this lead was captured."""
+  createdAt: DateTime!
+  """When this lead was last changed."""
+  updatedAt: DateTime!
+}
+```
+
+### `LeadOperation`
+
+```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.
+"""
+type LeadOperation implements Operation {
+  """Unique operation identifier."""
+  id: ID!
+  """What was done 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.
+  """
+  task: WorkflowTask
+  """ID of the lead, present after the lead is deleted."""
+  leadId: ID!
+  """The lead, or null once it has been deleted."""
+  lead: Lead
+}
+```
+
+### `LeadOperationConnection`
+
+```graphql
+"""Relay-style connection of a lead's operations, in the order asked."""
+type LeadOperationConnection {
+  """List of operation edges."""
+  edges: [LeadOperationEdge!]!
+  """
+  Flat list of operations, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [LeadOperation!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of operations on the lead."""
+  totalCount: Int!
+}
+```
+
+### `LeadOperationEdge`
+
+```graphql
+"""Edge type for `LeadOperationConnection`."""
+type LeadOperationEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The operation."""
+  node: LeadOperation!
+}
+```
+
+### `LeadResponse`
+
+```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.
+"""
+type LeadResponse {
+  """The field key this answer was stored under."""
+  key: String!
+  """The human-readable label the field declares."""
+  label: String!
+  """The kind of value the field captures."""
+  type: FieldType!
+  """The answer itself. Shape follows `type`."""
+  value: JSON
+}
+```
+
+### `LeadConnection`
+
+```graphql
+"""
+Relay-style connection of leads, with both an `edges` list and a flat `nodes` accessor.
+"""
+type LeadConnection {
+  """List of lead edges."""
+  edges: [LeadEdge!]!
+  """
+  Flat list of leads, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Lead!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """
+  Total number of leads matching the query. A query with a `session.` clause
+  has no total, and this field fails for one.
+  """
+  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.
+  """
+  matchCount: Int
+  """
+  Metrics over every lead the connection's `query` matches, across all pages.
+  """
+  metrics: LeadMetrics!
+}
+```
+
+### `LeadMetrics`
+
+```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.
+"""
+type LeadMetrics {
+  """
+  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.
+  """
+  count(groupBy: String): CountMetric!
+}
+```
+
+### `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.
+"""
+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.
+  """
+  SESSION
+}
+```
+
+### `LeadEdge`
+
+```graphql
+"""Edge type for `LeadConnection`."""
+type LeadEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The lead."""
+  node: Lead!
+}
+```
+
+### `LeadInput`
+
+```graphql
+"""Input for the top-level `lead` query."""
+input LeadInput {
+  """ID of the lead to fetch."""
+  id: ID!
+}
+```
+
+### `LeadDeleteInput`
+
+```graphql
+"""Input for `leadDelete`."""
+input LeadDeleteInput {
+  """ID of the lead to delete."""
+  id: ID!
+}
+```
+
+### `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.
+"""
+type LeadDeletePayload {
+  """ID of the deleted lead."""
+  deletedLeadId: ID
+}
+```
+
+### `LeadReport`
+
+```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.
+"""
+type LeadReport {
+  """Which of the Leads reports this is."""
+  kind: LeadReportKind!
+  """
+  URL of a signed embed of the report, for an iframe. The
+  signature expires 3 hours after the field is read.
+  """
+  embedUrl: String!
+}
+```
+
+### `LeadReportKind`
+
+```graphql
+"""The Leads reports."""
+enum LeadReportKind {
+  """
+  How leads are acquired: volume, channel, referrer, campaign, landing page, device, place and time of arrival.
+  """
+  ACQUISITION
+  """
+  The paths behind leads: first touch to lead, 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.
+  """
+  CONVERSION
+}
+```