DOCSEARCHbyAlgolia
Submit Docs

tumblr.js

repository·main·Indexed 20 days ago

https://github.com/tumblr/tumblr.js

Official JavaScript client library for the Tumblr API v2, providing a Promise-based interface for interacting with users, blogs, and posts. It supports API Key and OAuth1 authentication and includes specialized methods for the Neue Post Format (NPF) to create and edit posts, as well as utilities for managing user interactions like likes and follows. Designed for Node.js; not intended for in-browser use due to CORS restrictions.

Tokens
3.2K
Snippets
8
Records
19
Agent score
69%

What's inside tumblr.js

  1. Authenticate with the Tumblr API

    main

    Authentication requirements vary by method:

    1. API Key: Most methods require an API key (the OAuth Consumer Key), which you obtain by registering an application.
    2. OAuth Tokens: Methods requiring fully signed requests require OAuth tokens (token and token_secret). You can obtain these for your own account via the Tumblr OAuth applications page and the API console.
    3. 3-legged OAuth: If building an application for external users, you must implement the standard 3-legged OAuth flow.

  4. Reblog posts with NpfReblogParams

    main

    When reblogging content, extend NpfPostParams with NpfReblogParams to provide the necessary context for the original post.

    Required Reblog Fields

    • parent_tumblelog_uuid: The unique public identifier of the source Tumblelog.
    • parent_post_id: The unique public post ID being reblogged.
    • reblog_key: The unique per-post hash validating the reblog action.

    Reblog Customization

    • hide_trail: Whether to hide the reblog trail. Defaults to false.
    • exclude_trail_items: (Boolean) Used to specify specific reblog trail item indexes to exclude.

  5. Use the Client's Promise-based API

    main

    The tumblr.js client supports both callbacks and Promises. To use the modern Promise-based API, simply omit the callback argument from any method call. If a callback is provided, the method will execute using that callback instead of returning a Promise.

    // Promise usage (Recommended)
const posts = await client.blogPosts('myblog');

// Callback usage (Deprecated)
client.blogPosts('myblog', (err, resp) => {
  if (err) throw err;
  console.log(resp);
});

  6. Create NPF posts with NpfPostParams

    main

    To create new posts using the New Post Format (NPF), use the NpfPostParams interface. This allows you to define content using structured blocks rather than legacy formats.

    Core Parameters

    • content: An array of NpfContentBlock objects (e.g., text, image, video, audio, link, paywall).
    • layout: (Optional) An array of NpfLayoutBlock objects (e.g., rows, ask) to define the visual structure.
    • state: The initial state of the post. Options: 'published', 'queue', 'draft', 'private', 'unapproved'. Defaults to 'published'.
    • publish_on: (ISO 8601 string) The future date/time to publish. Only works if state is 'queue'.
    • date: (ISO 8601 string) A past date to backdate the post.
    • tags: An array of strings to associate with the post.
    • slug: A custom URL slug for the post's permalink.
    • source_url: Attribution for the content.
    • interactability_reblog: Controls reblogging permissions. Options: 'everyone', 'noone'.

    Media Handling

    For image, video, and audio blocks, the media property accepts either:

    1. A MediaObject: An object containing a url and optional metadata (type, width, height).
    2. A Node.js ReadStream: Used for uploading media directly from the file system.

  7. Initialize the Tumblr Client

    main

    Use the createClient function or the Client class to initialize a connection to the Tumblr API. You can provide an optional options object to configure the baseUrl and authentication credentials.

    Authentication Modes

    • None: No credentials provided.
    • API Key: Provide consumer_key (as a string).
    • OAuth1: Provide consumer_key, consumer_secret, token, and token_secret.

    Configuration Options

    • baseUrl: The base URL for API requests. Must not include a pathname, search parameters, username, password, or hash. Defaults to https://api.tumblr.com.
    • returnPromises: (Deprecated) Use the default behavior where omitting a callback returns a Promise.
    const { createClient } = require('tumblr.js');

// OAuth1 Authentication
const client = createClient({
  consumer_key: 'YOUR_CONSUMER_KEY',
  consumer_secret: 'YOUR_CONSUMER_SECRET',
  token: 'YOUR_TOKEN',
  token_secret: 'YOUR_TOKEN_SECRET'
});

// API Key Authentication
const clientApiKey = createClient({
  consumer_key: 'YOUR_CONSUMER_KEY'
});

  8. Initialize a Tumblr client in Node.js

    main

    In Node.js, you can initialize a client using tumblr.createClient() or by instantiating new tumblr.Client(). All request methods return Promises. The callback form is deprecated and should not be used.

    const tumblr = require('tumblr.js');
const client = tumblr.createClient({
  consumer_key: '<consumer key>',
  consumer_secret: '<consumer secret>',
  token: '<oauth token>',
  token_secret: '<oauth token secret>',
});

  9. Use Blog Methods

    main

    Access information and content related to specific blogs:

    • client.blogInfo(blogName): Get information about a given blog.
    • client.blogPosts(blogName, options): Get a list of posts for a blog (with optional filtering).
    • client.blogAvatar(blogName): Get the avatar URL for a blog.
    • client.blogLikes(blogName, options): Get the likes for a blog.
    • client.blogFollowers(blogName, options): Get the followers for a blog.
    • client.blogQueue(blogName, options): Get the queue for a blog.
    • client.blogDrafts(blogName, options): Get the drafts for a blog.
    • client.blogSubmissions(blogName, options): Get the submissions for a blog.

  11. Make arbitrary requests with getRequest, postRequest, and putRequest

    main

    If a specific method is not provided, you can make arbitrary requests using the following methods:

    • client.getRequest(apiPath, params)
    • client.postRequest(apiPath, params)
    • client.putRequest(apiPath, params)

  12. Use Post Methods

    main

    Create, edit, or delete posts:

    • client.createPost(blogName, options): Create a new post. To upload media, provide a ReadStream in the content array.
    • client.editPost(blogName, postId, options): Edit an existing post.
    • client.deletePost(blogName, postId): Delete a post.
    // Example: Creating a post with an image upload
import fs from 'node:fs';

await client.createPost(blogName, {
  content: [
    {
      type: 'image',
      media: fs.createReadStream(new URL('./image.jpg', import.meta.url)),
      alt_text: '…',
    },
  ],
});