@remkoj/optimizely-cms-api 6.0.0-pre9 → 6.0.0-rc.3

package/AGENTS.md

@@ -0,0 +1,66 @@
+# @remkoj/optimizely-cms-api — usage
+
+CMS Integration REST API client for Optimizely SaaS CMS. CommonJS module.
+
+## Install
+
+```bash
+npm install @remkoj/optimizely-cms-api
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `OPTIMIZELY_CMS_URL` | yes | CMS instance URL, e.g. `https://<tenant>.cms.optimizely.com` |
+| `OPTIMIZELY_CMS_CLIENT_ID` | yes | OAuth client ID |
+| `OPTIMIZELY_CMS_CLIENT_SECRET` | yes | OAuth client secret |
+| `OPTIMIZELY_CMS_API_BASEURL` | no | Override the API base URL |
+| `OPTIMIZELY_CMS_USER_ID` | no | Impersonate a specific user (`actAs`) |
+| `OPTIMIZELY_DEBUG` | no | Set to `"1"` to enable request/response logging |
+
+## Creating a client
+
+```typescript
+import { createClient, readEnvConfig } from '@remkoj/optimizely-cms-api'
+
+// From environment variables (recommended)
+const client = createClient()
+
+// With explicit config
+const client = createClient({
+  base: new URL('https://<tenant>.cms.optimizely.com'),
+  clientId: '...',
+  clientSecret: '...',
+  debug: false
+})
+```
+
+## Key exports
+
+| Export | Description |
+| --- | --- |
+| `createClient(config?)` | Creates a new API client instance. Reads env vars when config is omitted. |
+| `readEnvConfig()` | Reads and validates env vars into `CmsIntegrationApiOptions`. |
+| `readPartialEnvConfig()` | Reads env vars without requiring client credentials. |
+| `isClientInstance(value)` | Type guard for `CmsIntegrationApiClient`. |
+| `IntegrationApi.*` | All generated CMS API types (re-exported from `types.gen.ts`). |
+| `ContentRoots` | Enum of well-known content root node GUIDs (SystemRoot, Trash, etc.). |
+| `ApiClient` | Base client class. |
+| `ApiError` | Error thrown when an API operation fails. |
+| `ApiClientInstance` | Type alias for a client instance. |
+
+## Types
+
+```typescript
+import type { CmsIntegrationApiOptions, ApiClientInstance } from '@remkoj/optimizely-cms-api'
+import { IntegrationApi } from '@remkoj/optimizely-cms-api'
+
+// Use IntegrationApi.ContentType, IntegrationApi.DisplayTemplate, etc.
+```
+
+## Constraints
+
+- CommonJS module — works with both `require()` and `import`.
+- `ApiError` exposes `.status`, `.statusText`, `.data`, `.request`, `.response`.
+- `ContentRoots` values are GUIDs as strings.

package/README.md

