picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,350 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Feature schema
+
+The operations and types that `feature.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `feature`
+
+Fetch a single feature by ID and workspace ID. Requires authentication.
+
+```graphql
+feature(input: FeatureInput!): Feature @auth
+```
+
+### `features`
+
+List features in a workspace. Filter by name with `search` (case-insensitive
+substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+
+```graphql
+features(workspaceId: ID!, first: Int, after: String, last: Int, before: String, search: String, sortKey: FeatureSortKeys = NAME, reverse: Boolean = false): FeatureConnection! @auth
+```
+
+## Mutations
+
+### `featureCreate`
+
+Create a new feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+featureCreate(input: FeatureCreateInput!): FeatureCreatePayload! @auth
+```
+
+### `featureUpdate`
+
+Update a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+featureUpdate(input: FeatureUpdateInput!): FeatureUpdatePayload! @auth
+```
+
+### `featureDelete`
+
+Delete a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+featureDelete(input: FeatureDeleteInput!): FeatureDeletePayload! @auth
+```
+
+## Types
+
+### `FeatureValueType`
+
+```graphql
+"""What a feature's variants serve. Fixed when the feature is created."""
+enum FeatureValueType {
+  """
+  Two arms. The visitor's site receives `true` or `false`, split by `weight`.
+  """
+  BOOLEAN
+  """
+  Author-defined arms. The visitor's site receives a string, or `false` in control.
+  """
+  TEXT
+}
+```
+
+### `FeatureVariant`
+
+```graphql
+"""
+One arm of a feature.
+
+`key` is the stable identity: it is what the visitor's browser stores, what
+reporting records, and what a preview override names. It is also the order
+allocation runs in, so `name`, `value` and `weight` are all freely editable
+without moving a visitor between arms.
+
+Every feature has a control arm keyed `false` serving `false`. A `BOOLEAN`
+feature has exactly one more, keyed `true`, derived from `weight` rather than
+stored.
+"""
+type FeatureVariant {
+  """
+  Stable identity, unique within the feature. `true` and `false` are reserved for the structural arms.
+  """
+  key: String!
+  """
+  Display label. Shown in the dashboard and as the arm's label in reports.
+  """
+  name: String!
+  """
+  What the visitor's site receives — a string, or `false` for the control arm.
+  """
+  value: JSON!
+  """
+  Share of traffic relative to the other variants, as a whole number. Meaning is
+  relative, not absolute: `1, 1, 1` and `10, 10, 10` are the same even split.
+  Stored reduced by the greatest common divisor, so equivalent splits are equal.
+  """
+  weight: Int!
+}
+```
+
+### `Feature`
+
+```graphql
+"""
+An A/B test feature within a workspace. SDKs consume features by `key`
+and check `enabled` / `weight` to decide whether to expose the feature
+to a given visitor.
+
+`weight` is a percentage (0-100); 100 means "always serve this feature".
+`version` increments whenever the feature is updated and is exposed to
+SDKs as a cache-busting hint.
+"""
+type Feature {
+  """Unique feature identifier."""
+  id: ID!
+  """
+  Stable, human-readable key for SDK consumers (e.g. `homepage-banner-v2`).
+  """
+  key: String!
+  """Display name of the feature."""
+  name: String!
+  """Optional description of the feature."""
+  description: String
+  """
+  Whether the feature is enabled (`false` disables it for all visitors regardless of `weight`).
+  """
+  enabled: Boolean!
+  """
+  Share of visitors outside the control arm (0-100). For a `BOOLEAN` feature this
+  is the allocation input. For a `TEXT` feature it is derived from the variant
+  weights and carried for clients that predate variants; such a client puts the
+  right share of visitors in control, and current clients allocate from `variants`.
+  """
+  weight: Int!
+  """What this feature's variants serve. Fixed at creation."""
+  valueType: FeatureValueType!
+  """
+  The feature's arms. Always at least two, and the last is always the control arm
+  keyed `false`. A `BOOLEAN` feature's pair is derived from `weight` rather than
+  stored, so every consumer sees one shape regardless of value type.
+  """
+  variants: [FeatureVariant!]!
+  """
+  Version number, incremented on each update. Cache-busting hint for SDKs.
+  """
+  version: Int!
+  """The workspace this feature belongs to."""
+  workspace: Workspace!
+  """When this feature was created."""
+  createdAt: DateTime!
+  """When this feature was last updated."""
+  updatedAt: DateTime!
+}
+```
+
+### `FeatureEdge`
+
+```graphql
+"""Edge type for `FeatureConnection`."""
+type FeatureEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The feature."""
+  node: Feature!
+}
+```
+
+### `FeatureConnection`
+
+```graphql
+"""Relay-style connection of features."""
+type FeatureConnection {
+  """List of feature edges."""
+  edges: [FeatureEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of features."""
+  totalCount: Int!
+}
+```
+
+### `FeatureInput`
+
+```graphql
+"""Input for looking up a single feature."""
+input FeatureInput {
+  """Feature ID."""
+  id: ID!
+  """Workspace ID the feature belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `FeatureVariantInput`
+
+```graphql
+"""
+One arm, as submitted. Omit `key` on a new variant and it is derived from `name`.
+The control arm is submitted like any other, keyed `false` with value `false`, and
+must come last.
+"""
+input FeatureVariantInput {
+  """Stable identity. Derived from `name` when omitted."""
+  key: String
+  """Display label."""
+  name: String!
+  """
+  What the visitor's site receives — a string, or `false` for the control arm.
+  """
+  value: JSON!
+  """
+  Share of traffic relative to the other variants. Reduced by the greatest common divisor on save.
+  """
+  weight: Int!
+}
+```
+
+### `FeatureCreateInput`
+
+```graphql
+"""Input for `featureCreate`."""
+input FeatureCreateInput {
+  """Workspace ID to create the feature in."""
+  workspaceId: ID!
+  """
+  Organisation ID. Carried for authorisation; must match the workspace's organisation.
+  """
+  organizationId: ID!
+  """Display name for the feature."""
+  name: String!
+  """Optional human-readable key (auto-generated from `name` if omitted)."""
+  key: String
+  """Optional description."""
+  description: String
+  """Whether the feature is enabled. Defaults to `false`."""
+  enabled: Boolean
+  """
+  Traffic weight percentage (0-100). Defaults to `0`. Rejected for a `TEXT` feature, which derives its weight from `variants`.
+  """
+  weight: Int
+  """
+  What this feature's variants serve. Defaults to `BOOLEAN`. Cannot be changed after creation.
+  """
+  valueType: FeatureValueType
+  """
+  The full set of arms, control last. Required for a `TEXT` feature and rejected for a `BOOLEAN` one.
+  """
+  variants: [FeatureVariantInput!]
+}
+```
+
+### `FeatureCreatePayload`
+
+```graphql
+"""Payload returned by `featureCreate`."""
+type FeatureCreatePayload {
+  """The created feature."""
+  feature: Feature
+}
+```
+
+### `FeatureUpdateInput`
+
+```graphql
+"""Input for `featureUpdate`. Omit a field to leave it unchanged."""
+input FeatureUpdateInput {
+  """Feature ID."""
+  id: ID!
+  """Workspace ID the feature belongs to."""
+  workspaceId: ID!
+  """New display name."""
+  name: String
+  """New description."""
+  description: String
+  """Whether the feature is enabled."""
+  enabled: Boolean
+  """
+  New traffic weight percentage (0-100). Rejected for a `TEXT` feature, which derives its weight from `variants`.
+  """
+  weight: Int
+  """
+  Replaces the whole set of arms. Partial updates of a single arm are not
+  supported, because reducing weights by their greatest common divisor is a
+  property of the whole array. Rejected for a `BOOLEAN` feature.
+  """
+  variants: [FeatureVariantInput!]
+  """
+  Whether to increment the version number. Defaults to `true` so SDKs see the change.
+  """
+  incrementVersion: Boolean
+}
+```
+
+### `FeatureUpdatePayload`
+
+```graphql
+"""Payload returned by `featureUpdate`."""
+type FeatureUpdatePayload {
+  """The updated feature."""
+  feature: Feature
+}
+```
+
+### `FeatureDeleteInput`
+
+```graphql
+"""Input for `featureDelete`."""
+input FeatureDeleteInput {
+  """Feature ID."""
+  id: ID!
+  """Workspace ID the feature belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `FeatureDeletePayload`
+
+```graphql
+"""Payload returned by `featureDelete`."""
+type FeatureDeletePayload {
+  """ID of the deleted feature."""
+  deletedFeatureId: ID
+}
+```
+
+### `FeatureSortKeys`
+
+```graphql
+"""
+Sort keys for `features(...)`. Pair with `reverse: true` to flip the order (`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
+"""
+enum FeatureSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```

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

@@ -0,0 +1,103 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Feedback schema
+
+The operations and types that `feedback.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Mutations
+
+### `feedbackCreate`
+
+Submit user feedback from the dashboard. Requires authentication (USER token only).
+
+```graphql
+feedbackCreate(input: FeedbackCreateInput!): FeedbackCreatePayload! @auth(only: USER)
+```
+
+## Types
+
+### `FeedbackTopic`
+
+```graphql
+"""Topic categories for user feedback."""
+enum FeedbackTopic {
+  """Bug report — something doesn't work as expected."""
+  BUG
+  """Feature request — a missing capability the user wants."""
+  FEATURE_REQUEST
+  """Improvement — feedback on an existing capability."""
+  IMPROVEMENT
+  """Question — the user needs help."""
+  QUESTION
+  """Navigation — feedback on the dashboard's sidebar navigation."""
+  NAVIGATION
+  """Other — uncategorised feedback."""
+  OTHER
+}
+```
+
+### `FeedbackSentiment`
+
+```graphql
+"""
+Sentiment rating for user feedback. Optional; clients can omit when they don't prompt for sentiment.
+"""
+enum FeedbackSentiment {
+  """Very negative — user is frustrated or angry."""
+  VERY_NEGATIVE
+  """Negative — user is dissatisfied."""
+  NEGATIVE
+  """Neutral — user is indifferent."""
+  NEUTRAL
+  """Positive — user is satisfied."""
+  POSITIVE
+  """Very positive — user is delighted."""
+  VERY_POSITIVE
+}
+```
+
+### `FeedbackCreateInput`
+
+```graphql
+"""
+Input for `feedbackCreate` — submit a feedback message from the dashboard.
+"""
+input FeedbackCreateInput {
+  """The feedback message content."""
+  message: String!
+  """The topic category of the feedback."""
+  topic: FeedbackTopic!
+  """Optional sentiment rating."""
+  sentiment: FeedbackSentiment
+  """
+  The page path where feedback was submitted (e.g. `/orgs/acme/projects/123`).
+  """
+  pagePath: String
+  """The organisation context, if applicable."""
+  organizationId: ID
+  """The project context, if applicable."""
+  projectId: ID
+  """
+  The Picked session id, if available — links feedback to a session recording.
+  """
+  pickedSessionId: String
+  """The user's browser user-agent string."""
+  userAgent: String
+  """The user's screen resolution (e.g. `1920x1080`)."""
+  screenResolution: String
+}
+```
+
+### `FeedbackCreatePayload`
+
+```graphql
+"""Payload returned by `feedbackCreate`."""
+type FeedbackCreatePayload {
+  """The id of the newly created feedback row."""
+  feedbackId: ID!
+}
+```