0
# tumblr.js
1

2
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.
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
- **Node.js requirement**: >=18
11
- **License**: Apache-2.0
12

13
## Core Imports
14

15
```javascript
16
const { Client, createClient } = require('tumblr.js');
17
```
18

19
ES modules (if supported by your environment):
20

21
```javascript
22
import { Client, createClient } from 'tumblr.js';
23
```
24

25
## Basic Usage
26

27
```javascript
28
const tumblr = require('tumblr.js');
29

30
// Create a client with OAuth credentials
31
const client = tumblr.createClient({
32
  consumer_key: 'your-consumer-key',
33
  consumer_secret: 'your-consumer-secret',
34
  token: 'your-oauth-token',
35
  token_secret: 'your-oauth-token-secret'
36
});
37

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

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

46
// Create a new post using NPF (Neue Post Format)
47
await client.createPost('your-blog-name', {
48
  content: [
49
    {
50
      type: 'text',
51
      text: 'Hello, Tumblr!'
52
    }
53
  ]
54
});
55
```
56

57
## Architecture
58

59
tumblr.js is built around several key components:
60

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

67
## Capabilities
68

69
### Client Creation
70

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

73
```javascript { .api }
74
function createClient(options?: Options): Client;
75

76
class Client {
77
  constructor(options?: Options);
78
  static version: string;
79
}
80

81
interface Options {
82
  consumer_key?: string;
83
  consumer_secret?: string;
84
  token?: string;
85
  token_secret?: string;
86
  baseUrl?: string;
87
  returnPromises?: boolean; // deprecated
88
}
89
```
90

91
[Client Creation and Configuration](./client-configuration.md)
92

93
### HTTP Request Methods
94

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

97
```javascript { .api }
98
getRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
99
postRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
100
putRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
101
```
102

103
[HTTP Request Methods](./http-requests.md)
104

105
### Post Management
106

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

109
```javascript { .api }
110
createPost(blogIdentifier: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
111
editPost(blogIdentifier: string, postId: string, params: NpfPostParams | NpfReblogParams): Promise<any>;
112
deletePost(blogIdentifier: string, postId: string): Promise<any>;
113

114
// Legacy methods (deprecated)
115
createLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
116
editLegacyPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
117
reblogPost(blogIdentifier: string, params: Record<string, any>): Promise<any>;
118
```
119

120
[Post Management](./post-management.md)
121

122
### Blog Information and Content
123

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

126
```javascript { .api }
127
blogInfo(blogIdentifier: string, params?: { 'fields[blogs]'?: string }): Promise<any>;
128
blogPosts(blogIdentifier: string, params?: BlogPostsParams): Promise<any>;
129
blogQueue(blogIdentifier: string, params?: QueueParams): Promise<any>;
130
blogDrafts(blogIdentifier: string, params?: DraftsParams): Promise<any>;
131
blogSubmissions(blogIdentifier: string, params?: SubmissionsParams): Promise<any>;
132
blogAvatar(blogIdentifier: string, size?: AvatarSize): Promise<any>;
133
```
134

135
[Blog Information and Content](./blog-content.md)
136

137
### User Account Management
138

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

141
```javascript { .api }
142
userInfo(): Promise<any>;
143
userDashboard(params?: DashboardParams): Promise<any>;
144
userLikes(params?: LikesParams): Promise<any>;
145
userFollowing(params?: FollowingParams): Promise<any>;
146
```
147

148
[User Account Management](./user-management.md)
149

150
### Social Interactions
151

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

154
```javascript { .api }
155
likePost(postId: string, reblogKey: string): Promise<any>;
156
unlikePost(postId: string, reblogKey: string): Promise<any>;
157
followBlog(params: { url: string } | { email: string }): Promise<any>;
158
unfollowBlog(params: { url: string }): Promise<any>;
159
```
160

161
[Social Interactions](./social-interactions.md)
162

163
### Content Discovery
164

165
Search and discover content through tags and public feeds.
166

167
```javascript { .api }
168
taggedPosts(tag: string, params?: TaggedPostsParams): Promise<any>;
169
blogLikes(blogIdentifier: string, params?: BlogLikesParams): Promise<any>;
170
blogFollowers(blogIdentifier: string, params?: FollowersParams): Promise<any>;
171
```
172

173
[Content Discovery](./content-discovery.md)
174

