@embark-black-book/api-contract 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -0
- package/dist/auth-helpers.d.ts +14 -0
- package/dist/auth-helpers.js +11 -0
- package/dist/auth-refresh-utils.d.ts +24 -0
- package/dist/auth-refresh-utils.js +64 -0
- package/dist/generated/api-client.d.ts +3 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -152,6 +152,55 @@ async function createCategory(baseUrl: string, token?: string) {
|
|
|
152
152
|
}
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
+
## Auth Refresh Helpers
|
|
156
|
+
|
|
157
|
+
Use dedicated auth helpers for local login, logout, and refresh flows.
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import {
|
|
161
|
+
authLocalJson,
|
|
162
|
+
authLogoutJson,
|
|
163
|
+
authRefreshJson,
|
|
164
|
+
type AuthRefreshResponse,
|
|
165
|
+
} from "@embark-black-book/api-contract";
|
|
166
|
+
|
|
167
|
+
async function refreshAuth(baseUrl: string, refreshToken: string) {
|
|
168
|
+
const parsed = await authRefreshJson({
|
|
169
|
+
baseUrl,
|
|
170
|
+
refreshToken,
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
const payload: AuthRefreshResponse | null = parsed.data;
|
|
174
|
+
return payload;
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
`authRefreshJson` requires `refreshToken` (not access token) and throws `ApiResponseError` for non-2xx responses.
|
|
179
|
+
|
|
180
|
+
## Refresh Utilities
|
|
181
|
+
|
|
182
|
+
Optional utilities are exported to help app-level refresh policy code stay consistent.
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
import {
|
|
186
|
+
computeRefreshWindowDecision,
|
|
187
|
+
createSingleFlightRefresh,
|
|
188
|
+
} from "@embark-black-book/api-contract";
|
|
189
|
+
|
|
190
|
+
const refreshOnce = createSingleFlightRefresh(async (token: string) => {
|
|
191
|
+
return refreshAuth("http://localhost:1337/api", token);
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
const decision = computeRefreshWindowDecision({
|
|
195
|
+
expiresAtMs: Date.now() + 120_000,
|
|
196
|
+
refreshBeforeExpiryMs: 60_000,
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
if (decision.shouldRefresh) {
|
|
200
|
+
await refreshOnce("refresh-token-value");
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
155
204
|
## Call Endpoint Without Token
|
|
156
205
|
|
|
157
206
|
```ts
|
package/dist/auth-helpers.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type {
|
|
2
2
|
AuthLocalResponse,
|
|
3
3
|
AuthLogoutResponse,
|
|
4
|
+
AuthRefreshResponse,
|
|
4
5
|
GeneratedApiClient,
|
|
5
6
|
} from "./generated/api-client";
|
|
6
7
|
import type { ParsedApiResponse } from "./api-response-helpers";
|
|
@@ -13,6 +14,14 @@ export type AuthLogoutRequestOptions = Parameters<
|
|
|
13
14
|
GeneratedApiClient["createAuthLogout"]
|
|
14
15
|
>[0];
|
|
15
16
|
|
|
17
|
+
export type AuthRefreshRequestOptions = Omit<
|
|
18
|
+
Parameters<GeneratedApiClient["createAuthRefresh"]>[0],
|
|
19
|
+
"token"
|
|
20
|
+
> & {
|
|
21
|
+
/** Refresh token used for /auth/refresh. */
|
|
22
|
+
refreshToken: string;
|
|
23
|
+
};
|
|
24
|
+
|
|
16
25
|
export declare function authLocalJson(
|
|
17
26
|
options: AuthLocalRequestOptions,
|
|
18
27
|
client?: GeneratedApiClient
|
|
@@ -22,3 +31,8 @@ export declare function authLogoutJson(
|
|
|
22
31
|
options: AuthLogoutRequestOptions,
|
|
23
32
|
client?: GeneratedApiClient
|
|
24
33
|
): Promise<ParsedApiResponse<AuthLogoutResponse>>;
|
|
34
|
+
|
|
35
|
+
export declare function authRefreshJson(
|
|
36
|
+
options: AuthRefreshRequestOptions,
|
|
37
|
+
client?: GeneratedApiClient
|
|
38
|
+
): Promise<ParsedApiResponse<AuthRefreshResponse>>;
|
package/dist/auth-helpers.js
CHANGED
|
@@ -18,7 +18,18 @@ async function authLogoutJson(options, client) {
|
|
|
18
18
|
return parseApiResponse(response);
|
|
19
19
|
}
|
|
20
20
|
|
|
21
|
+
async function authRefreshJson(options, client) {
|
|
22
|
+
const resolvedClient = client || apiClient;
|
|
23
|
+
const { refreshToken, ...rest } = options;
|
|
24
|
+
const response = await resolvedClient.createAuthRefresh({
|
|
25
|
+
...rest,
|
|
26
|
+
token: refreshToken,
|
|
27
|
+
});
|
|
28
|
+
return requireApiResponseOk(response);
|
|
29
|
+
}
|
|
30
|
+
|
|
21
31
|
module.exports = {
|
|
22
32
|
authLocalJson,
|
|
23
33
|
authLogoutJson,
|
|
34
|
+
authRefreshJson,
|
|
24
35
|
};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export interface RefreshWindowOptions {
|
|
2
|
+
expiresAtMs: number;
|
|
3
|
+
nowMs?: number;
|
|
4
|
+
refreshBeforeExpiryMs?: number;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
export interface RefreshWindowDecision {
|
|
8
|
+
shouldRefresh: boolean;
|
|
9
|
+
nowMs: number;
|
|
10
|
+
expiresAtMs: number;
|
|
11
|
+
refreshAtMs: number;
|
|
12
|
+
timeToExpiryMs: number;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export declare function computeRefreshWindowDecision(
|
|
16
|
+
options: RefreshWindowOptions
|
|
17
|
+
): RefreshWindowDecision;
|
|
18
|
+
|
|
19
|
+
export declare function createSingleFlightRefresh<
|
|
20
|
+
TArgs extends unknown[],
|
|
21
|
+
TResult
|
|
22
|
+
>(
|
|
23
|
+
refreshFn: (...args: TArgs) => Promise<TResult>
|
|
24
|
+
): (...args: TArgs) => Promise<TResult>;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
function computeRefreshWindowDecision(options) {
|
|
4
|
+
if (!options || typeof options !== "object") {
|
|
5
|
+
throw new Error("computeRefreshWindowDecision requires options.");
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
const expiresAtMs = Number(options.expiresAtMs);
|
|
9
|
+
if (!Number.isFinite(expiresAtMs)) {
|
|
10
|
+
throw new Error("expiresAtMs must be a finite number.");
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const nowMs =
|
|
14
|
+
options.nowMs === undefined ? Date.now() : Number(options.nowMs);
|
|
15
|
+
if (!Number.isFinite(nowMs)) {
|
|
16
|
+
throw new Error("nowMs must be a finite number when provided.");
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const refreshBeforeExpiryMs =
|
|
20
|
+
options.refreshBeforeExpiryMs === undefined
|
|
21
|
+
? 60_000
|
|
22
|
+
: Number(options.refreshBeforeExpiryMs);
|
|
23
|
+
if (!Number.isFinite(refreshBeforeExpiryMs) || refreshBeforeExpiryMs < 0) {
|
|
24
|
+
throw new Error(
|
|
25
|
+
"refreshBeforeExpiryMs must be a finite number greater than or equal to 0."
|
|
26
|
+
);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const refreshAtMs = expiresAtMs - refreshBeforeExpiryMs;
|
|
30
|
+
const shouldRefresh = nowMs >= refreshAtMs;
|
|
31
|
+
|
|
32
|
+
return {
|
|
33
|
+
shouldRefresh,
|
|
34
|
+
nowMs,
|
|
35
|
+
expiresAtMs,
|
|
36
|
+
refreshAtMs,
|
|
37
|
+
timeToExpiryMs: expiresAtMs - nowMs,
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function createSingleFlightRefresh(refreshFn) {
|
|
42
|
+
if (typeof refreshFn !== "function") {
|
|
43
|
+
throw new Error("createSingleFlightRefresh requires a function.");
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
let inFlight = null;
|
|
47
|
+
|
|
48
|
+
return function singleFlightRefresh(...args) {
|
|
49
|
+
if (!inFlight) {
|
|
50
|
+
inFlight = Promise.resolve()
|
|
51
|
+
.then(() => refreshFn(...args))
|
|
52
|
+
.finally(() => {
|
|
53
|
+
inFlight = null;
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
return inFlight;
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
module.exports = {
|
|
62
|
+
computeRefreshWindowDecision,
|
|
63
|
+
createSingleFlightRefresh,
|
|
64
|
+
};
|
|
@@ -45,6 +45,7 @@ export interface ApiParameters {
|
|
|
45
45
|
export type AuthLocalRequest = { identifier: string; password: string; };
|
|
46
46
|
export type AuthLocalResponse = { jwt: string; refreshToken?: string; user: { id: number; documentId: string; username: string; email: string; provider: string; confirmed: boolean; blocked: boolean; role?: number | { id: unknown; name: unknown; description: unknown; type: unknown; createdAt: unknown; updatedAt: unknown; }; createdAt: string; updatedAt: string; publishedAt: string; }; };
|
|
47
47
|
export type AuthLogoutResponse = null;
|
|
48
|
+
export type AuthRefreshResponse = { jwt: string; refreshToken?: string; user: { id: number; documentId: string; username: string; email: string; provider: string; confirmed: boolean; blocked: boolean; role?: number | { id: unknown; name: unknown; description: unknown; type: unknown; createdAt: unknown; updatedAt: unknown; }; createdAt: string; updatedAt: string; publishedAt: string; }; };
|
|
48
49
|
|
|
49
50
|
export type ApiClientDefinition = { name: string; group: string; method: string; pathTemplate: string; pathParams: string[]; hasBody: boolean; queryParams: string[] };
|
|
50
51
|
|
|
@@ -256,7 +257,8 @@ export interface GeneratedApiClient {
|
|
|
256
257
|
}): Promise<Response>;
|
|
257
258
|
createAuthRefresh(options: {
|
|
258
259
|
baseUrl: string;
|
|
259
|
-
token
|
|
260
|
+
/** Refresh token passed as Authorization: Bearer <token> for /auth/refresh. */
|
|
261
|
+
token: string;
|
|
260
262
|
headers?: Record<string, string>;
|
|
261
263
|
signal?: AbortSignal;
|
|
262
264
|
fetchImpl?: typeof fetch;
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -3,9 +3,11 @@
|
|
|
3
3
|
const apiClient = require("./generated/api-client");
|
|
4
4
|
const responseHelpers = require("./api-response-helpers");
|
|
5
5
|
const authHelpers = require("./auth-helpers");
|
|
6
|
+
const authRefreshUtils = require("./auth-refresh-utils");
|
|
6
7
|
|
|
7
8
|
module.exports = {
|
|
8
9
|
...apiClient,
|
|
9
10
|
...responseHelpers,
|
|
10
11
|
...authHelpers,
|
|
12
|
+
...authRefreshUtils,
|
|
11
13
|
};
|