@divyacon/piece-trello 0.0.0-stage → 0.1.0

package/src/lib/actions/ai/list-cards-in-board.ts

@@ -0,0 +1,70 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+  QueryParams,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { listCardsInBoardActionOutputSchema } from '../../output-schemas';
+
+export const listCardsInBoard = createAction({
+  auth: trelloAuth,
+  name: 'list_cards_in_board',
+  displayName: 'List Cards In Board (Agent)',
+  description: 'List all cards on a Trello board.',
+  audience: 'ai',
+  outputSchema: listCardsInBoardActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Lists every card on a Trello board identified by board_id, returning each card id and fields. Use it to enumerate all cards across a board. Obtain board_id from List Boards. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    board_id: Property.ShortText({
+      displayName: 'Board ID',
+      description: 'The ID of the board. Obtain it from List Boards.',
+      required: true,
+    }),
+    filter: Property.StaticDropdown({
+      displayName: 'Filter',
+      description: 'Which cards to include.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Closed (archived)', value: 'closed' },
+          { label: 'All', value: 'all' },
+          { label: 'Visible', value: 'visible' },
+        ],
+      },
+    }),
+  },
+
+  async run(context) {
+    const params: QueryParams = {};
+    if (context.propsValue['filter']) {
+      params['filter'] = context.propsValue['filter'] as string;
+    }
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.GET,
+        url: `${trelloCommon.baseUrl}boards/${context.propsValue['board_id']}/cards`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, params),
+      };
+      const response = await httpClient.sendRequest<
+        Array<Record<string, unknown>>
+      >(request);
+      const cards = response.body ?? [];
+      return { cards, count: cards.length };
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Board not found. Verify the board_id (resolve it via List Boards).'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/list-cards-in-list.ts

@@ -0,0 +1,69 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+  QueryParams,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { listCardsInListActionOutputSchema } from '../../output-schemas';
+
+export const listCardsInList = createAction({
+  auth: trelloAuth,
+  name: 'list_cards_in_list',
+  displayName: 'List Cards In List (Agent)',
+  description: 'List all cards in a Trello list.',
+  audience: 'ai',
+  outputSchema: listCardsInListActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Lists the cards in a single Trello list identified by list_id, returning each card id and fields. Use it to enumerate the cards of a column (e.g. "what is in To Do"). Obtain list_id from List Lists. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    list_id: Property.ShortText({
+      displayName: 'List ID',
+      description: 'The ID of the list. Obtain it from List Lists.',
+      required: true,
+    }),
+    filter: Property.StaticDropdown({
+      displayName: 'Filter',
+      description: 'Which cards to include.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Closed (archived)', value: 'closed' },
+          { label: 'All', value: 'all' },
+        ],
+      },
+    }),
+  },
+
+  async run(context) {
+    const params: QueryParams = {};
+    if (context.propsValue['filter']) {
+      params['filter'] = context.propsValue['filter'] as string;
+    }
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.GET,
+        url: `${trelloCommon.baseUrl}lists/${context.propsValue['list_id']}/cards`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, params),
+      };
+      const response = await httpClient.sendRequest<
+        Array<Record<string, unknown>>
+      >(request);
+      const cards = response.body ?? [];
+      return { cards, count: cards.length };
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'List not found. Verify the list_id (resolve it via List Lists).'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/list-lists.ts

