Build a fides-types.d.ts type declaration file to include alongside our FidesJS developer docs

CHANGELOG.md

@@ -22,10 +22,12 @@ The types of changes are:
 - Added `getModalLinkLabel` method to global fides object [#4766](https://github.com/ethyca/fides/pull/4766)
 
 ### Fixed
-
 - Fixed select dropdowns being cut off by edges of modal forms [#4757](https://github.com/ethyca/fides/pull/4757)
 - Changed "allow user to dismiss" toggle to show on config form for TCF experience [#4755](https://github.com/ethyca/fides/pull/4755)
 
+### Developer Experience
+- Build a `fides-types.d.ts` type declaration file to include alongside our FidesJS developer docs [#4772](https://github.com/ethyca/fides/pull/4772)
+
 ## [2.33.1](https://github.com/ethyca/fides/compare/2.33.0...2.33.1)
 
 ### Added

clients/fides-js/package.json

@@ -77,6 +77,7 @@
   "typedocOptions": {
     "disableSources": true,
     "excludeExternals": true,
+    "excludeInternal": true,
     "excludePrivate": true,
     "githubPages": false,
     "hideBreadcrumbs": true,

clients/fides-js/rollup.config.mjs

@@ -114,6 +114,9 @@ const SCRIPTS = [
  */
 const rollupOptions = [];
 
+/**
+ * For each of our entrypoint scripts, build .js, .mjs, and .d.ts outputs
+ */
 SCRIPTS.forEach(({ name, gzipErrorSizeKb, gzipWarnSizeKb, isExtension }) => {
   const js = {
     input: `src/${name}.ts`,
@@ -164,4 +167,18 @@ SCRIPTS.forEach(({ name, gzipErrorSizeKb, gzipWarnSizeKb, isExtension }) => {
   rollupOptions.push(...[js, mjs, declaration]);
 });
 
+/**
+ * In addition to our regular built outputs (like fides.js!) also generate a
+ * fides-types.d.ts file from  our documented types for external use.
+ */
+rollupOptions.push({
+  input: `src/docs/index.ts`,
+  plugins: [dts()],
+  output: [
+    {
+      file: `dist/fides-types.d.ts`,
+    },
+  ],
+});
+
 export default rollupOptions;

clients/fides-js/src/docs/fides-event.ts

@@ -2,8 +2,9 @@
  * Defines the list of FidesEvent names. See {@link FidesEvent} for details on each!
  *
  * NOTE: We mark this type @private to exclude it from the generated SDK
- * documentation, since it's mostly just noise - the list of events on {@link
- * FidesEvent} provides a good reference.
+ * documentation, since it's mostly just noise there - the list of events on
+ * {@link FidesEvent} provides a good reference. But when coding, it's still
+ * useful to have this union type around!
  * 
  * @private
  */

clients/fides-js/src/docs/fides-options.ts

@@ -97,9 +97,9 @@ export interface FidesOptions {
 
   /**
    * TODO (PROD-1887): Add docs for using this option. Once added, remove the
-   * @private tag and rebuild!
+   * @internal tag and rebuild!
    * 
-   * @private
+   * @internal
    */
   fides_primary_color: string;
 

clients/fides-js/src/docs/fides.ts

@@ -209,58 +209,58 @@ export interface Fides {
   init: (config: any) => Promise<void>;
 
   /**
-   * NOTE: The properties below are all marked @private, despite being exported
+   * NOTE: The properties below are all marked @internal, despite being exported
    * on the global Fides object. This is because they are mostly implementation
    * details and internals that we probably *should* be hiding, to avoid
    * customers getting too comfortable with accessing them.
    */
 
   /**
    * DEFER (PROD-1815): This probably *should* be part of the documented SDK.
-   *
-   * @private
+   * 
+   * @internal
    */
   fides_meta: Record<any, any>;
 
   /**
    * DEFER (PROD-1815): This probably *should* be part of the documented SDK.
    *
-   * @private
+   * @internal
    */
   identity: Record<string, string>;
 
   /**
-   * @private
+   * @internal
    */
   experience?: any;
 
   /**
-   * @private
+   * @internal
    */
   geolocation?: any;
 
   /**
-   * @private
+   * @internal
    */
   options: any;
 
   /**
-   * @private
+   * @internal
    */
   tcf_consent: any;
 
   /**
-   * @private
+   * @internal
    */
   saved_consent: Record<string, boolean>;
 
   /**
-   * @private
+   * @internal
    */
   meta: (options: any) => void;
 
   /**
-   * @private
+   * @internal
    */
   shopify: (options: any) => void;
 }

clients/fides-js/src/docs/index.ts

@@ -41,14 +41,13 @@
  * Therefore, all the types in src/docs should be considered part of FidesJS'
  * *official* developer API, so treat them with care!
  *
- * You can also use the \@private tag to intentionally leave specific
+ * You can also use the "internal" tag to intentionally leave specific
  * properties/comments/etc. undocumented; this can be useful for internal-only
  * types for developers contributing directly to FidesJS, but that shouldn't be
- * included in the generic developer documentation. This comment itself is a
- * good example of that!
- * 
- * @private
+ * included in the generic developer documentation.
  */
+
+// Export all the types from files in src/docs directory
 export * from "./fides";
 export * from "./fides-event";
 export * from "./fides-options";

clients/fides-js/tsconfig.json

@@ -14,6 +14,7 @@
     "resolveJsonModule": true,
     "skipLibCheck": true,
     "strict": true,
+    "stripInternal": true,
     "target": "es2015",
     "plugins": [{ "name": "typescript-plugin-css-modules" }],
     "baseUrl": "./",