picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,362 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Common schema
+
+The operations and types that `common.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `ping`
+
+Liveness probe used by infrastructure to confirm the GraphQL endpoint is up. Unauthenticated.
+
+```graphql
+ping: String!
+```
+
+## Types
+
+### `JSON`
+
+```graphql
+"""
+Arbitrary JSON value. Encoded as a JSON document; decoded as a JavaScript
+value (object, array, number, string, boolean, or null).
+
+Used as an escape hatch when the underlying shape is dynamic (workspace
+flow graphs, condition logic, validation rules, project settings, CMS
+field values). When a typed alternative exists, prefer that.
+"""
+scalar JSON
+```
+
+### `DateTime`
+
+```graphql
+"""
+ISO 8601 date-time string in UTC, e.g. `2026-05-14T08:30:00.000Z`. Always
+encoded with millisecond precision and a `Z` suffix; the server never
+emits a local offset.
+"""
+scalar DateTime
+```
+
+### `IsoDate`
+
+```graphql
+"""
+ISO 8601 date (`YYYY-MM-DD`) or date-time value used by CMS `DATE` fields.
+Unlike `DateTime`, a bare date without a time component is accepted, matching
+a `DATE` field whose `includeTime` flag is `false`. Values are round-tripped
+verbatim, so a date-only field never gains a spurious time-of-day.
+"""
+scalar IsoDate
+```
+
+### `AuthType`
+
+```graphql
+"""
+Restricts which authentication kind is accepted by an `@auth` directive.
+Most fields accept either credential; pass `only` to lock a field down to
+one transport.
+"""
+enum AuthType {
+  """A Supabase JWT (the `Authorization: Bearer <token>` header)."""
+  USER
+  """An API key (the `X-API-Key` header)."""
+  API_KEY
+}
+```
+
+### `AuthMfaPolicy`
+
+```graphql
+"""
+Whether a field holds a signed-in user to the multi-factor authentication
+policy. Every `@auth` field enforces it unless it says otherwise.
+"""
+enum AuthMfaPolicy {
+  """
+  Refuse a user who must hold a verified second factor and whose session is `AAL1` with `MFA_REQUIRED`.
+  """
+  ENFORCE
+  """
+  Serve the field at `AAL1`. Reserved for what a user needs to reach `AAL2` (`user` and
+  the MFA mutations) and for `passwordUpdate`, which checks the caller's factors itself.
+  """
+  EXEMPT
+}
+```
+
+### `auth`
+
+```graphql
+"""
+Authenticates the request using a Supabase JWT (`USER`) or an API key
+(`API_KEY`). By default, both auth types are accepted; use `only` to
+restrict to a specific type.
+
+Throws `UNAUTHENTICATED` if no credential is present, the credential is
+malformed, or the credential's type is not allowed by `only`.
+
+A user session is then held to the multi-factor authentication policy: a
+super admin, a client manager, or a member of an organisation that requires
+two-factor authentication is refused with `MFA_REQUIRED` when the session is
+`AAL1`, unless the field is `mfa: EXEMPT`. Tokens minted by the OAuth 2.1
+server satisfy the policy, because consent is only given from an `AAL2`
+session. API keys are never evaluated.
+
+The auth result is memoised per-request, so multiple `@auth` fields in
+the same operation share a single verify call.
+"""
+directive @auth(only: AuthType, mfa: AuthMfaPolicy = ENFORCE) on FIELD_DEFINITION
+```
+
+### `cache`
+
+```graphql
+"""
+HTTP `Cache-Control` policy applied to a field's response. The directive
+stores the policy on the GraphQL context during field resolution; a yoga
+plugin reads it and emits a `Cache-Control` response header. Responses
+that contain GraphQL errors never receive the header.
+
+WARNING: `@cache` MUST NOT be selected in the same operation as any `@auth`
+field. The cache header attaches to the entire response, so a public
+`Cache-Control` on a payload containing authenticated data leaks that data
+to shared caches. This is enforced by convention only — there is no
+runtime check. Keep cached fields in their own operations.
+
+WARNING: `policy` is opaque. Whatever string is passed is emitted verbatim
+as `Cache-Control`; there is no runtime validation. Use a hardcoded
+literal (e.g. `policy: "public, max-age=300"`). NEVER derive `policy` from
+user input.
+"""
+directive @cache(policy: String!) on FIELD_DEFINITION
+```
+
+### `Scope`
+
+```graphql
+"""
+Authorisation scopes following the `{entity}/{action}` convention. Used
+for fine-grained access control at the entity level — the dashboard and
+the SDKs both check scopes via `Organization.viewerScopes` and the
+authenticated user's root-level `viewerScopes`.
+
+Scopes prefixed with `ORGANIZATION_` are organisation-scoped (granted via
+an organisation membership). Scopes prefixed with `STAFF_` and `FLAGS_`
+are system-level (granted via the staff role on the user record).
+"""
+enum Scope {
+  """Create new organisations."""
+  ORGANIZATION_CREATE
+  """Read organisation details."""
+  ORGANIZATION_READ
+  """Update organisation settings (name, slug)."""
+  ORGANIZATION_UPDATE
+  """Delete an organisation."""
+  ORGANIZATION_DELETE
+  """Invite new organisation members."""
+  ORGANIZATION_MEMBERS_CREATE
+  """View organisation members."""
+  ORGANIZATION_MEMBERS_READ
+  """Update organisation member roles."""
+  ORGANIZATION_MEMBERS_UPDATE
+  """Remove organisation members."""
+  ORGANIZATION_MEMBERS_DELETE
+  """Grant and revoke the scopes held by organisation members."""
+  ORGANIZATION_MEMBERS_MANAGE_SCOPES
+  """Create organisation invitations."""
+  ORGANIZATION_INVITATIONS_CREATE
+  """View organisation invitations."""
+  ORGANIZATION_INVITATIONS_READ
+  """Revoke organisation invitations."""
+  ORGANIZATION_INVITATIONS_DELETE
+  """Create projects within an organisation."""
+  ORGANIZATION_PROJECTS_CREATE
+  """View organisation projects."""
+  ORGANIZATION_PROJECTS_READ
+  """Update organisation projects."""
+  ORGANIZATION_PROJECTS_UPDATE
+  """Delete organisation projects."""
+  ORGANIZATION_PROJECTS_DELETE
+  """Create API keys for an organisation."""
+  ORGANIZATION_API_KEYS_CREATE
+  """View organisation API keys."""
+  ORGANIZATION_API_KEYS_READ
+  """Revoke organisation API keys."""
+  ORGANIZATION_API_KEYS_DELETE
+  """Create organisation integrations."""
+  ORGANIZATION_INTEGRATIONS_CREATE
+  """View organisation integrations."""
+  ORGANIZATION_INTEGRATIONS_READ
+  """Update organisation integrations."""
+  ORGANIZATION_INTEGRATIONS_UPDATE
+  """Delete organisation integrations."""
+  ORGANIZATION_INTEGRATIONS_DELETE
+  """Create organisation reports."""
+  ORGANIZATION_REPORTS_CREATE
+  """View organisation reports."""
+  ORGANIZATION_REPORTS_READ
+  """Update organisation reports."""
+  ORGANIZATION_REPORTS_UPDATE
+  """Delete organisation reports."""
+  ORGANIZATION_REPORTS_DELETE
+  """View the content a project's workspaces hold."""
+  ORGANIZATION_WORKSPACE_READ
+  """Create, change and remove the content a project's workspaces hold."""
+  ORGANIZATION_WORKSPACE_UPDATE
+  """Create leads for an organisation's projects."""
+  ORGANIZATION_LEADS_CREATE
+  """View leads captured by an organisation's projects."""
+  ORGANIZATION_LEADS_READ
+  """Update leads and their labels."""
+  ORGANIZATION_LEADS_UPDATE
+  """Delete leads and their labels."""
+  ORGANIZATION_LEADS_DELETE
+  """Read the action run a workflow was started by."""
+  ORGANIZATION_ACTION_RUNS_READ
+  """Record a response against an action run."""
+  ORGANIZATION_ACTION_RUNS_UPDATE
+  """Call an external API registered to the project."""
+  ORGANIZATION_EXTERNAL_APIS_CALL
+  """View staff-level data (system-level, not organisation-scoped)."""
+  STAFF_READ
+  """Invite admin users (system-level)."""
+  STAFF_INVITE_ADMIN
+  """Invite client managers (system-level)."""
+  STAFF_INVITE_CLIENT_MANAGER
+  """Create feature flags (system-level)."""
+  FLAGS_CREATE
+  """Update feature flags (system-level)."""
+  FLAGS_UPDATE
+  """Delete feature flags (system-level)."""
+  FLAGS_DELETE
+  """
+  Reset a user's two-factor authentication: delete their factors and revoke their sessions (system-level, super admins only).
+  """
+  USERS_RESET_MFA
+  """Read live workspace versions (preview tokens, organisation members)."""
+  ORGANIZATION_WORKSPACE_VERSION_READ
+  """Read published workspace versions (anonymous public access)."""
+  ORGANIZATION_WORKSPACE_VERSION_READ_PUBLIC
+}
+```
+
+### `ErrorCode`
+
+```graphql
+"""
+General-purpose error codes returned in the standard GraphQL `errors`
+array's `extensions.code`. Auth-specific codes live on `AuthErrorCode` —
+this enum covers the rest of the API (organisations, projects, members,
+invitations, validation, internal errors).
+
+Each code maps to an HTTP status code in the response envelope. Use
+this enum when handling errors programmatically; do not parse the
+human-readable `message`.
+"""
+enum ErrorCode {
+  """The provided credentials are invalid."""
+  INVALID_CREDENTIALS
+  """The request is not authorised (the caller is unauthenticated)."""
+  UNAUTHORIZED
+  """
+  The request is forbidden (the caller is authenticated but lacks scope).
+  """
+  FORBIDDEN
+  """The specified organisation was not found."""
+  ORGANIZATION_NOT_FOUND
+  """An organisation with the provided name already exists."""
+  ORGANIZATION_ALREADY_EXISTS
+  """The provided slug is already in use."""
+  SLUG_ALREADY_EXISTS
+  """
+  The provided slug is invalid (allowed: lowercase letters, digits, hyphens).
+  """
+  INVALID_SLUG
+  """The specified member was not found."""
+  MEMBER_NOT_FOUND
+  """The user is already a member of this organisation."""
+  MEMBER_ALREADY_EXISTS
+  """The primary owner cannot be removed from the organisation."""
+  CANNOT_REMOVE_PRIMARY_OWNER
+  """The specified invitation was not found."""
+  INVITATION_NOT_FOUND
+  """The invitation has expired."""
+  INVITATION_EXPIRED
+  """The invitation has already been accepted."""
+  INVITATION_ALREADY_ACCEPTED
+  """The specified project was not found."""
+  PROJECT_NOT_FOUND
+  """The specified user was not found."""
+  USER_NOT_FOUND
+  """The role has already been granted to this user."""
+  ROLE_ALREADY_GRANTED
+  """The role has not been granted to this user."""
+  ROLE_NOT_GRANTED
+  """
+  A validation error occurred. Inspect `extensions.fields` for affected paths.
+  """
+  VALIDATION_ERROR
+  """An internal server error occurred."""
+  INTERNAL_ERROR
+}
+```
+
+### `PageInfo`
+
+```graphql
+"""
+Relay-style page metadata returned by every cursor-paginated `*Connection`
+type. Cursors are opaque, base64-encoded strings; treat them as opaque
+identifiers and do not parse or modify them.
+
+When `hasNextPage` is true, pass `endCursor` as the next `after` argument
+to fetch the next page. When `hasPreviousPage` is true and the connection
+supports backward pagination, pass `startCursor` as `before`.
+"""
+type PageInfo {
+  """Whether there are more items after the last edge in this page."""
+  hasNextPage: Boolean!
+  """Whether there are more items before the first edge in this page."""
+  hasPreviousPage: Boolean!
+  """Cursor of the first edge in the page (null if the page is empty)."""
+  startCursor: String
+  """Cursor of the last edge in the page (null if the page is empty)."""
+  endCursor: String
+}
+```
+
+### `UserError`
+
+```graphql
+"""
+A user-facing validation error attached to a mutation payload's
+`userErrors` array. Distinct from thrown domain errors (which surface in
+the standard GraphQL `errors` array): `userErrors` represent business-
+logic constraints the client should surface to the user, often with
+structured context.
+
+`field` is a dotted path into the operation's input; `code` is the
+machine-readable error code (mutation-specific, defined alongside the
+payload); `message` is human-readable and should be shown to the user.
+
+Some mutations return a typed subclass of `UserError` (e.g.
+`ActionDeleteUserError`) with extra fields like `referencingExperiences`.
+"""
+type UserError {
+  """Path to the field that caused the error."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: String
+}
+```

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

@@ -0,0 +1,254 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Condition schema
+
+The operations and types that `condition.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `condition`
+
+Get a condition by ID within a workspace.
+
+```graphql
+condition(id: ID!, workspaceId: ID!): Condition @auth
+```
+
+### `conditions`
+
+List conditions in a workspace. Filter by name with `search` (case-insensitive
+substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+
+```graphql
+conditions(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: ConditionSortKeys = NAME, reverse: Boolean = false): ConditionConnection! @auth
+```
+
+## Mutations
+
+### `conditionCreate`
+
+Create a new condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+conditionCreate(input: ConditionCreateInput!): ConditionCreatePayload! @auth
+```
+
+### `conditionUpdate`
+
+Update a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+conditionUpdate(input: ConditionUpdateInput!): ConditionUpdatePayload! @auth
+```
+
+### `conditionDelete`
+
+Delete a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+conditionDelete(input: ConditionDeleteInput!): ConditionDeletePayload! @auth
+```
+
+## Types
+
+### `Condition`
+
+```graphql
+"""
+Branching logic in an experience flow. The condition is evaluated by the
+SDK using the JSON-Logic format; `logic` is the AST.
+
+When attached to a `ConditionNode`, the result selects which outgoing
+edge (`sourceHandle: TRUE` / `FALSE`) the flow follows.
+"""
+type Condition {
+  """Unique condition identifier."""
+  id: ID!
+  """Display name of the condition."""
+  name: String!
+  """Stable, human-readable key for SDK consumers."""
+  key: String!
+  """
+  JSON Logic expression. See https://jsonlogic.com for the grammar — the
+  shape is a recursive tagged-tree e.g. `{ "and": [{ "==": [{ "var": "country" }, "US"] }, ...] }`.
+  """
+  logic: JSON!
+  """When this condition was created."""
+  createdAt: DateTime!
+  """When this condition was last updated."""
+  updatedAt: DateTime!
+  """The workspace this condition belongs to."""
+  workspace: Workspace!
+  """
+  The workspace ID this condition belongs to (denormalised for query convenience).
+  """
+  workspaceId: ID
+}
+```
+
+### `ConditionConnection`
+
+```graphql
+"""
+Relay-style connection of conditions, with both an `edges` list and a flat `nodes` accessor.
+"""
+type ConditionConnection {
+  """List of condition edges."""
+  edges: [ConditionEdge!]!
+  """
+  Flat list of conditions, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Condition!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of conditions."""
+  totalCount: Int!
+}
+```
+
+### `ConditionEdge`
+
+```graphql
+"""Edge type for `ConditionConnection`."""
+type ConditionEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The condition."""
+  node: Condition!
+}
+```
+
+### `ConditionCreateInput`
+
+```graphql
+"""Input for `conditionCreate`."""
+input ConditionCreateInput {
+  """Workspace ID to create the condition in."""
+  workspaceId: ID!
+  """Display name for the condition."""
+  name: String!
+  """Unique key identifier for the condition."""
+  key: String!
+  """
+  JSON Logic expression string for condition evaluation. Server parses and validates the JSON before persisting.
+  """
+  logicString: String!
+}
+```
+
+### `ConditionCreatePayload`
+
+```graphql
+"""Payload returned by `conditionCreate`."""
+type ConditionCreatePayload {
+  """The created condition."""
+  condition: Condition
+}
+```
+
+### `ConditionUpdateInput`
+
+```graphql
+"""Input for `conditionUpdate`. Omit a field to leave it unchanged."""
+input ConditionUpdateInput {
+  """Condition ID."""
+  id: ID!
+  """Workspace ID the condition belongs to."""
+  workspaceId: ID!
+  """New display name."""
+  name: String
+  """
+  New JSON Logic expression string. Server parses and validates the JSON before persisting.
+  """
+  logicString: String
+}
+```
+
+### `ConditionUpdatePayload`
+
+```graphql
+"""Payload returned by `conditionUpdate`."""
+type ConditionUpdatePayload {
+  """The updated condition."""
+  condition: Condition
+}
+```
+
+### `ConditionDeleteInput`
+
+```graphql
+"""Input for `conditionDelete`."""
+input ConditionDeleteInput {
+  """Condition ID."""
+  id: ID!
+  """Workspace ID the condition belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `ConditionDeletePayload`
+
+```graphql
+"""
+Payload returned by `conditionDelete`. Returns `userErrors` when the condition is in use.
+"""
+type ConditionDeletePayload {
+  """ID of the deleted condition (null when `userErrors` is non-empty)."""
+  deletedConditionId: ID
+  """Validation errors. Empty array indicates success."""
+  userErrors: [ConditionDeleteUserError!]!
+}
+```
+
+### `ConditionDeleteUserErrorCode`
+
+```graphql
+"""Machine-readable error codes for `conditionDelete`."""
+enum ConditionDeleteUserErrorCode {
+  """
+  The condition is referenced by one or more experiences and cannot be deleted.
+  """
+  IN_USE
+}
+```
+
+### `ConditionDeleteUserError`
+
+```graphql
+"""
+A user error from `conditionDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
+"""
+type ConditionDeleteUserError {
+  """Path to the input field that caused the error."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: ConditionDeleteUserErrorCode!
+  """
+  Experiences that reference this condition (present when `code` is `IN_USE`).
+  """
+  referencingExperiences: [ReferencingExperience!]
+}
+```
+
+### `ConditionSortKeys`
+
+```graphql
+"""
+Sort keys for `conditions(...)`. Pair with `reverse: true` to flip the order
+(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
+"""
+enum ConditionSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```