ghostrider-05 / patreon-api.ts

Typescript library for the Patreon V2 API

Patreon-api.ts

Typescript library for the V2 Patreon API with Typescript types that strongly reflect your request.

// query: attributes[campaign]=title
const payload = await client.fetchCampaign(query)
    // ^? { data: { attributes: { title: string } }, ... }

Installation

npm install patreon-api.ts
pnpm add patreon-api.ts
yarn add patreon-api.ts

Usage

Caution

This package does not include v1 of the Patreon API and starts with API v2

The default API version for this package is 2 and might change in major versions. When the default API version is changed, old versions will still receive updates. You can not import this module by API version since it is unlikely that Patreon will release a new version any time soon.

import { type Campaign } from 'patreon-api.ts';

While some features are highlighted below, you can read more in the documentation. Still doubting if this library has everything you need related to the Patreon API? Compare all libraries yourself.

Compatibility

To check for compatibility with this package, look if your platform:

• has the globals: AbortController, setTimeout, clearTimeout, fetch, URL and URLSearchParams
  • for node.js: v18 or higher
  • for Cloudflare workers: enable Node.js
• supports ES2020
• supports createHmac of the node:crypto module

[!WARNING] This is a server-side API & Oauth package and requires your application tokens. Make sure you do not share or expose your tokens or run this code client-side.

Clients

Creator token

If you don't need to handle Oauth2 requests, but only your own creator profile, the first example will get you started. It is recommended to sync your token to your database or store it somewhere safe, so the token is not lost.

Example

import { PatreonCreatorClient, PatreonStore } from 'patreon-api.ts'

const creatorClient = new PatreonCreatorClient({
    oauth: {
        clientId: process.env.PATREON_CLIENT_ID!,
        clientSecret: process.env.PATREON_CLIENT_SECRET!,
        // Either set the token in the options
        // or configure a store and call <Client>.initialize()
        token: {
            access_token: process.env.PATREON_CREATOR_ACCESS_TOKEN!,
            refresh_token: process.env.PATREON_CREATOR_REFRESH_TOKEN!,
        },
    },
    store: new PatreonStore.Fetch('<url>'),
})

User oauth2

For handling Oauth2 requests, add redirectUri and if specified a state to the options. Then fetch the token for the user with request url. Note that for handling Oauth2 requests the client will not cache or store the tokens anywhere in case you need to refresh it!

Example

import { PatreonUserClient } from 'patreon-api.ts'

// Minimal configuration for handling Oauth2
const userClient = new PatreonUserClient({
    oauth: {
        clientId: process.env.PATREON_CLIENT_ID!,
        clientSecret: process.env.PATREON_CLIENT_SECRET!,
        redirectUri: '<uri>',
    }
})

export default {
    // The Oauth2 callback request with the code parameter
    fetch: async (request) => {
        const instance = await userClient.createInstance(request)
        await instance.fetchIdentity(<query>)
    }
}

Store

There are 3 built-in methods of retreiving and storing tokens:

1. Manual loading and storing, see the example below
2. Fetch: use an external server that accepts GET and PUT requests
3. KV: store the (creator) token in a KV-like storage system (present on a lot of edge-runtimes).

Example

// Use stored tokens in a database
// And directly call the `store.get` method on starting the client
const storeClient = new PatreonCreatorClient({
    oauth: {
        clientId: process.env.PATREON_CLIENT_ID!,
        clientSecret: process.env.PATREON_CLIENT_SECRET!,
    },
    name: '<application>', // The application name in the dashboard
    store: {
        get: async () => {
            // Get your stored token
            return <never>{
                access_token: '<token>',
                //...refresh, expires, etc.
            }
        },
        put: async (token) => {
            console.log(JSON.stringify(token))
        }
    }
})

Webhooks

You can interact with the webhooks API using one of the clients above. This library also exposes functions to create a webhook server.

Example

import { parseWebhookRequest } from 'patreon-api.ts'

export default {
    async fetch (request, env) {
        const { verified, payload, event } = await parseWebhookRequest(request, env.WEBHOOK_SECRET)
        if (!verified) return new Response('Invalid request', { status: 403 })

        // handle your event
    }
}

Examples

Note

In API v2, all attributes must be explicitly requested.

• Commonly used routes
• Example Cloudflare worker
• Example Node.js server

Changelog

Detailed changes are listed for each release in the changelog.

For upcoming releases, see the roadmap for planned changes.

Contributing

See the code of conduct and the contributing guide for how to contribute. You can also support the development by writing guides, posts and templates or by funding the maintainers.

License

MIT