feat: Reorganize and rename core Favro API typings using namespaces t…

…o keep things from polluting global scope. BREAKING

ROADMAP.md

@@ -1,21 +1,6 @@
 ## Bravo Roadmap
 
 ### TODOs
-
-- Setters for Custom Field Value setters (in priority order):
-  - ✅ Text
-  - ✅ Vote
-  - ✅ Rating
-  - ✅ Number
-  - ✅ Checkbox
-  - ✅ Date
-  - ✅ Link
-  - ✅ Status
-  - ✅ Multiple select
-  - ✅ Members
-  - Timeline
-  - Tags
-  - ~~Time~~ (only used in Enterprise)
 - Clean up all ONE MILLION types. Probably need to wrap in namespaces to keep it manageable.
 - Are custom fields unsettable? Maybe by sending a `null`?
 
@@ -75,7 +60,20 @@ Ordered hierarchically by the Favro data model (not by priority order):
   - ✔ Compose a card URL
   - ✔ Update a Card's built-in fields
   - ✔ Add an attachment to a card
-  - 🔜 Update a Card's Custom Fields
+  - ✔ Update a Card's Custom Fields
+    - ✔ Text
+    - ✔ Vote
+    - ✔ Rating
+    - ✔ Number
+    - ✔ Checkbox
+    - ✔ Date
+    - ✔ Link
+    - ✔ Status
+    - ✔ Multiple select
+    - ✔ Members
+    - ✔ Tags
+    - 🔥 Timeline
+    - ~~Time~~ (only used in Enterprise)
   - 🔥 Find card by field value, including Custom Fields
   - 🔥 Cache cards to reduce API calls (cards change frequently, so this might be a bad idea anyway)
 - Custom Fields

src/lib/BravoClient.ts

@@ -17,13 +17,7 @@ import { BravoUser } from '$/lib/entities/BravoUser';
 import { BravoOrganization } from '$entities/BravoOrganization';
 import { BravoWidget } from '$entities/BravoWidget.js';
 import type { DataFavroWidget } from '$/types/FavroWidgetTypes.js';
-import type {
-  OptionFavroCollectionVisibility,
-  OptionFavroCollectionColorBackground,
-  OptionFavroCollectionRole,
-  DataAnyEntity,
-  ConstructorFavroEntity,
-} from '$/types/FavroApiTypes';
+import type { FavroApi } from '$/types/FavroApiTypes';
 import type { OptionsBravoCreateWidget } from '$/types/ParameterOptions.js';
 import { BravoColumn } from './entities/BravoColumn.js';
 import type { DataFavroColumn } from '$/types/FavroColumnTypes.js';
@@ -42,7 +36,13 @@ import type { FavroResponse } from './clientLib/FavroResponse.js';
 import { readFileSync } from 'fs';
 import { basename } from 'path';
 import { BravoTagDefinition } from './entities/BravoTag.js';
-import type { FavroDataTypes } from '$/types/FavroTagTypes.js';
+import type { FavroApiData } from '$/types/FavroTagTypes.js';
+import type { BravoEntity } from './BravoEntity.js';
+
+type ConstructorFavroEntity<EntityData extends Record<string, any>> = new (
+  client: BravoClient,
+  data: EntityData,
+) => BravoEntity<EntityData>;
 
 /**
  * The `BravoClient` class should be singly-instanced for a given
@@ -70,7 +70,9 @@ export class BravoClient extends FavroClient {
   //#region Organizations
   private cache = new BravoClientCache();
 
-  private async requestWithReturnedEntities<EntityData extends DataAnyEntity>(
+  private async requestWithReturnedEntities<
+    EntityData extends Record<string, any>,
+  >(
     url: string,
     options: OptionsFavroRequest,
     entityClass: ConstructorFavroEntity<EntityData>,
@@ -181,12 +183,12 @@ export class BravoClient extends FavroClient {
   async createCollection(
     name: string,
     options?: {
-      publicSharing?: OptionFavroCollectionVisibility;
-      background?: OptionFavroCollectionColorBackground;
+      publicSharing?: FavroApi.Collection.FieldTypes.Visibility;
+      background?: FavroApi.Collection.FieldTypes.ColorBackground;
       sharedToUsers?: {
         email?: string;
         userId?: string;
-        role: OptionFavroCollectionRole;
+        role: FavroApi.Collection.FieldTypes.Role;
       }[];
     },
   ) {
@@ -233,7 +235,7 @@ export class BravoClient extends FavroClient {
    * Returns the cached result of the first call until
    * the cache is cleared.
    * (Does not include archived)
-   * {@link https://favro.com/developer/#get-all-collections}
+   * {@see https://favro.com/developer/#get-all-collections }
    */
   async listCollections() {
     const org = await this.getCurrentOrganization();
@@ -657,7 +659,7 @@ export class BravoClient extends FavroClient {
         { method: 'get' },
         BravoTagDefinition,
       )) as BravoResponseEntities<
