0
# Tumblr.js
1

2
Tumblr.js is the official JavaScript client library for the Tumblr API v2. It provides comprehensive methods for user operations, blog management, and post manipulation with support for both modern Promise-based and legacy callback-based approaches. The library offers OAuth authentication for secure API access, handles media uploads through ReadStream integration, and provides utilities for arbitrary API requests.
3

4
## Package Information
5

6
- **Package Name**: tumblr.js
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install tumblr.js`
10

11
## Core Imports
12

13
```javascript
14
const tumblr = require('tumblr.js');
15
const client = tumblr.createClient({
16
  consumer_key: '<consumer key>',
17
  consumer_secret: '<consumer secret>',
18
  token: '<oauth token>',
19
  token_secret: '<oauth token secret>',
20
});
21
```
22

23
Or using the constructor directly:
24

25
```javascript
26
const tumblr = require('tumblr.js');
27
const client = new tumblr.Client({ /* credentials */ });
28
```
29

30
For ES modules in Node.js:
31

32
```javascript
33
// Note: tumblr.js uses CommonJS, so ES import requires dynamic import
34
const { createClient, Client } = await import('tumblr.js');
35
const client = createClient({ /* credentials */ });
36
```
37

38
## Basic Usage
39

40
```javascript
41
const tumblr = require('tumblr.js');
42

43
// Create authenticated client
44
const client = tumblr.createClient({
45
  consumer_key: 'your_consumer_key',
46
  consumer_secret: 'your_consumer_secret',
47
  token: 'your_oauth_token',
48
  token_secret: 'your_oauth_token_secret',
49
});
50

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

55
// Get blog posts
56
const posts = await client.blogPosts('blogname');
57
console.log(posts.posts);
58

59
// Create a new text post
60
await client.createPost('blogname', {
61
  content: [
62
    {
63
      type: 'text',
64
      text: 'Hello Tumblr!',
65
    },
66
  ],
67
});
68
```
69

70
## Architecture
71

72
Tumblr.js is built around several key components:
73

74
- **Client Class**: Main API client providing all Tumblr operations with flexible authentication
75
- **Authentication System**: Supports no authentication, API key authentication, and full OAuth1 authentication
76
- **Request Infrastructure**: Generic HTTP methods (GET, POST, PUT) with automatic JSON handling and OAuth signing
77
- **NPF Support**: Modern Neue Post Format support with media upload capabilities via ReadStream objects
78
- **Legacy Compatibility**: Backward compatibility with legacy post formats and callback-based API
79
- **Error Handling**: Comprehensive error handling with HTTP status validation and API error extraction
80

81
## Capabilities
82

83
### Client Creation and Configuration
84

85
Client instantiation with flexible authentication options and configuration.
86

87
```javascript { .api }
88
function createClient(options?: ClientOptions): Client;
89

90
class Client {
91
  constructor(options?: ClientOptions);
92
  
93
  // Static and instance properties
94
  static version: string;
95
  version: string;
96
  baseUrl: string;
97
}
98

99
interface ClientOptions {
100
  consumer_key?: string;
101
  consumer_secret?: string;
102
  token?: string;
103
  token_secret?: string;
104
  baseUrl?: string;
105
  returnPromises?: boolean; // deprecated
106
}
107
```
108

109
[Client Setup](./client-setup.md)
110

111
### User Operations
112

113
Methods for accessing user information, dashboard, likes, and following operations.
114

115
```javascript { .api }
116
// User information and content
117
userInfo(): Promise<any>;
118
userDashboard(params?: Record<string, any>): Promise<any>;
119
userLikes(params?: UserLikesParams): Promise<any>;
120
userFollowing(params?: UserFollowingParams): Promise<any>;
121

122
// User actions
123
followBlog(params: {url: string} | {email: string}): Promise<any>;
124
unfollowBlog(params: {url: string}): Promise<any>;
125
likePost(postId: string, reblogKey: string): Promise<any>;
126
unlikePost(postId: string, reblogKey: string): Promise<any>;
127

128
interface UserLikesParams {
129
  limit?: number;
130
  offset?: number;
131
  before?: number;
132
  after?: number;
133
}
134

135
interface UserFollowingParams {
136
  limit?: number;
137
  offset?: number;
138
}
139
```
140

141
[User Operations](./user-operations.md)
142

143
### Blog Management
144

145
Comprehensive blog information retrieval and content access methods.
146

147
```javascript { .api }
148
// Blog information
149
blogInfo(blogIdentifier: string, params?: {'fields[blogs]'?: string}): Promise<any>;
150
blogAvatar(blogIdentifier: string, size?: 16|24|30|40|48|64|96|128|512): Promise<any>;
151

