chore: add markdown plugin (#641)

docs: adds and updates some docs comments

chore: adds platform client and updates more docs

Signed-off-by: Eugene Yakhnenko <[email protected]>

Author: eugenioenko

lib/package-lock.json

@@ -69,7 +69,8 @@
     "build:watch": "tsc --watch",
     "clean": "rm -rf {build,coverage,dist,tests/mocha/dist}",
     "coverage:merge": "for x in mocha wtr; do cp coverage/$x/coverage-final.json coverage/$x.json; done; nyc report --reporter text --reporter lcov -t coverage --lines 75 --statements 75 --branches 70 --functions 65 --check-coverage >coverage/coverage.txt",
-    "doc": "typedoc --out dist/docs src/index.ts",
+    "doc": "typedoc --out dist/docs src/index.ts --customCss ./typedoc-theme.css",
+    "doc:md": "typedoc --plugin typedoc-plugin-markdown --out dist/docs-md src/index.ts",
     "format": "prettier --write \"{src,tdf3,tests}/**/*.ts\"",
     "license-check": "license-checker-rseidelsohn --production --onlyAllow 'Apache-2.0; BSD; CC-BY-4.0; ISC; MIT'",
     "lint": "eslint ./src/**/*.ts ./tdf3/**/*.ts ./tests/**/*.ts",
@@ -133,7 +134,8 @@
     "process": "^0.11.10",
     "sinon": "~19.0.2",
     "tsconfig-paths": "^4.2.0",
-    "typedoc": "^0.27.9",
+    "typedoc": "^0.28.5",
+    "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.8.2",
     "typescript-eslint": "^8.26.0",
     "webpack": "^5.98.0",

lib/package.json

@@ -136,6 +136,12 @@ export async function noteInvalidPublicKey(url: URL, r: Promise<CryptoKey>): Pro
   }
 }
 
+/**
+ * Fetches the key access servers for a given platform URL.
+ * @param platformUrl The platform URL to fetch key access servers for.
+ * @param authProvider The authentication provider to use for the request.
+ * @returns A promise that resolves to an OriginAllowList.
+ */
 export async function fetchKeyAccessServers(
   platformUrl: string,
   authProvider: AuthProvider
@@ -190,6 +196,15 @@ const origin = (u: string): string => {
   }
 };
 
+/**
+ * Manages a list of origins that are allowed to access the Key Access Server (KAS).
+ * @origins A list of origins that are allowed to access the KAS.
+ * @allowAll If true, all origins are allowed to access the KAS.
+ * If false, only the origins in the list are allowed to access the KAS.
+ * @description This class is used to manage a list of origins that are allowed to access the KAS.
+ * It validates the URLs and provides a method to check if a given URL is allowed.
+ * It is used to ensure that only authorized origins can access the KAS.
+ */
 export class OriginAllowList {
   origins: string[];
   allowAll: boolean;

lib/src/access.ts

@@ -2,6 +2,20 @@ import { ConfigurationError } from '../errors.js';
 import { type AuthProvider, type HttpRequest } from './auth.js';
 import { AccessToken, type RefreshTokenCredentials } from './oidc.js';
 
+/**
+ * An AuthProvider that uses an OIDC refresh token to obtain an access token.
+ * It exchanges the refresh token for an access token and uses that to augment HTTP requests with credentials.
+ *  @example
+ * ```ts
+ * import { OIDCRefreshTokenProvider } from '@opentdf/sdk';
+ * await AuthProviders.refreshAuthProvider({
+    clientId: 'my-client-id',
+    exchange: 'refresh',
+    refreshToken: 'refresh-token-from-oidc-provider',
+    oidcOrigin: 'https://example.oidc.provider.com',
+  });
+  ```
+ */
 export class OIDCRefreshTokenProvider implements AuthProvider {
   oidcAuth: AccessToken;
   refreshToken?: string;

lib/src/auth/oidc-refreshtoken-provider.ts

@@ -2,6 +2,7 @@ export { type AuthProvider, type HttpMethod, HttpRequest, withHeaders } from './
 export * as AuthProviders from './auth/providers.js';
 export { attributeFQNsAsValues } from './policy/api.js';
 export { version, clientType, tdfSpecVersion } from './version.js';
+export { PlatformClient, type PlatformClientOptions, type PlatformServices } from './platform.js';
 export * from './opentdf.js';
 export * from './seekable.js';
 export * from '../tdf3/src/models/index.js';