documentation.md

biketag

BikeTag Official JavaScript library

Installation

This package is Isomorphic and Typescript ready

npm install biketag

How to include it in your projects

The library is a default export, as well as a named class export BikeTagClient. You can retrieve it from jsDeliver or npm, and it works in both the browser and nodejs.

Browser

Using jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/biketag/biketag.js"></script>

Using unpkg CDN:

<script src="https://unpkg.com/npm/biketag.js"></script>

CommonJS

import/require the module:

// Using import statement
import { BikeTagClient } from 'biketag'

// Using require()
const { BikeTagClient } = require('biketag')

---

Usage

Instantiate with credentials (Browser):

let client

// if you have your clientKey/clientToken to retrieve an access token automatically:
client = new biketag({
  game: 'portland',
  clientKey: process.env.BIKETAG_CLIENT_KEY,
  clientToken: process.env.BIKETAG_CLIENT_TOKEN,
})

// if you have Imgur credentials: clientId and clientSecret
client = new biketag({
  game: 'portland',
  imgur: {
    clientId: process.env.IMGUR_CLIENT_ID,
    clientSecret: process.env.IMGUR_CLIENT_SECRET,
  }
})

// or Sanity credentials: projectId and accessToken
client = new biketag({
  game: 'portland',
  sanity: {
    projectId: process.env.SANITY_PROJECT_ID,
    accessToken: process.env.SANITY_ACCESS_TOKEN,
    dataset: process.env.SANITY_DATASET,
    useCdn: false,
  }
})

Instantiate with credentials (NodeJs):

let client

// if you already have an access token acquired
client = new BikeTagClient({
  game: 'portland',
  clientToken: process.env.BIKETAG_ACCESS_TOKEN,
})

// or your imgur client ID and clientSecret
client = new BikeTagClient({
  game: 'portland',
  imgur: {
    hash: process.env.IMGUR_ALBUM_HASH,
    clientId: process.env.IMGUR_CLIENT_ID,
    clientSecret: process.env.IMGUR_CLIENT_SECRET,
  }
})

Configuration

The acceptable fields for a BikeTagConfiguration object are outlined below:

Key	[API] Description
game	[BikeTag] a string of the name of the game to load
clientKey	[BikeTag] The biketag Client Key for your access to the BikeTag API
clientToken	[BikeTag] The biketag Client Token for your access to the BikeTag API
accessToken	[BikeTag] The biketag Access Token acquired via authorization (externally)
hash	Imgur The imgur album hash to target when working with BikeTag posts
clientId	Imgur The imgur Client ID to use when pulling data from Imgur as a source
clientSecret	Imgur The imgur Client Secret to use when authenticating using the ImgurClient
accessToken	Imgur The Imgur Access Token acquired via authorization (externally)
dataset	Sanity The sanity dataset to target when working with BikeTag posts
projectId	Sanity The sanity Project Id
username	Sanity The sanity username to use for authentication
password	Sanity The sanity user password to use for authenticaiton
apiVersion	Sanity use current UTC date - see "specifying API version" in Sanity.IO docs
useCdn	Sanity false if you want to ensure fresh data (or are using an access token)
token	Sanity The sanity Access Token acquired via authorization (externally)

⚠️ For brevity, the rest of the examples will leave out the import and/or instantiation step.

Get Game Information

You can get game information by providing the name.

// retrieves the BikeTag game data 'portland' game
const biketagPortland = await client.getGame('portland')

Get Tags

You can get tags one by one or all at once for a given game using the getTag and getTags methods. You can also explicitely set the data adapter to any of the configurable sources (biketag, imgur, sanity):

// retrieves the BikeTag game data 'portland' game
const biketagPortland = await client.getGame('portland')

// retrieves the latest BikeTag posted for the 'portland' game from the most available API
const biketagPortlandCurrent = await client.getTag()

// retrieves the BikeTag #1 for the 'portland' game from imgur adapter
const biketagPortland1 = await client.getTag(1, { source: 'imgur' })

