@c-rex/core 0.1.21 → 0.1.23

package/dist/requests.d.mts

@@ -1,3 +1,6 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { JWTPayload } from 'jose';
+
 /**
  * HTTP methods supported by the API client.
  */
@@ -6,6 +9,62 @@ type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTION
  * Type for query parameter values - supports primitives and arrays.
  */
 type ParamValue = string | number | boolean | undefined | (string | number | boolean)[];
+/**
+ * Cache constants below represent two distinct layers:
+ * - internal cache tags (`CREX_*_TAG`) used by Next.js tag-based revalidation
+ * - external cache segments (`CREX_CACHE_SEGMENT_*`) used by admin/API invalidation endpoints
+ */
+declare const CREX_API_CACHE_TAG = "crex-api";
+declare const CREX_API_CACHE_VCARD_TAG = "crex-api:vcard";
+declare const CREX_READMODEL_CACHE_TAG = "crex-readmodel";
+declare const CREX_READMODEL_CACHE_VCARD_TAG = "crex-readmodel:vcard";
+declare const CREX_READMODEL_CACHE_METADATA_TAG = "crex-readmodel:metadata";
+declare const CREX_READMODEL_CACHE_ORGANIZATION_TAG = "crex-readmodel:organization";
+declare const CREX_READMODEL_CACHE_INFORMATION_SUBJECTS_TAG = "crex-readmodel:information-subjects";
+declare const CREX_READMODEL_CACHE_DOCUMENT_TYPES_TAG = "crex-readmodel:document-types";
+declare const CREX_READMODEL_CACHE_COMPONENTS_TAG = "crex-readmodel:components";
+declare const CREX_READMODEL_CACHE_PARTIES_TAG = "crex-readmodel:parties";
+declare const CREX_CACHE_SEGMENT_ALL = "all";
+declare const CREX_CACHE_SEGMENT_METADATA = "metadata";
+declare const CREX_CACHE_SEGMENT_VCARD = "vcard";
+declare const CREX_CACHE_SEGMENT_REQUESTS = "requests";
+/**
+ * External cache segment names used by admin/API invalidation endpoints.
+ * Segments are user-facing buckets; tags are internal cache keys used by Next.js revalidation.
+ */
+type CrexCacheSegment = typeof CREX_CACHE_SEGMENT_ALL | typeof CREX_CACHE_SEGMENT_METADATA | typeof CREX_CACHE_SEGMENT_VCARD | typeof CREX_CACHE_SEGMENT_REQUESTS;
+/**
+ * Segment-to-tag mapping for cache invalidation.
+ *
+ * Why both levels exist:
+ * - Segment (`metadata`, `vcard`, ...) is the coarse external API contract.
+ * - Tag (`crex-readmodel:metadata`, ...) is the internal revalidation key.
+ */
+declare const CREX_CACHE_SEGMENT_TO_TAGS: Record<CrexCacheSegment, string[]>;
+/**
+ * Resolves effective cache tags for the requested external segments.
+ * Unknown segment strings are ignored.
+ */
+declare const resolveCacheTagsForSegments: (segments: string[]) => string[];
+/**
+ * Returns the canonical list of supported external cache segments.
+ */
+declare const getSupportedCacheSegments: () => CrexCacheSegment[];
+declare class CacheClearAuthUnauthorizedError extends Error {
+    constructor(message: string);
+}
+declare class CacheClearAuthConfigurationError extends Error {
+    constructor(message: string);
+}
+declare const verifyCacheClearBearerToken: (token: string) => Promise<JWTPayload>;
+declare const extractScopesFromJwtPayload: (payload: Record<string, unknown> | JWTPayload | null) => string[];
+declare const handleCacheClearPostRequest: (req: NextRequest) => Promise<NextResponse>;
+/**
+ * Clears process-local request caches.
+ * Used by explicit cache invalidation endpoints so short-lived in-memory caches
+ * do not serve stale results right after tag revalidation.
+ */
+declare const clearProcessLocalRequestCaches: () => void;
 /**
  * Interface for API call parameters.
  */
