@se-studio/contentful-rest-api 1.12.0 → 1.13.0

package/dist/telemetry/queryContext.d.ts

@@ -0,0 +1,7 @@
+export interface CmsQueryContext {
+    operation: string;
+    identifier?: string;
+}
+export declare function withCmsQueryContext<T>(context: CmsQueryContext, fn: () => T): T;
+export declare function getCmsQueryContext(): CmsQueryContext | undefined;
+//# sourceMappingURL=queryContext.d.ts.map

package/dist/telemetry/queryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryContext.d.ts","sourceRoot":"","sources":["../../src/telemetry/queryContext.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE/E;AAED,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE"}

package/dist/telemetry/queryContext.js

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function withCmsQueryContext(context, fn) {
+    return storage.run(context, fn);
+}
+export function getCmsQueryContext() {
+    return storage.getStore();
+}
+//# sourceMappingURL=queryContext.js.map

package/dist/telemetry/queryContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryContext.js","sourceRoot":"","sources":["../../src/telemetry/queryContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAmB,CAAC;AAEzD,MAAM,UAAU,mBAAmB,CAAI,OAAwB,EAAE,EAAW;IAC1E,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/telemetry/queryLog.d.ts

@@ -0,0 +1,17 @@
+export interface CmsQueryLogEntry {
+    url: string;
+    operation: string;
+    identifier?: string;
+    bytes: number;
+    ms: number;
+}
+export declare function isCmsQueryLoggingEnabled(): boolean;
+/** Format byte count as a compact human-readable size (e.g. 23.5k, 1.2M). */
+export declare function formatPayloadSize(bytes: number): string;
+export declare function logCmsQuery(entry: Omit<CmsQueryLogEntry, 'operation' | 'identifier'> & Partial<Pick<CmsQueryLogEntry, 'operation' | 'identifier'>>): void;
+/** Read response body bytes and return text for JSON parsing. */
+export declare function readResponseBodyWithSize(response: Response): Promise<{
+    bytes: number;
+    text: string;
+}>;
+//# sourceMappingURL=queryLog.d.ts.map

package/dist/telemetry/queryLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLog.d.ts","sourceRoot":"","sources":["../../src/telemetry/queryLog.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC,GAC5D,IAAI,CAuBN;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAc1C"}

package/dist/telemetry/queryLog.js

@@ -0,0 +1,54 @@
+import { deriveOperationFromUrl } from './deriveOperation.js';
+import { getCmsQueryContext } from './queryContext.js';
+export function isCmsQueryLoggingEnabled() {
+    return process.env.LOG_CMS_QUERIES === '1';
+}
+/** Format byte count as a compact human-readable size (e.g. 23.5k, 1.2M). */
+export function formatPayloadSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}`;
+    if (bytes < 1024 * 1024) {
+        const kb = bytes / 1024;
+        return kb >= 100 ? `${Math.round(kb)}k` : `${kb.toFixed(1)}k`;
+    }
+    const mb = bytes / (1024 * 1024);
+    return mb >= 100 ? `${Math.round(mb)}M` : `${mb.toFixed(1)}M`;
+}
+export function logCmsQuery(entry) {
+    if (!isCmsQueryLoggingEnabled())
+        return;
+    const context = getCmsQueryContext();
+    const derived = deriveOperationFromUrl(entry.url);
+    const payload = {
+        url: entry.url,
+        operation: entry.operation ?? context?.operation ?? derived.operation,
+        ...(entry.identifier !== undefined
+            ? entry.identifier
+                ? { identifier: entry.identifier }
+                : {}
+            : context?.identifier
+                ? { identifier: context.identifier }
+                : derived.identifier
+                    ? { identifier: derived.identifier }
+                    : {}),
+        bytes: entry.bytes,
+        ms: entry.ms,
+    };
+    console.log(`[CMS query] ${JSON.stringify(payload)}`);
+}
+/** Read response body bytes and return text for JSON parsing. */
+export async function readResponseBodyWithSize(response) {
+    const contentLength = response.headers.get('content-length');
+    if (contentLength) {
+        const parsed = Number.parseInt(contentLength, 10);
+        const text = await response.text();
+        return {
+            bytes: Number.isNaN(parsed) ? Buffer.byteLength(text, 'utf8') : parsed,
+            text,
+        };
+    }
+    const buffer = await response.arrayBuffer();
+    const text = new TextDecoder().decode(buffer);
+    return { bytes: buffer.byteLength, text };
+}
+//# sourceMappingURL=queryLog.js.map

package/dist/telemetry/queryLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLog.js","sourceRoot":"","sources":["../../src/telemetry/queryLog.ts"],"names":[],"mappings":"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"}

package/docs/llms.md

@@ -304,6 +304,30 @@ import {
 } from '@se-studio/contentful-rest-api';
 ```
 
+## Query logging (dev)
+
+Set `LOG_CMS_QUERIES=1` to emit structured per-fetch lines:
+
+```
+[CMS query] {"url":"...","operation":"Reading article","identifier":"my-slug","bytes":24064,"ms":45}
+```
+
+Merge with Next.js dev fetch cache lines (`(cache hit|miss)`) after the fact:
+
+```bash
+pnpm dev 2>&1 | tee dev.log
+pnpm --filter @se-studio/contentful-rest-api consolidate-cms-logs -- dev.log
+# => Reading article my-slug - 23.5k (cached) in 12ms
+```
+
+For reliable URL matching, enable full fetch URLs in the app's `next.config.js`:
+
+```js
+logging: { fetches: { fullUrl: true } }
+```
+
+Related: `LOG_CMS=1` (conversion warnings), `LOG_CMS_FETCH=1` (raw URLs only).
+
 ## Important Constraints
 
 - Always supply `spaceId`, `accessToken`, and `environment`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-rest-api",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Type-safe Contentful REST API client with caching and rate limiting for Next.js applications",
   "repository": {
     "type": "git",
@@ -78,7 +78,8 @@
     "dev": "tsc --project tsconfig.build.json --watch",
     "type-check": "tsc --noEmit",
     "lint": "biome lint .",
-    "test": "vitest run",
+    "test": "vitest run && node --test scripts/cms-query-log-consolidate.test.mjs",
+    "consolidate-cms-logs": "node scripts/consolidate-cms-query-logs.mjs",
     "clean": "rm -rf dist .turbo *.tsbuildinfo",
     "extract-single-page": "bash -c 'set -a && source ../../.env.local && set +a && tsx scripts/extract-page.ts \"$@\"' --",
     "extract-single-article": "bash -c 'set -a && source ../../.env.local && set +a && tsx scripts/extract-article.ts \"$@\"' --"