0
# Utilities and Logging
1
2
Utility functions for cryptography, JWT handling, URL manipulation, and configurable logging system.
3
4
## Capabilities
5
6
### Logging
7
8
Configurable logging system with multiple log levels.
9
10
```typescript { .api }
11
/**
12
* Logger instance with contextual name
13
*/
14
class Logger {
15
constructor(name: string);
16
17
debug(message: string, ...args: unknown[]): void;
18
info(message: string, ...args: unknown[]): void;
19
warn(message: string, ...args: unknown[]): void;
20
error(message: string, ...args: unknown[]): void;
21
22
create(name: string): Logger;
23
}
24
25
/**
26
* Global log configuration
27
*/
28
class Log {
29
static readonly NONE: number;
30
static readonly ERROR: number;
31
static readonly WARN: number;
32
static readonly INFO: number;
33
static readonly DEBUG: number;
34
35
static level: number;
36
static logger: Console;
37
}
38
```
39
40
### Cryptographic Utilities
41
42
PKCE and cryptographic helper functions.
43
44
```typescript { .api }
45
/**
46
* Cryptographic utilities for OIDC operations
47
*/
48
class CryptoUtils {
49
/** Generate RFC4122 version 4 UUID without hyphens */
50
static generateUUIDv4(): string;
51
52
/** Generate PKCE code verifier */
53
static generateCodeVerifier(): string;
54
55
/** Generate PKCE code challenge from verifier */
56
static generateCodeChallenge(codeVerifier: string): Promise<string>;
57
58
/** Generate basic auth header */
59
static generateBasicAuth(client_id: string, client_secret: string): string;
60
}
61
```
62
63
### JWT Utilities
64
65
JWT token parsing and validation.
66
67
```typescript { .api }
68
/**
69
* JWT utilities for token processing
70
*/
71
class JwtUtils {
72
/** Decode JWT token and return claims (does not validate) */
73
static decode(token: string): JwtClaims;
74
}
75
```
76
77
### URL Utilities
78
79
URL manipulation and parsing functions.
80
81
```typescript { .api }
82
/**
83
* URL utilities for OIDC operations
84
*/
85
class UrlUtils {
86
/** Read parameters from URL query string or fragment */
87
static readParams(url: string, responseMode?: "query" | "fragment"): URLSearchParams;
88
}
89
```
90
91
### Timer Utilities
92
93
Timer management for scheduled operations.
94
95
```typescript { .api }
96
/**
97
* Timer utility for scheduling operations
98
*/
99
class Timer {
100
constructor(name: string, logger?: Logger, timerDuration?: number, callback?: () => void);
101
102
init(duration: number): void;
103
cancel(): void;
104
addHandler(callback: () => void): void;
105
removeHandler(callback: () => void): void;
106
}
107
```
108
109
### Event Utilities
110
111
Event emitter implementation.
112
113
```typescript { .api }
114
/**
115
* Event emitter for user and token events
116
*/
117
class Event<T = void> {
118
constructor(name: string);
119
120
addHandler(callback: (data: T) => void): void;
121
removeHandler(callback: (data: T) => void): void;
122
raise(data: T): void;
123
}
124
```
125
126
### Popup Utilities
127
128
Popup window management utilities.
129
130
### Version Information
131
132
Library version constant.
133
134
```typescript { .api }
135
/**
136
* Library version from package.json
137
*/
138
const Version: string;
139
```
140
141
```typescript { .api }
142
/**
143
* Popup window feature configuration
144
*/
145
interface PopupWindowFeatures {
146
location?: boolean;
147
toolbar?: boolean;
148
height?: number;
149
width?: number;
150
left?: number;
151
top?: number;
152
closePopupWindowAfterInSeconds?: number;
153
}
154
155
/**
156
* Popup window management utilities
157
*/
158
class PopupUtils {
159
static center(options: { width: number; height: number }): { left: number; top: number };
160
static serialize(features: PopupWindowFeatures): string;
161
}
162
```
163
164
## Usage Examples
165
166
### Logging Configuration
167
168
```typescript
169
import { Log, Logger } from "oidc-client-ts";
170
171
// Configure global logging
172
Log.level = Log.INFO;
173
Log.logger = console;
174
175
// Create contextual logger
176
const logger = new Logger("MyApp");
177
logger.info("Application started");
178
logger.debug("Debug information"); // Won't show unless level is DEBUG
179
180
// Create sub-logger
181
const authLogger = logger.create("Auth");
182
authLogger.warn("Authentication warning");
183
```
184
185
### Custom Crypto Operations
186
187
```typescript
188
import { CryptoUtils } from "oidc-client-ts";
189
190
// Generate PKCE parameters
191
const codeVerifier = CryptoUtils.generateCodeVerifier();
192
const codeChallenge = await CryptoUtils.generateCodeChallenge(codeVerifier);
193
194
console.log("PKCE Parameters:", {
195
verifier: codeVerifier,
196
challenge: codeChallenge,
197
});
198
199
// Generate UUID for state parameter
200
const state = CryptoUtils.generateUUIDv4();
201
202
// Basic auth header
203
const authHeader = CryptoUtils.generateBasicAuth("client_id", "client_secret");
204
```
205
206
### JWT Processing
207
208
```typescript
209
import { JwtUtils } from "oidc-client-ts";
210
211
const idToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";
212
const claims = JwtUtils.decode(idToken);
213
214
console.log("JWT Claims:", {
215
issuer: claims.iss,
216
subject: claims.sub,
217
audience: claims.aud,
218
expiration: new Date(claims.exp * 1000),
219
name: (claims as any).name,
220
});
221
```
222
223
### URL Manipulation
224
225
```typescript
226
import { UrlUtils } from "oidc-client-ts";
227
228
// Read query parameters
229
const queryUrl = "https://provider.com/callback?code=abc123&state=xyz789";
230
const queryParams = UrlUtils.readParams(queryUrl, "query");
231
console.log("Query params:", Object.fromEntries(queryParams));
232
// { code: "abc123", state: "xyz789" }
233
234
// Read fragment parameters
235
const fragmentUrl = "https://provider.com/callback#access_token=abc123&token_type=Bearer&expires_in=3600";
236
const fragmentParams = UrlUtils.readParams(fragmentUrl, "fragment");
237
console.log("Fragment params:", Object.fromEntries(fragmentParams));
238
// { access_token: "abc123", token_type: "Bearer", expires_in: "3600" }
239
```