@@ -15,6 +74,8 @@ interface CallParams {
     body?: any;
     headers?: Record<string, string>;
     params?: Record<string, ParamValue>;
+    skipCookieTokenLookup?: boolean;
+    authToken?: string;
 }
 /**
  * API client class for the CREX application.
@@ -24,6 +85,8 @@ declare class CrexApi {
     private customerConfig;
     private baseUrl;
     private logger;
+    private debugTiming;
+    private resolveLogCategory;
     /**
      * Initializes the API client if it hasn't been initialized yet.
      * Loads customer configuration and initializes the logger.
@@ -41,6 +104,7 @@ declare class CrexApi {
      * @returns The full URL with query string
      */
     private buildUrl;
+    private getApiRootUrl;
     /**
      * Executes an API request with caching, authentication, and retry logic.
      *
@@ -53,7 +117,7 @@ declare class CrexApi {
      * @returns The response data
      * @throws Error if the request fails after maximum retries
      */
-    execute<T>({ url, method, params, body, headers, }: CallParams): Promise<T>;
+    execute<T>({ url, method, params, body, headers, skipCookieTokenLookup, authToken, }: CallParams): Promise<T>;
 }
 
-export { CrexApi };
+export { CREX_API_CACHE_TAG, CREX_API_CACHE_VCARD_TAG, CREX_CACHE_SEGMENT_ALL, CREX_CACHE_SEGMENT_METADATA, CREX_CACHE_SEGMENT_REQUESTS, CREX_CACHE_SEGMENT_TO_TAGS, CREX_CACHE_SEGMENT_VCARD, CREX_READMODEL_CACHE_COMPONENTS_TAG, CREX_READMODEL_CACHE_DOCUMENT_TYPES_TAG, CREX_READMODEL_CACHE_INFORMATION_SUBJECTS_TAG, CREX_READMODEL_CACHE_METADATA_TAG, CREX_READMODEL_CACHE_ORGANIZATION_TAG, CREX_READMODEL_CACHE_PARTIES_TAG, CREX_READMODEL_CACHE_TAG, CREX_READMODEL_CACHE_VCARD_TAG, CacheClearAuthConfigurationError, CacheClearAuthUnauthorizedError, CrexApi, type CrexCacheSegment, clearProcessLocalRequestCaches, extractScopesFromJwtPayload, getSupportedCacheSegments, handleCacheClearPostRequest, resolveCacheTagsForSegments, verifyCacheClearBearerToken };

package/dist/requests.d.ts

@@ -1,3 +1,6 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { JWTPayload } from 'jose';
+
 /**
  * HTTP methods supported by the API client.
  */
@@ -6,6 +9,62 @@ type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTION
  * Type for query parameter values - supports primitives and arrays.
  */
 type ParamValue = string | number | boolean | undefined | (string | number | boolean)[];
