@agnocon/piece-canny 0.1.6

package/src/lib/actions/delete-vote.ts

@@ -0,0 +1,39 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+
+import { cannyAuth } from '../auth';
+import { cannyRequest } from '../common/client';
+
+export const deleteVoteAction = createAction({
+  auth: cannyAuth,
+  name: 'delete_vote',
+  displayName: 'Delete Vote',
+  description: 'Removes a vote from a post for a given user.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      "Removes a specific user's vote from a Canny post. Use to retract support previously registered for a post. Requires the post ID and the voter Canny user ID. Idempotent: removing an already-absent vote leaves the post in the same state.",
+    idempotent: true,
+  },
+  props: {
+    postID: Property.ShortText({
+      displayName: 'Post ID',
+      description: 'The unique identifier of the post to remove the vote from.',
+      required: true,
+    }),
+    voterID: Property.ShortText({
+      displayName: 'Voter ID',
+      description: 'The unique identifier of the voter (Canny user ID).',
+      required: true,
+    }),
+  },
+  async run({ auth, propsValue }) {
+    return await cannyRequest({
+      apiKey: auth.secret_text,
+      path: '/votes/delete',
+      body: {
+        postID: propsValue.postID,
+        voterID: propsValue.voterID,
+      },
+    });
+  },
+});

package/src/lib/actions/list-posts.ts

@@ -0,0 +1,99 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+
+import { cannyAuth } from '../auth';
+import { cannyRequest, cleanBody } from '../common/client';
+
+export const listPostsAction = createAction({
+  auth: cannyAuth,
+  name: 'list_posts',
+  displayName: 'List Posts',
+  description: 'Returns a list of posts for a board, with optional filtering and sorting.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Lists Canny posts, optionally scoped to one board or queried across all boards when no board is given, with optional search text, status filter, sort order, and pagination (limit/skip). Use to discover or search posts rather than fetch one known post by ID. Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    boardID: Property.Dropdown({
+      auth: cannyAuth,
+      displayName: 'Board',
+      description: 'The board to list posts for (optional — omit to list across all boards).',
+      required: false,
+      refreshers: [],
+      options: async ({ auth }) => {
+        if (!auth) {
+          return {
+            disabled: true,
+            placeholder: 'Connect your Canny account first.',
+            options: [],
+          };
+        }
+
+        const response = await cannyRequest<{
+          boards: Array<{ id: string; name: string }>;
+        }>({
+          apiKey: auth.secret_text,
+          path: '/boards/list',
+        });
+
+        return {
+          disabled: false,
+          options: (response.boards ?? []).map((b) => ({
+            label: b.name,
+            value: b.id,
+          })),
+        };
+      },
+    }),
+    search: Property.ShortText({
+      displayName: 'Search',
+      description: 'A search query to filter posts.',
+      required: false,
+    }),
+    sort: Property.StaticDropdown({
+      displayName: 'Sort',
+      description: 'The order of returned posts.',
+      required: false,
+      options: {
+        disabled: false,
+        options: [
+          { label: 'Newest', value: 'newest' },
+          { label: 'Oldest', value: 'oldest' },
+          { label: 'Score', value: 'score' },
+          { label: 'Trending', value: 'trending' },
+          { label: 'Status Changed', value: 'statusChanged' },
+        ],
+      },
+    }),
+    status: Property.ShortText({
+      displayName: 'Status',
+      description: 'Comma-separated list of statuses to filter by (e.g. "open,planned").',
+      required: false,
+    }),
+    limit: Property.Number({
+      displayName: 'Limit',
+      description: 'Number of posts to fetch (default 10).',
+      required: false,
+    }),
+    skip: Property.Number({
+      displayName: 'Skip',
+      description: 'Number of posts to skip (for pagination).',
+      required: false,
+    }),
+  },
+  async run({ auth, propsValue }) {
+    return await cannyRequest({
+      apiKey: auth.secret_text,
+      path: '/posts/list',
+      body: cleanBody({
+        boardID: propsValue.boardID,
+        search: propsValue.search,
+        sort: propsValue.sort,
+        status: propsValue.status,
+        limit: propsValue.limit,
+        skip: propsValue.skip,
+      }),
+    });
+  },
+});

package/src/lib/actions/retrieve-post.ts

