feat: Restructure Widget types into the new namespaced FavroApi typin…

…gs. BREAKING

src/lib/BravoClient.ts

@@ -16,9 +16,7 @@ import { BravoCollection } from './entities/BravoCollection';
 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 { FavroApi } from '$favro';
-import type { OptionsBravoCreateWidget } from '$/types/ParameterOptions.js';
 import { BravoColumn } from './entities/BravoColumn.js';
 import type { DataFavroColumn } from '$/types/FavroColumnTypes.js';
 import type { ArrayMatchFunction, RequiredBy } from '$/types/Utility.js';
@@ -312,7 +310,7 @@ export class BravoClient extends FavroClient {
         'widgets',
         { method: 'get', query: { collectionId } },
         BravoWidget,
-      )) as BravoResponseEntities<DataFavroWidget, BravoWidget>;
+      )) as BravoResponseEntities<FavroApi.Widget.Data, BravoWidget>;
       this.cache.setWidgets(res, collectionId);
     }
     return this.cache.getWidgets(collectionId)!;
@@ -326,7 +324,7 @@ export class BravoClient extends FavroClient {
   async createWidget(
     collectionId: string,
     name: string,
-    options?: OptionsBravoCreateWidget,
+    options?: Omit<FavroApi.Widget.Create, 'collectionId'>,
   ) {
     const res = await this.requestWithReturnedEntities(
       `widgets`,

src/lib/clientLib/BravoResponse.ts

@@ -2,14 +2,13 @@ import type { BravoClient } from '$lib/BravoClient';
 import type { BravoEntity } from '$lib/BravoEntity';
 import type { FavroResponse } from './FavroResponse';
 import type { DataFavroCustomFieldDefinition } from '$/types/FavroCustomFieldTypes.js';
-import type { DataFavroWidget } from '$/types/FavroWidgetTypes.js';
 import type { BravoWidget } from '$entities/BravoWidget.js';
 import type { BravoCustomFieldDefinition } from '../entities/BravoCustomField.js';
 import type { FavroApi } from '$favro';
 import type { BravoTagDefinition } from '../entities/BravoTag.js';
 
 export type BravoResponseWidgets = BravoResponseEntities<
-  DataFavroWidget,
+  FavroApi.Widget.Data,
   BravoWidget
 >;
 

src/lib/entities/BravoCollection.ts

@@ -1,7 +1,6 @@
 import { BravoEntity } from '../BravoEntity.js';
 import type { BravoWidget } from './BravoWidget.js';
 import type { FavroApi } from '$favro';
-import type { OptionsBravoCreateWidget } from '$/types/ParameterOptions.js';
 
 export class BravoCollection extends BravoEntity<FavroApi.Collection.Data> {
   get name() {
@@ -16,7 +15,10 @@ export class BravoCollection extends BravoEntity<FavroApi.Collection.Data> {
     return this._data.organizationId;
   }
 
-  async createWidget(name: string, options?: OptionsBravoCreateWidget) {
+  async createWidget(
+    name: string,
+    options?: Omit<FavroApi.Widget.Create, 'collectionId'>,
+  ) {
     return await this._client.createWidget(this.collectionId, name, options);
   }
 

src/lib/entities/BravoWidget.ts

@@ -1,6 +1,6 @@
 import { BravoEntity } from '$lib/BravoEntity.js';
-import { selectRandom, stringsMatch } from '$lib/utility.js';
-import type { DataFavroWidget } from '$types/FavroWidgetTypes.js';
+import { stringsMatch } from '$lib/utility.js';
+import type { FavroApi } from '$favro';
 import type { BravoColumn } from './BravoColumn.js';
 import type { ArrayMatchFunction } from '$/types/Utility.js';
 import type {
@@ -9,9 +9,7 @@ import type {
 } from '$/types/FavroCardTypes.js';
 import type { BravoCardInstance } from './BravoCard.js';
 
-export type OptionWidgetColor = typeof BravoWidget['colors'][number];
-
-export class BravoWidget extends BravoEntity<DataFavroWidget> {
+export class BravoWidget extends BravoEntity<FavroApi.Widget.Data> {
   get widgetCommonId() {
     return this._data.widgetCommonId;
   }
@@ -129,24 +127,4 @@ export class BravoWidget extends BravoEntity<DataFavroWidget> {
       this.widgetCommonId === widget.widgetCommonId
     );
   }
-
-  /** Allowed colors for Widgets */
-  static get colors() {
-    return [
-      'blue',
-      'lightgreen',
-      'brown',
-      'purple',
-      'orange',
-      'yellow',
-      'gray',
-      'red',
-      'cyan',
-      'green',
-    ] as const;
-  }
-  /** Choose a random color useable by Widgets */
-  static getRandomColor() {
-    return selectRandom(BravoWidget.colors);
-  }
 }

src/test/client.test.ts

@@ -299,7 +299,7 @@ describe('BravoClient', function () {
 
     it('can create a widget', async function () {
       testWidget = await testCollection.createWidget(testWidgetName, {
-        color: 'cyan',
+        color: 'purple',
       });
       expect(testWidget, 'Should be able to create widget').to.exist;
     });

src/types/FavroApi.ts

@@ -163,4 +163,62 @@ export namespace FavroApi {
       color: FieldTypes.Color;
     }
   }
+
+  /**
+   * Favro API Data models for Widgets (a.k.a. "Boards")
+   */
+  export namespace Widget {
+    /**
+     * Helper types for the values of {@link Widget.Data} fields.
+     */
+    export namespace FieldTypes {
+      export type Color =
+        | 'blue'
+        | 'lightgreen'
+        | 'brown'
+        | 'purple'
+        | 'orange'
+        | 'yellow'
+        | 'gray'
+        | 'red'
+        | 'cyan'
+        | 'green';
+
+      export type Type = 'backlog' | 'board';
+      export type Role = 'owners' | 'fullMembers' | 'guests';
+    }
+
+    /**
+     * The data model for a Widget returned from the Favro API.
+     */
+    export interface Data {
+      /** The shared id of the widget. */
+      widgetCommonId: string;
+      /** The id of the organization that this widget exists in. */
+      organizationId: string;
+      /** The ids of the collections that this widget exists in. This array will only contain collections that the user has access to. */
+      collectionIds: string[];
+      /** The name of the widget. */
+      name: string;
+      /** The type of the widget. */
+      type: FieldTypes.Type;
+      /** If set, this means that this widget is a breakdown of a card. */
+      breakdownCardCommonId: string;
+      /** The color of the widget icon. Refer to widget colors. */
+      color: FieldTypes.Color;
+      /** The users that have ownership of the widget. */
+      ownerRole: FieldTypes.Role;
+      /** The users that can add, edit and move cards on the widget. */
+      editRole: FieldTypes.Role;
+    }
+
+    /**
+     * The data model for the request body when creating a widget.
+     *
+     * See {@link https://favro.com/developer/#update-a-widget}
+     */
+    export type Create = { collectionId: string } & Partial<
+      Pick<Data, 'name' | 'type' | 'color' | 'ownerRole' | 'editRole'>
+    >;
+  }
 }

src/types/FavroCardTypes.ts

@@ -1,4 +1,4 @@
-import type { OptionWidgetType } from './FavroWidgetTypes.js';
+import type { FavroApi } from '$favro';
 
 export type OptionFavroDescriptionFormat = 'plaintext' | 'markdown';
 
@@ -216,7 +216,7 @@ export interface DataFavroCardFavroAttachment {
    * The cardCommonId of card or widgetCommonId of widget that
    * is linked to the card. */
   itemCommonId: string;
-  type: 'card' | OptionWidgetType;
+  type: 'card' | FavroApi.Widget.FieldTypes.Type;
 }
 
 /**