@@ -0,0 +1,69 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+  QueryParams,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { listListsActionOutputSchema } from '../../output-schemas';
+
+export const listLists = createAction({
+  auth: trelloAuth,
+  name: 'list_lists',
+  displayName: 'List Lists (Agent)',
+  description: 'List the lists (columns) on a Trello board.',
+  audience: 'ai',
+  outputSchema: listListsActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Lists the lists (columns) on a Trello board, returning each list id and name. This is the key resolver for turning a column name into a list_id used by Create Card, Move Card, and other list actions. Obtain board_id from List Boards. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    board_id: Property.ShortText({
+      displayName: 'Board ID',
+      description: 'The ID of the board. Obtain it from List Boards.',
+      required: true,
+    }),
+    filter: Property.StaticDropdown({
+      displayName: 'Filter',
+      description: 'Which lists to include.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Closed (archived)', value: 'closed' },
+          { label: 'All', value: 'all' },
+        ],
+      },
+    }),
+  },
+
+  async run(context) {
+    const params: QueryParams = {};
+    if (context.propsValue['filter']) {
+      params['filter'] = context.propsValue['filter'] as string;
+    }
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.GET,
+        url: `${trelloCommon.baseUrl}boards/${context.propsValue['board_id']}/lists`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, params),
+      };
+      const response = await httpClient.sendRequest<
+        Array<Record<string, unknown>>
+      >(request);
+      const lists = response.body ?? [];
+      return { lists, count: lists.length };
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Board not found. Verify the board_id (resolve it via List Boards).'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/list-organization-boards.ts

@@ -0,0 +1,53 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { listOrganizationBoardsActionOutputSchema } from '../../output-schemas';
+
+export const listOrganizationBoards = createAction({
+  auth: trelloAuth,
+  name: 'list_organization_boards',
+  displayName: 'List Organization Boards (Agent)',
+  description: 'List the boards in a Trello workspace.',
+  audience: 'ai',
+  outputSchema: listOrganizationBoardsActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Lists the boards in a Trello workspace (organization), returning each board id and name. Use it when you have an org_id and want only that workspace\'s boards; for all boards you can access, use List Boards instead. Obtain org_id from Get My Member or List Boards. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    org_id: Property.ShortText({
+      displayName: 'Organization ID',
+      description:
+        'The workspace (organization) id. Obtain it from Get My Member or a board\'s details.',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.GET,
+        url: `${trelloCommon.baseUrl}organizations/${context.propsValue['org_id']}/boards`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth),
+      };
+      const response = await httpClient.sendRequest<
+        Array<Record<string, unknown>>
+      >(request);
+      const boards = response.body ?? [];
+      return { boards, count: boards.length };
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Organization not found. Verify the org_id.'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/move-all-cards-in-list.ts