// retrieves the all BikeTags for the 'portland' game from sanity adapter
const allPortlandTags = await client.getTags(undefined, { source: 'sanity' })

Get Players

You can get the players of a game by calling getPlayers

// retrieves the BikeTag game data 'portland' game
const biketagPortland = await client.getGame('portland')

There are a series of getter methods, statically accessible by BikeTagClient.getters. Their use is explained below:

method	Description
getTagnumberFromSlug	parses a slug for a tag number based on existing BikeTag slugs. (uses getTagnumberFromSlugRegex)
getTagNumbersFromText	parses text for tag numbers on existing BikeTag posts. (uses getTagNumbersFromTextRegex)
getPlayerFromText	parses text for a player name based on existing BikeTag posts. (uses getPlayerFromTextRegex)
getFoundLocationFromText	parses text for a found location based on existing BikeTag posts. (uses getFoundLocationFromTextRegex)
getHintFromText	parses text for a hint based on existing BikeTag posts. (uses getHintFromTextRegex)
geTimeFromText	parses text for a timestamp based on existing BikeTag posts. (uses getTimeFromTextRegex)
getGPSLocationFromText	parses text for GPS coordinates. (uses getGPSLocationFromTextRegex)
getImageURLsFromText	parses text for URLs of known BikeTag image providers. (uses getImageURLsFromTextRegex)
getDiscussionUrlFromText	parses a url, or string, for a Reddit post link. (uses getDiscussionUrlFromTextRegex)
getImageHashFromText	parses a url, or string, for an Imgur url with an imageHash. (uses getImgurImageHashFromUrlRegex)
getImgurFoundImageHashFromBikeTagData	parses BikeTag Data for the found image Imgur hash.
getImgurFoundDescriptionFromBikeTagData	constructs an Imgur image title from BikeTag data for the found image.
getImgurFoundTitleFromBikeTagData	constructs an Imgur image description from BikeTag data for the found image.
getImgurMysteryImageHashFromBikeTagData	parses BikeTag Data for the mystery image Imgur hash.
getImgurMysteryTitleFromBikeTagData	constructs an Imgur image title from BikeTag data for the mystery image.
getImgurMysteryDescriptionFromBikeTagData	constructs an Imgur image description from BikeTag data for the mystery image.

There are a series of regular expressions, accessible by client.expressions. Their use is explained below:

expression	Description
getTagNumbersFromTextRegex	Searches a string for numbers associated with BikeTag posts.
getPlayerFromTextRegex	Searches a string for player names associated with BikeTag posts.
getFoundLocationFromTextRegex	Searches a string for "found at ()" and parses out the innards of that substring.
getHintFromTextRegex	Searches a string for "(hint: )" and parses out the innards of that substring.
getTimeFromTextRegex	Searches a string for "on [ x/x/x @ y:y:y ]" and parses out the innards of that substring to a usable timestamp.
getGPSLocationFromTextRegex	Searches a string for GPS coordinates in the format (lat,long,alt)
getImageURLsFromTextRegex	Searches a string for an Imgur.com image url
getDiscussionUrlFromTextRegex	Searches a string for a URL within {} brackets
getGPSCoordinatesValueFromTextRegex	Searches a string for GPS coordinates within () brackets
getTagnumberFromSlugRegex	Parses out the number from a BikeTag slug.
getImgurImageHashFromUrlRegex	Parses out the Imgur image hash from an Imgur image url

Credits

This project is heavily influenced by the node-imgur package, the Imgur API and it's documentation, and Sanity.IO's javascript client.

Using the typescript library configured and developed on the node-imgur v2 project: https://github.com/kaimallea/node-imgur, this package comes bundled with testing using jest and automated releases using github actions. Many thanks to Kaimallea for collaborating with me on the imgur API because I learned so much along the way!

Support the BikeTag Project on GitHub, Patreon, or directly by going out and playing a round of BikeTag in your city!

Vendors

Images powered by imgur.com

Structured Content powered by sanity.io