-        FavroDataTypes.Tag.Definition,
+        FavroApiData.Tag.Definition,
         BravoTagDefinition
       >;
       this.cache.tags = res;
@@ -667,7 +669,7 @@ export class BravoClient extends FavroClient {
 
   async createTagDefinition(
     options: Partial<
-      Omit<FavroDataTypes.Tag.Definition, 'tagId' | 'organizationId'>
+      Omit<FavroApiData.Tag.Definition, 'tagId' | 'organizationId'>
     >,
   ) {
     const res = (await this.requestWithReturnedEntities(
@@ -678,15 +680,15 @@ export class BravoClient extends FavroClient {
       },
       BravoTagDefinition,
     )) as BravoResponseEntities<
-      FavroDataTypes.Tag.Definition,
+      FavroApiData.Tag.Definition,
       BravoTagDefinition
     >;
     return await res.getFirstEntity();
   }
 
   async updateTagDefinition(
     options: RequiredBy<
-      Partial<Omit<FavroDataTypes.Tag.Definition, 'organizationId'>>,
+      Partial<Omit<FavroApiData.Tag.Definition, 'organizationId'>>,
       'tagId'
     >,
   ) {
@@ -698,7 +700,7 @@ export class BravoClient extends FavroClient {
       },
       BravoTagDefinition,
     )) as BravoResponseEntities<
-      FavroDataTypes.Tag.Definition,
+      FavroApiData.Tag.Definition,
       BravoTagDefinition
     >;
     return await res.getFirstEntity();

src/lib/BravoEntity.ts

@@ -1,10 +1,9 @@
-import type { DataAnyEntity } from '$/types/FavroApiTypes.js';
 import type { BravoClient } from './BravoClient.js';
 
 /**
  * Base class for Favro Entities (wrapping raw API data)
  */
