or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

blog-content.mdclient-configuration.mdcontent-discovery.mdhttp-requests.mdindex.mdpost-management.mdsocial-interactions.mduser-management.md
tile.json

index.mddocs/

tumblr.js

The official JavaScript client library for the Tumblr API v2. This comprehensive client provides full access to Tumblr's platform capabilities including post creation, blog management, user authentication, and social interactions through a promise-based API with comprehensive TypeScript support.

Package Information

  • Package Name: tumblr.js
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install tumblr.js
  • Node.js requirement: >=18
  • License: Apache-2.0

Core Imports

const { Client, createClient } = require('tumblr.js');

ES modules (if supported by your environment):

import { Client, createClient } from 'tumblr.js';

Basic Usage

const tumblr = require('tumblr.js');

// Create a client with OAuth credentials
const client = tumblr.createClient({
  consumer_key: 'your-consumer-key',
  consumer_secret: 'your-consumer-secret',
  token: 'your-oauth-token',
  token_secret: 'your-oauth-token-secret'
});

// Get user information
const userInfo = await client.userInfo();
console.log(userInfo.user.name);

// Get blog posts
const posts = await client.blogPosts('your-blog-name');
console.log(posts.posts[0].summary);

// Create a new post using NPF (Neue Post Format)
await client.createPost('your-blog-name', {
  content: [
    {
      type: 'text',
      text: 'Hello, Tumblr!'
    }
  ]
});

Architecture

tumblr.js is built around several key components:

  • Client Class: Main API client handling authentication, requests, and responses
  • Authentication System: Support for OAuth 1.0, API key, and unauthenticated requests
  • NPF Support: Full support for Tumblr's Neue Post Format with media upload capabilities
  • Promise API: All methods return promises with optional legacy callback support
  • Type Safety: Complete TypeScript definitions for all API components

Capabilities

Client Creation

Factory functions and constructors for creating API client instances with flexible authentication options.

function createClient(options?: Options): Client;

class Client {
  constructor(options?: Options);
  static version: string;
}

interface Options {
  consumer_key?: string;
  consumer_secret?: string;
  token?: string;
  token_secret?: string;
  baseUrl?: string;
  returnPromises?: boolean; // deprecated
}

Client Creation and Configuration

HTTP Request Methods

Low-level HTTP request methods for direct API access and custom endpoints.

getRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
postRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
putRequest(apiPath: string, params?: Record<string, any>): Promise<any>;

HTTP Request Methods

Post Management

Create, edit, and delete posts using modern NPF (Neue Post Format) or legacy formats.

