0
# Client Setup
1

2
Client instantiation and configuration for the Tumblr.js library, providing flexible authentication options and base URL customization.
3

4
## Capabilities
5

6
### Create Client 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 - Optional client configuration and credentials
14
 * @returns Client instance configured with provided options
15
 */
16
function createClient(options?: ClientOptions): Client;
17
```
18

19
**Usage Examples:**
20

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

24
// Create client with no authentication (public endpoints only)
25
const publicClient = tumblr.createClient();
26

27
// Create client with API key authentication
28
const apiKeyClient = tumblr.createClient({
29
  consumer_key: 'your_api_key',
30
});
31

32
// Create client with full OAuth authentication
33
const oauthClient = tumblr.createClient({
34
  consumer_key: 'your_consumer_key',
35
  consumer_secret: 'your_consumer_secret',
36
  token: 'user_oauth_token',
37
  token_secret: 'user_oauth_token_secret',
38
});
39
```
40

41
### Client Constructor
42

43
Direct instantiation of the Client class with the same options as createClient.
44

45
```javascript { .api }
46
/**
47
 * Creates a Tumblr API client using the given options
48
 * @param options - Optional client configuration and credentials
49
 */
50
class Client {
51
  constructor(options?: ClientOptions);
52
}
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
const tumblr = require('tumblr.js');
59

60
// Direct instantiation
61
const client = new tumblr.Client({
62
  consumer_key: 'your_consumer_key',
63
  consumer_secret: 'your_consumer_secret',
64
  token: 'user_oauth_token',
65
  token_secret: 'user_oauth_token_secret',
66
});
67
```
68

69
### Client Properties
70

71
Static and instance properties available on the Client class and instances.
72

73
```javascript { .api }
74
/**
75
 * Package version (static property)
76
 */
77
static version: string;
78

79
/**
80
 * Package version (instance property)
81
 */
82
version: string;
83

84
/**
85
 * Base URL for API requests
86
 */
87
baseUrl: string;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const tumblr = require('tumblr.js');
94

95
// Access static version
96
console.log(tumblr.Client.version); // "4.0.1"
97

98
// Access instance properties
99
const client = tumblr.createClient();
100
console.log(client.version); // "4.0.1"
101
console.log(client.baseUrl); // "https://api.tumblr.com/"
102
```
103

104
### Client Options Interface
105

106
Configuration options for client instantiation, supporting various authentication modes.
107

108
```javascript { .api }
109
/**
110
 * Configuration options for Tumblr client
111
 */
112
interface ClientOptions {
113
  /** OAuth1 credential. Required for API key auth endpoints. */
114
  consumer_key?: string;
115
  /** OAuth1 credential. Required for OAuth endpoints. */
116
  consumer_secret?: string;
117
  /** OAuth1 credential. Required for OAuth endpoints. */
118
  token?: string;
119
  /** OAuth1 credential. Required for OAuth endpoints. */
120
  token_secret?: string;
121
  /** The API base URL if different from the default */
122
  baseUrl?: string;
123
  /** @deprecated Methods will return promises if no callback is provided */
124
  returnPromises?: boolean;
125
}
126
```
127

128
### Authentication Modes
129

130
The client supports three authentication modes:
131

132
**No Authentication:**
133
```javascript
134
const client = tumblr.createClient();
135
// Only works with public endpoints
136
```
137

138
**API Key Authentication:**
139
```javascript
140
const client = tumblr.createClient({
141
  consumer_key: 'your_api_key',
142
});
143
// Works with endpoints that require API key
144
```
145

146
**Full OAuth Authentication:**
147
```javascript
148
const client = tumblr.createClient({
149
  consumer_key: 'your_consumer_key',
150
  consumer_secret: 'your_consumer_secret',
151
  token: 'user_oauth_token',
152
  token_secret: 'user_oauth_token_secret',
153
});
154
// Works with all endpoints including user-specific operations
155
```
156

157
### Base URL Configuration
158

159
Customize the API base URL for testing or alternative endpoints.
160

161
```javascript { .api }
162
/**
163
 * Base URL configuration examples
164
 */
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
// Default Tumblr API
171
const client = tumblr.createClient(); // baseUrl: "https://api.tumblr.com/"
172

173
// Custom base URL
174
const testClient = tumblr.createClient({
175
  baseUrl: 'https://test-api.example.com',
176
  consumer_key: 'test_key',
177
});
178

179
// Invalid base URL configurations (will throw errors)
180
// tumblr.createClient({ baseUrl: 'https://api.tumblr.com/v2' }); // Error: pathname not allowed
181
// tumblr.createClient({ baseUrl: 'https://api.tumblr.com/?param=value' }); // Error: query not allowed
182
```
183

184
### Error Handling
185

186
The client constructor validates configuration options and throws descriptive errors for invalid configurations.
187

188
**Common Configuration Errors:**
189

190
- `TypeError: baseUrl option must not include a pathname.` - When baseUrl includes a path
191
- `TypeError: baseUrl option must not include search params (query).` - When baseUrl includes query parameters  
192
- `TypeError: baseUrl option must not include username.` - When baseUrl includes username
193
- `TypeError: baseUrl option must not include password.` - When baseUrl includes password
194
- `TypeError: baseUrl option must not include hash.` - When baseUrl includes hash fragment
195
- `TypeError: You must provide a consumer_key.` - When consumer_key is not a string
196
- `TypeError: Provide consumer_key or all oauth credentials. Invalid [credential] provided.` - When OAuth credentials are incomplete