itch-graphql

Unofficial GraphQL server and typedefs/resolvers for the itch.io API.

If you've ever wanted a GraphQL wrapper around the itch.io REST API, you've come to the right place. I know this is pretty niche, but at least you have the option now.

• [x] Export a built-in server
• [x] Export typedefs and resolvers
• [x] API key support
• [ ] JWT support
• [ ] NPM command
• [ ] Socially acceptable tests

Installing / Getting started

First, you have to install it to the project:

# with NPM
npm install itch-graphql

# with yarn
yarn add itch-graphql

From here, there are (currently) two ways that you can use this package: Either as a standalone server, or by importing the types/resolvers and integrating them with your own server.

We'll assume you're using an ESM-supported environment for the purposes of this README, but if you're confused, just know that

import { server } from 'itch-graphql'

is the same thing as

const { server } = require('itch-graphql')

Standalone

This is pretty simple. All you need to do is import the server and call it with the port and a boolean for GraphiQL. Internally, it's using micro, apollo-server-micro, and microrouter.

For authorization, it's up to you whether to include a ItchToken: <your token here> HTTP header or to set up an ITCH_TOKEN environment variable. We recommend the latter.

import { server } from 'itch-graphql'

server(
  // Port number
  3000,
  // GraphiQL boolean, defaults to true
  false
)

Open up GraphQL Playground to http://localhost:3000/graphql or your web browser of choice to http://localhost:3000/graphiql and you're ready to play around.

Integrating with your own server

This is a little bit more in-depth, but not too terrible.

// import and alias our types and resolvers for readability
import { typeDefs as itchTypes, resolvers as itchResolvers } from 'itch-graphql'
import { makeExecutableSchema } from 'graphql-tools'
import { graphqlExpress } from 'apollo-server-express'
import express from 'express'

// Stitch together the schema of legends
const schema = makeExecutableSchema({
  typeDefs: [
    someType,
    moreType,
    ...itchTypes
  ],
  resolvers: {
    ...someResolvers,
    ...moreResolvers,
    ...itchResolvers
  }
})

// Assemble the GraphQL handler
const graphqlHandler = expressGraphql((req, res) => {
  return {
    schema,
    // Add our Itch token for authorization
    context: {
      // You can set this up however you like
      itchToken:
        process.env.ITCH_TOKEN || req.headers.ItchToken
    }
  }
})

// Start the app
const app = express()
app.get('/graphql', graphqlHandler)
app.listen(3000)

And you're golden!

Developing

Built With

• esm
• graphql-tools
• popsicle
• micro
• microrouter
• apollo-server-micro
• ava

Prerequisites

In order to get started developing, you're going to need a version of Node installed (preferably the latest release), and an itch.io token. You can create the token from your profile on the website.

Setting up Dev

If you're interested in contributing, it's pretty simple to get started locally:

git clone https://github.com/puregarlic/itch-graphql
cd itch-graphql/
npm install
npm run dev

And you're good to go. We recommend using GraphQL Playground to test the API, because you can pass HTTP Headers from the application. GraphiQL is only great if you're handing the token to context via an ITCH_TOKEN environment variable.

If you make any changes to the source code, the server will autoreload thanks to nodemon.

Deploying / Publishing

Publishing happens automatically via semantic-release, deployed with Buddy.

The main thing to know is that we use commitlint to enforce conventional commits. These are very important for correctly generating changelogs and creating new versions.

If you need to know more about how to write conventional commits, check out the spec, and if you need to know the different allowed types, check out this JSON file.

Tests

My current tests are absolutely horrible. If you can write better ones, or simply want to improve my existing ones, please please please make a PR.

If you want to run the tests locally, you're going to need a .env file in the project root. This needs to contain a few values:

# <REQUIRED> Itch API Token
ITCH_TOKEN=

# <REQUIRED> User ID number. You can retrieve this with the me query
USER_ID=

# You need one of these two, for the purchases and download key query:
GAME_ID=
EMAIL=

# You can add this if you really want:
DOWNLOAD_KEY=

My user account is downright lacking when it comes to test data, so if you're willing to donate an API token for the testing environment, please get in touch with me on Twitter.

Style guide

This project follows the Standard style, so if you want to install an editor linter for that, go right ahead. However, it's not really necessary -- Each time you commit, we'll lint your staged changes with the --fix flag, and then format it all with prettier-standard. As a result, you don't need to worry about styling too much, because it'll be fixed later.

Api Reference

Since this is a wrapper around the Itch server-side API, you can read the docs here.

Legal

I'm not affiliated with itch.io in any capacity, and the images used in the project logo are the property of their respective owners.