@@ -0,0 +1,31 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+
+import { cannyAuth } from '../auth';
+import { cannyRequest } from '../common/client';
+
+export const retrievePostAction = createAction({
+  auth: cannyAuth,
+  name: 'retrieve_post',
+  displayName: 'Retrieve Post',
+  description: 'Retrieves the details of an existing post by its ID.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Looks up a single Canny post by its unique post ID and returns its full details. Use when you already have a post ID and need its current data (status, score, author, board). Read-only and idempotent.',
+    idempotent: true,
+  },
+  props: {
+    id: Property.ShortText({
+      displayName: 'Post ID',
+      description: 'The unique identifier of the post.',
+      required: true,
+    }),
+  },
+  async run({ auth, propsValue }) {
+    return await cannyRequest({
+      apiKey: auth.secret_text,
+      path: '/posts/retrieve',
+      body: { id: propsValue.id },
+    });
+  },
+});

package/src/lib/auth.ts

@@ -0,0 +1,34 @@
+import { PieceAuth } from '@agnocon/pieces-framework';
+
+import { cannyRequest } from './common/client';
+
+export const cannyAuth = PieceAuth.SecretText({
+  displayName: 'API Key',
+  description:
+    'Your Canny secret API key. Find it at Settings → API in your Canny admin dashboard.',
+  required: true,
+  validate: async ({ auth }) => {
+    try {
+      const response = await cannyRequest<{
+        boards?: Array<{ id: string }>;
+      }>({
+        apiKey: auth,
+        path: '/boards/list',
+      });
+
+      if (Array.isArray(response.boards)) {
+        return { valid: true };
+      }
+
+      return {
+        valid: false,
+        error: 'Unexpected response from Canny API. Check your API key.',
+      };
+    } catch {
+      return {
+        valid: false,
+        error: 'Invalid API key or could not reach the Canny API.',
+      };
+    }
+  },
+});

package/src/lib/common/client.ts

@@ -0,0 +1,44 @@
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+
+export const CANNY_API_BASE = 'https://canny.io/api/v1';
+
+/**
+ * All Canny API endpoints use POST with JSON body.
+ * Authentication is via an `apiKey` field in the request body.
+ */
+export async function cannyRequest<T = unknown>({
+  apiKey,
+  path,
+  body,
+}: {
+  apiKey: string;
+  path: string;
+  body?: Record<string, unknown>;
+}): Promise<T> {
+  const response = await httpClient.sendRequest<T>({
+    method: HttpMethod.POST,
+    url: `${CANNY_API_BASE}${path}`,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: {
+      apiKey: apiKey.trim(),
+      ...body,
+    },
+  });
+
+  return response.body;
+}
+
+/**
+ * Strip undefined/null/empty-string values from an object before sending.
+ */
+export function cleanBody(
+  obj: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(
+      ([, v]) => v !== undefined && v !== null && v !== '',
+    ),
+  );
+}

package/src/lib/common/props.ts

@@ -0,0 +1,36 @@
+import { Property } from '@agnocon/pieces-framework';
+
+import { cannyAuth } from '../auth';
+import { cannyRequest } from './client';
+
+export const boardIdProp = Property.Dropdown({
+  auth: cannyAuth,
+  displayName: 'Board',
+  description: 'The board to use.',
+  required: true,
+  refreshers: [],
+  options: async ({ auth }) => {
+    if (!auth) {
+      return {
+        disabled: true,
+        placeholder: 'Connect your Canny account first.',
+        options: [],
+      };
+    }
+
+    const response = await cannyRequest<{
+      boards: Array<{ id: string; name: string }>;
+    }>({
+      apiKey: auth.secret_text,
+      path: '/boards/list',
+    });
+
+    return {
+      disabled: false,
+      options: (response.boards ?? []).map((b) => ({
+        label: b.name,
+        value: b.id,
+      })),
+    };
+  },
+});

package/src/lib/triggers/new-comment.ts

