0
# Client Creation and Configuration
1

2
Client creation and authentication configuration for connecting to the Tumblr API with various credential types.
3

4
## Capabilities
5

6
### createClient Function
7

8
Factory function to create a new Tumblr API client instance.
9

10
```javascript { .api }
11
/**
12
 * Creates a Tumblr API client using the given options
13
 * @param options - Client configuration options
14
 * @returns Client instance
15
 */
16
function createClient(options?: Options): Client;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const tumblr = require('tumblr.js');
23

24
// Create client with OAuth credentials
25
const client = tumblr.createClient({
26
  consumer_key: 'your-consumer-key',
27
  consumer_secret: 'your-consumer-secret', 
28
  token: 'your-oauth-token',
29
  token_secret: 'your-oauth-token-secret'
30
});
31

32
// Create client with API key only
33
const apiKeyClient = tumblr.createClient({
34
  consumer_key: 'your-consumer-key'
35
});
36

37
// Create client with no authentication
38
const publicClient = tumblr.createClient();
39
```
40

41
### Client Constructor
42

43
Direct constructor for creating client instances.
44

45
```javascript { .api }
46
/**
47
 * Creates a Tumblr API client using the given options
48
 * @param options - Client configuration options
49
 */
50
class Client {
51
  constructor(options?: Options);
52
  
53
  /** Package version */
54
  static version: string;
55
  
56
  /** Package version (instance property) */
57
  version: string;
58
  
59
  /** Base URL for API requests */
60
  baseUrl: string;
61
}
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
const { Client } = require('tumblr.js');
68

69
// Using constructor directly
70
const client = new Client({
71
  consumer_key: 'your-consumer-key',
72
  consumer_secret: 'your-consumer-secret',
73
  token: 'your-oauth-token', 
74
  token_secret: 'your-oauth-token-secret'
75
});
76

77
console.log(client.version); // "5.0.1"
78
console.log(Client.version); // "5.0.1"
79
```
80

81
### returnPromises Method (Deprecated)
82

83
Legacy method for enabling promise mode. Now promises are returned automatically when no callback is provided.
84

85
```javascript { .api }
86
/**
87
 * @deprecated Promises are returned if no callback is provided
88
 */
89
returnPromises(): void;
90
```
91

92
## Authentication Types
93

94
### OAuth 1.0 Authentication
95

96
Full OAuth 1.0 authentication for authenticated endpoints requiring user permissions.
97

98
```javascript { .api }
99
interface OAuth1Options {
100
  consumer_key: string;
101
  consumer_secret: string;
102
  token: string;
103
  token_secret: string;
104
  baseUrl?: string;
105
}
106
```
107

108
**Requirements:**
109
- All four OAuth credentials must be provided
110
- Used for endpoints requiring user authentication
111
- Generates OAuth signatures for requests
112

113
**Usage Example:**
114

115
```javascript
116
const client = tumblr.createClient({
117
  consumer_key: 'your-consumer-key',
118
  consumer_secret: 'your-consumer-secret',
119
  token: 'user-oauth-token',
120
  token_secret: 'user-oauth-token-secret'
121
});
122

123
// Can access authenticated endpoints
124
const userInfo = await client.userInfo();
125
const dashboard = await client.userDashboard();
126
```
127

128
### API Key Authentication
129

130
API key authentication for read-only endpoints.
131

132
```javascript { .api }
133
interface ApiKeyOptions {
134
  consumer_key: string;
135
  baseUrl?: string;
136
}
137
```
138

139
**Requirements:**
140
- Only consumer_key is required
141
- Used for public read-only endpoints
142
- API key sent as query parameter
143

144
**Usage Example:**
145

146
```javascript
147
const client = tumblr.createClient({
148
  consumer_key: 'your-consumer-key'
149
});
150

151
// Can access public endpoints
152
const blogInfo = await client.blogInfo('staff');
153
const posts = await client.blogPosts('staff');
154
const taggedPosts = await client.taggedPosts('cats');
155
```
156

157
### No Authentication
158

159
No authentication for completely public endpoints.
160

161
```javascript { .api }
162
interface NoAuthOptions {
163
  baseUrl?: string;
164
}
165
```
166

167
**Usage Example:**
168

169
```javascript
170
const client = tumblr.createClient();
171

172
// Limited to completely public endpoints
173
const taggedPosts = await client.taggedPosts('cats');
174
```
175

176
## Configuration Options
177

178
### Options Interface
179

180
Complete configuration interface for client creation.
181

182
```javascript { .api }
183
interface Options {
184
  /** OAuth1 credential. Required for API key auth endpoints */
185
  consumer_key?: string;
186
  /** OAuth1 credential. Required for OAuth endpoints */
187
  consumer_secret?: string;
188
  /** OAuth1 credential. Required for OAuth endpoints */
189
  token?: string;
190
  /** OAuth1 credential. Required for OAuth endpoints */
191
  token_secret?: string;
192
  /** The API url if different from the default */
193
  baseUrl?: string;
194
  /** @deprecated Methods will return promises if no callback is provided */
195
  returnPromises?: boolean;
196
}
197
```
198

199
### Base URL Configuration
200

201
Custom base URL for API requests (useful for testing or alternative endpoints).
202

203
**Usage Example:**
204

205
```javascript
206
const client = tumblr.createClient({
207
  consumer_key: 'your-key',
208
  baseUrl: 'https://api.tumblr.com'  // default
209
});
210
```
211

212
**Base URL Requirements:**
213
- Must be a valid URL with protocol (https://)
214
- Must not include pathname, query parameters, or hash
215
- Must not include authentication credentials in URL
216

217
## Error Handling
218

219
### Configuration Errors
220

221
The client constructor validates configuration and throws specific errors:
222

223
```javascript
224
// Missing OAuth credentials
225
try {
226
  const client = new Client({
227
    consumer_key: 'key',
228
    consumer_secret: 'secret'
229
    // Missing token and token_secret
230
  });
231
} catch (error) {
232
  // TypeError: Provide consumer_key or all oauth credentials. Invalid token provided.
233
}
234

235
// Invalid baseUrl
236
try {
237
  const client = new Client({
238
    baseUrl: 'https://api.tumblr.com/v2'  // includes path
239
  });
240
} catch (error) {
241
  // TypeError: baseUrl option must not include a pathname.
242
}
243
```
244

245
### Common Configuration Patterns
246

247
```javascript
248
// Development/testing with custom base URL
249
const devClient = tumblr.createClient({
250
  consumer_key: process.env.TUMBLR_CONSUMER_KEY,
251
  baseUrl: 'https://api-test.tumblr.com'
252
});
253

254
// Production with full OAuth
255
const prodClient = tumblr.createClient({
256
  consumer_key: process.env.TUMBLR_CONSUMER_KEY,
257
  consumer_secret: process.env.TUMBLR_CONSUMER_SECRET,
258
  token: userOAuthToken,
259
  token_secret: userOAuthTokenSecret
260
});
261

262
// Public read-only client
263
const publicClient = tumblr.createClient({
264
  consumer_key: process.env.TUMBLR_CONSUMER_KEY
265
});
266
```