-export abstract class BravoEntity<EntityData extends DataAnyEntity> {
+export abstract class BravoEntity<EntityData extends Record<string, any>> {
   protected _deleted = false;
 
   constructor(protected _client: BravoClient, protected _data: EntityData) {}

src/lib/clientLib/BravoResponse.ts

@@ -5,7 +5,7 @@ import type { DataFavroCustomFieldDefinition } from '$/types/FavroCustomFieldTyp
 import type { DataFavroWidget } from '$/types/FavroWidgetTypes.js';
 import type { BravoWidget } from '$entities/BravoWidget.js';
 import type { BravoCustomFieldDefinition } from '../entities/BravoCustomField.js';
-import type { FavroDataTypes } from '$/types/FavroTagTypes.js';
+import type { FavroApiData } from '$/types/FavroTagTypes.js';
 import type { BravoTagDefinition } from '../entities/BravoTag.js';
 
 export type BravoResponseWidgets = BravoResponseEntities<
@@ -19,7 +19,7 @@ export type BravoResponseCustomFields = BravoResponseEntities<
 >;
 
 export type BravoResponseTags = BravoResponseEntities<
-  FavroDataTypes.Tag.Definition,
+  FavroApiData.Tag.Definition,
   BravoTagDefinition
 >;
 

src/lib/clientLib/FavroClient.ts

@@ -1,13 +1,12 @@
 import { assertBravoClaim, BravoError } from '$lib/errors.js';
 import fetch from 'node-fetch';
 import { URL } from 'url';
-import type {
-  DataAnyEntity,
-  OptionFavroHttpMethod,
-} from '$/types/FavroApiTypes';
+import type { FavroApi } from '$/types/FavroApiTypes';
 import { FavroResponse } from '$lib/clientLib/FavroResponse';
 import { toBase64 } from '$lib/utility.js';
 
+type OptionFavroHttpMethod = 'get' | 'post' | 'put' | 'delete';
+
 export interface OptionsFavroRequest {
   method?: OptionFavroHttpMethod;
   query?: Record<string, any>;
@@ -136,7 +135,7 @@ export class FavroClient {
    *
    * @param url Relative to the base URL {@link https://favro.com/api/v1}
    */
-  async request<EntityData extends DataAnyEntity | null = null>(
+  async request<EntityData extends Record<string, any> | null = null>(
     url: string,
     options?: OptionsFavroRequest,
   ): Promise<FavroResponse<EntityData, this>> {

src/lib/clientLib/FavroResponse.ts

@@ -1,9 +1,6 @@
 import type { Response } from 'node-fetch';
 import { URL } from 'url';
-import type {
-  DataFavroResponse,
-  DataFavroResponsePaged,
-} from '$/types/FavroApiTypes';
+import type { FavroApi } from '$/types/FavroApiTypes';
 import { BravoError } from '../errors.js';
 import type { FavroClient } from './FavroClient.js';
 
@@ -16,7 +13,7 @@ export class FavroResponse<
    * If not defined, have not tried to obtain the body.
    * If null, have tried to obtain, but there wasn't one.
    */
-  private _parsedBody?: null | undefined | DataFavroResponse<DataEntity>;
+  private _parsedBody?: null | undefined | FavroApi.Response<DataEntity>;
 
   constructor(protected _client: Client, protected _response: Response) {}
 
@@ -63,7 +60,7 @@ export class FavroResponse<
       return;
     }
     const body =
-      (await this.getParsedBody()) as DataFavroResponsePaged<DataEntity>;
+      (await this.getParsedBody()) as FavroApi.ResponsePaged<DataEntity>;
     const urlInst = new URL(this._response.url);
     urlInst.searchParams.set('requestId', body.requestId);
     urlInst.searchParams.set('page', `${body.page + 1}`);
@@ -82,11 +79,11 @@ export class FavroResponse<
       this._parsedBody = null;
       return this._parsedBody;
     }
-    let responseBody: string | DataFavroResponse<DataEntity> = (
+    let responseBody: string | FavroApi.Response<DataEntity> = (
       await this._response.buffer()
     ).toString('utf8');
     try {
-      responseBody = JSON.parse(responseBody) as DataFavroResponse<DataEntity>;
+      responseBody = JSON.parse(responseBody) as FavroApi.Response<DataEntity>;
       this._parsedBody = responseBody;
       return this._parsedBody;
     } catch {

src/lib/entities/BravoCollection.ts

@@ -1,9 +1,9 @@
 import { BravoEntity } from '../BravoEntity.js';
 import type { BravoWidget } from './BravoWidget.js';
-import type { DataFavroCollection } from '$/types/FavroApiTypes';
+import type { FavroApi } from '$/types/FavroApiTypes';
 import type { OptionsBravoCreateWidget } from '$/types/ParameterOptions.js';
 
-export class BravoCollection extends BravoEntity<DataFavroCollection> {
+export class BravoCollection extends BravoEntity<FavroApi.Collection.Data> {
   get name() {
     return this._data.name;
   }

src/lib/entities/BravoOrganization.ts

@@ -1,8 +1,8 @@
-import type { DataFavroOrganization } from '$types/FavroApiTypes';
+import type { FavroApi } from '$types/FavroApiTypes';
 import { BravoEntity } from '$lib/BravoEntity.js';
 
 /** Hydrated Favro Organization. */
-export class BravoOrganization extends BravoEntity<DataFavroOrganization> {
+export class BravoOrganization extends BravoEntity<FavroApi.Organization.Data> {
   get name() {
     return this._data.name;
   }

src/lib/entities/BravoTag.ts

@@ -1,8 +1,8 @@
-import type { FavroDataTypes } from '$/types/FavroTagTypes.js';
+import type { FavroApiData } from '$/types/FavroTagTypes.js';
 import { BravoEntity } from '$lib/BravoEntity.js';
 
 /** Hydrated Favro Organization. */
-export class BravoTagDefinition extends BravoEntity<FavroDataTypes.Tag.Definition> {
+export class BravoTagDefinition extends BravoEntity<FavroApiData.Tag.Definition> {
   get name() {
     return this._data.name;
   }

src/lib/entities/BravoUser.ts

@@ -1,4 +1,4 @@
-import type { DataFavroUser } from '$types/FavroApiTypes';
+import type { FavroApi } from '$types/FavroApiTypes';
 import { BravoEntity } from '$lib/BravoEntity.js';
 
 /**
@@ -22,7 +22,7 @@ class BravoUserBase<
  * A hydrated User entity, as returned from the Users API
  * endpoint.
  */
-export class BravoUser extends BravoUserBase<DataFavroUser> {
+export class BravoUser extends BravoUserBase<FavroApi.User.Data> {
   get name() {
     return this._data.name;
   }