@3lineas/groovepack 0.1.4 → 1.2.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.
Files changed (42) hide show
  1. package/README.md +261 -138
  2. package/dist/action-response.type-XlzII9Lr.d.ts +11 -0
  3. package/dist/api-action/index.d.ts +44 -0
  4. package/dist/api-action/index.js +105 -0
  5. package/dist/api-action/index.js.map +1 -0
  6. package/dist/api-client/index.d.ts +52 -0
  7. package/dist/api-client/index.js +142 -0
  8. package/dist/api-client/index.js.map +1 -0
  9. package/dist/api-toast/index.d.ts +80 -0
  10. package/dist/api-toast/index.js +104 -0
  11. package/dist/api-toast/index.js.map +1 -0
  12. package/dist/batch-capable-db.type-Cyybxkjc.d.ts +8 -0
  13. package/dist/chunk-3FQ5C44Y.js +119 -0
  14. package/dist/chunk-3FQ5C44Y.js.map +1 -0
  15. package/dist/groovepack-locale.type-CaXo9vLj.d.ts +3 -0
  16. package/dist/i18n/index.d.ts +82 -0
  17. package/dist/i18n/index.js +17 -0
  18. package/dist/i18n/index.js.map +1 -0
  19. package/dist/logger/index.d.ts +19 -0
  20. package/dist/logger/index.js +89 -0
  21. package/dist/logger/index.js.map +1 -0
  22. package/dist/pipeline/pipeline.d.ts +41 -0
  23. package/dist/pipeline/pipeline.js +64 -0
  24. package/dist/pipeline/pipeline.js.map +1 -0
  25. package/dist/pipeline/with-d1-transaction.d.ts +16 -0
  26. package/dist/pipeline/with-d1-transaction.js +17 -0
  27. package/dist/pipeline/with-d1-transaction.js.map +1 -0
  28. package/package.json +55 -16
  29. package/dist/index.js +0 -468
  30. package/dist/index.js.map +0 -1
  31. package/registry/common/api-client/files/README.md.template +0 -64
  32. package/registry/common/api-client/files/index.ts.template +0 -296
  33. package/registry/common/logger/files/README.md.template +0 -55
  34. package/registry/common/logger/files/index.ts.template +0 -194
  35. package/registry/react/api-action/files/README.md.template +0 -61
  36. package/registry/react/api-action/files/index.ts.template +0 -291
  37. package/registry/react/api-toast/files/README.md.template +0 -51
  38. package/registry/react/api-toast/files/index.ts.template +0 -169
  39. package/registry/server/pipeline/files/README.md.template +0 -205
  40. package/registry/server/pipeline/files/pipeline.ts.template +0 -134
  41. package/registry/server/pipeline/files/types.ts.template +0 -35
  42. package/registry/server/pipeline/files/with-d1-transaction.ts.template +0 -50