@@ -1,7 +1,11 @@
+# Optimizely CMS - Integration API Client <!-- omit in toc -->
+
+> [!WARNING]
+> There'll be an update of Optimizely SaaS CMS that is incompatible with all SDK versions prior to 5.1.6. If you don't upgrade, you will see empty pages (main website) and "Component not found" messages (preview).
+
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 ![Static Badge](https://img.shields.io/badge/Optimizely-Content_Management_System-blue?cacheSeconds=7200)
 
-# Optimizely CMS - Integration API Client <!-- omit in toc -->
 A Javascript client for the Integration API provided by the Optimizely CMS. It wraps the [Optimizely CMS SaaS Core REST API](https://docs.developers.optimizely.com/content-management-system/v1.0.0-SaaS-Core/reference/introduction-to-the-cms-content-api).
 
 ## Installation
@@ -40,4 +44,4 @@ The following configuration options are available for
 | OPTIMIZELY_CMS_URL | base | no | Sets the URL of the Optimizely CMS instance |
 | OPTIMIZELY_CMS_CLIENT_ID | clientId | yes | The API Client ID, as configured within the CMS |
 | OPTIMIZELY_CMS_CLIENT_SECRET | clientSecret | yes | The API Client Secret as generated by the CMS when creating the client |
-| OPTIMIZELY_CMS_USER_ID | actAs | no | The username of the CMS user to impersonate |
+| OPTIMIZELY_CMS_USER_ID | actAs | no | The username of the CMS user to impersonate |

package/dist/api-client.d.ts

@@ -1,58 +1,17 @@
+import { ApiClient as AbstractApiClient } from "@remkoj/hey-api-wrapper";
 import * as Operations from './client/sdk.gen';
-import { createClient, type RequestResult, type ResponseStyle } from './client/client';
-import * as InstanceOperations from './instance.client/sdk.gen';
-import { createClient as createInstanceClient, type RequestResult as InstanceRequestResult, type ResponseStyle as InstanceResponseStyle } from './instance.client/client';
+import { createClient } from './client/client';
 import { type CmsIntegrationApiOptions } from "./config";
-import { type InstanceApiVersionInfo, OptiCmsVersion } from "./types";
-type OperationsType = {
-    -readonly [KT in keyof typeof Operations]: (typeof Operations)[KT];
-};
-type OperationsNames = keyof OperationsType;
-type OperationReturnType<RT extends (...args: any) => any> = ReturnType<RT> extends RequestResult<any, any, boolean, ResponseStyle> ? Promise<NonNullable<Awaited<ReturnType<RT>>['data']>> : never;
-type InstanceOperationsType = {
-    -readonly [KT in keyof typeof InstanceOperations]: (typeof InstanceOperations)[KT];
-};
-type InstanceOperationsNames = keyof InstanceOperationsType;
-type InstanceOperationReturnType<RT extends (...args: any) => any> = ReturnType<RT> extends InstanceRequestResult<any, any, boolean, InstanceResponseStyle> ? Promise<NonNullable<Awaited<ReturnType<RT>>['data']>> : never;
-type BaseApiClientFunctions = {
-    readonly [KT in OperationsNames]: OperationsType[KT] extends Function ? (options?: Parameters<OperationsType[KT]>[0]) => OperationReturnType<OperationsType[KT]> : never;
-};
-type InstanceClientFunctions = {
-    readonly [KT in InstanceOperationsNames as InstanceOperationsType[KT] extends Function ? `preview2${Capitalize<KT>}` : never]: InstanceOperationsType[KT] extends Function ? (options?: Parameters<InstanceOperationsType[KT]>[0]) => InstanceOperationReturnType<InstanceOperationsType[KT]> : never;
-};
-type ApiClientFunctions = BaseApiClientFunctions & InstanceClientFunctions;
-type BaseClass = {
-    new (...args: any[]): BaseApiClient;
-};
-type NonConstructorKeys<T> = ({
-    [P in keyof T]: T[P] extends new () => any ? never : P;
-})[keyof T];
-type OmitConstructor<TBase extends BaseClass> = Pick<TBase, NonConstructorKeys<TBase>>;
-export type ClassWithMixin<TBase extends BaseClass, Mixin> = OmitConstructor<TBase> & {
-    new (...args: ConstructorParameters<TBase>): InstanceType<TBase> & Mixin;
-};
-declare class BaseApiClient {
-    protected _config: CmsIntegrationApiOptions;
-    protected _client: ReturnType<typeof createClient>;
-    protected _instanceClient: ReturnType<typeof createInstanceClient>;
+import type { OpenAPIV3_1 } from "openapi-types";
+/**
+ * Base implementation of the ApiClient wrapper for the Optimizely CMS Rest API
+ */
+declare class BaseApiClient extends AbstractApiClient<CmsIntegrationApiOptions, ReturnType<typeof createClient>> {
     constructor(config?: CmsIntegrationApiOptions);
-    /**
-     * Get the runtime configuration of the target CMS version.
-     *
-     * If this differs from the cmsVersion the client may not work fully or not
-     * at all.
-     *
-     * @deprecated  This is based on the OPTIMIZELY_CMS_SCHEMA environment that is ignored by API client
-     */
-    get runtimeCmsVersion(): OptiCmsVersion;
     /**
      * The URL of the CMS instance
      */
     get cmsUrl(): URL | undefined;
-    /**
-     * Marker to indicate if the client has debugging enabled
-     */
-    get debug(): boolean;
     /**
      * Detect the API Version from the URL, returning the runtime version. When
      * this version differs from the `apiVersion` property errors can be expected.
@@ -66,37 +25,11 @@ declare class BaseApiClient {
      * The CMS version for which this client was build
      */
     get cmsVersion(): string;
-    /**
-     * Retrieve the version information
-     *
-     * @returns The version information from the running instance
-     */
-    getInstanceInfo(): Promise<InstanceApiVersionInfo>;
-    getOpenApiSpec(): Promise<any>;
+    getOpenApiSpec(): Promise<OpenAPIV3_1.Document>;
     getSchemaItemBase(): URL | undefined;
 }
-export declare class ApiError extends Error {
-    protected _ctx: {
-        error: unknown;
-        request: Request;
-        response: Response;
-    };
-    constructor(data: {
-        error: unknown;
-        request: Request;
-        response: Response;
-    });
-    get data(): unknown;
-    /**
-     * @deprecated use data() instead
-     */
-    get body(): unknown;
-    get request(): unknown;
-    get response(): unknown;
-    get status(): number;
-    get statusText(): string;
-}
-export declare const ApiClient: ClassWithMixin<typeof BaseApiClient, ApiClientFunctions>;
+export { ApiError } from "@remkoj/hey-api-wrapper";
+export declare const ApiClient: import("@remkoj/hey-api-wrapper/dist/types").ClassWithMixin<typeof BaseApiClient, import("@remkoj/hey-api-wrapper/dist/types").ApiClientFunctions<typeof Operations>>;
 export type ApiClientStatic = typeof ApiClient;
 export type CmsIntegrationApiClient = InstanceType<typeof ApiClient>;
 export default ApiClient;

package/dist/api-client.js

@@ -37,114 +37,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiClient = exports.ApiError = void 0;
+const hey_api_wrapper_1 = require("@remkoj/hey-api-wrapper");
 const Operations = __importStar(require("./client/sdk.gen"));
 const client_1 = require("./client/client");
-const InstanceOperations = __importStar(require("./instance.client/sdk.gen"));
-const client_2 = require("./instance.client/client");
-const config_1 = require("./config");
-const types_1 = require("./types");
 const client_config_1 = require("./client-config");
+const config_1 = require("./config");
 const version_json_1 = __importDefault(require("./version.json"));
-function applyOperations(Base) {
-    // Create the new class
-    class NewClass extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-    }
-    // Bind the operations
-    Object.getOwnPropertyNames(Operations).filter(isApiClientFunction).forEach(propName => {
-        async function wrapper(args) {
-            const operationArgs = {
-                throwOnError: false,
-                ...args,
-                //@ts-expect-error
-                client: this._client
-            };
-            //@ts-expect-error
-            const result = await Operations[propName](operationArgs);
-            if (result.data)
-                return result.data;
-            throw new ApiError(result);
-        }
-        //@ts-expect-error
-        NewClass.prototype[propName] = wrapper;
-    });
-    // Bind the older Preview2 operations
-    Object.getOwnPropertyNames(InstanceOperations).filter(isInstanceClientFunction).forEach(propName => {
-        async function wrapper(args) {
-            const operationArgs = {
-                throwOnError: false,
-                ...args,
-                //@ts-expect-error
-                client: this._instanceClient
-            };
-            //@ts-expect-error
-            const result = await InstanceOperations[propName](operationArgs);
-            if (result.data)
-                return result.data;
-            throw new ApiError(result);
-        }
-        const fnName = `preview2${toCapitalized(propName)}`;
-        //@ts-expect-error
-        NewClass.prototype[fnName] = wrapper;
-    });
-    // Return the new class
-    return NewClass;
-}
-function toCapitalized(toCapitalize) {
-    return (toCapitalize.substring(0, 1).toUpperCase() + toCapitalize.substring(1));
-}
-function createIsFunctionValidator(baseType) {
-    return (propName) => {
-        return typeof (baseType[propName]) == 'function';
-    };
-}
-const isApiClientFunction = createIsFunctionValidator(Operations);
-const isInstanceClientFunction = createIsFunctionValidator(InstanceOperations);
-class BaseApiClient {
-    _config;
-    _client;
-    _instanceClient;
+/**
+ * Base implementation of the ApiClient wrapper for the Optimizely CMS Rest API
+ */
+class BaseApiClient extends hey_api_wrapper_1.ApiClient {
     constructor(config) {
-        // Store instance variables
-        this._config = config ?? (0, config_1.readEnvConfig)();
-        this._client = (0, client_1.createClient)((0, client_config_1.createClientConfig)((0, client_1.createConfig)({
-            baseUrl: 'https://api.cms.optimizely.com/preview3'
-        }), this._config));
-        this._instanceClient = (0, client_2.createClient)((0, client_config_1.createClientConfig)((0, client_2.createConfig)({
-            baseUrl: new URL('/_cms/preview2', this._config.base).href
-        })));
-        // Configure Client
-        if (this._config.debug) {
-            this._client.interceptors.request.use(async (request) => {
-                console.log(`🔍 [CMS API] Sending ${request.method} request to ${request.url}`);
-                return request;
-            });
-            this._client.interceptors.response.use((response, request) => {
-                console.log(`✨ [CMS API] Received response ${response.status} ${response.statusText} of type ${response.headers.get('Content-Type') ?? 'unknown'} for ${request.url}`);
-                return response;
-            });
-            this._instanceClient.interceptors.request.use(async (request) => {
-                console.log(`🔍 [CMS API] Sending ${request.method} request to ${request.url}`);
-                return request;
-            });
-            this._instanceClient.interceptors.response.use((response, request) => {
-                console.log(`✨ [CMS API] Received response ${response.status} ${response.statusText} of type ${response.headers.get('Content-Type') ?? 'unknown'} for ${request.url}`);
-                return response;
-            });
-        }
-    }
-    /**
-     * Get the runtime configuration of the target CMS version.
-     *
-     * If this differs from the cmsVersion the client may not work fully or not
-     * at all.
-     *
-     * @deprecated  This is based on the OPTIMIZELY_CMS_SCHEMA environment that is ignored by API client
-     */
-    get runtimeCmsVersion() {
-        return this._config.cmsVersion ?? types_1.OptiCmsVersion.CMSSAAS;
+        const apiConfig = config ?? (0, config_1.readEnvConfig)();
+        const apiClient = (0, client_1.createClient)((0, client_config_1.createClientConfig)((0, client_1.createConfig)({
+            baseUrl: 'https://api.cms.optimizely.com/v1',
+        }), config));
+        super(apiConfig, apiClient);
     }
     /**
      * The URL of the CMS instance
@@ -155,19 +63,13 @@ class BaseApiClient {
         const baseUrl = this._client.getConfig().baseUrl;
         return baseUrl ? new URL(baseUrl) : undefined;
     }
-    /**
-     * Marker to indicate if the client has debugging enabled
-     */
-    get debug() {
-        return this._config.debug ?? false;
-    }
     /**
      * Detect the API Version from the URL, returning the runtime version. When
      * this version differs from the `apiVersion` property errors can be expected.
      */
     get version() {
         const baseUrl = this._client.getConfig().baseUrl;
-        const detectedVersion = baseUrl?.match(/^https{0,1}:\/\/.+?\/(_cms\/){0,1}([a-z0-9\.]+)(\/|$)/)?.at(2);
+        const detectedVersion = baseUrl?.match(/^https{0,1}:\/\/.+?\/(_cms\/){0,1}([a-z0-9.]+)(\/|$)/)?.at(2);
         return detectedVersion || "";
     }
     /**
@@ -182,39 +84,14 @@ class BaseApiClient {
     get cmsVersion() {
         return version_json_1.default.cms;
     }
-    /**
-     * Retrieve the version information
-     *
-     * @returns The version information from the running instance
-     */
-    async getInstanceInfo() {
-        const result = await this._client.get({
-            url: '/info'
-        });
-        const instanceResult = await this._instanceClient.get({
-            url: '/info'
-        });
-        if (result.data) {
-            const data = result.data;
-            data.baseUrl = this._client.getConfig().baseUrl;
-            data.results = {
-                preview2Data: {
-                    baseUrl: this._instanceClient.getConfig().baseUrl,
-                    ...instanceResult?.data ?? {}
-                },
-                ...data.results,
-            };
-            return data;
-        }
-        throw new ApiError(result);
-    }
     async getOpenApiSpec() {
         const result = await this._client.get({
             url: '/docs/content-openapi.json',
+            throwOnError: false
         });
-        if (result.data)
+        if (this.isDataResponse(result))
             return result.data;
-        throw new ApiError(result);
+        throw new hey_api_wrapper_1.ApiError(result);
     }
     getSchemaItemBase() {
         let baseUrl = this._client.getConfig().baseUrl;
@@ -223,37 +100,7 @@ class BaseApiClient {
         return baseUrl ? new URL(baseUrl) : undefined;
     }
 }
-class ApiError extends Error {
-    _ctx;
-    constructor(data) {
-        if (typeof data.error == 'string')
-            super(data.error);
-        else
-            super(`Optimizely CMS API Error: ${data.response.status} ${data.response.statusText}`);
-        this._ctx = data;
-    }
-    get data() {
-        return this._ctx.error;
-    }
-    /**
-     * @deprecated use data() instead
-     */
-    get body() {
-        return this._ctx.error;
-    }
-    get request() {
-        return this._ctx.request;
-    }
-    get response() {
-        return this._ctx.response;
-    }
-    get status() {
-        return this._ctx.response.status;
-    }
-    get statusText() {
-        return this._ctx.response.statusText;
-    }
-}
-exports.ApiError = ApiError;
-exports.ApiClient = applyOperations(BaseApiClient);
+var hey_api_wrapper_2 = require("@remkoj/hey-api-wrapper");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return hey_api_wrapper_2.ApiError; } });
+exports.ApiClient = (0, hey_api_wrapper_1.withOperations)(BaseApiClient, Operations);
 exports.default = exports.ApiClient;