@agnocon/piece-buffer 0.0.5

package/src/index.ts

@@ -0,0 +1,33 @@
+import { createPiece } from '@agnocon/pieces-framework';
+import { createCustomApiCallAction } from '@agnocon/pieces-common';
+import { PieceCategory } from '@agnocon/pieces-framework';
+import { bufferAuth } from './lib/common/auth';
+import { bufferClient } from './lib/common/client';
+import { createPost } from './lib/actions/create-post';
+import { createIdea } from './lib/actions/create-idea';
+import { newChannel } from './lib/triggers/new-channel';
+import { newQueueItem } from './lib/triggers/new-queue-item';
+import { newSentItem } from './lib/triggers/new-sent-item';
+
+export const buffer = createPiece({
+  displayName: 'Buffer',
+  description:
+    'Schedule, publish and analyze social media posts across multiple channels with Buffer.',
+  auth: bufferAuth,
+  minimumSupportedRelease: '0.36.1',
+  logoUrl: 'https://cdn.activepieces.com/pieces/buffer.png',
+  categories: [PieceCategory.MARKETING],
+  authors: ['sanket-a11y'],
+  actions: [
+    createPost,
+    createIdea,
+    createCustomApiCallAction({
+      baseUrl: () => bufferClient.apiUrl,
+      auth: bufferAuth,
+      authMapping: async (auth) => ({
+        Authorization: `Bearer ${auth.secret_text}`,
+      }),
+    }),
+  ],
+  triggers: [newChannel, newQueueItem, newSentItem],
+});

package/src/lib/actions/create-idea.ts