@@ -1,296 +0,0 @@
1
- /**
2
- * @fileoverview Universal API Client Factory for REST and Hono RPC.
3
- * Provides unified HTTP methods, automatic authorization token injection,
4
- * BigInt-safe serialization, and optional Hono RPC client instantiation.
5
- *
6
- * @example
7
- * ```typescript
8
- * import { createApiClient, createHonoClient } from "@/lib/api-client";
9
- *
10
- * // Example A: REST Client (React, Next.js, Astro, Node)
11
- * export const api = createApiClient({
12
- * baseUrl: "https://api.example.com",
13
- * getToken: () => localStorage.getItem("token"),
14
- * });
15
- *
16
- * const response = await api.get("/users");
17
- * const data = await response.json();
18
- *
19
- * // Example B: Hono RPC Client with typed routes
20
- * import type { AppType } from "api";
21
- * export const rpc = createHonoClient<AppType>({
22
- * baseUrl: "http://localhost:8787",
23
- * });
24
- * const res = await rpc.v1.products.$get();
25
- * ```
26
- */
27
-
28
- import { hc } from "hono/client";
29
- import type { Hono } from "hono";
30
-
31
- /**
32
- * Configuration options for the API client.
33
- */
34
- export interface ApiClientConfig {
35
- /**
36
- * Base URL for API requests.
37
- * Defaults to empty string in browser (relative to current origin) or "http://localhost:8787" in development.
38
- */
39
- baseUrl?: string;
40
- /**
41
- * Static or dynamic headers to attach to every request.
42
- */
43
- headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
44
- /**
45
- * Callback to retrieve the authentication token.
46
- * If provided and returns a valid string, an `Authorization: Bearer <token>` header is automatically attached.
47
- */
48
- getToken?: () => string | null | undefined | Promise<string | null | undefined>;
49
- /**
50
- * Storage key name used for default token management in browser localStorage.
51
- * Defaults to "auth_token".
52
- */
53
- tokenStorageKey?: string;
54
- /**
55
- * Custom fetch implementation (e.g. for testing, SSR or Cloudflare Service Bindings).
56
- */
57
- fetch?: typeof fetch;
58
- }
59
-
60
- /**
61
- * Universal REST API client interface.
62
- */
63
- export interface RestApiClient {
64
- /** Performs a raw fetch request prepending the base URL and injecting auth headers */
65
- fetch: (path: string, init?: RequestInit) => Promise<Response>;
66
- /** Performs a GET request */
67
- get: (path: string, init?: RequestInit) => Promise<Response>;
68
- /** Performs a POST request with automatic JSON body serialization */
69
- post: (path: string, body?: unknown, init?: RequestInit) => Promise<Response>;
70
- /** Performs a PUT request with automatic JSON body serialization */
71
- put: (path: string, body?: unknown, init?: RequestInit) => Promise<Response>;
72
- /** Performs a PATCH request with automatic JSON body serialization */
73
- patch: (path: string, body?: unknown, init?: RequestInit) => Promise<Response>;
74
- /** Performs a DELETE request */
75
- delete: (path: string, init?: RequestInit) => Promise<Response>;
76
- }
77
-
78
- /**
79
- * Retrieves the stored authentication token from localStorage if running in browser.
80
- *
81
- * @param key - The localStorage key name (default: "auth_token").
82
- * @returns The token string if found, or null otherwise.
83
- */
84
- export function getStoredToken(key = "auth_token"): string | null {
85
- if (typeof window === "undefined" || !window.localStorage) {
86
- return null;
87
- }
88
- return localStorage.getItem(key);
89
- }
90
-
91
- /**
92
- * Saves the authentication token in localStorage if running in browser.
93
- *
94
- * @param token - The token string to persist.
95
- * @param key - The localStorage key name (default: "auth_token").
96
- */
97
- export function setStoredToken(token: string, key = "auth_token"): void {
98
- if (typeof window === "undefined" || !window.localStorage) {
99
- return;
100
- }
101
- localStorage.setItem(key, token);
102
- }
103
-
104
- /**
105
- * Removes the stored authentication token from localStorage if running in browser.
106
- *
107
- * @param key - The localStorage key name (default: "auth_token").
108
- */
109
- export function removeStoredToken(key = "auth_token"): void {
110
- if (typeof window === "undefined" || !window.localStorage) {
111
- return;
112
- }
113
- localStorage.removeItem(key);
114
- }
115
-
116
- /**
117
- * Resolves request headers merging base headers, custom headers, and dynamic auth token.
118
- */
119
- async function resolveHeaders(
120
- config: ApiClientConfig,
121
- customHeaders?: HeadersInit,
122
- ): Promise<Headers> {
123
- const headers = new Headers(customHeaders);
124
-
125
- // 1. Resolve base config headers
126
- if (config.headers) {
127
- const baseHeaders =
128
- typeof config.headers === "function"
129
- ? await config.headers()
130
- : config.headers;
131
-
132
- for (const [key, value] of Object.entries(baseHeaders)) {
133
- if (!headers.has(key)) {
134
- headers.set(key, value);
135
- }
136
- }
137
- }
138
-
139
- // 2. Resolve Auth Token if not explicitly provided in custom headers
140
- if (!headers.has("Authorization")) {
141
- let token: string | null | undefined = null;
142
-
143
- if (config.getToken) {
144
- token = await config.getToken();
145
- } else {
146
- const storageKey = config.tokenStorageKey || "auth_token";
147
- token = getStoredToken(storageKey);
148
- }
149
-
150
- if (token) {
151
- headers.set("Authorization", `Bearer ${token}`);
152
- }
153
- }
154
-
155
- return headers;
156
- }
157
-
158
- /**
159
- * Resolves the full target URL from relative path and base URL.
160
- */
161
- function resolveUrl(baseUrl: string | undefined, path: string): string {
162
- if (path.startsWith("http://") || path.startsWith("https://")) {
163
- return path;
164
- }
165
-
166
- const base = baseUrl || "";
167
- const cleanBase = base.replace(/\/+$/, "");
168
- const cleanPath = path.replace(/^\/+/, "");
169
-
170
- if (!cleanBase) {
171
- return `/${cleanPath}`;
172
- }
173
-
174
- return `${cleanBase}/${cleanPath}`;
175
- }
176
-
177
- /**
178
- * Serializes payload safely with BigInt support.
179
- */
180
- function serializeBody(body: unknown): string | undefined {
181
- if (body === undefined || body === null) {
182
- return undefined;
183
- }
184
- if (typeof body === "string") {
185
- return body;
186
- }
187
- if (body instanceof FormData || body instanceof URLSearchParams || body instanceof Blob) {
188
- return body as unknown as string;
189
- }
190
-
191
- return JSON.stringify(body, (_key, value) =>
192
- typeof value === "bigint" ? Number(value) : value,
193
- );
194
- }
195
-
196
- /**
197
- * Factory function to create a universal REST API client with automatic token injection.
198
- *
199
- * @example
200
- * ```typescript
201
- * import { createApiClient } from "@/lib/api-client";
202
- *
203
- * export const api = createApiClient({
204
- * baseUrl: "https://api.myapp.com/v1",
205
- * tokenStorageKey: "app_token",
206
- * });
207
- *
208
- * // Performs GET https://api.myapp.com/v1/customers with Bearer token
209
- * const response = await api.get("/customers");
210
- * ```
211
- *
212
- * @param config - Client configuration settings.
213
- * @returns Instantiated RestApiClient object.
214
- */
215
- export function createApiClient(config: ApiClientConfig = {}): RestApiClient {
216
- const fetchFn = config.fetch || fetch;
217
-
218
- const request = async (path: string, init: RequestInit = {}): Promise<Response> => {
219
- const fullUrl = resolveUrl(config.baseUrl, path);
220
- const headers = await resolveHeaders(config, init.headers);
221
-
222
- const isPayload = init.body !== undefined && init.body !== null;
223
- const isFormData = init.body instanceof FormData;
224
-
225
- if (isPayload && !isFormData && !headers.has("Content-Type")) {
226
- headers.set("Content-Type", "application/json");
227
- }
228
-
229
- return fetchFn(fullUrl, {
230
- ...init,
231
- headers,
232
- });
233
- };
234
-
235
- return {
236
- fetch: request,
237
- get: (path, init) => request(path, { ...init, method: "GET" }),
238
- post: (path, body, init) =>
239
- request(path, {
240
- ...init,
241
- method: "POST",
242
- body: serializeBody(body),
243
- }),
244
- put: (path, body, init) =>
245
- request(path, {
246
- ...init,
247
- method: "PUT",
248
- body: serializeBody(body),
249
- }),
250
- patch: (path, body, init) =>
251
- request(path, {
252
- ...init,
253
- method: "PATCH",
254
- body: serializeBody(body),
255
- }),
256
- delete: (path, init) => request(path, { ...init, method: "DELETE" }),
257
- };
258
- }
259
-
260
- /**
261
- * Factory function to instantiate a strongly-typed Hono RPC client (`hc<TRouter>`) with auth injection.
262
- *
263
- * @template TRouter - Hono router or application type (e.g. `AppType`).
264
- * @example
265
- * ```typescript
266
- * import { createHonoClient } from "@/lib/api-client";
267
- * import type { AppType } from "api";
268
- *
269
- * export const api = createHonoClient<AppType>({
270
- * baseUrl: "http://localhost:8787",
271
- * });
272
- *
273
- * // Fully typed autocomplete on backend routes
274
- * const res = await api.v1.sales.$post({ json: saleData });
275
- * ```
276
- *
277
- * @param config - Client configuration options.
278
- * @returns Instantiated typed Hono RPC client.
279
- */
280
- export function createHonoClient<TRouter extends Hono<any, any, any>>(
281
- config: ApiClientConfig = {},
282
- ): ReturnType<typeof hc<TRouter>> {
283
- const baseUrl = config.baseUrl || "http://localhost:8787";
284
-
285
- return hc<TRouter>(baseUrl, {
286
- headers: async () => {
287
- const headers = await resolveHeaders(config);
288
- const record: Record<string, string> = {};
289
- headers.forEach((val, key) => {
290
- record[key] = val;
291
- });
292
- return record;
293
- },
294
- fetch: config.fetch,
295
- });
296
- }
@@ -1,55 +0,0 @@
1
- # 🪵 Structured Logger (`src/lib/logger`)
2
-
3
- > **Universal, zero-dependency structured logger for Node.js, Cloudflare Workers, Next.js, and Browsers.**
4
- > Human-readable ANSI color-coded formatting in development; structured JSON in production and edge runtimes.
5
-
6
- ---
7
-
8
- ## 📖 How to Use
9
-
10
- ```typescript
11
- import { Logger } from "@/lib/logger";
12
-
13
- // 1. Create a logger instance for your service or domain
14
- const logger = new Logger("AuthService");
15
-
16
- // 2. Log informational events with metadata
17
- logger.info("User registered successfully", {
18
- file: "auth.service.ts",
19
- line: 42,
20
- userId: "usr_123",
21
- });
22
-
23
- // 3. Log warnings for non-fatal business flow anomalies
24
- logger.warn("Rate limit threshold reached", { ip: "192.168.1.1" });
25
-
26
- // 4. Log critical errors with caught exceptions
27
- try {
28
- await db.insert(user);
29
- } catch (error) {
30
- logger.error("Failed to persist user", { file: "auth.service.ts", line: 55 }, error);
31
- }
32
- ```
33
-
34
- ---
35
-
36
- ## 📥 Inputs & Outputs
37
-
38
- ### Constructor: `new Logger(serviceName: string)`
39
- - **`serviceName`**: Identifies the module or domain in log outputs (e.g. `"API:Auth"`, `"POS:Checkout"`).
40
-
41
- ### Methods: `logger.debug`, `logger.info`, `logger.warn`, `logger.error`
42
- - **`message`** (`string`): Main description of the event.
43
- - **`context`** (`LogContext`, optional): Key-value metadata object (e.g. `{ file, line, customerId }`).
44
- - **`...args`** (`unknown[]`, optional): Extra parameters, raw objects, or caught `Error` instances.
45
- - **Return Value**: `void`.
46
-
47
- ---
48
-
49
- ## ⚠️ Possible Errors & Troubleshooting
50
-
51
- | Issue / Error | Cause | Solution |
52
- | :--- | :--- | :--- |
53
- | **`Cannot find name 'process'` (TS2580)** | Outdated logger templates referencing raw `process`. | GroovePack's logger uses safe `globalThis` detection; ensure your template is up-to-date. |
54
- | **Logs printed as raw JSON during local development** | `NODE_ENV` is not set to `"development"` or `"test"`. | Ensure your dev script sets `NODE_ENV=development` or relies on default local runner flags. |
55
- | **Circular reference in log context (`TypeError: Converting circular structure to JSON`)** | Passing a DOM node, active socket, or recursive object in `context` or `args`. | Pass plain serializable DTOs or extract specific properties before passing to the logger. |
@@ -1,194 +0,0 @@
1
- /**
2
- * @fileoverview Universal Structured Logger for Groovepack.
3
- * Provides ANSI color formatting for development and structured JSON for production / Cloudflare Workers.
4
- *
5
- * @example
6
- * ```typescript
7
- * import { Logger } from "@/lib/logger";
8
- *
9
- * // 1. Create a logger instance for your service or domain
10
- * const logger = new Logger("AuthService");
11
- *
12
- * // 2. Log informational messages
13
- * logger.info("User registered successfully", { userId: "usr_123", email: "user@example.com" });
14
- *
15
- * // 3. Log errors with caught exceptions and context
16
- * try {
17
- * await db.insert(user);
18
- * } catch (error) {
19
- * logger.error("Failed to insert user into database", { file: "auth.service.ts", line: 45 }, error);
20
- * }
21
- * ```
22
- */
23
-
24
- export type LogLevel = "debug" | "info" | "warn" | "error";
25
-
26
- /**
27
- * Context interface for logging metadata.
28
- * Allows tracking the origin of the log like file name, line number, or custom business properties.
29
- */
30
- export interface LogContext {
31
- /** The filename where the log was triggered */
32
- file?: string;
33
- /** The line number in the source file */
34
- line?: number;
35
- /** Any other dynamic contextual properties */
36
- [key: string]: unknown;
37
- }
38
-
39
- /**
40
- * Standard structured logger designed to run across multiple environments:
41
- * - Local development (`NODE_ENV === "development"` or `"test"`): Prints readable, ANSI-colored formatted console logs.
42
- * - Production / Cloudflare Workers: Outputs structured JSON for automated log indexing and search.
43
- *
44
- * @example
45
- * ```typescript
46
- * import { Logger } from "@/lib/logger";
47
- *
48
- * const logger = new Logger("PaymentModule");
49
- *
50
- * logger.info("Processing checkout", { orderId: 456, amount: 2500 });
51
- * logger.warn("Low inventory detected", { productId: "prod_789", remaining: 2 });
52
- * logger.error("Payment gateway timeout", { gateway: "mercadopago" }, new Error("Timeout"));
53
- * ```
54
- */
55
- export class Logger {
56
- private serviceName: string;
57
-
58
- /**
59
- * Initializes a new Logger instance.
60
- * @param serviceName - The name of the application service or module (e.g. "API:Auth", "Web:ServerAction").
61
- */
62
- constructor(serviceName: string) {
63
- this.serviceName = serviceName;
64
- }
65
-
66
- /**
67
- * Evaluates if the current execution is running in development mode.
68
- * Safe across Node.js, Cloudflare Workers, Edge runtimes, and browsers
69
- * without requiring @types/node in the consumer project.
70
- * @returns true if running in development or testing, false otherwise.
71
- */
72
- private checkIsDev(): boolean {
73
- const globalEnv = (
74
- globalThis as unknown as {
75
- process?: {
76
- env?: Record<string, string | undefined>;
77
- };
78
- }
79
- ).process?.env;
80
-
81
- if (globalEnv?.NODE_ENV) {
82
- return (
83
- globalEnv.NODE_ENV === "development" ||
84
- globalEnv.NODE_ENV === "test"
85
- );
86
- }
87
-
88
- return true; // Fallback to dev if we can't determine
89
- }
90
-
91
- /**
92
- * Internal formatting and logging dispatcher.
93
- * Prints color logs to stdout in dev, and stringifies structured JSON in prod.
94
- * @param level - Severity level of the log.
95
- * @param message - Main descriptive message of the event.
96
- * @param context - Additional structured metadata.
97
- * @param args - Extra raw parameters or caught errors to include.
98
- */
99
- private log(
100
- level: LogLevel,
101
- message: string,
102
- context?: LogContext,
103
- ...args: unknown[]
104
- ): void {
105
- const isDev = this.checkIsDev();
106
- const timestamp = new Date().toISOString();
107
-
108
- if (isDev) {
109
- // ANSI colors for readable terminal formatting in development
110
- const colors = {
111
- debug: "\x1b[36m", // Cyan
112
- info: "\x1b[32m", // Green
113
- warn: "\x1b[33m", // Yellow
114
- error: "\x1b[31m", // Red
115
- };
116
- const reset = "\x1b[0m";
117
- const color = colors[level] || reset;
118
-
119
- // Format contextual properties like [filename.ts:line] if provided
120
- const contextStr = context
121
- ? ` [${context.file || ""}${context.line ? `:${context.line}` : ""}]`
122
- : "";
123
-
124
- console.log(
125
- `${color}[${timestamp}] [${level.toUpperCase()}] [${this.serviceName}]${contextStr}:${reset} ${message}`,
126
- context ? { ...context } : "",
127
- ...args,
128
- );
129
- return;
130
- }
131
-
132
- // Structured JSON logging for production (Cloudflare Workers logs)
133
- const logData = {
134
- timestamp,
135
- level,
136
- serviceName: this.serviceName,
137
- message,
138
- context,
139
- details: args.length > 0 ? args : undefined,
140
- };
141
-
142
- if (level === "error") {
143
- console.error(JSON.stringify(logData));
144
- return;
145
- }
146
-
147
- if (level === "warn") {
148
- console.warn(JSON.stringify(logData));
149
- return;
150
- }
151
-
152
- console.log(JSON.stringify(logData));
153
- }
154
-
155
- /**
156
- * Logs events at the 'debug' level for local tracing.
157
- * @param message - Main event description.
158
- * @param context - Optional key-value metadata to append.
159
- * @param args - Additional parameters or error trace object.
160
- */
161
- debug(message: string, context?: LogContext, ...args: unknown[]): void {
162
- this.log("debug", message, context, ...args);
163
- }
164
-
165
- /**
166
- * Logs events at the 'info' level.
167
- * @param message - Main event description.
168
- * @param context - Optional key-value metadata to append.
169
- * @param args - Additional parameters or error trace object.
170
- */
171
- info(message: string, context?: LogContext, ...args: unknown[]): void {
172
- this.log("info", message, context, ...args);
173
- }
174
-
175
- /**
176
- * Logs warnings about unexpected business flow issues or schema validation errors.
177
- * @param message - Main event description.
178
- * @param context - Optional key-value metadata to append.
179
- * @param args - Additional parameters or error trace object.
180
- */
181
- warn(message: string, context?: LogContext, ...args: unknown[]): void {
182
- this.log("warn", message, context, ...args);
183
- }
184
-
185
- /**
186
- * Logs critical errors, server crashes, or API connection issues.
187
- * @param message - Main event description.
188
- * @param context - Optional key-value metadata to append.
189
- * @param args - Additional parameters or error trace object.
190
- */
191
- error(message: string, context?: LogContext, ...args: unknown[]): void {
192
- this.log("error", message, context, ...args);
193
- }
194
- }
@@ -1,61 +0,0 @@
1
- # ⚡ API Action Wrapper (`src/lib/api-action`)
2
-
3
- > **Universal React action wrapper for Server Actions, React hooks, and mutations with strict error-only logging.**
4
-
5
- ---
6
-
7
- ## 📖 How to Use
8
-
9
- ```typescript
10
- import { apiAction } from "@/lib/api-action";
11
- import { api } from "@/lib/api-client";
12
-
13
- // Wrapping a REST call
14
- export async function getCustomersAction() {
15
- return apiAction<Customer[]>({
16
- actionName: "getCustomers",
17
- apiCall: () => api.get("/customers"),
18
- onSuccess: (customers) => {
19
- console.log(`Loaded ${customers.length} customers`);
20
- },
21
- });
22
- }
23
-
24
- // Handling in a React component
25
- const res = await getCustomersAction();
26
- if (res.success) {
27
- console.log("Data:", res.data);
28
- } else {
29
- console.error("Error:", res.error);
30
- }
31
- ```
32
-
33
- ---
34
-
35
- ## 📥 Inputs & Outputs
36
-
37
- ### Parameters: `ApiActionOptions<T>`
38
- - **`actionName`** (`string`, required): Contextual identifier used for targeted error logging.
39
- - **`apiCall`** (`() => Promise<ApiCallResult<T>>`, required): Async function returning a Fetch `Response`, Hono RPC response, or `ActionResponse<T>`.
40
- - **`onSuccess`** (`(data: T) => void | Promise<void>`, optional): Callback executed exclusively on successful operations.
41
- - **`logger`** (`ErrorLogger`, optional): Custom logger implementing `.error()`. Defaults to ANSI colored console error.
42
-
43
- ### Return Value: `Promise<ActionResponse<T>>`
44
- ```typescript
45
- interface ActionResponse<T> {
46
- success: boolean;
47
- data?: T;
48
- message?: string | unknown;
49
- error?: string;
50
- }
51
- ```
52
-
53
- ---
54
-
55
- ## ⚠️ Possible Errors & Troubleshooting
56
-
57
- | Issue / Error | Cause | Solution |
58
- | :--- | :--- | :--- |
59
- | **`success: false` on HTTP 200** | Backend responded with a JSON body having `{ success: false }`. | `apiAction` automatically extracts business error messages from backend responses. |
60
- | **No logs appearing in console on success** | By design: `apiAction` follows the **Error-Only Logging** rule. | Normal successful requests do not pollute client or server logs. Only HTTP != 2xx or crashes are logged. |
61
- | **Type `T` not matching response payload** | Discrepancy between TypeScript generic and API JSON structure. | Verify your backend return type or inspect the raw response shape. |