# Forge GraphQL toolkit

## What is it?

The [@atlassian/forge-graphql](https://www.npmjs.com/package/@atlassian/forge-graphql) package provides commonly used GraphQL requests against [Atlassian GraphQL Gateway](https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/) wrapped up as a convenient API fit for Forge App developer consumption, for use in [Forge](https://developer.atlassian.com/platform/forge/) apps.

## How to Install

For the latest version, run:

```bash
npm install @atlassian/forge-graphql

If you encounter GraphQL Document Validation errors after changes to the schema, try deleting your local cache.graphql.
```

## Package documentation

Refer to the [Forge GraphQL toolkit documentation](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit) for more thorough documentation of the methods defined in the package.

## Examples

```ts
import graphqlGateway from '@atlassian/forge-graphql';

const id =
  'ari:cloud:compass:4e381e6e-957b-3f8d-a8c2-2509478c45b1:component/c22ec0bd-121a-33de-b851-1d279e508dcb/d99ec9b2-1b37-57e1-ce04-8d454008cbf1f';

const {
  errors,
  data: { component },
} = await graphqlGateway.compass.asUser().getComponent({ componentId: id });
```

Let's break down this example.

The `graphqlGateway` object is an instantiation of the [Api](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Classes/Api/) class. There is a function on `graphqlGateway` called `compass` which contains all the Compass related functionality. The return value of this `compass` function is an object defined by the [CompassApi](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compass-api/CompassApi/) class. The resulting object has two methods defined on it which are `asUser()` and `asApp()`. Both of which return an object defined by the class [CompassRequests](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compass-requests/CompassRequests/). `CompassRequests` contains multiple methods that make requests to Graphql Gateway. (Scroll through [the left sidebar here](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compass-requests/CompassRequests/) to see all the requests you can make to Graphql Gateway.) The request defined in this example is a [getComponent](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/CompassRequests/getComponent/) query. This query uses the parameters defined by the [GetComponentInput](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compound-types/GetComponentInput/) type and returns an object of type [ComponentPayload](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compound-types/ComponentPayload/) wrapped in an [ApiPayload](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/compound-types/ApiPayload/) and returned as a Promise. The `ApiPayload` defines the `errors` and `data` properties while the `ComponentPayload` defines the type of the data returned.

Below is an example of a mutation you can make.

```ts
import graphqlGateway, {
  CompassComponentType,
} from '@atlassian/forge-graphql';

const {
  errors,
  data: { component },
} = await graphqlGateway.compass.asApp().createComponent({
  cloudId: '4e381e6e-957b-3f8d-a8c2-2509478c45b1',
  name: 'Example Compass component',
  typeId: 'SERVICE',
  links: [
    {
      type: CompassLinkType.Repository,
      url: 'https://github.com/atlassian-labs/gitlab-for-compass',
    },
  ],
});
```

This example uses the [createComponent](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Classes/CompassRequests/#createcomponent) mutation. The input to the mutation is defined by [CreateComponentInput](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Interfaces/CreateComponentInput/#createcomponentinput) which extends [BaseComponentInput](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Interfaces/BaseComponentInput/). And the function returns an object of type [ComponentPayload](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Interfaces/ComponentPayload/) wrapped in an [ApiPayload](https://developer.atlassian.com/cloud/compass/forge-graphql-toolkit/Interfaces/ApiPayload/) and returned as a Promise.

## How to contribute

This repository is designed to enable Forge developers by allowing them to quickly write requests to AGG. We appreciate your bugfixes and improvements in this effort. Read below to learn how to take part in improving Forge GraphQL toolkit.

### Contributing

See [CONTRIBUTING.md](https://bitbucket.org/atlassian/forge-graphql-tools/src/main/CONTRIBUTING.md) to learn how to report bugs, suggest enhancements, and make changes via pull requests.

### Code of Conduct

Participation in Forge GraphQL toolkit community is governed by the [CODE_OF_CONDUCT.md](https://bitbucket.org/atlassian/forge-graphql-tools/src/main/CODE_OF_CONDUCT.md)

### License

Copyright (c) 2021 Atlassian and others. Apache 2.0 licensed, see [LICENSE](https://bitbucket.org/atlassian/forge-graphql-tools/src/main/LICENSE) file.