152
// Blog content access
153
blogPosts(blogIdentifier: string, params?: BlogPostsParams): Promise<any>;
154
blogLikes(blogIdentifier: string, params?: BlogLikesParams): Promise<any>;
155
blogFollowers(blogIdentifier: string, params?: BlogFollowersParams): Promise<any>;
156
blogQueue(blogIdentifier: string, params?: BlogQueueParams): Promise<any>;
157
blogDrafts(blogIdentifier: string, params?: BlogDraftsParams): Promise<any>;
158
blogSubmissions(blogIdentifier: string, params?: BlogSubmissionsParams): Promise<any>;
159

160
interface BlogPostsParams {
161
  id?: string;
162
  tag?: string | string[];
163
  type?: 'text' | 'quote' | 'link' | 'answer' | 'video' | 'audio' | 'photo' | 'chat';
164
  limit?: number;
165
  offset?: number;
166
  reblog_info?: boolean;
167
  notes_info?: boolean;
168
  npf?: boolean;
169
}
170
```
171

172
[Blog Management](./blog-management.md)
173

174
### Post Operations
175

176
Modern NPF (Neue Post Format) post creation, editing, and deletion with media upload support.
177

178
```javascript { .api }
179
// NPF post operations
180
createPost(blogIdentifier: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
181
editPost(blogIdentifier: string, postId: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
182
deletePost(blogIdentifier: string, postId: string): Promise<any>;
183

184
// Legacy post operations (deprecated)
185
createLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
186
editLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
187
reblogPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
188

189
interface NpfPostParams {
190
  content: NpfContentBlock[];
191
  layout?: NpfLayoutBlock[];
192
  state?: 'published' | 'queue' | 'draft' | 'private' | 'unapproved';
193
  publish_on?: string;
194
  date?: string;
195
  tags?: string[];
196
  source_url?: string;
197
  is_private?: boolean;
198
  slug?: string;
199
  interactability_reblog?: 'everyone' | 'noone';
200
}
201
```
202

203
[Post Operations](./post-operations.md)
204

205
### Tagged Content and Generic Requests
206

207
Methods for accessing tagged content and making arbitrary API requests.
208

209
```javascript { .api }
210
// Tagged content
211
taggedPosts(tag: string, params?: Record<string, any>): Promise<any>;
212

213
// Generic HTTP methods
214
getRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
215
postRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
216
putRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
217
```
218

219
[Tagged Content and Generic Requests](./tagged-and-generic.md)
220

221
## Core Types
222

223
```javascript { .api }
224
// Content block types for NPF
225
type NpfContentBlock = AudioBlock | ImageBlock | LinkBlock | PaywallBlock | TextBlock | VideoBlock;
226

227
interface AudioBlock {
228
  type: 'audio';
229
  media: ReadStream | MediaObject;
230
  [prop: string]: any;
231
}
232

233
interface ImageBlock {
234
  type: 'image';
235
  media: ReadStream | MediaObject;
236
  [prop: string]: any;
237
}
238

239
interface VideoBlock {
240
  type: 'video';
241
  media: ReadStream | MediaObject;
242
  [prop: string]: any;
243
}
244

245
interface TextBlock {
246
  type: 'text';
247
  [prop: string]: any;
248
}
249

250
interface LinkBlock {
251
  type: 'link';
252
  [prop: string]: any;
253
}
254

255
interface PaywallBlock {
256
  type: 'paywall';
257
  [prop: string]: any;
258
}
259

260
// Media object for NPF content
261
interface MediaObject {
262
  url: string;
263
  type?: string;
264
  width?: number;
265
  height?: number;
266
  original_dimensions_missing?: boolean;
267
  has_original_dimensions?: boolean;
268
  cropped?: boolean;
269
}
270

271
// Layout blocks for NPF
272
type NpfLayoutBlock = NpfLayoutAsk | NpfLayoutRows;
273

274
interface NpfLayoutAsk {
275
  type: 'ask';
276
  blocks: readonly number[];
277
  attribution: any;
278
}
279

280
interface NpfLayoutRows {
281
  type: 'rows';
282
  display: readonly {blocks: readonly number[]; mode?: {type: string}}[];
283
  truncate_after?: 1;
284
}
285

286
// Callback type (deprecated)
287
type TumblrClientCallback = (err: Error | null, resp: Record<string, any> | null, response?: any) => void;
288
```