Skip to content
This repository has been archived by the owner on Dec 30, 2021. It is now read-only.

Latest commit

 

History

History
262 lines (205 loc) · 13.2 KB

README.md

File metadata and controls

262 lines (205 loc) · 13.2 KB

imgur

Unofficial JavaScript library

npm next version Build states

Join the community on GitHub Discussions

🚨 This is the active development branch for v2. It is continuously deployed and available via npm install imgur@next.

Installation

npm install imgur@next

Or find a specific versions to pin on our npm page.

Usage

Import and instantiate with credentials:

// ESModule syntax
import { ImgurClient } from 'imgur';

// CommonJS syntax
const { ImgurClient } = require('imgur');

let client;

// if you already have an access token acquired
client = new ImgurClient({ accessToken: process.env.ACCESS_TOKEN });

// or your client ID
client = new ImgurClient({ clientId: process.env.CLIENT_ID });

// or your username/password/client id to retrieve an access token automatically:
client = new ImgurClient({
  username: process.env.USERNAME,
  password: process.env.PASSWORD,
  clientId: process.env.CLIENT_ID,
});

If you don't have any credentials, you'll need to:

  1. Create an Imgur account
  2. Register an application

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

Upload one or more images and videos

You can upload one or more files by simply passing a path to a file or array of paths to multiple files.

// a single image via an absolute path
const response = await client.upload('/home/kai/dank-meme.jpg');
console.log(response.link);

// multiple images via an array of absolute paths
const responses = await client.upload([
  '/home/kai/dank-meme.jpg',
  '/home/kai/another-dank-meme',
]);
responses.forEach((r) => console.log(r.link));

If you want to provide metadata, such as a title, description, etc., then pass an object instead of a string:

// a single image via an absolute path
const response = await client.upload({
  image: '/home/kai/dank-meme.jpg',
  title: 'Meme',
  description: 'Dank Meme',
});
console.log(response.link);

// multiple images via an array of absolute paths
const responses = await client.upload([
  {
    image: '/home/kai/dank-meme.jpg',
    title: 'Meme',
    description: 'Dank Meme',
  },
  {
    video: '/home/kai/cat.mp4',
    title: 'A Cat Movie',
    description: 'Caturday',
  },
]);
responses.forEach((r) => console.log(r.link));

Acceptable key/values match what the Imgur API expects:

Key Description
image A string that is either a path binary file, a base64 string, or a URL pointing to a remote image (up to 10MB)
video A string that is a path to binary file (up to 200MB)
album The id of the album you want to add the media to. For anonymous albums, album should be the deletehash that is returned at creation
type The type of the media that's being transmitted; file, base64 or url
name The name of the media. This is automatically detected, but you can override
title The title of the media
description The description of the media
disable_audio 1 will remove the audio track from a video file

Upload and track progress of uploads

Instances of ImgurClient emit uploadProgress events so that you can track progress with event listeners.

const client = new ImgurClient({ accessToken: process.env.ACCESS_TOKEN });

client.on('uploadProgress', (progress) => console.log(progress));
await client.upload('/home/kai/cat.mp4');

The progress object looks like the following:

{
  percent: 1,
  transferred: 577,
  total: 577,
  id: '/home/user/trailer.mp4'
}
Key Description
percent 0 to 1, measures the percentage of upload (e.g., 0, 0.5, 0.8, 1). Basically transferred / total
transferred total number of bytes transferred thus far
total total number of bytes to be transferred
id unique id for the media being transferred; useful when uploading multiple things concurrently

Delete an image

Requires an image hash or delete hash, which are obtained in an image upload response

client.delete('someImageHash');

Update image information

Update the title and/or description of an image

client.updateImage({
  imageHash: 'someImageHash',
  title: 'A new title',
  description: 'A new description',
});

Update multiple images at once:

client.updateImage([
  {
    imageHash: 'someImageHash',
    title: 'A new title',
    description: 'A new description',
  },
  {
    imageHash: 'anotherImageHash',
    title: 'A better title',
    description: 'A better description',
  },
]);

Favorite an image:

client.favoriteImage('someImageHash');

Get gallery images

client.getGallery({
  section: 'hot',
  sort: 'viral',
  mature: false,
});

getGallery() accepts an object of type GalleryOptions. The follow options are available:

Key Required Description
section required hot | top | user
sort optional viral | top | time | rising (only available with user section). Defaults to viral
page optional number - the data paging number
window optional Change the date range of the request if the section is top. Accepted values are day | week | month | year | all. Defaults to day
showViral optional true | false - Show or hide viral images from the user section. Defaults to true
mature optional true | false - Show or hide mature (nsfw) images in the response section. Defaults to false. NOTE: This parameter is only required if un-authed. The response for authed users will respect their account setting
album_previews optional true | false - Include image metadata for gallery posts which are albums

Get subreddit gallery images

client.getSubredditGallery({
  subreddit: 'wallstreetbets',
  sort: 'time',
});

getSubredditGallery() accepts an object of type SubredditGalleryOptions. The follow options are available:

Key Required Description
subreddit required A valid subreddit name
sort optional time | top - defaults to time
page optional number - the data paging number
window optional Change the date range of the request if the section is top. Accepted values are day | week | month | year | all. Defaults to week

Search the gallery

client.searchGallery({
  query: 'title: memes',
});

searchGallery() accepts an object of type SearchGalleryOptions. The follow options are available:

| Key | Required | Description | | -------------- | -------- | --------------------------------------------------------------------- | ------ | ------- | ------ | ------------------------- | | query or q | required | Query string | | sort | optional | time | viral | top - defaults to time | | page | optional | number - the data paging number | | window | optional | Change the date range of the request if the sort is top -- to day | week | month | year | all, defaults to all. |

Additionally, the following advanced search query options can be set (NOTE: if any of the below are set in the options, the query option is ignored and these will take precedent):

Key Required Description
q_all optional Search for all of these words (and)
q_any optional Search for any of these words (or)
q_exactly optional Search for exactly this word or phrase
q_not optional Exclude results matching this string
q_type optional Show results for any file type, jpg | png | gif | anigif (animated gif) | album
q_size_px optional Size ranges, small (500 pixels square or less) | med (500 to 2,000 pixels square) | big (2,000 to 5,000 pixels square) | lrg (5,000 to 10,000 pixels square) | huge (10,000 square pixels and above)

Get album info

const album = await client.getAlbum('XtMnA');