@contentful/optimization-api-client 0.1.0-alpha7 → 0.1.0-alpha9

package/dist/logger.d.ts

@@ -0,0 +1,287 @@
+/**
+ * A {@link LogSink} that writes log events to the browser or Node.js console,
+ * filtering by a configurable verbosity threshold.
+ *
+ * @example
+ * ```typescript
+ * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.addSink(new ConsoleLogSink('debug'))
+ * ```
+ *
+ * @public
+ */
+export declare class ConsoleLogSink extends LogSink {
+    /** Identifies this sink when registered with the {@link Logger}. */
+    name: string;
+    /**
+     * Minimum log level required for events to be output.
+     *
+     * @defaultValue 'error'
+     */
+    readonly verbosity: LogLevels;
+    /**
+     * Creates a new ConsoleLogSink.
+     *
+     * @param verbosity - Minimum log level to output.
+     */
+    constructor(verbosity?: LogLevels);
+    /**
+     * Writes a log event to the console if its level meets the verbosity threshold.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.
+ *
+ * @param location - The module or component identifier to prepend.
+ * @returns A {@link ScopedLogger} bound to the specified location.
+ *
+ * @example
+ * ```typescript
+ * import { createScopedLogger } from '@contentful/optimization-api-client/logger'
+ *
+ * const log = createScopedLogger('MyModule')
+ * log.info('Initialization complete')
+ * ```
+ *
+ * @public
+ */
+export declare function createScopedLogger(location: string): ScopedLogger;
+
+/**
+ * A log event emitted by the logger package.
+ *
+ * @public
+ */
+export declare interface LogEvent {
+    /** Logger scope name. */
+    name: string;
+    /** Event severity level. */
+    level: LogLevels;
+    /** Event payload, where the first entry is the formatted message. */
+    messages: unknown[];
+    /** Optional additional context attached by sinks or middleware. */
+    [other: string]: unknown;
+}
+
+/**
+ * Central logger that routes log events through registered {@link LogSink} instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.info('MyModule', 'Application started')
+ * ```
+ *
+ * @public
+ */
+declare class Logger {
+    /** The logger's identifier, used as the event scope name. */
+    readonly name = "@contentful/optimization";
+    private readonly PREFIX_PARTS;
+    private readonly DELIMITER;
+    private sinks;
+    private assembleLocationPrefix;
+    /**
+     * Registers a log sink. If a sink with the same name already exists, it is replaced.
+     *
+     * @param sink - The {@link LogSink} instance to register.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+     *
+     * logger.addSink(new ConsoleLogSink('debug'))
+     * ```
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a registered sink by name.
+     *
+     * @param name - The name of the sink to remove.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSink('ConsoleLogSink')
+     * ```
+     */
+    removeSink(name: string): void;
+    /**
+     * Removes all registered sinks.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSinks()
+     * ```
+     */
+    removeSinks(): void;
+    /**
+     * Logs a message at the debug level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.debug('MyModule', 'Debugging value', someVariable)
+     * ```
+     */
+    debug(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the info level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.info('MyModule', 'Operation completed')
+     * ```
+     */
+    info(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the log level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.log('MyModule', 'General log entry')
+     * ```
+     */
+    log(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the warn level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.warn('MyModule', 'Deprecated method called')
+     * ```
+     */
+    warn(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the error level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.error('MyModule', new Error('Something failed'))
+     * ```
+     */
+    error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    /**
+     * Logs a message at the fatal level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.fatal('MyModule', new Error('Unrecoverable failure'))
+     * ```
+     */
+    fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    private emit;
+    private onLogEvent;
+}
+export { Logger }
+export default Logger;
+
+/**
+ * Shared singleton {@link Logger} instance used across the SDK.
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * Supported log levels ordered from highest to lowest severity.
+ *
+ * @public
+ */
+export declare type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log';
+
+/**
+ * Numeric severity map used for log-level threshold comparisons.
+ *
+ * @public
+ */
+export declare const logLevelSeverity: Readonly<Record<LogLevels, number>>;
+
+/**
+ * Abstract base class for log sinks that receive and process log events.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomSink extends LogSink {
+ *   name = 'MyCustomSink'
+ *
+ *   ingest(event: LogEvent): void {
+ *     // process the event
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class LogSink {
+    /** Display name used to identify this sink for addition and removal. */
+    abstract name: string;
+    /**
+     * Processes an incoming log event.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    abstract ingest(event: LogEvent): void;
+}
+
+/**
+ * A location-scoped logger interface whose methods omit the `logLocation` parameter.
+ *
+ * @public
+ */
+export declare interface ScopedLogger {
+    /** Logs at debug level. */
+    debug: (message: string, ...args: unknown[]) => void;
+    /** Logs at info level. */
+    info: (message: string, ...args: unknown[]) => void;
+    /** Logs at log level. */
+    log: (message: string, ...args: unknown[]) => void;
+    /** Logs at warn level. */
+    warn: (message: string, ...args: unknown[]) => void;
+    /** Logs at error level. */
+    error: (message: string | Error, ...args: unknown[]) => void;
+    /** Logs at fatal level. */
+    fatal: (message: string | Error, ...args: unknown[]) => void;
+}
+
+export { }

package/dist/logger.mjs

@@ -0,0 +1 @@
+export { ConsoleLogSink, LogSink, Logger, createScopedLogger, default, logLevelSeverity, logger } from "./649.mjs";

package/package.json

@@ -1,16 +1,41 @@
 {
   "name": "@contentful/optimization-api-client",
-  "version": "0.1.0-alpha7",
+  "version": "0.1.0-alpha9",
   "license": "MIT",
-  "type": "commonjs",
+  "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./logger": {
+      "import": {
+        "types": "./dist/logger.d.mts",
+        "default": "./dist/logger.mjs"
+      },
+      "require": {
+        "types": "./dist/logger.d.cts",
+        "default": "./dist/logger.cjs"
+      }
+    },
+    "./api-schemas": {
+      "import": {
+        "types": "./dist/api-schemas.d.mts",
+        "default": "./dist/api-schemas.mjs"
+      },
+      "require": {
+        "types": "./dist/api-schemas.d.cts",
+        "default": "./dist/api-schemas.cjs"
+      }
     },
     "./package.json": "./package.json"
   },
@@ -18,10 +43,8 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "diary": "^0.4.5",
-    "es-toolkit": "^1.39.10",
-    "p-retry": "^6.2.1",
-    "zod": "^4.1.5",
-    "@contentful/optimization-api-schemas": "0.1.0-alpha7"
+    "es-toolkit": "^1.44.0",
+    "zod": "^4.3.6",
+    "@contentful/optimization-api-schemas": "0.1.0-alpha9"
   }
 }

package/dist/ApiClient.d.ts

@@ -1,74 +0,0 @@
-import type { ApiConfig, GlobalApiConfigProperties } from './ApiClientBase';
-import ExperienceApiClient, { type ExperienceApiClientConfig } from './experience';
-import InsightsApiClient, { type InsightsApiClientConfig } from './insights';
-/**
- * Configuration for the high-level {@link ApiClient}.
- *
- * @public
- */
-export interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfigProperties> {
-    /**
-     * Configuration for the personalization (Experience) API client.
-     *
-     * @remarks
-     * Any properties shared with {@link ApiConfig} are taken from the top-level
-     * config and overridden by this object when specified.
-     */
-    personalization?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
-    /**
-     * Configuration for the analytics (Insights) API client.
-     *
-     * @remarks
-     * Any properties shared with {@link ApiConfig} are taken from the top-level
-     * config and overridden by this object when specified.
-     */
-    analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
-}
-/**
- * Aggregated API client providing access to Experience and Insights APIs.
- *
- * @public
- *
- * @remarks
- * This client encapsulates shared configuration and exposes dedicated
- * sub-clients for personalization and analytics use cases.
- *
- * @example
- * ```ts
- * const client = new ApiClient({
- *   clientId: 'org-id',
- *   environment: 'main',
- *   preview: false,
- *   personalization: {
- *     // experience-specific overrides
- *   },
- *   analytics: {
- *     // insights-specific overrides
- *   },
- * })
- *
- * const profile = await client.experience.getProfile('profile-id')
- * const batch = await client.insights.upsertManyProfiles({ events: batchEvents })
- * ```
- */
-export default class ApiClient {
-    /**
-     * Shared configuration applied to both Experience and Insights clients.
-     */
-    readonly config: ApiConfig;
-    /**
-     * Client for personalization and experience-related operations.
-     */
-    readonly experience: ExperienceApiClient;
-    /**
-     * Client for analytics and insights-related operations.
-     */
-    readonly insights: InsightsApiClient;
-    /**
-     * Creates a new aggregated {@link ApiClient} instance.
-     *
-     * @param config - Global API client configuration with optional per-client overrides.
-     */
-    constructor(config: ApiClientConfig);
-}
-//# sourceMappingURL=ApiClient.d.ts.map

package/dist/ApiClient.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAC3E,OAAO,mBAAmB,EAAE,EAAE,KAAK,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAClF,OAAO,iBAAiB,EAAE,EAAE,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC;IACjF;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,yBAAyB,EAAE,yBAAyB,CAAC,CAAA;IAE5E;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAA;CACrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IAEpC;;;;OAIG;gBACS,MAAM,EAAE,eAAe;CAepC"}

package/dist/ApiClient.js

@@ -1,61 +0,0 @@
-import ExperienceApiClient from './experience';
-import InsightsApiClient from './insights';
-/**
- * Aggregated API client providing access to Experience and Insights APIs.
- *
- * @public
- *
- * @remarks
- * This client encapsulates shared configuration and exposes dedicated
- * sub-clients for personalization and analytics use cases.
- *
- * @example
- * ```ts
- * const client = new ApiClient({
- *   clientId: 'org-id',
- *   environment: 'main',
- *   preview: false,
- *   personalization: {
- *     // experience-specific overrides
- *   },
- *   analytics: {
- *     // insights-specific overrides
- *   },
- * })
- *
- * const profile = await client.experience.getProfile('profile-id')
- * const batch = await client.insights.upsertManyProfiles({ events: batchEvents })
- * ```
- */
-export default class ApiClient {
-    /**
-     * Shared configuration applied to both Experience and Insights clients.
-     */
-    config;
-    /**
-     * Client for personalization and experience-related operations.
-     */
-    experience;
-    /**
-     * Client for analytics and insights-related operations.
-     */
-    insights;
-    /**
-     * Creates a new aggregated {@link ApiClient} instance.
-     *
-     * @param config - Global API client configuration with optional per-client overrides.
-     */
-    constructor(config) {
-        const { personalization, analytics, ...apiConfig } = config;
-        this.config = apiConfig;
-        this.experience = new ExperienceApiClient({
-            ...apiConfig,
-            ...personalization,
-        });
-        this.insights = new InsightsApiClient({
-            ...apiConfig,
-            ...analytics,
-        });
-    }
-}
-//# sourceMappingURL=ApiClient.js.map

package/dist/ApiClient.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ApiClient.js","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AACA,OAAO,mBAAuD,MAAM,cAAc,CAAA;AAClF,OAAO,iBAAmD,MAAM,YAAY,CAAA;AA2B5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B;;OAEG;IACM,MAAM,CAAW;IAE1B;;OAEG;IACM,UAAU,CAAqB;IAExC;;OAEG;IACM,QAAQ,CAAmB;IAEpC;;;;OAIG;IACH,YAAY,MAAuB;QACjC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,GAAG,MAAM,CAAA;QAE3D,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QAEvB,IAAI,CAAC,UAAU,GAAG,IAAI,mBAAmB,CAAC;YACxC,GAAG,SAAS;YACZ,GAAG,eAAe;SACnB,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,iBAAiB,CAAC;YACpC,GAAG,SAAS;YACZ,GAAG,SAAS;SACb,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/ApiClientBase.d.ts

@@ -1,113 +0,0 @@
-import { type FetchMethod, type ProtectedFetchMethodOptions } from './fetch';
-/**
- * Configuration options for API clients extending {@link ApiClientBase}.
- *
- * @public
- */
-export interface ApiConfig {
-    /**
-     * Base URL for the API.
-     *
-     * @remarks
-     * When omitted, the concrete client is expected to construct full URLs
-     * internally.
-     */
-    baseUrl?: string;
-    /**
-     * Contentful environment identifier.
-     *
-     * @remarks
-     * Defaults to `main` when not provided.
-     */
-    environment?: string;
-    /**
-     * Options used to configure the underlying protected fetch method.
-     *
-     * @remarks
-     * `apiName` is derived from the client name and must not be provided here.
-     */
-    fetchOptions?: Omit<ProtectedFetchMethodOptions, 'apiName'>;
-    /**
-     * Client identifier used for authentication or tracking.
-     */
-    clientId: string;
-}
-/**
- * Properties that may be shared between global and per-client API configuration.
- *
- * @public
- */
-export type GlobalApiConfigProperties = 'environment' | 'fetchOptions' | 'clientId';
-/**
- * Base class for API clients that provides shared configuration and error logging.
- *
- * @internal
- *
- * @remarks
- * This abstract class is intended for internal use within the package and
- * should not be treated as part of the public API surface.
- *
- * Concrete API clients should extend this class to inherit consistent logging
- * behavior and fetch configuration.
- *
- * @example
- * ```ts
- * interface MyClientConfig extends ApiConfig {
- *   // additional config
- * }
- *
- * class MyClient extends ApiClientBase {
- *   constructor(config: MyClientConfig) {
- *     super('MyClient', config)
- *   }
- *
- *   async getSomething() {
- *     const response = await this.fetch('https://example.com', { method: 'GET' })
- *     return response.json()
- *   }
- * }
- * ```
- */
-declare abstract class ApiClientBase {
-    /**
-     * Name of the API client, used in log messages and as the `apiName` for fetch.
-     */
-    protected readonly name: string;
-    /**
-     * Client identifier used for authentication or tracking.
-     */
-    protected readonly clientId: string;
-    /**
-     * Contentful environment associated with this client.
-     */
-    protected readonly environment: string;
-    /**
-     * Protected fetch method used by the client to perform HTTP requests.
-     */
-    protected readonly fetch: FetchMethod;
-    /**
-     * Creates a new API client base instance.
-     *
-     * @param name - Human-readable name of the client (used for logging and `apiName`).
-     * @param config - Configuration options for the client.
-     */
-    constructor(name: string, { fetchOptions, clientId, environment }: ApiConfig);
-    /**
-     * Logs errors that occur during API requests with standardized messages.
-     *
-     * @param error - The error thrown by the underlying operation.
-     * @param options - Additional metadata about the request.
-     * @param options.requestName - Human-readable name of the request operation.
-     *
-     * @protected
-     *
-     * @remarks
-     * Abort errors are logged at `warn` level and other errors at `error` level.
-     * The log message includes the client name for better debugging context.
-     */
-    protected logRequestError(error: unknown, { requestName }: {
-        requestName: string;
-    }): void;
-}
-export default ApiClientBase;
-//# sourceMappingURL=ApiClientBase.d.ts.map

package/dist/ApiClientBase.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ApiClientBase.d.ts","sourceRoot":"","sources":["../src/ApiClientBase.ts"],"names":[],"mappings":"AACA,OAAc,EAAE,KAAK,WAAW,EAAE,KAAK,2BAA2B,EAAE,MAAM,SAAS,CAAA;AAWnF;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAA;IAE3D;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,aAAa,GAAG,cAAc,GAAG,UAAU,CAAA;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,uBAAe,aAAa;IAC1B;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAE/B;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAErC;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,SAAS;IAQ5E;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAW1F;AAED,eAAe,aAAa,CAAA"}