picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/pagination.md

@@ -0,0 +1,192 @@
+---
+type: reference
+layout: docs
+---
+
+# Pagination
+
+The Picked API paginates every list field that can return a large result. It uses a
+cursor, in the Relay-style pattern. This guide covers the connection pattern and
+shows how to move through a result.
+
+## Connection pattern
+
+A paginated field returns a **connection** object with this shape:
+
+```graphql
+type ExampleConnection {
+  edges: [ExampleEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type ExampleEdge {
+  cursor: String!
+  node: Example!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
+| `pageInfo.hasNextPage` | `true` when more results come after the last edge |
+| `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
+| `pageInfo.startCursor` | The cursor of the first edge on the current page |
+| `pageInfo.endCursor` | The cursor of the last edge on the current page |
+| `totalCount` | The number of items on every page together |
+
+## Forward pagination with `first` and `after`
+
+To move forward through the results, use two arguments. The `first` argument gives
+the page size. The `after` argument gives the cursor to start after.
+
+### First page
+
+Leave the `after` argument out to read the first page:
+
+```graphql
+query {
+  organizations(input: { first: 10 }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+### Next page
+
+Pass the `endCursor` from the previous response as the `after` argument:
+
+```graphql
+query {
+  organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+## Check for more pages
+
+Read the `hasNextPage` field before you ask for the next page:
+
+- `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
+  argument of the next request.
+- `hasNextPage: false` — you read every result. Stop here.
+
+## Full paginated query example
+
+This example reads every member of an organization, one page at a time:
+
+```graphql
+# Page 1
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20) {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+If `pageInfo.hasNextPage` is `true`, fetch the next page:
+
+```graphql
+# Page 2
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20, after: "cursor_from_page_1") {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+Continue until `hasNextPage` returns `false`.
+
+## Paginated fields
+
+These fields in the schema return a connection type. They all take the `first` and
+`after` arguments:
+
+| Parent Type | Field | Connection Type |
+|------------|-------|----------------|
+| `Query` | `organizations` | `OrganizationConnection` |
+| `User` | `organizations` | `OrganizationConnection` |
+| `User` | `invitations` | `ViewerInvitationConnection` |
+| `Organization` | `members` | `OrganizationMemberConnection` |
+| `Organization` | `invitations` | `OrganizationInvitationConnection` |
+| `Organization` | `projects` | `ProjectConnection` |
+| `Project` | `reports` | `ProjectReportConnection` |
+
+All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
+
+## Tips
+
+- **The default page size** — the API applies a default limit when you leave `first`
+  out. Set `first` yourself to make sure that each page has the size you expect.
+- **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
+  build it, or change it. Pass it back exactly as the API gave it.
+- **The order is stable** — a connection returns its results in a stable order. The
+  same cursor always points at the same position in the result.
+- **Use them with other fields** — you can use the pagination arguments together with
+  other query fields. One request that reads an organization and the first page of
+  its members is common, and it is efficient.
+
+## Related
+
+- [Your first API call](/tutorials/first-api-call)
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes)

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

@@ -0,0 +1,261 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Action schema
+
+The operations and types that `action.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `action`
+
+Get an action by ID within a workspace.
+
+```graphql
+action(id: ID!, workspaceId: ID!): Action @auth
+```
+
+### `actions`
+
+List actions in a workspace. Filter by name with `search` (case-insensitive
+substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+
+```graphql
+actions(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: ActionSortKeys = NAME, reverse: Boolean = false): ActionConnection! @auth
+```
+
+## Mutations
+
+### `actionCreate`
+
+Create a new action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+actionCreate(input: ActionCreateInput!): ActionCreatePayload! @auth
+```
+
+### `actionUpdate`
+
+Update an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+actionUpdate(input: ActionUpdateInput!): ActionUpdatePayload! @auth
+```
+
+### `actionDelete`
+
+Delete an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+actionDelete(input: ActionDeleteInput!): ActionDeletePayload! @auth
+```
+
+## Types
+
+### `Action`
+
+```graphql
+"""
+A side effect triggered during experience flow execution. Workspace-
+scoped — actions are copied into a new workspace when the workspace is
+duplicated.
+
+Examples: API calls (`tracking/send-event`), analytics events
+(`segment/identify`), or SDK state updates (`features/toggle`). The
+shape of the side effect itself is encoded in the action's `key` and
+handled by the SDK plugin matching that key.
+"""
+type Action {
+  """Unique action identifier."""
+  id: ID!
+  """Display name of the action."""
+  name: String!
+  """Stable, human-readable key for SDK consumers."""
+  key: String!
+  """Optional description of what this action does."""
+  description: String
+  """When this action was created."""
+  createdAt: DateTime!
+  """When this action was last updated."""
+  updatedAt: DateTime!
+  """The workspace this action belongs to."""
+  workspace: Workspace!
+  """
+  The workspace ID this action belongs to (denormalised for query convenience).
+  """
+  workspaceId: ID
+  """Fields whose responses this action receives."""
+  fields(first: Int, after: String, last: Int, before: String): FieldConnection!
+  """The one workflow this action starts, or null when it starts none."""
+  workflow: Workflow
+}
+```
+
+### `ActionConnection`
+
+```graphql
+"""
+Relay-style connection of actions, with both an `edges` list and a flat `nodes` accessor.
+"""
+type ActionConnection {
+  """List of action edges."""
+  edges: [ActionEdge!]!
+  """
+  Flat list of actions, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Action!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of actions."""
+  totalCount: Int!
+}
+```
+
+### `ActionEdge`
+
+```graphql
+"""Edge type for `ActionConnection`."""
+type ActionEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The action."""
+  node: Action!
+}
+```
+
+### `ActionCreateInput`
+
+```graphql
+"""Input for `actionCreate`."""
+input ActionCreateInput {
+  """Workspace ID to create the action in."""
+  workspaceId: ID!
+  """Display name for the action."""
+  name: String!
+  """Unique key identifier for the action (stable across versions)."""
+  key: String!
+  """Description of what this action does."""
+  description: String
+  """Ids of the fields whose responses this action receives."""
+  fieldIds: [ID!]
+}
+```
+
+### `ActionCreatePayload`
+
+```graphql
+"""Payload returned by `actionCreate`."""
+type ActionCreatePayload {
+  """The created action."""
+  action: Action
+}
+```
+
+### `ActionUpdateInput`
+
+```graphql
+"""Input for `actionUpdate`. Omit a field to leave it unchanged."""
+input ActionUpdateInput {
+  """Action ID."""
+  id: ID!
+  """Workspace ID the action belongs to."""
+  workspaceId: ID!
+  """New display name."""
+  name: String
+  """New description."""
+  description: String
+  """
+  Replacement set of field ids. Omit to leave the set unchanged; pass an empty
+  list to request nothing.
+  """
+  fieldIds: [ID!]
+}
+```
+
+### `ActionUpdatePayload`
+
+```graphql
+"""Payload returned by `actionUpdate`."""
+type ActionUpdatePayload {
+  """The updated action."""
+  action: Action
+}
+```
+
+### `ActionDeleteInput`
+
+```graphql
+"""Input for `actionDelete`."""
+input ActionDeleteInput {
+  """Action ID."""
+  id: ID!
+  """Workspace ID the action belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `ActionDeletePayload`
+
+```graphql
+"""
+Payload returned by `actionDelete`. Returns `userErrors` when the action is in use.
+"""
+type ActionDeletePayload {
+  """ID of the deleted action (null when `userErrors` is non-empty)."""
+  deletedActionId: ID
+  """Validation errors. Empty array indicates success."""
+  userErrors: [ActionDeleteUserError!]!
+}
+```
+
+### `ActionDeleteUserErrorCode`
+
+```graphql
+"""Machine-readable error codes for `actionDelete`."""
+enum ActionDeleteUserErrorCode {
+  """
+  The action is referenced by one or more experiences and cannot be deleted.
+  """
+  IN_USE
+}
+```
+
+### `ActionDeleteUserError`
+
+```graphql
+"""
+A user error from `actionDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
+"""
+type ActionDeleteUserError {
+  """Path to the input field that caused the error."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: ActionDeleteUserErrorCode!
+  """
+  Experiences that reference this action (present when `code` is `IN_USE`).
+  """
+  referencingExperiences: [ReferencingExperience!]
+}
+```
+
+### `ActionSortKeys`
+
+```graphql
+"""
+Sort keys for `actions(...)`. Pair with `reverse: true` to flip the order
+(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
+"""
+enum ActionSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```