@@ -0,0 +1,48 @@
+import { createCannyTrigger } from './register-trigger';
+
+export const newCommentTrigger = createCannyTrigger({
+  name: 'new_comment',
+  displayName: 'New Comment',
+  description: 'Triggers when a new comment is created on a post.',
+  aiMetadata: {
+    description:
+      'Fires when a new comment is added to any Canny post, delivering the comment along with its author and parent post. Use to react to discussion activity on feedback.',
+  },
+  eventType: 'comment.created',
+  sampleData: {
+    created: '2026-04-06T11:05:00.000Z',
+    objectType: 'comment',
+    type: 'comment.created',
+    object: {
+      id: 'comment123',
+      value: 'This is a great idea! We really need this feature.',
+      created: '2026-04-06T11:05:00.000Z',
+      by: null,
+      author: {
+        id: 'author456',
+        name: 'John Smith',
+        email: 'john@example.com',
+        isAdmin: false,
+        avatarURL: null,
+        created: '2026-01-08T07:26:38.452Z',
+        url: 'https://yourcompany.canny.io/admin/users/john-smith',
+        userID: null,
+      },
+      post: {
+        id: 'post123',
+        title: 'Sample feature request',
+        status: 'open',
+        score: 5,
+        created: '2026-04-06T10:35:58.342Z',
+        url: 'https://yourcompany.canny.io/admin/board/feature-requests/p/sample-feature-request',
+        board: {
+          id: 'board123',
+          name: 'Feature Requests',
+          postCount: 5,
+          created: '2026-04-06T10:35:08.905Z',
+          url: 'https://yourcompany.canny.io/admin/board/feature-requests',
+        },
+      },
+    },
+  },
+});

package/src/lib/triggers/new-post.ts

@@ -0,0 +1,52 @@
+import { createCannyTrigger } from './register-trigger';
+
+export const newPostTrigger = createCannyTrigger({
+  name: 'new_post',
+  displayName: 'New Post',
+  description: 'Triggers when a new post is created on a Canny board.',
+  aiMetadata: {
+    description:
+      'Fires when a new feedback post is created on any Canny board, delivering the post with its board and author. Use to react to incoming feature requests or feedback as they are submitted.',
+  },
+  eventType: 'post.created',
+  sampleData: {
+    created: '2026-04-06T10:35:59.055Z',
+    objectType: 'post',
+    type: 'post.created',
+    object: {
+      id: 'post123',
+      title: 'Sample feature request',
+      details: 'It would be great if the app had dark mode.',
+      status: 'open',
+      score: 1,
+      commentCount: 0,
+      created: '2026-04-06T10:35:58.342Z',
+      statusChangedAt: '2026-04-06T10:35:58.342Z',
+      url: 'https://yourcompany.canny.io/admin/board/feature-requests/p/sample-feature-request',
+      eta: null,
+      by: null,
+      category: null,
+      owner: null,
+      tags: [],
+      imageURLs: [],
+      customFields: [],
+      board: {
+        id: 'board123',
+        name: 'Feature Requests',
+        postCount: 1,
+        created: '2026-04-06T10:35:08.905Z',
+        url: 'https://yourcompany.canny.io/admin/board/feature-requests',
+      },
+      author: {
+        id: 'author123',
+        name: 'Jane Doe',
+        email: 'jane@example.com',
+        isAdmin: false,
+        avatarURL: null,
+        created: '2026-01-08T07:26:38.452Z',
+        url: 'https://yourcompany.canny.io/admin/users/jane-doe',
+        userID: null,
+      },
+    },
+  },
+});

package/src/lib/triggers/new-vote.ts

@@ -0,0 +1,60 @@
+import { createCannyTrigger } from './register-trigger';
+
+export const newVoteTrigger = createCannyTrigger({
+  name: 'new_vote',
+  displayName: 'New Vote',
+  description: 'Triggers when a user votes on a post.',
+  aiMetadata: {
+    description:
+      'Fires when a user casts a vote on a Canny post, delivering the vote with its voter and the parent post. Use to react to changes in demand or support for feedback.',
+  },
+  eventType: 'vote.created',
+  sampleData: {
+    created: '2026-04-06T10:47:47.056Z',
+    objectType: 'vote',
+    type: 'vote.created',
+    object: {
+      id: 'vote123',
+      created: '2026-04-06T10:47:46.858Z',
+      score: 1,
+      votePriority: 'No priority',
+      by: null,
+      voter: {
+        id: 'user123',
+        name: 'Jane Doe',
+        email: 'jane@example.com',
+        isAdmin: false,
+        avatarURL: null,
+        created: '2026-01-08T07:26:38.452Z',
+        url: 'https://yourcompany.canny.io/admin/users/jane-doe',
+        userID: null,
+      },
+      post: {
+        id: 'post123',
+        title: 'Sample feature request',
+        details: 'It would be great if the app had dark mode.',
+        status: 'open',
+        score: 1,
+        created: '2026-04-06T10:35:58.342Z',
+        url: 'https://yourcompany.canny.io/admin/board/feature-requests/p/sample-feature-request',
+        board: {
+          id: 'board123',
+          name: 'Feature Requests',
+          postCount: 1,
+          created: '2026-04-06T10:35:08.905Z',
+          url: 'https://yourcompany.canny.io/admin/board/feature-requests',
+        },
+        author: {
+          id: 'author123',
+          name: 'John Smith',
+          email: 'john@example.com',
+          isAdmin: false,
+          avatarURL: null,
+          created: '2026-01-08T07:26:38.452Z',
+          url: 'https://yourcompany.canny.io/admin/users/john-smith',
+          userID: null,
+        },
+      },
+    },
+  },
+});