+/**
+ * Cache constants below represent two distinct layers:
+ * - internal cache tags (`CREX_*_TAG`) used by Next.js tag-based revalidation
+ * - external cache segments (`CREX_CACHE_SEGMENT_*`) used by admin/API invalidation endpoints
+ */
+declare const CREX_API_CACHE_TAG = "crex-api";
+declare const CREX_API_CACHE_VCARD_TAG = "crex-api:vcard";
+declare const CREX_READMODEL_CACHE_TAG = "crex-readmodel";
+declare const CREX_READMODEL_CACHE_VCARD_TAG = "crex-readmodel:vcard";
+declare const CREX_READMODEL_CACHE_METADATA_TAG = "crex-readmodel:metadata";
+declare const CREX_READMODEL_CACHE_ORGANIZATION_TAG = "crex-readmodel:organization";
+declare const CREX_READMODEL_CACHE_INFORMATION_SUBJECTS_TAG = "crex-readmodel:information-subjects";
+declare const CREX_READMODEL_CACHE_DOCUMENT_TYPES_TAG = "crex-readmodel:document-types";
+declare const CREX_READMODEL_CACHE_COMPONENTS_TAG = "crex-readmodel:components";
+declare const CREX_READMODEL_CACHE_PARTIES_TAG = "crex-readmodel:parties";
+declare const CREX_CACHE_SEGMENT_ALL = "all";
+declare const CREX_CACHE_SEGMENT_METADATA = "metadata";
+declare const CREX_CACHE_SEGMENT_VCARD = "vcard";
+declare const CREX_CACHE_SEGMENT_REQUESTS = "requests";
+/**
+ * External cache segment names used by admin/API invalidation endpoints.
+ * Segments are user-facing buckets; tags are internal cache keys used by Next.js revalidation.
+ */
+type CrexCacheSegment = typeof CREX_CACHE_SEGMENT_ALL | typeof CREX_CACHE_SEGMENT_METADATA | typeof CREX_CACHE_SEGMENT_VCARD | typeof CREX_CACHE_SEGMENT_REQUESTS;
+/**
+ * Segment-to-tag mapping for cache invalidation.
+ *
+ * Why both levels exist:
+ * - Segment (`metadata`, `vcard`, ...) is the coarse external API contract.
+ * - Tag (`crex-readmodel:metadata`, ...) is the internal revalidation key.
+ */
+declare const CREX_CACHE_SEGMENT_TO_TAGS: Record<CrexCacheSegment, string[]>;
+/**
+ * Resolves effective cache tags for the requested external segments.
+ * Unknown segment strings are ignored.
+ */
+declare const resolveCacheTagsForSegments: (segments: string[]) => string[];
+/**
+ * Returns the canonical list of supported external cache segments.
+ */
+declare const getSupportedCacheSegments: () => CrexCacheSegment[];
+declare class CacheClearAuthUnauthorizedError extends Error {
+    constructor(message: string);
+}
+declare class CacheClearAuthConfigurationError extends Error {
+    constructor(message: string);
+}
+declare const verifyCacheClearBearerToken: (token: string) => Promise<JWTPayload>;
+declare const extractScopesFromJwtPayload: (payload: Record<string, unknown> | JWTPayload | null) => string[];
+declare const handleCacheClearPostRequest: (req: NextRequest) => Promise<NextResponse>;
+/**
+ * Clears process-local request caches.
+ * Used by explicit cache invalidation endpoints so short-lived in-memory caches
+ * do not serve stale results right after tag revalidation.
+ */
+declare const clearProcessLocalRequestCaches: () => void;
 /**
  * Interface for API call parameters.
  */
@@ -15,6 +74,8 @@ interface CallParams {
     body?: any;
     headers?: Record<string, string>;
     params?: Record<string, ParamValue>;
+    skipCookieTokenLookup?: boolean;
+    authToken?: string;
 }
 /**
  * API client class for the CREX application.
@@ -24,6 +85,8 @@ declare class CrexApi {
     private customerConfig;
     private baseUrl;
     private logger;
+    private debugTiming;
+    private resolveLogCategory;
     /**
      * Initializes the API client if it hasn't been initialized yet.
      * Loads customer configuration and initializes the logger.
@@ -41,6 +104,7 @@ declare class CrexApi {
      * @returns The full URL with query string
      */
     private buildUrl;
+    private getApiRootUrl;
     /**
      * Executes an API request with caching, authentication, and retry logic.
      *
@@ -53,7 +117,7 @@ declare class CrexApi {
      * @returns The response data
      * @throws Error if the request fails after maximum retries
      */
-    execute<T>({ url, method, params, body, headers, }: CallParams): Promise<T>;
+    execute<T>({ url, method, params, body, headers, skipCookieTokenLookup, authToken, }: CallParams): Promise<T>;
 }
 
-export { CrexApi };
+export { CREX_API_CACHE_TAG, CREX_API_CACHE_VCARD_TAG, CREX_CACHE_SEGMENT_ALL, CREX_CACHE_SEGMENT_METADATA, CREX_CACHE_SEGMENT_REQUESTS, CREX_CACHE_SEGMENT_TO_TAGS, CREX_CACHE_SEGMENT_VCARD, CREX_READMODEL_CACHE_COMPONENTS_TAG, CREX_READMODEL_CACHE_DOCUMENT_TYPES_TAG, CREX_READMODEL_CACHE_INFORMATION_SUBJECTS_TAG, CREX_READMODEL_CACHE_METADATA_TAG, CREX_READMODEL_CACHE_ORGANIZATION_TAG, CREX_READMODEL_CACHE_PARTIES_TAG, CREX_READMODEL_CACHE_TAG, CREX_READMODEL_CACHE_VCARD_TAG, CacheClearAuthConfigurationError, CacheClearAuthUnauthorizedError, CrexApi, type CrexCacheSegment, clearProcessLocalRequestCaches, extractScopesFromJwtPayload, getSupportedCacheSegments, handleCacheClearPostRequest, resolveCacheTagsForSegments, verifyCacheClearBearerToken };