@@ -0,0 +1,123 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bufferAuth } from '../common/auth';
+import { bufferClient } from '../common/client';
+import { bufferProps } from '../common/props';
+
+type CreateIdeaResponse = {
+  createIdea: {
+    __typename?: string;
+    message?: string;
+    idea?: {
+      id: string;
+      organizationId: string;
+      groupId?: string;
+      createdAt?: number;
+      updatedAt?: number;
+      content?: {
+        title?: string;
+        text?: string;
+        media?: Array<{ url: string; type: string; alt?: string }>;
+        tags?: Array<{ id: string; name: string; color?: string }>;
+      };
+    };
+    refreshIdeas?: boolean;
+  };
+};
+
+const CREATE_IDEA_MUTATION = `
+  mutation CreateIdea($input: CreateIdeaInput!) {
+    createIdea(input: $input) {
+      __typename
+      ... on IdeaResponse {
+        idea {
+          id
+          organizationId
+          groupId
+          createdAt
+          updatedAt
+          content {
+            title
+            text
+            media { url type alt }
+            tags { id name color }
+          }
+        }
+        refreshIdeas
+      }
+      ... on MutationError {
+        message
+      }
+    }
+  }
+`;
+
+export const createIdea = createAction({
+  auth: bufferAuth,
+  name: 'create_idea',
+  displayName: 'Create Idea',
+  description: "Save a new idea to your Buffer Idea Bank.",
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Saves a new draft idea (title, body text, and/or attached images) to a Buffer organization\'s Idea Bank for later use. Choose it to stash content concepts without scheduling them to a channel. The idea must include at least a title, text, or one image. Not idempotent — each call creates a new idea.',
+    idempotent: false,
+  },
+  props: {
+    organizationId: bufferProps.organizationId(),
+    title: Property.ShortText({
+      displayName: 'Title',
+      description: 'A short title or headline for the idea.',
+      required: false,
+    }),
+    text: Property.LongText({
+      displayName: 'Text',
+      description: 'The main body of the idea.',
+      required: false,
+    }),
+    imageUrls: Property.Array({
+      displayName: 'Image URLs',
+      description: 'Public URLs of images to attach to the idea.',
+      required: false,
+    }),
+    aiAssisted: Property.Checkbox({
+      displayName: 'AI Assisted',
+      description: 'Mark this idea as created with AI assistance.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(context) {
+    const { organizationId, title, text, imageUrls, aiAssisted } =
+      context.propsValue;
+
+    if (!title && !text && (!imageUrls || imageUrls.length === 0)) {
+      throw new Error(
+        'An idea must include at least a title, text, or one image.',
+      );
+    }
+
+    const media = (imageUrls ?? []).map((url) => ({
+      url: url as string,
+      type: 'image',
+    }));
+
+    const content: Record<string, unknown> = {};
+    if (title) content['title'] = title;
+    if (text) content['text'] = text;
+    if (media.length > 0) content['media'] = media;
+    if (aiAssisted) content['aiAssisted'] = true;
+
+    const data = await bufferClient.graphql<CreateIdeaResponse>({
+      accessToken: context.auth.secret_text,
+      query: CREATE_IDEA_MUTATION,
+      variables: { input: { organizationId, content } },
+    });
+
+    if (data.createIdea.message) {
+      throw new Error(
+        `Buffer rejected the idea: ${data.createIdea.message}`,
+      );
+    }
+    return data;
+  },
+});

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

@@ -0,0 +1,173 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bufferAuth } from '../common/auth';
+import { bufferClient } from '../common/client';
+import { bufferProps } from '../common/props';
+
+type CreatePostResponse = {
+  createPost: {
+    __typename?: string;
+    message?: string;
+    post?: {
+      id: string;
+      text?: string;
+      status?: string;
+      dueAt?: string;
+      sentAt?: string;
+      channelId?: string;
+    };
+  };
+};
+
+const CREATE_POST_MUTATION = `
+  mutation CreatePost($input: CreatePostInput!) {
+    createPost(input: $input) {
+      __typename
+      ... on PostActionSuccess {
+        post {
+          id
+          text
+          status
+          dueAt
+          sentAt
+          channelId
+        }
+      }
+      ... on MutationError {
+        message
+      }
+    }
+  }
+`;
+
+export const createPost = createAction({
+  auth: bufferAuth,
+  name: 'create_post',
+  displayName: 'Create Post',
+  description:
+    'Create a post in Buffer and add it to the queue, share it next, share it now, or schedule it for a custom time.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Creates a social media post in Buffer for one or more channels, where the share mode controls timing: add to the channel queue, share next (skip the queue), share now, or schedule for a custom time. Choose it to draft or publish content to connected social accounts. A custom-scheduled post requires the scheduled time; posting to multiple channels creates a separate post per channel. Not idempotent — each call creates new posts.',
+    idempotent: false,
+  },
+  props: {
+    organizationId: bufferProps.organizationId(),
+    channelIds: bufferProps.channelIds(true),
+    text: Property.LongText({
+      displayName: 'Text',
+      description: 'The text content of the post.',
+      required: true,
+    }),
+    mode: Property.StaticDropdown({
+      displayName: 'Share Mode',
+      description: 'When and how the post should be published.',
+      required: true,
+      defaultValue: 'addToQueue',
+      options: {
+        disabled: false,
+        options: [
+          { label: 'Add to Queue', value: 'addToQueue' },
+          { label: 'Share Next (skip the queue)', value: 'shareNext' },
+          { label: 'Share Now', value: 'shareNow' },
+          { label: 'Schedule for Custom Time', value: 'customScheduled' },
+        ],
+      },
+    }),
+    dueAt: Property.DateTime({
+      displayName: 'Scheduled Time',
+      description:
+        'When to publish the post. Required when Share Mode is "Schedule for Custom Time". ISO 8601 (UTC).',
+      required: false,
+    }),
+    schedulingType: Property.StaticDropdown({
+      displayName: 'Scheduling Type',
+      description:
+        'Use "Automatic" for channels Buffer can publish to directly. Use "Notification" for channels that require manual publishing via the Buffer mobile app (e.g. Instagram personal accounts).',
+      required: true,
+      defaultValue: 'automatic',
+      options: {
+        disabled: false,
+        options: [
+          { label: 'Automatic', value: 'automatic' },
+          { label: 'Notification (manual publish)', value: 'notification' },
+        ],
+      },
+    }),
+    saveToDraft: Property.Checkbox({
+      displayName: 'Save as Draft',
+      description:
+        'Save the post as a draft instead of scheduling it. Drafts are not published until explicitly scheduled.',
+      required: false,
+      defaultValue: false,
+    }),
+    imageUrls: Property.Array({
+      displayName: 'Image URLs',
+      description: 'Public URLs of images to attach to the post.',
+      required: false,
+    }),
+    linkUrl: Property.ShortText({
+      displayName: 'Link URL',
+      description: 'A link to attach to the post (used as a link preview).',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const {
+      channelIds,
+      text,
+      mode,
+      dueAt,
+      schedulingType,
+      saveToDraft,
+      imageUrls,
+      linkUrl,
+    } = context.propsValue;
+
+    if (mode === 'customScheduled' && !dueAt) {
+      throw new Error(
+        'Scheduled Time is required when Share Mode is "Schedule for Custom Time".',
+      );
+    }
+
+    const assets: Array<Record<string, unknown>> = [];
+    for (const url of imageUrls ?? []) {
+      assets.push({ image: { url: url as string } });
+    }
+    if (linkUrl) {
+      assets.push({ link: { url: linkUrl } });
+    }
+
+    const results: CreatePostResponse['createPost'][] = [];
+    for (const channelId of channelIds ?? []) {
+      const input: Record<string, unknown> = {
+        channelId,
+        text,
+        mode,
+        schedulingType,
+        assets,
+      };
+      if (mode === 'customScheduled' && dueAt) {
+        input['dueAt'] = dueAt;
+      }
+      if (saveToDraft) {
+        input['saveToDraft'] = true;
+      }
+
+      const data = await bufferClient.graphql<CreatePostResponse>({
+        accessToken: context.auth.secret_text,
+        query: CREATE_POST_MUTATION,
+        variables: { input },
+      });
+
+      if (data.createPost.message) {
+        throw new Error(
+          `Buffer rejected the post for channel ${channelId}: ${data.createPost.message}`,
+        );
+      }
+      results.push(data.createPost);
+    }
+
+    return { posts: results };
+  },
+});

package/src/lib/common/auth.ts

@@ -0,0 +1,31 @@
+import { PieceAuth } from '@agnocon/pieces-framework';
+import { bufferClient } from './client';
+
+export const bufferAuth = PieceAuth.SecretText({
+  displayName: 'Access Token',
+  description: `
+**How to get your Buffer access token:**
+
+1. Sign in to Buffer at https://buffer.com and open the [Developer Apps](https://publish.buffer.com/developers/apps) page.
+2. Click **Create New App** and fill in the basic details (callback URL can be any placeholder).
+3. After the app is created, copy the **Access Token** shown on the app's page.
+4. Paste it below.
+
+The token is sent as a Bearer token to the Buffer GraphQL API (https://api.buffer.com).`,
+  required: true,
+  validate: async ({ auth }) => {
+    try {
+      await bufferClient.graphql<{ account: { id: string } }>({
+        accessToken: auth,
+        query: `query { account { id } }`,
+      });
+      return { valid: true };
+    } catch (e) {
+      return {
+        valid: false,
+        error:
+          'Invalid Buffer access token. Make sure the token has the required scopes and try again.',
+      };
+    }
+  },
+});

package/src/lib/common/client.ts

@@ -0,0 +1,44 @@
+import { httpClient, HttpMethod } from '@agnocon/pieces-common';
+
+const BUFFER_API_URL = 'https://api.buffer.com';
+
+type GraphQLResponse<T> = {
+  data?: T;
+  errors?: Array<{ message: string; path?: string[]; extensions?: unknown }>;
+};
+
+async function graphqlRequest<T>({
+  accessToken,
+  query,
+  variables,
+}: {
+  accessToken: string;
+  query: string;
+  variables?: Record<string, unknown>;
+}): Promise<T> {
+  const response = await httpClient.sendRequest<GraphQLResponse<T>>({
+    method: HttpMethod.POST,
+    url: BUFFER_API_URL,
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: { query, variables: variables ?? {} },
+  });
+
+  const body = response.body;
+  if (body.errors && body.errors.length > 0) {
+    throw new Error(
+      `Buffer API error: ${body.errors.map((e) => e.message).join('; ')}`,
+    );
+  }
+  if (!body.data) {
+    throw new Error('Buffer API returned no data');
+  }
+  return body.data;
+}
+
+export const bufferClient = {
+  graphql: graphqlRequest,
+  apiUrl: BUFFER_API_URL,
+};

package/src/lib/common/props.ts

@@ -0,0 +1,224 @@
+import { Property } from '@agnocon/pieces-framework';
+import { bufferAuth } from './auth';
+import { bufferClient } from './client';
+
+async function fetchOrganizations(accessToken: string): Promise<Organization[]> {
+  const data = await bufferClient.graphql<{
+    account: { organizations: Organization[] };
+  }>({
+    accessToken,
+    query: `query { account { organizations { id name } } }`,
+  });
+  return data.account?.organizations ?? [];
+}
+
+async function fetchChannels(
+  accessToken: string,
+  organizationId: string,
+): Promise<Channel[]> {
+  const data = await bufferClient.graphql<{ channels: Channel[] }>({
+    accessToken,
+    query: `query Channels($organizationId: OrganizationId!) {
+      channels(input: { organizationId: $organizationId }) {
+        id
+        name
+        service
+        organizationId
+        createdAt
+      }
+    }`,
+    variables: { organizationId },
+  });
+  return data.channels ?? [];
+}
+
+async function fetchPosts({
+  accessToken,
+  organizationId,
+  channelIds,
+  statusFilter,
+  first = 50,
+}: {
+  accessToken: string;
+  organizationId: string;
+  channelIds?: string[];
+  statusFilter?: (status: string | undefined) => boolean;
+  first?: number;
+}): Promise<BufferPost[]> {
+  const filter: Record<string, unknown> = {};
+  if (channelIds && channelIds.length > 0) filter['channelIds'] = channelIds;
+
+  const data = await bufferClient.graphql<{
+    posts: { edges?: Array<{ node: BufferPost }> };
+  }>({
+    accessToken,
+    query: `query Posts($input: PostsInput!, $first: Int) {
+      posts(input: $input, first: $first) {
+        edges {
+          node {
+            id
+            text
+            status
+            createdAt
+            updatedAt
+            dueAt
+            sentAt
+            channelId
+            channelService
+            channel { id name service }
+            tags { id name }
+          }
+        }
+      }
+    }`,
+    variables: {
+      input: {
+        organizationId,
+        ...(Object.keys(filter).length > 0 ? { filter } : {}),
+      },
+      first,
+    },
+  });
+  const posts = (data.posts?.edges ?? []).map((edge) => edge.node);
+  return statusFilter ? posts.filter((post) => statusFilter(post.status)) : posts;
+}
+
+export const bufferProps = {
+  organizationId: () =>
+    Property.Dropdown<string, true, typeof bufferAuth>({
+      auth: bufferAuth,
+      displayName: 'Organization',
+      description: 'The Buffer organization to use.',
+      required: true,
+      refreshers: [],
+      options: async ({ auth }) => {
+        if (!auth) {
+          return {
+            disabled: true,
+            placeholder: 'Connect your Buffer account first.',
+            options: [],
+          };
+        }
+        try {
+          const organizations = await fetchOrganizations(auth.secret_text);
+          return {
+            disabled: false,
+            options: organizations.map((org) => ({
+              label: org.name,
+              value: org.id,
+            })),
+          };
+        } catch {
+          return {
+            disabled: true,
+            placeholder: 'Failed to load organizations.',
+            options: [],
+          };
+        }
+      },
+    }),
+
+  channelIds: (required = true) =>
+    Property.MultiSelectDropdown<string, boolean, typeof bufferAuth>({
+      auth: bufferAuth,
+      displayName: 'Channels',
+      description: 'The Buffer channels to publish to.',
+      required,
+      refreshers: ['organizationId'],
+      options: async ({ auth, organizationId }) => {
+        if (!auth || !organizationId) {
+          return {
+            disabled: true,
+            placeholder: 'Select an organization first.',
+            options: [],
+          };
+        }
+        try {
+          const channels = await fetchChannels(
+            auth.secret_text,
+            organizationId as string,
+          );
+          return {
+            disabled: false,
+            options: channels.map((channel) => ({
+              label: `${channel.name} (${channel.service})`,
+              value: channel.id,
+            })),
+          };
+        } catch {
+          return {
+            disabled: true,
+            placeholder: 'Failed to load channels.',
+            options: [],
+          };
+        }
+      },
+    }),
+
+  channelId: () =>
+    Property.Dropdown<string, true, typeof bufferAuth>({
+      auth: bufferAuth,
+      displayName: 'Channel',
+      description: 'The Buffer channel.',
+      required: true,
+      refreshers: ['organizationId'],
+      options: async ({ auth, organizationId }) => {
+        if (!auth || !organizationId) {
+          return {
+            disabled: true,
+            placeholder: 'Select an organization first.',
+            options: [],
+          };
+        }
+        try {
+          const channels = await fetchChannels(
+            auth.secret_text,
+            organizationId as string,
+          );
+          return {
+            disabled: false,
+            options: channels.map((channel) => ({
+              label: `${channel.name} (${channel.service})`,
+              value: channel.id,
+            })),
+          };
+        } catch {
+          return {
+            disabled: true,
+            placeholder: 'Failed to load channels.',
+            options: [],
+          };
+        }
+      },
+    }),
+};
+
+export const bufferQueries = {
+  fetchOrganizations,
+  fetchChannels,
+  fetchPosts,
+};
+
+export type Organization = { id: string; name: string };
+
+export type Channel = {
+  id: string;
+  name: string;
+  service: string;
+  organizationId: string;
+  createdAt?: string;
+};
+
+export type BufferPost = {
+  id: string;
+  text?: string;
+  status?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  dueAt?: string;
+  sentAt?: string;
+  channelId?: string;
+  channelService?: string;
+  channel?: { id: string; name: string; service: string };
+  tags?: Array<{ id: string; name: string }>;
+};

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

@@ -0,0 +1,73 @@
+import {
+  createTrigger,
+  TriggerStrategy,
+  AppConnectionValueForAuthProperty,
+} from '@agnocon/pieces-framework';
+import {
+  DedupeStrategy,
+  Polling,
+  pollingHelper,
+} from '@agnocon/pieces-common';
+import { bufferAuth } from '../common/auth';
+import { bufferProps, bufferQueries, Channel } from '../common/props';
+
+const polling: Polling<
+  AppConnectionValueForAuthProperty<typeof bufferAuth>,
+  { organizationId: string }
+> = {
+  strategy: DedupeStrategy.TIMEBASED,
+  async items({ auth, propsValue }) {
+    const channels = await bufferQueries.fetchChannels(
+      auth.secret_text,
+      propsValue.organizationId,
+    );
+    return channels.map((channel) => ({
+      epochMilliSeconds: channel.createdAt
+        ? new Date(channel.createdAt).getTime()
+        : 0,
+      data: channel,
+    }));
+  },
+};
+
+export const newChannel = createTrigger({
+  auth: bufferAuth,
+  name: 'new_channel',
+  displayName: 'New Channel',
+  description: 'Triggers when a new channel is connected to your Buffer organization.',
+  aiMetadata: {
+    description:
+      'Fires when a new social media channel (e.g. a Facebook page, Instagram or X account) is connected to the selected Buffer organization, representing the newly linked channel.',
+  },
+  type: TriggerStrategy.POLLING,
+  props: {
+    organizationId: bufferProps.organizationId(),
+  },
+  sampleData: {
+    id: 'channel_id_example',
+    name: 'My Page',
+    service: 'facebook',
+    organizationId: 'org_id_example',
+    createdAt: '2026-05-25T10:00:00.000Z',
+  } satisfies Channel,
+  async onEnable(context) {
+    await pollingHelper.onEnable(polling, {
+      auth: context.auth,
+      store: context.store,
+      propsValue: context.propsValue,
+    });
+  },
+  async onDisable(context) {
+    await pollingHelper.onDisable(polling, {
+      auth: context.auth,
+      store: context.store,
+      propsValue: context.propsValue,
+    });
+  },
+  async test(context) {
+    return await pollingHelper.test(polling, context);
+  },
+  async run(context) {
+    return await pollingHelper.poll(polling, context);
+  },
+});