chore: adds platform client and updates more docs

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

Author: eugenioenko

lib/package.json

@@ -69,7 +69,7 @@
     "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'",

lib/src/auth/oidc-refreshtoken-provider.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/index.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';

lib/src/opentdf.ts

@@ -310,19 +310,56 @@ export type TDFReader = {
   attributes: () => Promise<string[]>;
 };
 
-/** SDK for dealing with OpenTDF data and policy services. */
+/**
+ * The main OpenTDF class that provides methods for creating and reading TDF files.
+ * It supports both NanoTDF and ZTDF formats.
+ * It can be used to create new TDF files and read existing ones.
+ * This class is the entry point for using the OpenTDF SDK.
+ * It requires an authentication provider to be passed in the constructor.
+ * It also requires a platform URL to be set, which is used to fetch key access servers and policies.
+ * @example
+ * ```
+ * import { type Chunker, OpenTDF } from '@opentdf/sdk';
+ *
+ * const oidcCredentials: RefreshTokenCredentials = {
+ *   clientId: keycloakClientId,
+ *   exchange: 'refresh',
+ *   refreshToken: refreshToken,
+ *   oidcOrigin: keycloakUrl,
+ * };
+ * const authProvider = await AuthProviders.refreshAuthProvider(oidcCredentials);
+ *
+ * const client = new OpenTDF({
+ *   authProvider,
+ *   platformUrl: 'https://platform.example.com',
+ * });
+ *
+ * const cipherText = await client.createZTDF({
+ *   source: { type: 'stream', location: source },
+ *   autoconfigure: false,
+ * });
+ *
+ * const clearText = await client.read({ type: 'stream', location: cipherText });
+ * ```
+ */
 export class OpenTDF {
-  // Configuration service and more is at this URL/connectRPC endpoint
+  /** The platform URL */
   readonly platformUrl: string;
+  /** The policy service endpoint */
   readonly policyEndpoint: string;
+  /** The auth provider for the OpenTDF instance. */
   readonly authProvider: AuthProvider;
+  /** If DPoP is enabled for this instance. */
   readonly dpopEnabled: boolean;
+  /** Default options for creating TDF objects. */
   defaultCreateOptions: Omit<CreateOptions, 'source'>;
+  /** Default options for reading TDF objects. */
   defaultReadOptions: Omit<ReadOptions, 'source'>;
+  /** The DPoP keys for this instance, if any. */
   readonly dpopKeys: Promise<CryptoKeyPair>;
-
-  // Header cache for reading nanotdf collections
+  /** Cache for rewrapped keys */
   private readonly rewrapCache: RewrapCache;
+  /** The TDF3 client for encrypting and decrypting ZTDF files. */
   readonly tdf3Client: TDF3Client;
 
   constructor({
@@ -420,10 +457,7 @@ export class OpenTDF {
     return stream;
   }
 
-  /**
-   * Opens a TDF file for inspection and decryption.
-   * @param opts The file to open, and any appropriate configuration options.
-   */
+  /** Opens a TDF file for inspection and decryption. */
   open(opts: ReadOptions): TDFReader {
     opts = { ...this.defaultReadOptions, ...opts };
     return new UnknownTypeReader(this, opts, this.rewrapCache);
@@ -453,6 +487,7 @@ class UnknownTypeReader {
     this.delegate = this.resolveType();
   }
 
+  /** Resolves the TDF type based on the file prefix. */
   async resolveType(): Promise<TDFReader> {
     if (this.state === 'done') {
       throw new ConfigurationError('reader is closed');
@@ -474,21 +509,25 @@ class UnknownTypeReader {
     throw new InvalidFileError(`unsupported format; prefix not recognized ${prefix}`);
   }
 
+  /** Decrypts the TDF file */
   async decrypt(): Promise<DecoratedStream> {
     const actual = await this.delegate;
     return actual.decrypt();
   }
 
+  /** Returns the attributes of the TDF file */
   async attributes(): Promise<string[]> {
     const actual = await this.delegate;
     return actual.attributes();
   }
 
+  /** Returns the manifest of the TDF file */
   async manifest(): Promise<Manifest> {
     const actual = await this.delegate;
     return actual.manifest();
   }
 
+  /** Closes the TDF reader */
   async close() {
     if (this.state === 'done') {
       return;
@@ -534,6 +573,7 @@ class NanoTDFReader {
     });
   }
 
+  /** Decrypts the NanoTDF file and returns a decorated stream. */
   async decrypt(): Promise<DecoratedStream> {
     const nanotdf = await this.container;
     const cachedDEK = this.rewrapCache.get(nanotdf.header.ephemeralPublicKey);
@@ -576,10 +616,12 @@ class NanoTDFReader {
 
   async close() {}
 
+  /** Returns blank manifest. NanoTDF has no manifest. */
   async manifest(): Promise<Manifest> {
     return {} as Manifest;
   }
 
+  /** Returns the attributes of the NanoTDF file. */
   async attributes(): Promise<string[]> {
     const nanotdf = await this.container;
     if (!nanotdf.header.policy?.content) {
@@ -695,12 +737,16 @@ async function streamify(ab: Promise<ArrayBuffer>): Promise<ReadableStream<Uint8
 
 /** A writer for NanoTDF collections. */
 export type NanoTDFCollectionWriter = {
+  /** The NanoTDF client used for encrypting data in this collection. */
   encrypt: (source: Source) => Promise<ReadableStream<Uint8Array>>;
+  /** Closes the collection and releases any resources. */
   close: () => Promise<void>;
 };
 
 class Collection {
+  /** The NanoTDF client used for encrypting data in this collection. */
   client?: NanoTDFDatasetClient;
+  /** Options for encrypting data in this collection. */
   encryptOptions?: NanoEncryptOptions;
 
   constructor(authProvider: AuthProvider, opts: CreateNanoTDFCollectionOptions) {
@@ -733,6 +779,7 @@ class Collection {
     });
   }
 
+  /** Encrypts a source into a NanoTDF stream. */
   async encrypt(source: Source): Promise<DecoratedStream> {
     if (!this.client) {
       throw new ConfigurationError('Collection is closed');
@@ -750,6 +797,7 @@ class Collection {
     return stream;
   }
 
+  /** Releases client resources. */
   async close() {
     delete this.client;
   }

lib/src/platform.ts

@@ -50,8 +50,22 @@ export interface PlatformClientOptions {
  *
  * This client supports authentication via an `AuthProvider` or custom interceptors, which can
  * be used to add authentication headers or other custom logic to outgoing requests.
+ * @example
+ * ```
+ * import { AuthProviders, OpenTDF } from '@opentdf/sdk';
+ * import { PlatformClient } from '@opentdf/sdk/platform';
  *
+ * const authProvider: AuthProvider = await AuthProviders.refreshAuthProvider({...});
+ * const platform = new PlatformClient({
+ *   authProvider,
+ *   platformUrl: 'https://platform.example.com',
+ * });
+ *
+ * const wellKnownResponse = await platform.v1.wellknown.getWellKnownConfiguration({});
+ * console.log('Well-known configuration:', wellKnownResponse.configuration);
+ * ```
  */
+
 export class PlatformClient {
   readonly v1: PlatformServices;
 

lib/typedoc-theme.css

@@ -0,0 +1,42 @@
+body {
+  line-height: 1.5;
+}
+pre {
+  line-height: 1.5;
+}
+
+:root {
+  /* Light */
+  --light-color-background: #ffffff;
+  --light-color-background-secondary: #fafafa;
+  --light-color-background-active: #d6d8da;
+  --light-color-background-warning: #FFC107;
+  --light-color-warning-text: #262626;
+  --light-color-accent: #cfcfcf;
+  --light-color-text: #262626;
+  --light-color-contrast-text: #000;
+  --light-color-link: #004987;
+  --light-color-ts-keyword: #004987;
+  --light-color-ts-variable: #004987;
+}
+
+:root {
+  /* Dark */
+  --dark-color-background: #262626;
+  --dark-color-background-secondary: #1a1a1a;
+  --dark-color-background-active: #525252;
+  --dark-color-background-warning: #FFC107;
+  --dark-color-warning-text: #262626;
+  --dark-color-accent: #9096a2;
+  --dark-color-text: #f5f5f5;
+  --dark-color-contrast-text: #ffffff;
+  --dark-color-text-aside: #dddddd;
+  --dark-color-link: #6AAAE4;
+  --dark-color-focus-outline: #6AAAE4;
+  --dark-color-ts-keyword: #6AAAE4;
+  --dark-color-ts-variable: #6AAAE4;
+}
+
+.tsd-toolbar-contents  a {
+  color: var(--color-link);
+}