picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/mcp-server.md

@@ -0,0 +1,299 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Mcp server schema
+
+The operations and types that `mcp-server.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `mcpServer`
+
+Fetch a single registered MCP server by ID, or null if it doesn't exist. Requires authentication.
+
+```graphql
+mcpServer(input: McpServerInput!): McpServer @auth
+```
+
+## Mutations
+
+### `mcpServerRegister`
+
+Register a new third-party MCP server. Requires a user context; API keys are rejected.
+
+```graphql
+mcpServerRegister(input: McpServerRegisterInput!): McpServerRegisterPayload! @auth(only: USER)
+```
+
+### `mcpServerUpdate`
+
+Update an MCP server's display name. URL rotation goes through `mcpServerUrlSet`. Requires a user context; API keys are rejected.
+
+```graphql
+mcpServerUpdate(input: McpServerUpdateInput!): McpServerUpdatePayload! @auth(only: USER)
+```
+
+### `mcpServerUrlSet`
+
+Rotate the MCP server's URL. The new URL is encrypted; the response surfaces only the display URL. Requires a user context; API keys are rejected.
+
+```graphql
+mcpServerUrlSet(input: McpServerUrlSetInput!): McpServerUrlSetPayload! @auth(only: USER)
+```
+
+### `mcpServerAuthHeaderSet`
+
+Set or replace the single auth header on an MCP server. Requires a user context; API keys are rejected.
+
+```graphql
+mcpServerAuthHeaderSet(input: McpServerAuthHeaderSetInput!): McpServerAuthHeaderSetPayload! @auth(only: USER)
+```
+
+### `mcpServerAuthHeaderClear`
+
+Remove the auth header from an MCP server. Idempotent. Requires a user context; API keys are rejected.
+
+```graphql
+mcpServerAuthHeaderClear(input: McpServerAuthHeaderClearInput!): McpServerAuthHeaderClearPayload! @auth(only: USER)
+```
+
+### `mcpServerDelete`
+
+Delete an MCP server registration and any encrypted credentials. Idempotent.
+
+```graphql
+mcpServerDelete(input: McpServerDeleteInput!): McpServerDeletePayload! @auth
+```
+
+## Types
+
+### `McpServer`
+
+```graphql
+"""
+A third-party MCP (Model Context Protocol) server registered to a project. Only the display URL (`urlDisplay` — scheme + host + pathname) and the auth header name are exposed; the full URL and any auth header value are encrypted at rest and never returned by this API.
+"""
+type McpServer {
+  """Unique MCP server identifier."""
+  id: ID!
+  """ID of the project this server belongs to."""
+  projectId: ID!
+  """Display name of the server."""
+  name: String!
+  """
+  Display URL — scheme + host + pathname (e.g. `https://example.com/mcp`). The query and fragment of the full URL are stripped; they often carry secrets and are not returned by this API.
+  """
+  urlDisplay: String!
+  """The auth header name, or null when no auth header is configured."""
+  authHeaderName: String
+  """True when an auth header value is configured on this server."""
+  hasAuthHeaderValue: Boolean!
+  """When this server was registered."""
+  createdAt: DateTime!
+  """When this server was last updated."""
+  updatedAt: DateTime!
+}
+```
+
+### `McpServerEdge`
+
+```graphql
+"""Edge type for MCP server connection."""
+type McpServerEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The MCP server."""
+  node: McpServer!
+}
+```
+
+### `McpServerConnection`
+
+```graphql
+"""Connection type for MCP servers (Relay-style pagination)."""
+type McpServerConnection {
+  """List of MCP server edges."""
+  edges: [McpServerEdge!]!
+  """Pagination information."""
+  pageInfo: PageInfo!
+  """Total number of MCP servers registered to the project."""
+  totalCount: Int!
+}
+```
+
+### `McpAuthHeaderInput`
+
+```graphql
+"""
+A single auth header to send when calling a registered MCP server. The value is encrypted at rest and only ever decrypted server-side.
+"""
+input McpAuthHeaderInput {
+  """Header name; defaults server-side to 'authorization' when omitted."""
+  name: String
+  """Header value to encrypt and persist."""
+  value: String!
+}
+```
+
+### `McpServerInput`
+
+```graphql
+"""Input for the top-level `mcpServer` query."""
+input McpServerInput {
+  """ID of the MCP server to fetch."""
+  id: ID!
+}
+```
+
+### `McpServerRegisterInput`
+
+```graphql
+"""
+Input for `mcpServerRegister`. The full URL is encrypted on commit; subsequent reads return only the display URL (scheme + host + pathname).
+"""
+input McpServerRegisterInput {
+  """
+  Project the MCP server should be registered to. The organisation is derived server-side from the project.
+  """
+  projectId: ID!
+  """Display name of the server."""
+  name: String!
+  """
+  MCP endpoint URL (may contain query-param secrets). Encrypted at rest; only the scheme + host + pathname portion is returned by this API.
+  """
+  url: String!
+  """Optional auth header to set on registration."""
+  authHeader: McpAuthHeaderInput
+}
+```
+
+### `McpServerUpdateInput`
+
+```graphql
+"""
+Input for `mcpServerUpdate`. Name-only — URL rotation goes through `mcpServerUrlSet`; header lifecycle is managed via `mcpServerAuthHeaderSet` / `mcpServerAuthHeaderClear`.
+"""
+input McpServerUpdateInput {
+  """ID of the MCP server to update."""
+  id: ID!
+  """New display name."""
+  name: String!
+}
+```
+
+### `McpServerUrlSetInput`
+
+```graphql
+"""
+Input for `mcpServerUrlSet`. Rotates the full URL atomically and updates the display URL.
+"""
+input McpServerUrlSetInput {
+  """ID of the MCP server."""
+  id: ID!
+  """
+  New full URL (may contain query-param secrets); validated server-side for scheme and host.
+  """
+  url: String!
+}
+```
+
+### `McpServerAuthHeaderSetInput`
+
+```graphql
+"""
+Input for `mcpServerAuthHeaderSet`. Creates or replaces the auth header value.
+"""
+input McpServerAuthHeaderSetInput {
+  """ID of the MCP server."""
+  id: ID!
+  """Header name; defaults server-side to 'authorization' when omitted."""
+  name: String
+  """Header value to encrypt and persist."""
+  value: String!
+}
+```
+
+### `McpServerAuthHeaderClearInput`
+
+```graphql
+"""
+Input for `mcpServerAuthHeaderClear`. Idempotent: clearing a server that has no header is a no-op success.
+"""
+input McpServerAuthHeaderClearInput {
+  """ID of the MCP server."""
+  id: ID!
+}
+```
+
+### `McpServerDeleteInput`
+
+```graphql
+"""Input for `mcpServerDelete`."""
+input McpServerDeleteInput {
+  """ID of the MCP server to delete."""
+  id: ID!
+}
+```
+
+### `McpServerRegisterPayload`
+
+```graphql
+"""Payload for `mcpServerRegister`."""
+type McpServerRegisterPayload {
+  """The freshly registered MCP server."""
+  mcpServer: McpServer
+}
+```
+
+### `McpServerUpdatePayload`
+
+```graphql
+"""Payload for `mcpServerUpdate`."""
+type McpServerUpdatePayload {
+  """The updated MCP server."""
+  mcpServer: McpServer
+}
+```
+
+### `McpServerUrlSetPayload`
+
+```graphql
+"""Payload for `mcpServerUrlSet`."""
+type McpServerUrlSetPayload {
+  """The updated MCP server."""
+  mcpServer: McpServer
+}
+```
+
+### `McpServerAuthHeaderSetPayload`
+
+```graphql
+"""Payload for `mcpServerAuthHeaderSet`."""
+type McpServerAuthHeaderSetPayload {
+  """The updated MCP server."""
+  mcpServer: McpServer
+}
+```
+
+### `McpServerAuthHeaderClearPayload`
+
+```graphql
+"""Payload for `mcpServerAuthHeaderClear`."""
+type McpServerAuthHeaderClearPayload {
+  """The updated MCP server."""
+  mcpServer: McpServer
+}
+```
+
+### `McpServerDeletePayload`
+
+```graphql
+"""Payload for `mcpServerDelete`."""
+type McpServerDeletePayload {
+  """True when the server was deleted."""
+  success: Boolean!
+}
+```

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

@@ -0,0 +1,223 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Metric schema
+
+The operations and types that `metric.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Types
+
+### `MetricTimeUnit`
+
+```graphql
+"""
+A unit of calendar time: a window's length, or a timeseries bucket's width.
+"""
+enum MetricTimeUnit {
+  """One hour."""
+  HOUR
+  """One day, from local midnight."""
+  DAY
+  """One week, from Monday at local midnight."""
+  WEEK
+  """One calendar month, from the first at local midnight."""
+  MONTH
+}
+```
+
+### `MetricDurationInput`
+
+```graphql
+"""A length of time as a whole number of units."""
+input MetricDurationInput {
+  """How many units. At least 1."""
+  amount: Int!
+  """The unit."""
+  unit: MetricTimeUnit!
+}
+```
+
+### `MetricDateRangeInput`
+
+```graphql
+"""Whole calendar days, both ends inclusive."""
+input MetricDateRangeInput {
+  """The first day."""
+  start: IsoDate!
+  """The last day, included."""
+  end: IsoDate!
+}
+```
+
+### `MetricWindowInput`
+
+```graphql
+"""
+The span of time a metric covers. Give exactly one of `last`, `dates`, or
+both `from` and `to`.
+
+`last` ends with the current unit and covers the `amount - 1` units before it,
+with unit boundaries in `timezone`: `{ amount: 7, unit: DAY }` is today and
+the six days before it. Two requests within the same unit resolve to the same
+window.
+"""
+input MetricWindowInput {
+  """A relative window ending with the current unit."""
+  last: MetricDurationInput
+  """
+  Whole days, from local midnight on `start` to local midnight after `end`.
+  """
+  dates: MetricDateRangeInput
+  """Start of an absolute window, inclusive."""
+  from: DateTime
+  """End of an absolute window, exclusive."""
+  to: DateTime
+  """
+  IANA time zone that unit and bucket boundaries align to. Defaults to the project's `timezone`.
+  """
+  timezone: String
+}
+```
+
+### `MetricWindow`
+
+```graphql
+"""
+The concrete span a metric covered after its window was resolved. Label a chart with it.
+"""
+type MetricWindow {
+  """Start of the window, inclusive."""
+  from: DateTime!
+  """End of the window, exclusive."""
+  to: DateTime!
+  """The IANA time zone unit and bucket boundaries align to."""
+  timezone: String!
+}
+```
+
+### `Metric`
+
+```graphql
+"""
+Something countable over time. Read `total` for a single number and
+`timeseries` for a chart.
+
+`window` defaults to the window of the resource the metric hangs off, such
+as the `window` given to `Project.leads`; a metric with neither fails. A
+measurement that would read too much data, or for too long, fails with an
+error rather than returning a partial value.
+"""
+interface Metric {
+  """
+  The metric over a window, split by the metric's group-by when it has one.
+  """
+  total(window: MetricWindowInput): MetricTotal!
+  """
+  The metric over a window, in buckets of `interval`. At most 745 buckets.
+  """
+  timeseries(window: MetricWindowInput, interval: MetricTimeUnit!): Timeseries!
+}
+```
+
+### `CountMetric`
+
+```graphql
+"""A plain count, such as leads captured or sessions started."""
+type CountMetric implements Metric {
+  """
+  The count over a window, split by the metric's group-by when it has one.
+  """
+  total(window: MetricWindowInput): MetricTotal!
+  """
+  The count over a window, in buckets of `interval`. At most 745 buckets.
+  """
+  timeseries(window: MetricWindowInput, interval: MetricTimeUnit!): Timeseries!
+}
+```
+
+### `MetricTotal`
+
+```graphql
+"""A metric's value over one window."""
+type MetricTotal {
+  """The window that was counted."""
+  window: MetricWindow!
+  """The value over the whole window."""
+  value: Float!
+  """
+  The value per group, largest first, when the metric has a group-by; empty
+  otherwise. At most 10 groups; the rest fold into one group whose `key` is null.
+  """
+  groups: [MetricGroupValue!]!
+  """True when values are estimates rather than exact counts."""
+  approximate: Boolean!
+  """The newest data the values reflect."""
+  freshAsOf: DateTime!
+}
+```
+
+### `MetricGroupValue`
+
+```graphql
+"""One group's share of a metric total."""
+type MetricGroupValue {
+  """
+  The group-by value, or null for the group folding every group past the cap.
+  """
+  key: String
+  """A human-readable name for the group."""
+  label: String!
+  """The group's value."""
+  value: Float!
+}
+```
+
+### `Timeseries`
+
+```graphql
+"""
+A metric bucketed over time, column by column. `buckets` is the time axis
+every series shares, and each series carries one value per bucket, so
+`series[i].values[j]` is the value of series `i` in the bucket starting at
+`buckets[j]`.
+"""
+type Timeseries {
+  """The window that was counted."""
+  window: MetricWindow!
+  """The width of each bucket."""
+  interval: MetricTimeUnit!
+  """
+  The start of each bucket, oldest first. Every bucket is present; an empty one counts 0.
+  """
+  buckets: [DateTime!]!
+  """
+  The series, largest first. One series with a null `key` when the metric has
+  no group-by. At most 10 series; the groups past the cap fold into one series
+  whose `key` is null.
+  """
+  series: [TimeseriesSeries!]!
+  """True when values are estimates rather than exact counts."""
+  approximate: Boolean!
+  """The newest data the values reflect."""
+  freshAsOf: DateTime!
+}
+```
+
+### `TimeseriesSeries`
+
+```graphql
+"""One line of a timeseries."""
+type TimeseriesSeries {
+  """
+  The group-by value; null for the folded "Other" series and for the single series of an ungrouped metric.
+  """
+  key: String
+  """A human-readable name for the series."""
+  label: String!
+  """One value per bucket, aligned with `Timeseries.buckets`."""
+  values: [Float!]!
+}
+```

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

@@ -0,0 +1,96 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Operation schema
+
+The operations and types that `operation.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Types
+
+### `OperationType`
+
+```graphql
+"""What an operation did to its resource."""
+enum OperationType {
+  """The resource was created."""
+  CREATED
+  """The resource was changed."""
+  UPDATED
+  """The resource was removed."""
+  DELETED
+}
+```
+
+### `OperationSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `WorkflowTask.operations(...)` and `Lead.operations(...)`.
+Pair with `reverse: true` to flip the order; both fields default to
+`reverse: true`, the latest operation first. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+"""
+enum OperationSortKeys {
+  """Sort by `occurredAt`."""
+  OCCURRED_AT
+}
+```
+
+### `Operation`
+
+```graphql
+"""
+One entry in the log of what was done to a resource.
+
+Every resource that is logged has its own implementing type carrying the
+resource itself — `LeadOperation.lead`, `LabelOperation.label` — and this
+interface carries what they share. `task` is the workflow run task that
+performed the operation, or null when a person or an integration did.
+"""
+interface Operation {
+  """Unique operation identifier."""
+  id: ID!
+  """What was done to the resource."""
+  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
+}
+```
+
+### `OperationConnection`
+
+```graphql
+"""
+Relay-style connection of operations of any resource, in the order asked.
+"""
+type OperationConnection {
+  """List of operation edges."""
+  edges: [OperationEdge!]!
+  """
+  Flat list of operations, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Operation!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of operations in the list."""
+  totalCount: Int!
+}
+```
+
+### `OperationEdge`
+
+```graphql
+"""Edge type for `OperationConnection`."""
+type OperationEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The operation."""
+  node: Operation!
+}
+```