package/src/lib/triggers/post-status-changed.ts

@@ -0,0 +1,52 @@
+import { createCannyTrigger } from './register-trigger';
+
+export const postStatusChangedTrigger = createCannyTrigger({
+  name: 'post_status_changed',
+  displayName: 'Post Status Changed',
+  description: "Triggers when a post's status is changed (e.g. open → in progress → complete).",
+  aiMetadata: {
+    description:
+      'Fires when a Canny post moves to a different status (for example open to in progress to complete), delivering the post in its new state. Use to react to changes in how a feature request is progressing.',
+  },
+  eventType: 'post.status_changed',
+  sampleData: {
+    created: '2026-04-06T11:00:00.000Z',
+    objectType: 'post',
+    type: 'post.status_changed',
+    object: {
+      id: 'post123',
+      title: 'Sample feature request',
+      details: 'It would be great if the app had dark mode.',
+      status: 'in progress',
+      score: 5,
+      commentCount: 2,
+      created: '2026-04-06T10:35:58.342Z',
+      statusChangedAt: '2026-04-06T11:00:00.000Z',
+      url: 'https://yourcompany.canny.io/admin/board/feature-requests/p/sample-feature-request',
+      eta: null,
+      by: null,
+      category: null,
+      owner: null,
+      tags: [],
+      imageURLs: [],
+      customFields: [],
+      board: {
+        id: 'board123',
+        name: 'Feature Requests',
+        postCount: 5,
+        created: '2026-04-06T10:35:08.905Z',
+        url: 'https://yourcompany.canny.io/admin/board/feature-requests',
+      },
+      author: {
+        id: 'author123',
+        name: 'Jane Doe',
+        email: 'jane@example.com',
+        isAdmin: false,
+        avatarURL: null,
+        created: '2026-01-08T07:26:38.452Z',
+        url: 'https://yourcompany.canny.io/admin/users/jane-doe',
+        userID: null,
+      },
+    },
+  },
+});

package/src/lib/triggers/register-trigger.ts

@@ -0,0 +1,50 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { WebhookHandshakeStrategy } from '@agnocon/pieces-framework';
+
+import { cannyAuth } from '../auth';
+
+export type CannyEventType =
+  | 'post.created'
+  | 'post.status_changed'
+  | 'comment.created'
+  | 'vote.created';
+
+export function createCannyTrigger({
+  name,
+  displayName,
+  description,
+  aiMetadata,
+  eventType,
+  sampleData,
+}: {
+  name: string;
+  displayName: string;
+  description: string;
+  aiMetadata: { description: string };
+  eventType: CannyEventType;
+  sampleData: unknown;
+}) {
+  return createTrigger({
+    auth: cannyAuth,
+    name,
+    displayName,
+    description,
+    aiMetadata,
+    props: {},
+    sampleData,
+    type: TriggerStrategy.WEBHOOK,
+    handshakeConfiguration: { strategy: WebhookHandshakeStrategy.NONE },
+    async onEnable(_context) {
+      // Canny webhooks must be configured manually in the Canny dashboard.
+      // Point the webhook URL to this trigger's webhook URL.
+    },
+    async onDisable(_context) {
+      // Nothing to clean up — webhooks are managed manually in Canny.
+    },
+    async run(context) {
+      const payload = context.payload.body as { type?: string };
+      if (payload?.type !== eventType) return [];
+      return [payload];
+    },
+  });
+}