feat: Add TypeScript definitions

package.json

@@ -36,7 +36,7 @@
     "jest-junit": "^16.0.0",
     "jsdoc-to-markdown": "^8.0.0",
     "stdout-stderr": "^0.1.9",
-    "typescript": "^5.1.6"
+    "typescript": "^5.8.3"
   },
   "engines": {
     "node": ">=18"
@@ -51,9 +51,11 @@
   ],
   "license": "Apache-2.0",
   "main": "src/index.js",
+  "types": "types/index.d.ts",
   "repository": "https://github.com/adobe/aio-lib-ims",
   "scripts": {
     "lint": "eslint src test",
+    "build:types": "tsc",
     "test": "npm run unit-tests && npm run lint",
     "unit-tests": "jest --config test/jest.config.js --ci",
     "e2e": "jest --config e2e/jest.config.js",

test/types.check.ts

@@ -0,0 +1,67 @@
+import { getToken, context, Ims, ValidationCache, ACCESS_TOKEN, REFRESH_TOKEN, AUTHORIZATION_CODE, CLIENT_ID, CLIENT_SECRET, SCOPE, getTokenData } from '../src/index';
+
+// Test usage of getToken
+async function testGetToken() {
+  const tokenPromise: Promise<string> = getToken('testContext', {
+    scope: 'additional_scope',
+    force: false
+  });
+  const token: string = await tokenPromise;
+  console.log(token);
+}
+
+// Test usage of context
+async function testContext() {
+  if (context) {
+    const currentContextName: Promise<string> = context.getCurrent();
+    console.log(await currentContextName);
+
+    const contextDataPromise: Promise<object> = context.get('someKey');
+    console.log(await contextDataPromise);
+  }
+}
+
+// Test usage of Ims
+function testIms() {
+  const imsInstance = new Ims('prod');
+  console.log(imsInstance.imsHost);
+}
+
+// Test usage of ValidationCache
+function testValidationCache() {
+  const cacheKey = 'testCacheKey';
+  const cacheValue = { data: 'testData' };
+  ValidationCache.set(cacheKey, cacheValue);
+  const retrievedValue: { data: string } | undefined = ValidationCache.get(cacheKey);
+  console.log(retrievedValue);
+  ValidationCache.invalidate(cacheKey);
+}
+
+// Test usage of constants
+function testConstants() {
+  const accessTokenKey: string = ACCESS_TOKEN;
+  const refreshTokenKey: string = REFRESH_TOKEN;
+  const authCodeKey: string = AUTHORIZATION_CODE;
+  const clientIdKey: string = CLIENT_ID;
+  const clientSecretKey: string = CLIENT_SECRET;
+  const scopeKey: string = SCOPE;
+  console.log(accessTokenKey, refreshTokenKey, authCodeKey, clientIdKey, clientSecretKey, scopeKey);
+}
+
+// Test usage of getTokenData
+async function testGetTokenData() {
+    const tokenData = await getTokenData('jwtTokenString');
+    if (tokenData) {
+        console.log(tokenData.client_id, tokenData.user_id, tokenData.expires_in);
+    }
+}
+
+// Call test functions (optional, mainly for linting if functions are unused)
+testGetToken();
+testContext();
+testIms();
+testValidationCache();
+testConstants();
+testGetTokenData();
+
+console.log('Type test file created. Type checking will determine success.');

tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "skipLibCheck": true,
+    "maxNodeModuleJsDepth": 0
+  },
+  "include": [
+    "src/**/*",
+    "test/types.check.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

types/ValidationCache.d.ts

@@ -0,0 +1,87 @@
+export = ValidationCache;
+/**
+ * @typedef {object} ValidationResult
+ * @property {number} status validation response status code, e.g 200, 401, 403, ...
+ * @property {string} message validation message, e.g. reason of failed validation
+ */
+/**
+ * @typedef {Function} ValidationFunction
+ * @param {...string} params validation params used for building the cache key (at least one)
+ * @returns {Promise<ValidationResult>} validation result
+ */
+/**
+ * A class to cache valid or invalid results. Internally two separate cache entries are
+ * maintained. Each cache entry is about 66Bytes big.
+ *
+ * @class ValidationCache
+ */
+declare class ValidationCache {
+    /**
+     * Creates a new LRU cache instance.
+     *
+     * @param {number} maxAge - The maximum age in milliseconds of cache validity.
+     * @param {number} maxValidEntries - The maximum number of valid entries that can be contained in the cache.
+     * @param {number} maxInvalidEntries - The maximum number of invalid entries that can be contained in the cache.
+     */
+    constructor(maxAge: number, maxValidEntries: number, maxInvalidEntries: number);
+    /** @private */
+    private validCache;
+    /** @private */
+    private invalidCache;
+    /** @private */
+    private encodingState;
+    /**
+     * @param {ValidationResult} res
+     * @returns {string} a single char
+     * @memberof ValidationCache
+     * @private
+     */
+    private resultStr;
+    /**
+     * @param {ValidationResult} res
+     * @returns {string} a single char
+     * @memberof ValidationCache
+     * @private
+     */
+    private encodeValidationResult;
+    /**
+     * @param {string} char
+     * @returns {ValidationResult} a validation result entry
+     * @memberof ValidationCache
+     * @private
+     */
+    private decodeValidationResult;
+    /**
+     * @param {Array} params
+     * @returns {string} the computed hash key
+     * @memberof ValidationCache
+     * @private
+     */
+    private computeCacheKey;
+    /**
+     *
+     * Applies a validation function and caches the result. If there is a cache entry
+     * available returns the cached result without calling the validation function.
+     * The cache key is computed from the validation params
+     *
+     * @param {ValidationFunction} validationFunction a function that returns an object of the form `{ status, message }`
+     * @param {...string} validationParams  parameters for the validationFunction, must be at least one
+     * @returns {Promise<object>} validation result
+     * @memberof ValidationCache
+     */
+    validateWithCache(validationFunction: ValidationFunction, ...validationParams: string[]): Promise<object>;
+}
+declare namespace ValidationCache {
+    export { ValidationResult, ValidationFunction };
+}
+type ValidationResult = {
+    /**
+     * validation response status code, e.g 200, 401, 403, ...
+     */
+    status: number;
+    /**
+     * validation message, e.g. reason of failed validation
+     */
+    message: string;
+};
+type ValidationFunction = Function;

types/context.d.ts

@@ -0,0 +1,18 @@
+/** @private */
+export function resetContext(): void;
+/** @private */
+export function getContext(): any;
+/** Name of context type action */
+export const TYPE_ACTION: "action";
+/** Name of context type cli */
+export const TYPE_CLI: "cli";
+/** Name of the IMS configuration context data structure */
+export const IMS: "ims";
+/** Property holding the current context name */
+export const CURRENT: "current";
+/** Property holding the cli context name */
+export const CLI: "cli";
+/** Property holding an object with all contexts */
+export const CONTEXTS: "contexts";
+/** Property holding an object with context management configuration */
+export const CONFIG: "config";

types/ctx/ConfigCliContext.d.ts

@@ -0,0 +1,53 @@
+export = ConfigCliContext;
+/**
+ * The `ConfigCliContext` class stores IMS `contexts` for the Adobe I/O CLI in the local file
+ * system using the Adobe I/O Core Configuration Library.
+ */
+declare class ConfigCliContext extends Context {
+    /** @private */
+    private aioConfig;
+    /**
+     * Gets the cli context data
+     *
+     * @returns {Promise<any>} the cli context data
+     */
+    getCli(): Promise<any>;
+    /**
+     * Sets the cli context data
+     *
+     * @param {object} contextData the data to save
+     * @param {boolean} [local=false] set to true to save to local config, false for global config
+     * @param {boolean} [merge=true] set to true to merge existing data with the new data
+     */
+    setCli(contextData: object, local?: boolean, merge?: boolean): Promise<void>;
+    /**
+     * @protected
+     * @override
+     * @ignore
+     */
+    protected override getContextValue(key: any): Promise<{
+        data: any;
+        local: boolean;
+    }>;
+    /**
+     * @protected
+     * @override
+     * @ignore
+     */
+    protected override getConfigValue(key: any): Promise<any>;
+    /**
+     * @protected
+     * @override
+     * @ignore
+     */
+    protected override setContextValue(key: any, value: any, isLocal: any): Promise<void>;
+    /**
+     * @protected
+     * @override
+     * @ignore
+     */
+    protected override setConfigValue(key: any, value: any, isLocal: any): Promise<void>;
+    /** @private */
+    private getContextValueFromOptionalSource;
+}
+import Context = require("./Context");

types/ctx/Context.d.ts

@@ -0,0 +1,97 @@
+export = Context;
+/**
+ * The `Context` abstract class provides an interface to manage the IMS configuration contexts on behalf of
+ * the Adobe I/O Lib IMS Library.
+ */
+declare class Context {
+    constructor(keyNames: any);
+    keyNames: any;
+    /**
+     * Gets the current context name.
+     *
+     * @returns {Promise<string>} the current context name
+     */
+    getCurrent(): Promise<string>;
+    /**
+     * Sets the current context name in the local configuration
+     *
+     * @param {string} contextName The name of the context to use as the current context
+     * @returns {Promise<any>} returns an instance of the Config object
+     */
+    setCurrent(contextName: string): Promise<any>;
+    /**
+     * Returns an object representing the named context.
+     * If the contextName parameter is empty or missing, it defaults to the
+     * current context name. The result is an object with two properties:
+     *
+     *   - `name`: The actual context name used
+     *   - `data`: The IMS context data
+     *   - `local`: Whether the context data is stored locally or not
+     *
+     * @param {string} contextName Name of the context information to return.
+     * @returns {Promise<object>} The configuration object
+     */
+    get(contextName: string): Promise<object>;
+    /**
+     * Updates the named configuration with new configuration data. If a configuration
+     * object for the named context already exists it is completely replaced with this new
+     * configuration.
+     *
+     * @param {string} contextName Name of the context to update
+     * @param {object} contextData The configuration data to store for the context
+     * @param {boolean} local Persist in local or global configuration. When running in
+     *      Adobe I/O Runtime, this has no effect unless `contextData` contains an
+     *      `access_token` or `refresh_token` field, in which case setting `local=true` will
+     *      prevent the persistence of those fields in the [`State
+     *      SDK`](https://github.com/adobe/aio-lib-state). Please note that when calling
+     *      `getToken` in an I/O Runtime Action, generated tokens will always be persisted
+     *      as `getToken` internally calls `context.set` with `local=false`.
+     */
+    set(contextName: string, contextData: object, local?: boolean): Promise<void>;
+    /**
+     * Returns the names of the configured contexts as an array of strings.
+     *
+     * @returns {Promise<string[]>} The names of the currently known configurations.
+     */
+    keys(): Promise<string[]>;
+    /**
+     *
+     * @param {string} configName config name
+     * @returns {Promise<any>} config value
+     * @protected
+     * @ignore
+     */
+    protected getConfigValue(configName: string): Promise<any>;
+    /**
+     * @param {string} configName config name
+     * @param {any} configValue config value
+     * @param {boolean} isLocal write local or not
+     * @protected
+     * @ignore
+     */
+    protected setConfigValue(configName: string, configValue: any, isLocal: boolean): Promise<void>;
+    /**
+     * @param {string} contextName context name
+     * @returns {Promise<{data: any, local: boolean}>} context value
+     * @protected
+     * @ignore
+     */
+    protected getContextValue(contextName: string): Promise<{
+        data: any;
+        local: boolean;
+    }>;
+    /**
+     * @param {string} contextName config name
+     * @param {any} ctxValue config value
+     * @param {boolean} isLocal write local or not
+     * @protected
+     * @ignore
+     */
+    protected setContextValue(contextName: string, ctxValue: any, isLocal: boolean): Promise<void>;
+    /**
+     * @ignore
+     * @protected
+     * @returns {Promise<string[]>} return defined contexts
+     */
+    protected contextKeys(): Promise<string[]>;
+}