createPost(blogIdentifier: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
editPost(blogIdentifier: string, postId: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
deletePost(blogIdentifier: string, postId: string): Promise<any>;

// Legacy methods (deprecated)
createLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
editLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
reblogPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;

Post Management

Blog Information and Content

Retrieve blog information, posts, and various blog-specific content like queue, drafts, and submissions.

blogInfo(blogIdentifier: string, params?: { 'fields[blogs]'?: string }): Promise<any>;
blogPosts(blogIdentifier: string, params?: BlogPostsParams): Promise<any>;
blogQueue(blogIdentifier: string, params?: QueueParams): Promise<any>;
blogDrafts(blogIdentifier: string, params?: DraftsParams): Promise<any>;
blogSubmissions(blogIdentifier: string, params?: SubmissionsParams): Promise<any>;
blogAvatar(blogIdentifier: string, size?: AvatarSize): Promise<any>;

Blog Information and Content

User Account Management

Access user account information, dashboard, likes, and following relationships.

userInfo(): Promise<any>;
userDashboard(params?: DashboardParams): Promise<any>;
userLikes(params?: LikesParams): Promise<any>;
userFollowing(params?: FollowingParams): Promise<any>;

User Account Management

Social Interactions

Like, unlike, follow, and unfollow functionality for social engagement.

likePost(postId: string, reblogKey: string): Promise<any>;
unlikePost(postId: string, reblogKey: string): Promise<any>;
followBlog(params: { url: string } | { email: string }): Promise<any>;
unfollowBlog(params: { url: string }): Promise<any>;

Social Interactions

Content Discovery

Search and discover content through tags and public feeds.

taggedPosts(tag: string, params?: TaggedPostsParams): Promise<any>;
blogLikes(blogIdentifier: string, params?: BlogLikesParams): Promise<any>;
blogFollowers(blogIdentifier: string, params?: FollowersParams): Promise<any>;

Content Discovery

Deprecated Methods

Legacy utility methods that are deprecated but still available.

returnPromises(): void; // Deprecated - promises are returned by default if no callback is provided

Types

Core Types

interface Options {
  consumer_key?: string;
  consumer_secret?: string;
  token?: string;
  token_secret?: string;
  baseUrl?: string;
  returnPromises?: boolean;
}

// Node.js imports for type references
type ReadStream = import('fs').ReadStream;
type IncomingMessage = import('http').IncomingMessage;

type TumblrClientCallback = (
  err: Error | null,
  resp: Record<string, any> | null,
  response?: IncomingMessage | null | undefined
) => void;

type PostType = 'text' | 'quote' | 'link' | 'answer' | 'video' | 'audio' | 'photo' | 'chat';
type PostFormatFilter = 'text' | 'raw';
type PostState = 'published' | 'queue' | 'draft' | 'private' | 'unapproved';
type AvatarSize = 16 | 24 | 30 | 40 | 48 | 64 | 96 | 128 | 512;

NPF Content Types

interface NpfPostParams {
  content: NpfContentBlock[];
  layout?: NpfLayoutBlock[];
  state?: PostState;
  publish_on?: string;
  date?: string;
  tags?: string[];
  source_url?: string;
  is_private?: boolean;
  slug?: string;
  interactability_reblog?: 'everyone' | 'noone';
}

interface NpfReblogParams extends NpfPostParams {
  parent_tumblelog_uuid: string;
  parent_post_id: string;
  reblog_key: string;
  hide_trail?: boolean;
  exclude_trail_items?: boolean;
}

type NpfContentBlock = AudioBlock | ImageBlock | LinkBlock | PaywallBlock | TextBlock | VideoBlock;

interface AudioBlock {
  type: 'audio';
  media: ReadStream | MediaObject;
  [prop: string]: any;
}

interface ImageBlock {
  type: 'image';
  media: ReadStream | MediaObject;
  [prop: string]: any;
}

interface VideoBlock {
  type: 'video';
  media: ReadStream | MediaObject;
  [prop: string]: any;
}

interface TextBlock {
  type: 'text';
  [prop: string]: any;
}

interface LinkBlock {
  type: 'link';
  [prop: string]: any;
}

interface PaywallBlock {
  type: 'paywall';
  [prop: string]: any;
}

type NpfLayoutBlock = NpfLayoutAsk | NpfLayoutRows;

interface NpfLayoutRows {
  type: 'rows';
  display: Array<{ blocks: number[]; mode?: { type: string } }>;
  truncate_after?: 1;
}

interface NpfLayoutAsk {
  type: 'ask';
  blocks: number[];
  attribution: any;
}

interface MediaObject {
  url: string;
  type?: string;
  width?: number;
  height?: number;
  original_dimensions_missing?: boolean;
  has_original_dimensions?: boolean;
  cropped?: boolean;
}

Parameter Types

interface BlogPostsParams {
  id?: string;
  tag?: string | string[];
  type?: PostType;
  limit?: number;
  offset?: number;
  reblog_info?: boolean;
  notes_info?: boolean;
  npf?: boolean;
}

interface QueueParams {
  limit?: number;
  offset?: number;
  filter?: PostFormatFilter;
}

interface DraftsParams {
  before_id?: number;
  filter?: PostFormatFilter;
}

interface SubmissionsParams {
  offset?: number;
  filter?: PostFormatFilter;
}

interface DashboardParams {
  limit?: number;
  offset?: number;
  type?: PostType;
  since_id?: number;
  reblog_info?: boolean;
  notes_info?: boolean;
}

interface LikesParams {
  limit?: number;
  offset?: number;
  before?: number;
  after?: number;
}

interface FollowingParams {
  limit?: number;
  offset?: number;
}

interface TaggedPostsParams {
  before?: number;
  limit?: number;
  filter?: PostFormatFilter;
}

interface BlogLikesParams {
  limit?: number;
  offset?: number;
  before?: number;
  after?: number;
}

interface FollowersParams {
  limit?: number;
  offset?: number;
}