@@ -0,0 +1,61 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+
+export const moveAllCardsInList = createAction({
+  auth: trelloAuth,
+  name: 'move_all_cards_in_list',
+  displayName: 'Move All Cards In List (Agent)',
+  description: 'Move every card from one Trello list to another.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Moves every card from a source list to a destination list (e.g. clear a "Done" column into an "Archive" list). Obtain board_id from List Boards and both list ids from List Lists; the destination list must be on the given board. This is a bulk mutation, so it is not idempotent.',
+    idempotent: false,
+  },
+  props: {
+    list_id: Property.ShortText({
+      displayName: 'Source List ID',
+      description: 'The list to move all cards from. Obtain it from List Lists.',
+      required: true,
+    }),
+    board_id: Property.ShortText({
+      displayName: 'Destination Board ID',
+      description:
+        'The board the destination list belongs to. Obtain it from List Boards.',
+      required: true,
+    }),
+    destination_list_id: Property.ShortText({
+      displayName: 'Destination List ID',
+      description: 'The list to move all cards into. Obtain it from List Lists.',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.POST,
+        url: `${trelloCommon.baseUrl}lists/${context.propsValue['list_id']}/moveAllCards`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, {
+          idBoard: context.propsValue['board_id'],
+          idList: context.propsValue['destination_list_id'],
+        }),
+      };
+      const response = await httpClient.sendRequest(request);
+      return response.body;
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'A list or board was not found. Verify the source list_id, destination board_id, and destination list_id.'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/move-card.ts

@@ -0,0 +1,57 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { moveCardActionOutputSchema } from '../../output-schemas';
+
+export const moveCard = createAction({
+  auth: trelloAuth,
+  name: 'move_card',
+  displayName: 'Move Card (Agent)',
+  description: 'Move a Trello card to a different list.',
+  audience: 'ai',
+  outputSchema: moveCardActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Moves a Trello card to a different list (the high-intent single-purpose alternative to Update Card). Obtain card_id from Search Cards and the destination list_id from List Lists. Moving to the list it is already in converges to the same state, so it is idempotent.',
+    idempotent: true,
+  },
+  props: {
+    card_id: Property.ShortText({
+      displayName: 'Card ID',
+      description: 'The ID of the card to move. Obtain it from Search Cards.',
+      required: true,
+    }),
+    list_id: Property.ShortText({
+      displayName: 'Destination List ID',
+      description:
+        'The list to move the card into. Obtain it from List Lists.',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.PUT,
+        url: `${trelloCommon.baseUrl}cards/${context.propsValue['card_id']}/idList`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, {
+          value: context.propsValue['list_id'],
+        }),
+      };
+      const response = await httpClient.sendRequest(request);
+      return response.body;
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Card or list not found. Verify the card_id and list_id (resolve via Search Cards / List Lists).'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/remove-label-from-card.ts

@@ -0,0 +1,53 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+
+export const removeLabelFromCard = createAction({
+  auth: trelloAuth,
+  name: 'remove_label_from_card',
+  displayName: 'Remove Label From Card (Agent)',
+  description: 'Detach a label from a Trello card.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Detaches a label from a Trello card. Obtain card_id from Search Cards and label_id from Get Card or List Board Labels. Removing an already-absent label converges to the same state, so it is idempotent.',
+    idempotent: true,
+  },
+  props: {
+    card_id: Property.ShortText({
+      displayName: 'Card ID',
+      description: 'The ID of the card. Obtain it from Search Cards.',
+      required: true,
+    }),
+    label_id: Property.ShortText({
+      displayName: 'Label ID',
+      description:
+        'The label id to detach. Obtain it from Get Card or List Board Labels.',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.DELETE,
+        url: `${trelloCommon.baseUrl}cards/${context.propsValue['card_id']}/idLabels/${context.propsValue['label_id']}`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth),
+      };
+      const response = await httpClient.sendRequest(request);
+      return response.body;
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Card or label not found. Verify the card_id and label_id.'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/remove-member-from-card.ts

@@ -0,0 +1,55 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { removeMemberFromCardActionOutputSchema } from '../../output-schemas';
+
+export const removeMemberFromCard = createAction({
+  auth: trelloAuth,
+  name: 'remove_member_from_card',
+  displayName: 'Remove Member From Card (Agent)',
+  description: 'Unassign a member from a Trello card.',
+  audience: 'ai',
+  outputSchema: removeMemberFromCardActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Unassigns a member from a Trello card. Obtain card_id from Search Cards and member_id from List Card Members. Removing an already-absent member converges to the same state, so it is idempotent.',
+    idempotent: true,
+  },
+  props: {
+    card_id: Property.ShortText({
+      displayName: 'Card ID',
+      description: 'The ID of the card. Obtain it from Search Cards.',
+      required: true,
+    }),
+    member_id: Property.ShortText({
+      displayName: 'Member ID',
+      description:
+        'The member id to unassign. Obtain it from List Card Members.',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.DELETE,
+        url: `${trelloCommon.baseUrl}cards/${context.propsValue['card_id']}/idMembers/${context.propsValue['member_id']}`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth),
+      };
+      const response = await httpClient.sendRequest(request);
+      return response.body;
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'Card or member not found. Verify the card_id and member_id.'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/rename-list.ts

@@ -0,0 +1,55 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { withAuthParams, rethrowTrelloError } from './ai-common';
+import { renameListActionOutputSchema } from '../../output-schemas';
+
+export const renameList = createAction({
+  auth: trelloAuth,
+  name: 'rename_list',
+  displayName: 'Rename List (Agent)',
+  description: 'Rename a Trello list.',
+  audience: 'ai',
+  outputSchema: renameListActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Renames a Trello list identified by list_id. Obtain list_id from List Lists. Setting the same name again converges to the same list, so it is idempotent.',
+    idempotent: true,
+  },
+  props: {
+    list_id: Property.ShortText({
+      displayName: 'List ID',
+      description: 'The ID of the list. Obtain it from List Lists.',
+      required: true,
+    }),
+    name: Property.ShortText({
+      displayName: 'New Name',
+      required: true,
+    }),
+  },
+
+  async run(context) {
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.PUT,
+        url: `${trelloCommon.baseUrl}lists/${context.propsValue['list_id']}/name`,
+        headers: { Accept: 'application/json' },
+        queryParams: withAuthParams(context.auth, {
+          value: context.propsValue['name'],
+        }),
+      };
+      const response = await httpClient.sendRequest(request);
+      return response.body;
+    } catch (error: any) {
+      rethrowTrelloError(
+        error,
+        'List not found. Verify the list_id (resolve it via List Lists).'
+      );
+    }
+  },
+});

package/src/lib/actions/ai/search-cards.ts

@@ -0,0 +1,91 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpRequest,
+  HttpMethod,
+  QueryParams,
+} from '@agnocon/pieces-common';
+import { trelloCommon } from '../../common';
+import { trelloAuth } from '../../..';
+import { searchCardsActionOutputSchema } from '../../output-schemas';
+
+export const searchCards = createAction({
+  auth: trelloAuth,
+  name: 'search_cards',
+  displayName: 'Search Cards (Agent)',
+  description: 'Full-text search for Trello cards.',
+  audience: 'ai',
+  outputSchema: searchCardsActionOutputSchema,
+  aiMetadata: {
+    description:
+      'Searches Trello cards by free-text query (name, description, comments) and returns matching cards with their ids. This is the primary way to resolve a card from text before acting on it; results are best-effort/eventually-consistent, so hydrate full fields via Get Card. Optionally narrow to specific boards or a list. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    query: Property.ShortText({
+      displayName: 'Query',
+      description: 'The search text to match against cards.',
+      required: true,
+    }),
+    board_ids: Property.Array({
+      displayName: 'Board IDs',
+      description:
+        'Restrict the search to these board ids (obtain from List Boards). Leave empty to search all boards you can access.',
+      required: false,
+    }),
+    list_id: Property.ShortText({
+      displayName: 'List ID',
+      description: 'Restrict the search to a single list id.',
+      required: false,
+    }),
+    limit: Property.Number({
+      displayName: 'Limit',
+      description: 'Maximum number of cards to return (1-1000, default 50).',
+      required: false,
+    }),
+  },
+
+  async run(context) {
+    const qs: QueryParams = {
+      query: context.propsValue['query'],
+      modelTypes: 'cards',
+      key: context.auth.username,
+      token: context.auth.password,
+    };
+    const boardIds = context.propsValue['board_ids'] as string[] | undefined;
+    if (boardIds && boardIds.length > 0) {
+      qs['idBoards'] = boardIds.join(',');
+    }
+    if (context.propsValue['list_id']) {
+      qs['idList'] = context.propsValue['list_id'] as string;
+    }
+    if (context.propsValue['limit']) {
+      qs['cards_limit'] = String(context.propsValue['limit']);
+    }
+
+    try {
+      const request: HttpRequest = {
+        method: HttpMethod.GET,
+        url: `${trelloCommon.baseUrl}search`,
+        headers: { Accept: 'application/json' },
+        queryParams: qs,
+      };
+      const response = await httpClient.sendRequest<{
+        cards?: Array<Record<string, unknown>>;
+      }>(request);
+      const cards = response.body.cards ?? [];
+      return { cards, count: cards.length };
+    } catch (error: any) {
+      const status = error?.response?.status;
+      if (status === 401 || status === 403) {
+        throw new Error(
+          'Permission denied searching cards. Check the connection token.'
+        );
+      }
+      if (status === 429) {
+        throw new Error('Trello rate limit exceeded. Retry after a short delay.');
+      }
+      throw error;
+    }
+  },
+});