picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,15 @@ generated: true
 
 # Integration schema
 
-The operations and types that `integration.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Mutations
 
 ### `integrationInstall`
 
-Install an integration for a project. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
+Installs an integration for a project. A project that already has an integration of that type
+gets a `CONFLICT` error.
+Scope: `ORGANIZATION_INTEGRATIONS_CREATE` and `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 integrationInstall(input: IntegrationInstallInput!): IntegrationInstallPayload! @auth
@@ -20,7 +22,8 @@ integrationInstall(input: IntegrationInstallInput!): IntegrationInstallPayload!
 
 ### `integrationUninstall`
 
-Uninstall an integration (cascades to delete all configurations). Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
+Uninstalls an integration and deletes its configuration.
+Scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
 
 ```graphql
 integrationUninstall(id: ID!): IntegrationUninstallPayload! @auth
@@ -28,7 +31,9 @@ integrationUninstall(id: ID!): IntegrationUninstallPayload! @auth
 
 ### `integrationConfigurationCreate`
 
-Create a configuration for an installed integration. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
+Creates the configuration of an installed integration. An integration has at most one
+configuration; a second gets a `CONFLICT` error.
+Scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
 
 ```graphql
 integrationConfigurationCreate(input: IntegrationConfigurationCreateInput!): IntegrationConfigurationCreatePayload! @auth
@@ -36,7 +41,8 @@ integrationConfigurationCreate(input: IntegrationConfigurationCreateInput!): Int
 
 ### `integrationConfigurationUpdate`
 
