feat: Add draft type for the body content of a Card update.

README.md

@@ -72,7 +72,8 @@ As environment variables:
   - ✔ List cards
   - ✔ Find card by name
   - ✔ Delete a card (from a board or from EVERYWHERE)
-  - 🔜 Change field values on a card, including Custom Fields
+  - 🔜 Fetch a Card directly by its ID
+  - 🔜 Update a Card, including Custom Fields
   - 🔜 Find card by field value, including Custom Fields
   - ❓ Add an attachment
   - ❓ Cache cards to reduce API calls (cards change frequently, so this might be a bad idea anyway)

src/lib/BravoClient.ts

@@ -30,7 +30,7 @@ import { ArrayMatchFunction } from '$/types/Utility.js';
 import {
   DataFavroCard,
   FavroApiGetCardsParams,
-  FavroApiPostCard,
+  FavroApiParamsCardCreate,
 } from '$/types/FavroCardTypes.js';
 import { BravoCard } from './entities/BravoCard.js';
 import { BravoCustomField } from './entities/BravoCustomField.js';
@@ -489,7 +489,7 @@ export class BravoClient extends FavroClient {
    *
    * {@link https://favro.com/developer/#create-a-card}
    */
-  async createCard(data: FavroApiPostCard) {
+  async createCard(data: FavroApiParamsCardCreate) {
     const res = await this.requestWithReturnedEntities(
       `cards`,
       {

src/test/client.ts

@@ -125,7 +125,7 @@ describe('BravoClient', function () {
     expect(organizations.length).to.be.greaterThan(0);
   });
 
-  it('can find a specific organization and set it as the current one', async function () {
+  it('can find a specific organization', async function () {
     const org = await client.findOrganizationByName(
       process.env.FAVRO_ORGANIZATION_NAME!,
     );

src/types/FavroCardTypes.ts

@@ -2,7 +2,7 @@ import type { OptionWidgetType } from './FavroWidgetTypes.js';
 
 export type OptionFavroDescriptionFormat = 'plaintext' | 'markdown';
 
-export type FavroApiPostCard = Partial<
+export type FavroApiParamsCardCreate = Partial<
   Omit<DataFavroCard, 'cardId' | 'organizationId'>
 > & {
   name: string;
@@ -49,21 +49,21 @@ export type FavroApiGetCardsParams =
 // FOR SETTING VALUES ON A CARD
 
 interface DataFavroCustomFieldMembers {
-  /** The list of members, that will be added to the card custom field (array of userIds). Optional. */
+  /** The list of members, that will be added to the card custom field (array of userIds).*/
   addUserIds: string[];
-  /** The list of members, that will be removed from card custom field (array of userIds). Optional. */
+  /** The list of members, that will be removed from card custom field (array of userIds).*/
   removeUserIds: string[];
-  /** The list of card assignment, that will update their statuses on the custom field accordingly. Optional. */
+  /** The list of card assignment, that will update their statuses on the custom field accordingly.*/
   completeUsers: string[];
 }
 interface DataFavroCustomFieldTags {
-  /** The list of tag names or card tags that will be added to this card custom field. If the tag does not exist in the organization it will be created. Optional. */
+  /** The list of tag names or card tags that will be added to this card custom field. If the tag does not exist in the organization it will be created.*/
   addTags: string[];
-  /** A list of tagIds that will be added to this card custom field. Optional. */
+  /** A list of tagIds that will be added to this card custom field.*/
   addTagIds: string[];
-  /** The list of tag names, that will be removed from this card custom field. Optional. */
+  /** The list of tag names, that will be removed from this card custom field.*/
   removeTags: string[];
-  /** The list of tag IDs, that will be removed from this card custom field. Optional. */
+  /** The list of tag IDs, that will be removed from this card custom field.*/
   removeTagIds: string[];
 }
 
@@ -148,7 +148,7 @@ interface DataFavroCardFieldLink {
   link: {
     /** The url of the field. Required. */
     url: string;
-    /** The display text of the field. Optional. */
+    /** The display text of the field.*/
     text: string;
   };
 }
@@ -316,3 +316,86 @@ export interface DataFavroCard {
   /** The Favro attachments on the card. See card favro attachment. */
   favroAttachments: DataFavroCardFavroAttachment[];
 }
+
+/**
+ * Body parameters for updating a Card.
+ *
+ * Note that `cardId` must be specified in the URL,
+ * and `descriptionFormat` should be set to `'markdown'`
+ * in the query params so that the returned result will
+ * have a Markdown body.
+ *
+ * {@link https://favro.com/developer/#update-a-card}
+ */
+export interface FavroApiParamsCardUpdate {
+  /** The name of the card. */
+  name?: string;
+  /** The detailed description of the card. Supports formatting. */
+  detailedDescription?: string;
+  /** The widgetCommonId to commit the card in (if adding to a Widget). */
+  widgetCommonId?: string;
+  /** The columnId to commit the card in. It must belong to the widget specified in the widgetCommonId parameter. */
+  columnId?: string;
+  /** The laneId to commit the card in. This is only applicable if creating the card on a widget that has lanes enabled. */
+  laneId?: string;
+  /** The id of the parent card in the card hierarchy (sheet or card list), where the card will be commited. It must belong to the widget specified in the widgetCommonId parameter. */
+  parentCardId?: string;
+  /** 'commit' to commit card, 'move' to move card. 'commit' by default. */
+  dragMode?: 'commit' | 'move';
+  /**
+   * @deprecated
+   * Mapped to listPosition for right-pane widgets, and to sheetPosition for left-pane widgets.
+   */
+  position?: number;
+  /** New position of the card in a column on a Kanban board, or in a todo list. */
+  listPosition?: number;
+  /** New position of the card in a hierarchical view (sheet or card list).*/
+  sheetPosition?: number;
+  /** The list of assignments, that will be added to card (array of userIds).*/
+  addAssignmentIds?: string[];
+  /** The list of assignments, that will be removed from card (array of userIds).*/
+  removeAssignmentIds?: string[];
+  /** The list of card assignment, that will update their statuses accordingly.*/
+  completeAssignments?: string[];
+  /** The list of tag names or card tags that will be added to the card. If the tag does not exist in the organization it will be created.*/
+  addTags?: string[];
+  /** A list of tagIds that will be added to card.*/
+  addTagIds?: string[];
+  /** The list of tag names, that will be removed from card.*/
+  removeTags?: string[];
+  /** The list of tag IDs, that will be removed from card.*/
+  removeTagIds?: string[];
+  /** The start date of card. Format ISO-8601. If null, start date will be removed.*/
+  startDate?: string;
+  /** The due date of card. Format ISO-8601. If null, due date will be removed.*/
+  dueDate?: string;
+  /** The list of card tasklists, that will be added to card.*/
+  addTasklists?: {
+    name: string;
+    tasks: (string | { name: string; completed?: boolean })[];
+  }[];
+  /**
+   * The list of card attachments URLs, that will be removed from the card.
+   *
+   * @note Unclear what URL is being referenced here. Best guess is the
+   * `fileURL` field from an attachment object.
+   */
+  removeAttachments?: string[];
+  /**
+   * The list of card custom field parameters, that will be added or modified.
+   *
+   * // TODO
+   */
+  customFields?: unknown[];
+  /** The list of card favro attachment that will be added to the card.*/
+  addFavroAttachments?: DataFavroCardFavroAttachment[];
+  /**
+   * The list of cardCommonId and widgetCommonId of card
+   * favro attachment, that will be removed from the card.
+   *
+   * @note Presumably this is the `itemCommonId` field value
+   */
+  removeFavroAttachmentIds?: string[];
+  /** Archive or unarchive card.*/
+  archive: boolean;
+}