175
### Deprecated Methods
176

177
Legacy utility methods that are deprecated but still available.
178

179
```javascript { .api }
180
returnPromises(): void; // Deprecated - promises are returned by default if no callback is provided
181
```
182

183
## Types
184

185
### Core Types
186

187
```javascript { .api }
188
interface Options {
189
  consumer_key?: string;
190
  consumer_secret?: string;
191
  token?: string;
192
  token_secret?: string;
193
  baseUrl?: string;
194
  returnPromises?: boolean;
195
}
196

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

201
type TumblrClientCallback = (
202
  err: Error | null,
203
  resp: Record<string, any> | null,
204
  response?: IncomingMessage | null | undefined
205
) => void;
206

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

213
### NPF Content Types
214

215
```javascript { .api }
216
interface NpfPostParams {
217
  content: NpfContentBlock[];
218
  layout?: NpfLayoutBlock[];
219
  state?: PostState;
220
  publish_on?: string;
221
  date?: string;
222
  tags?: string[];
223
  source_url?: string;
224
  is_private?: boolean;
225
  slug?: string;
226
  interactability_reblog?: 'everyone' | 'noone';
227
}
228

229
interface NpfReblogParams extends NpfPostParams {
230
  parent_tumblelog_uuid: string;
231
  parent_post_id: string;
232
  reblog_key: string;
233
  hide_trail?: boolean;
234
  exclude_trail_items?: boolean;
235
}
236

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

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

245
interface ImageBlock {
246
  type: 'image';
247
  media: ReadStream | MediaObject;
248
  [prop: string]: any;
249
}
250

251
interface VideoBlock {
252
  type: 'video';
253
  media: ReadStream | MediaObject;
254
  [prop: string]: any;
255
}
256

257
interface TextBlock {
258
  type: 'text';
259
  [prop: string]: any;
260
}
261

262
interface LinkBlock {
263
  type: 'link';
264
  [prop: string]: any;
265
}
266

267
interface PaywallBlock {
268
  type: 'paywall';
269
  [prop: string]: any;
270
}
271

272
type NpfLayoutBlock = NpfLayoutAsk | NpfLayoutRows;
273

274
interface NpfLayoutRows {
275
  type: 'rows';
276
  display: Array<{ blocks: number[]; mode?: { type: string } }>;
277
  truncate_after?: 1;
278
}
279

280
interface NpfLayoutAsk {
281
  type: 'ask';
282
  blocks: number[];
283
  attribution: any;
284
}
285

286
interface MediaObject {
287
  url: string;
288
  type?: string;
289
  width?: number;
290
  height?: number;
291
  original_dimensions_missing?: boolean;
292
  has_original_dimensions?: boolean;
293
  cropped?: boolean;
294
}
295
```
296

297
### Parameter Types
298

299
```javascript { .api }
300
interface BlogPostsParams {
301
  id?: string;
302
  tag?: string | string[];
303
  type?: PostType;
304
  limit?: number;
305
  offset?: number;
306
  reblog_info?: boolean;
307
  notes_info?: boolean;
308
  npf?: boolean;
309
}
310

311
interface QueueParams {
312
  limit?: number;
313
  offset?: number;
314
  filter?: PostFormatFilter;
315
}
316

317
interface DraftsParams {
318
  before_id?: number;
319
  filter?: PostFormatFilter;
320
}
321

322
interface SubmissionsParams {
323
  offset?: number;
324
  filter?: PostFormatFilter;
325
}
326

327
interface DashboardParams {
328
  limit?: number;
329
  offset?: number;
330
  type?: PostType;
331
  since_id?: number;
332
  reblog_info?: boolean;
333
  notes_info?: boolean;
334
}
335

336
interface LikesParams {
337
  limit?: number;
338
  offset?: number;
339
  before?: number;
340
  after?: number;
341
}
342

343
interface FollowingParams {
344
  limit?: number;
345
  offset?: number;
346
}
347

348
interface TaggedPostsParams {
349
  before?: number;
350
  limit?: number;
351
  filter?: PostFormatFilter;
352
}
353

354
interface BlogLikesParams {
355
  limit?: number;
356
  offset?: number;
357
  before?: number;
358
  after?: number;
359
}
360

361
interface FollowersParams {
362
  limit?: number;
363
  offset?: number;
364
}
365
```