@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 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
@@ -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>>;
@@ -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?: string;
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
@@ -2,3 +2,4 @@ export * from './generated/api-types';
2
2
  export * from './generated/api-client';
3
3
  export * from './api-response-helpers';
4
4
  export * from './auth-helpers';
5
+ export * from './auth-refresh-utils';
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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@embark-black-book/api-contract",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Type contract package generated from Blackbook by Embark Strapi OpenAPI",
5
5
  "license": "UNLICENSED",
6
6
  "exports": {