Skip to content

Latest commit

 

History

History
61 lines (40 loc) · 4.72 KB

README.md

File metadata and controls

61 lines (40 loc) · 4.72 KB
Raw

Typeble

GitHub Workflow Status codecov GitHub GitHub search hit counter

Typeble is an unofficial Tumblr API library written entirely in typescript to fill the gap left by the official Tumblr JS lib that doesn't supply type information nor seems to support the OAuth2 standard. It's still heavily WIP, but many of the important endpoints of the API are covered.

⚠️ Notice ⚠️

This library is NOT official, endorsed, sponsored by, or otherwise associated with Tumblr in any way, shape, or form.

It was built using the API reference documents, and like any other project built using the API (including those made using this library) should conform to the Tumblr Application Developer and API License Agreement. Be sure you also follow it.

How to use

  1. Install the package into your project with NPM with the command npm install typeble
  2. Import the functions you need for your project as you would any library, documentation here
  3. Obtain an OAuth 2 token for tumblr using my tumblr authentication library or some other method
  4. DON'T SHARE THE TOKEN WITH ANYONE! It will expire (unless it has the offline_access scope) but someone could do damage to your account if they get access to the token
  5. Pass the token as the first argument to any of the functions

Contributing

First and foremost, once again, make sure to honour the Tumblr Application Developer and API License Agreement. Don't try to bypass any rate limits, and make sure that this project isn't in any way percievable as officially endorsed by Tumblr.

Code that is not documented, is poorly documented, or is "hacky" in some way, especially parts close to the API, will likely not be added to the codebase. Code that isn't at least somewhat covered by unit tests is heavily discouraged.

Testing (Local)

Create a .env file with the following contents (You can also just set them as environment variables, but afaik that's less secure):

CONSUMER_ID=[your Tumblr OAuth App ID here]
CONSUMER_SECRET=[your Tumblr OAuth App secret here]

Then run npm test. A browser window will open up a Tumblr authentication page, asking you to approve the scopes. REMEMBER THAT THE TESTS WILL BE RUN USING WHATEVER ACCOUNT YOU ARE LOGGED INTO! Create a bot account if you need to.

Testing (Github)

Truth be told, CI (tests) will likely only run on master as there is a chance of destructive actions being taken using the bot used for testing. If you want to run CI on your own fork, be sure to set the following github secrets:

  • SECRETS_ACCESS_TOKEN: A github PAT (can be fine-grained) with write access to your fork's secrets (used to update the refresh token)
  • TUMBLR_CLIENT_ID: The client ID from your Tumblr OAuth App (Can just be a normal environment variable, but oh well)
  • TUMBLR_CLIENT_SECRET: The client secret from your Tumblr OAuth App
  • TUMBLR_REFRESH_TOKEN: A refresh token from a successful login to a Tumblr OAuth App with the offline_access scope, you can use my tumblr authentication library from the command line with the scope parameter set to include offline_access and the json option set to get the full response (which includes the refresh token). REMEMBER THAT THE RUN USING WHATEVER ACCOUNT YOU ARE LOGGED INTO! You really want to use a bot account for this, since if you accidentally merge malicious code, it could run on your main account.

Roadmap

Other Resources