-Update an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
+Updates an integration's configuration.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 integrationConfigurationUpdate(id: ID!, input: IntegrationConfigurationUpdateInput!): IntegrationConfigurationUpdatePayload! @auth
@@ -44,10 +50,17 @@ integrationConfigurationUpdate(id: ID!, input: IntegrationConfigurationUpdateInp
 
 ### `integrationConfigurationDelete`
 
-Delete an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
+Deletes an integration's configuration. The integration stays installed.
+Scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
 
 ```graphql
-integrationConfigurationDelete(id: ID!, type: IntegrationType!): IntegrationConfigurationDeletePayload! @auth
+integrationConfigurationDelete(
+  id: ID!
+  """
+  The type of the integration. Not read: `id` alone identifies the configuration.
+  """
+  type: IntegrationType!
+): IntegrationConfigurationDeletePayload! @auth
 ```
 
 ## Types
@@ -55,11 +68,9 @@ integrationConfigurationDelete(id: ID!, type: IntegrationType!): IntegrationConf
 ### `IntegrationType`
 
 ```graphql
-"""Integration types available for project configuration."""
+"""The service an integration connects a project to."""
 enum IntegrationType {
-  """
-  Vercel deployment integration — fires deploy hooks on workspace publish.
-  """
+  """Vercel, through deploy hooks."""
   VERCEL
 }
 ```
@@ -68,27 +79,26 @@ enum IntegrationType {
 
 ```graphql
 """
-An integration installed for a project. Created via `integrationInstall`;
-removed via `integrationUninstall` (cascades to the configuration).
-
-`configuration` is null until `integrationConfigurationCreate` is
-invoked. The configuration union is resolved by `type`.
+A connection between a project and another service. A project has at most one integration of
+each type.
 """
 type Integration {
-  """Unique integration identifier."""
+  """The ID of the integration."""
   id: ID!
-  """ID of the project this integration belongs to."""
+  """The ID of the project the integration belongs to."""
   projectId: ID!
-  """The type of integration."""
+  """The service the integration connects to."""
   type: IntegrationType!
-  """When this integration was installed."""
+  """When the integration was installed."""
   installedAt: DateTime!
-  """When this integration was last updated."""
+  """When the integration last changed."""
   updatedAt: DateTime!
-  """The project this integration belongs to."""
+  """The project the integration belongs to."""
   project: Project!
   """
-  Integration-specific configuration (resolved by `type`). Null until `integrationConfigurationCreate` is invoked.
+  The integration's settings, of the type that matches `type`. Null until
+  `integrationConfigurationCreate` creates them.
+  Scope: `ORGANIZATION_INTEGRATIONS_READ`.
   """
   configuration: IntegrationConfiguration @auth
 }
@@ -97,9 +107,7 @@ type Integration {
 ### `IntegrationConfiguration`
 
 ```graphql
-"""
-Union of all integration-specific configuration types. New types extend this union.
-"""
+"""The settings of an integration, one member per integration type."""
 union IntegrationConfiguration = VercelConfiguration
 ```
 
@@ -107,20 +115,18 @@ union IntegrationConfiguration = VercelConfiguration
 
 ```graphql
 """
-Configuration for a Vercel integration with deploy hooks. Fires the
-configured hooks on workspace publish so the downstream Vercel project
-re-deploys with the latest content.
+The settings of a Vercel integration: the deploy hooks that redeploy the Vercel project.
 """
 type VercelConfiguration {
-  """Unique configuration identifier."""
+  """The ID of the configuration."""
   id: ID!
-  """ID of the parent integration."""
+  """The ID of the integration the configuration belongs to."""
   integrationId: ID!
-  """List of deploy hooks configured for this integration."""
+  """The deploy hooks."""
   deployHooks: [VercelDeployHook!]!
-  """When this configuration was created."""
+  """When the configuration was created."""
   createdAt: DateTime!
-  """When this configuration was last updated."""
+  """When the configuration last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -128,15 +134,11 @@ type VercelConfiguration {
 ### `VercelDeployHook`
 
 ```graphql
-"""A Vercel deploy hook with environment name and URL."""
+"""A Vercel deploy hook for one environment."""
 type VercelDeployHook {
-  """
-  Environment name (e.g. `Production`, `Staging`). Shown in the dashboard.
-  """
+  """The environment name, such as `Production`."""
   name: String!
-  """
-  Vercel deploy hook URL. Treat as sensitive — anyone with this URL can trigger the deploy.
-  """
+  """The deploy hook URL. Anyone with the URL can trigger a deployment."""
   hookUrl: String!
 }
 ```
@@ -144,11 +146,11 @@ type VercelDeployHook {
 ### `IntegrationInstallInput`
 
 ```graphql
-"""Input for `integrationInstall`."""
+"""The input of `integrationInstall`."""
 input IntegrationInstallInput {
-  """ID of the project to install the integration for."""
+  """The ID of the project."""
   projectId: ID!
-  """Type of integration to install."""
+  """The service to connect."""
   type: IntegrationType!
 }
 ```
@@ -156,11 +158,9 @@ input IntegrationInstallInput {
 ### `IntegrationInstallPayload`
 
 ```graphql
-"""Payload returned by `integrationInstall`."""
+"""The result of `integrationInstall`."""
 type IntegrationInstallPayload {
-  """
-  The installed integration. Configuration is null until `integrationConfigurationCreate` is invoked.
-  """
+  """The installed integration. Null when it cannot be read back."""
   integration: Integration
 }
 ```
@@ -168,11 +168,9 @@ type IntegrationInstallPayload {
 ### `IntegrationUninstallPayload`
 
 ```graphql
-"""
-Payload returned by `integrationUninstall`. Removing an integration cascades to its configuration.
-"""
+"""The result of `integrationUninstall`."""
 type IntegrationUninstallPayload {
-  """Whether the uninstall was successful."""
+  """Whether the integration was uninstalled. Always `true`."""
   success: Boolean!
 }
 ```
@@ -180,11 +178,13 @@ type IntegrationUninstallPayload {
 ### `VercelDeployHookInput`
 
 ```graphql
-"""Input for a Vercel deploy hook."""
+"""A Vercel deploy hook to save."""
 input VercelDeployHookInput {
-  """Environment name (e.g. `Production`, `Staging`)."""
+  """The environment name, such as `Production`."""
   name: String!
-  """Vercel deploy hook URL."""
+  """
+  The deploy hook URL. Must start with `https://api.vercel.com/v1/integrations/deploy/`.
+  """
   hookUrl: String!
 }
 ```
@@ -192,11 +192,9 @@ input VercelDeployHookInput {
 ### `VercelConfigurationInput`
 
 ```graphql
-"""
-Vercel-specific configuration input for `integrationConfigurationCreate`.
-"""
+"""The settings of a new Vercel configuration."""
 input VercelConfigurationInput {
-  """Deploy hooks for this configuration."""
+  """The deploy hooks. At least one."""
   deployHooks: [VercelDeployHookInput!]!
 }
 ```
@@ -204,11 +202,9 @@ input VercelConfigurationInput {
 ### `VercelConfigurationUpdateFields`
 
 ```graphql
-"""
-Vercel-specific fields for `integrationConfigurationUpdate`. Omit a field to leave it unchanged.
-"""
+"""The Vercel settings to change. Omit a field to keep its value."""
 input VercelConfigurationUpdateFields {
-  """Updated deploy hooks. Replaces the existing list when set."""
+  """The deploy hooks, which replace the current list. At least one."""
   deployHooks: [VercelDeployHookInput!]
 }
 ```
@@ -216,14 +212,12 @@ input VercelConfigurationUpdateFields {
 ### `IntegrationConfigurationCreateInput`
 
 ```graphql
-"""
-Input for `integrationConfigurationCreate`. Set the sub-input that matches the integration's `type`.
-"""
+"""The input of `integrationConfigurationCreate`."""
 input IntegrationConfigurationCreateInput {
-  """ID of the integration to create the configuration for."""
+  """The ID of the integration."""
   integrationId: ID!
   """
-  Vercel-specific configuration. Provide when the integration type is `VERCEL`.
+  The Vercel settings. Required: only `VERCEL` integrations take a configuration.
   """
   vercel: VercelConfigurationInput
 }
@@ -232,9 +226,9 @@ input IntegrationConfigurationCreateInput {
 ### `IntegrationConfigurationCreatePayload`
 
 ```graphql
-"""Payload returned by `integrationConfigurationCreate`."""
+"""The result of `integrationConfigurationCreate`."""
 type IntegrationConfigurationCreatePayload {
-  """The created configuration."""
+  """The created configuration. Null when it cannot be read back."""
   configuration: IntegrationConfiguration
 }
 ```
@@ -242,11 +236,11 @@ type IntegrationConfigurationCreatePayload {
 ### `IntegrationConfigurationUpdateInput`
 
 ```graphql
-"""Input for `integrationConfigurationUpdate`."""
+"""
+The input of `integrationConfigurationUpdate`. Omit a field to keep its value.
+"""
 input IntegrationConfigurationUpdateInput {
-  """
-  Vercel-specific configuration updates. Provide when the integration type is `VERCEL`.
-  """
+  """The Vercel settings to change. Required."""
   vercel: VercelConfigurationUpdateFields
 }
 ```
@@ -254,9 +248,9 @@ input IntegrationConfigurationUpdateInput {
 ### `IntegrationConfigurationUpdatePayload`
 
 ```graphql
-"""Payload returned by `integrationConfigurationUpdate`."""
+"""The result of `integrationConfigurationUpdate`."""
 type IntegrationConfigurationUpdatePayload {
-  """The updated configuration."""
+  """The updated configuration. Null when it cannot be read back."""
   configuration: IntegrationConfiguration
 }
 ```
@@ -264,9 +258,9 @@ type IntegrationConfigurationUpdatePayload {
 ### `IntegrationConfigurationDeletePayload`
 
 ```graphql
-"""Payload returned by `integrationConfigurationDelete`."""
+"""The result of `integrationConfigurationDelete`."""
 type IntegrationConfigurationDeletePayload {
-  """Whether the deletion was successful."""
+  """Whether the configuration was deleted. Always `true`."""
   success: Boolean!
 }
 ```