@auxiora/connector-social 1.0.0

package/src/twitter.ts

@@ -0,0 +1,253 @@
+import { defineConnector } from '@auxiora/connectors';
+import type { TriggerEvent } from '@auxiora/connectors';
+
+async function twitterFetch(token: string, path: string, options?: { method?: string; body?: unknown }) {
+  const res = await fetch(`https://api.twitter.com/2${path}`, {
+    method: options?.method ?? 'GET',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: options?.body ? JSON.stringify(options.body) : undefined,
+  });
+  if (!res.ok) throw new Error(`Twitter API error: ${res.status} ${await res.text().catch(() => res.statusText)}`);
+  return res.json() as Promise<Record<string, unknown>>;
+}
+
+async function getMyUserId(token: string): Promise<string> {
+  const res = await twitterFetch(token, '/users/me');
+  const data = res.data as Record<string, unknown>;
+  return data.id as string;
+}
+
+export const twitterConnector = defineConnector({
+  id: 'twitter',
+  name: 'Twitter / X',
+  description: 'Integration with Twitter/X for tweets, mentions, and direct messages',
+  version: '1.0.0',
+  category: 'social',
+  icon: 'twitter',
+
+  auth: {
+    type: 'oauth2',
+    oauth2: {
+      authUrl: 'https://twitter.com/i/oauth2/authorize',
+      tokenUrl: 'https://api.twitter.com/2/oauth2/token',
+      scopes: ['tweet.read', 'tweet.write', 'users.read', 'dm.read', 'dm.write', 'offline.access'],
+    },
+  },
+
+  actions: [
+    {
+      id: 'timeline-read',
+      name: 'Read Timeline',
+      description: 'Read the authenticated user timeline',
+      trustMinimum: 1,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: false,
+      params: {},
+    },
+    {
+      id: 'mentions-list',
+      name: 'List Mentions',
+      description: 'List recent mentions of the authenticated user',
+      trustMinimum: 1,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: false,
+      params: {},
+    },
+    {
+      id: 'post-tweet',
+      name: 'Post Tweet',
+      description: 'Post a new tweet',
+      trustMinimum: 3,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: true,
+      params: {
+        text: { type: 'string', description: 'Tweet text', required: true },
+      },
+    },
+    {
+      id: 'reply-tweet',
+      name: 'Reply to Tweet',
+      description: 'Reply to an existing tweet',
+      trustMinimum: 3,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: true,
+      params: {
+        tweetId: { type: 'string', description: 'Tweet ID to reply to', required: true },
+        text: { type: 'string', description: 'Reply text', required: true },
+      },
+    },
+    {
+      id: 'delete-tweet',
+      name: 'Delete Tweet',
+      description: 'Delete an existing tweet',
+      trustMinimum: 3,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: true,
+      params: {
+        tweetId: { type: 'string', description: 'Tweet ID to delete', required: true },
+      },
+    },
+    {
+      id: 'search-tweets',
+      name: 'Search Tweets',
+      description: 'Search for tweets matching a query',
+      trustMinimum: 1,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: false,
+      params: {
+        query: { type: 'string', description: 'Search query', required: true },
+      },
+    },
+    {
+      id: 'dm-list',
+      name: 'List Direct Messages',
+      description: 'List recent direct messages',
+      trustMinimum: 1,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: false,
+      params: {},
+    },
+    {
+      id: 'dm-send',
+      name: 'Send Direct Message',
+      description: 'Send a direct message to a user',
+      trustMinimum: 3,
+      trustDomain: 'messaging',
+      reversible: false,
+      sideEffects: true,
+      params: {
+        recipientId: { type: 'string', description: 'Recipient user ID', required: true },
+        text: { type: 'string', description: 'Message text', required: true },
+      },
+    },
+  ],
+
+  triggers: [
+    {
+      id: 'new-mention',
+      name: 'New Mention',
+      description: 'Triggered when the user is mentioned in a tweet',
+      type: 'poll',
+      pollIntervalMs: 60_000,
+    },
+    {
+      id: 'new-dm',
+      name: 'New Direct Message',
+      description: 'Triggered when a new direct message is received',
+      type: 'poll',
+      pollIntervalMs: 120_000,
+    },
+  ],
+
+  entities: [
+    {
+      id: 'tweet',
+      name: 'Tweet',
+      description: 'A tweet on Twitter/X',
+      fields: { id: 'string', text: 'string', authorId: 'string', createdAt: 'string', likeCount: 'number', retweetCount: 'number' },
+    },
+    {
+      id: 'direct-message',
+      name: 'Direct Message',
+      description: 'A direct message on Twitter/X',
+      fields: { id: 'string', text: 'string', senderId: 'string', createdAt: 'string' },
+    },
+  ],
+
+  async executeAction(actionId: string, params: Record<string, unknown>, token: string): Promise<unknown> {
+    switch (actionId) {
+      case 'timeline-read': {
+        const userId = await getMyUserId(token);
+        const res = await twitterFetch(token, `/users/${userId}/timelines/reverse_chronological`);
+        return { tweets: res.data };
+      }
+      case 'mentions-list': {
+        const userId = await getMyUserId(token);
+        const res = await twitterFetch(token, `/users/${userId}/mentions`);
+        return { mentions: res.data };
+      }
+      case 'post-tweet': {
+        const res = await twitterFetch(token, '/tweets', {
+          method: 'POST',
+          body: { text: params.text },
+        });
+        const data = res.data as Record<string, unknown>;
+        return { tweetId: data.id, status: 'posted' };
+      }
+      case 'reply-tweet': {
+        const res = await twitterFetch(token, '/tweets', {
+          method: 'POST',
+          body: { text: params.text, reply: { in_reply_to_tweet_id: params.tweetId } },
+        });
+        const data = res.data as Record<string, unknown>;
+        return { tweetId: data.id, status: 'replied' };
+      }
+      case 'delete-tweet': {
+        await twitterFetch(token, `/tweets/${params.tweetId as string}`, { method: 'DELETE' });
+        return { tweetId: params.tweetId, status: 'deleted' };
+      }
+      case 'search-tweets': {
+        const query = encodeURIComponent(params.query as string);
+        const res = await twitterFetch(token, `/tweets/search/recent?query=${query}`);
+        return { tweets: res.data };
+      }
+      case 'dm-list': {
+        const res = await twitterFetch(token, '/dm_events');
+        return { messages: res.data };
+      }
+      case 'dm-send': {
+        const res = await twitterFetch(token, `/dm_conversations/with/${params.recipientId as string}/messages`, {
+          method: 'POST',
+          body: { text: params.text },
+        });
+        const data = res.data as Record<string, unknown>;
+        return { messageId: data.dm_event_id ?? data.id, status: 'sent' };
+      }
+      default:
+        throw new Error(`Unknown action: ${actionId}`);
+    }
+  },
+
+  async pollTrigger(triggerId: string, token: string, lastPollAt?: number): Promise<TriggerEvent[]> {
+    switch (triggerId) {
+      case 'new-mention': {
+        const userId = await getMyUserId(token);
+        const startTime = lastPollAt ? new Date(lastPollAt).toISOString() : undefined;
+        const query = startTime ? `?start_time=${startTime}` : '';
+        const res = await twitterFetch(token, `/users/${userId}/mentions${query}`);
+        const mentions = (res.data ?? []) as Array<Record<string, unknown>>;
+        return mentions.map((m) => ({
+          triggerId: 'new-mention',
+          connectorId: 'twitter',
+          data: m,
+          timestamp: m.created_at ? new Date(m.created_at as string).getTime() : Date.now(),
+        }));
+      }
+      case 'new-dm': {
+        const res = await twitterFetch(token, '/dm_events?event_types=MessageCreate');
+        const events = (res.data ?? []) as Array<Record<string, unknown>>;
+        const cutoff = lastPollAt ?? 0;
+        return events
+          .filter((e) => {
+            const ts = e.created_at ? new Date(e.created_at as string).getTime() : 0;
+            return ts > cutoff;
+          })
+          .map((e) => ({
+            triggerId: 'new-dm',
+            connectorId: 'twitter',
+            data: e,
+            timestamp: e.created_at ? new Date(e.created_at as string).getTime() : Date.now(),
+          }));
+      }
+      default:
+        return [];
+    }
+  },
+});

package/tests/instagram.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { instagramConnector } from '../src/instagram.js';
+
+let fetchMock: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function mockResponse(body: unknown) {
+  return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+describe('Instagram Connector', () => {
+  it('should have correct metadata', () => {
+    expect(instagramConnector.id).toBe('instagram');
+    expect(instagramConnector.name).toBe('Instagram');
+    expect(instagramConnector.version).toBe('1.0.0');
+    expect(instagramConnector.category).toBe('social');
+  });
+
+  it('should use OAuth2 authentication', () => {
+    expect(instagramConnector.auth.type).toBe('oauth2');
+    expect(instagramConnector.auth.oauth2).toBeDefined();
+    expect(instagramConnector.auth.oauth2!.authUrl).toBe('https://api.instagram.com/oauth/authorize');
+    expect(instagramConnector.auth.oauth2!.tokenUrl).toBe('https://api.instagram.com/oauth/access_token');
+    expect(instagramConnector.auth.oauth2!.scopes).toContain('instagram_basic');
+    expect(instagramConnector.auth.oauth2!.scopes.length).toBe(4);
+  });
+
+  it('should define all 6 actions', () => {
+    expect(instagramConnector.actions).toHaveLength(6);
+    const actionIds = instagramConnector.actions.map((a) => a.id);
+    expect(actionIds).toContain('feed-read');
+    expect(actionIds).toContain('stories-read');
+    expect(actionIds).toContain('dm-list');
+    expect(actionIds).toContain('dm-send');
+    expect(actionIds).toContain('post-schedule');
+    expect(actionIds).toContain('profile-get');
+  });
+
+  it('should have correct trust and side effect settings', () => {
+    const readAction = instagramConnector.actions.find((a) => a.id === 'feed-read');
+    expect(readAction!.trustMinimum).toBe(1);
+    expect(readAction!.sideEffects).toBe(false);
+
+    const dmAction = instagramConnector.actions.find((a) => a.id === 'dm-send');
+    expect(dmAction!.trustMinimum).toBe(3);
+    expect(dmAction!.sideEffects).toBe(true);
+  });
+
+  it('should execute feed-read action', async () => {
+    // GET /me/media?fields=... -> { data: [] }
+    fetchMock.mockResolvedValueOnce(mockResponse({ data: [] }));
+    const result = await instagramConnector.executeAction('feed-read', {}, 'token');
+    expect(result).toEqual({ posts: [] });
+  });
+
+  it('should execute dm-send action', async () => {
+    // dm-send returns unavailable status (Instagram Messaging API requires approved access)
+    const result = await instagramConnector.executeAction('dm-send', { recipientId: 'u1', text: 'Hi' }, 'token') as any;
+    expect(result.status).toBe('unavailable');
+  });
+
+  it('should execute post-schedule action', async () => {
+    // POST /me/media -> { id: 'container1' } (create media container)
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'container1' }));
+    // POST /me/media_publish -> { id: 'post1' } (publish)
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'post1' }));
+    const result = await instagramConnector.executeAction('post-schedule', { caption: 'Hello', mediaUrl: 'https://example.com/img.jpg' }, 'token') as any;
+    expect(result.status).toBe('published');
+    expect(result.postId).toBe('post1');
+  });
+
+  it('should execute profile-get action', async () => {
+    // GET /me?fields=... -> profile object
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'me123', username: 'testuser', name: 'Test' }));
+    const result = await instagramConnector.executeAction('profile-get', {}, 'token') as any;
+    expect(result.id).toBe('me123');
+  });
+
+  it('should throw for unknown action', async () => {
+    await expect(instagramConnector.executeAction('unknown', {}, 'token')).rejects.toThrow('Unknown action');
+  });
+
+  it('should return empty events from pollTrigger', async () => {
+    // new-dm trigger returns [] directly without fetching
+    const events = await instagramConnector.pollTrigger!('new-dm', 'token');
+    expect(events).toEqual([]);
+  });
+
+  it('should define triggers', () => {
+    expect(instagramConnector.triggers).toHaveLength(2);
+    const triggerIds = instagramConnector.triggers.map((t) => t.id);
+    expect(triggerIds).toContain('new-dm');
+    expect(triggerIds).toContain('new-comment');
+  });
+
+  it('should define entities', () => {
+    expect(instagramConnector.entities).toHaveLength(2);
+    const entityIds = instagramConnector.entities.map((e) => e.id);
+    expect(entityIds).toContain('post');
+    expect(entityIds).toContain('story');
+  });
+});

package/tests/linkedin.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { linkedinConnector } from '../src/linkedin.js';
+
+let fetchMock: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function mockResponse(body: unknown) {
+  return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+describe('LinkedIn Connector', () => {
+  it('should have correct metadata', () => {
+    expect(linkedinConnector.id).toBe('linkedin');
+    expect(linkedinConnector.name).toBe('LinkedIn');
+    expect(linkedinConnector.version).toBe('1.0.0');
+    expect(linkedinConnector.category).toBe('social');
+  });
+
+  it('should use OAuth2 authentication', () => {
+    expect(linkedinConnector.auth.type).toBe('oauth2');
+    expect(linkedinConnector.auth.oauth2).toBeDefined();
+    expect(linkedinConnector.auth.oauth2!.authUrl).toBe('https://www.linkedin.com/oauth/v2/authorization');
+    expect(linkedinConnector.auth.oauth2!.tokenUrl).toBe('https://www.linkedin.com/oauth/v2/accessToken');
+    expect(linkedinConnector.auth.oauth2!.scopes).toContain('w_member_social');
+    expect(linkedinConnector.auth.oauth2!.scopes.length).toBe(4);
+  });
+
+  it('should define all 7 actions', () => {
+    expect(linkedinConnector.actions).toHaveLength(7);
+    const actionIds = linkedinConnector.actions.map((a) => a.id);
+    expect(actionIds).toContain('feed-read');
+    expect(actionIds).toContain('post-update');
+    expect(actionIds).toContain('post-article');
+    expect(actionIds).toContain('connections-list');
+    expect(actionIds).toContain('messages-list');
+    expect(actionIds).toContain('message-send');
+    expect(actionIds).toContain('profile-get');
+  });
+
+  it('should use correct trust domains', () => {
+    const messageAction = linkedinConnector.actions.find((a) => a.id === 'message-send');
+    expect(messageAction!.trustDomain).toBe('messaging');
+
+    const feedAction = linkedinConnector.actions.find((a) => a.id === 'feed-read');
+    expect(feedAction!.trustDomain).toBe('integrations');
+
+    const postAction = linkedinConnector.actions.find((a) => a.id === 'post-update');
+    expect(postAction!.trustDomain).toBe('integrations');
+  });
+
+  it('should execute post-update action', async () => {
+    // GET /me -> { id: 'abc' }
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'abc' }));
+    // POST /ugcPosts -> { id: 'post1' }
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'post1' }));
+    const result = await linkedinConnector.executeAction('post-update', { text: 'Update' }, 'token') as any;
+    expect(result.status).toBe('posted');
+    expect(result.postId).toBe('post1');
+  });
+
+  it('should execute message-send action', async () => {
+    // POST /messages -> { id: 'msg1' }
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'msg1' }));
+    const result = await linkedinConnector.executeAction('message-send', { recipientId: 'p1', text: 'Hi' }, 'token') as any;
+    expect(result.status).toBe('sent');
+    expect(result.messageId).toBe('msg1');
+  });
+
+  it('should execute profile-get action', async () => {
+    // GET /me -> profile object
+    fetchMock.mockResolvedValueOnce(mockResponse({ id: 'me', firstName: 'Test', lastName: 'User' }));
+    const result = await linkedinConnector.executeAction('profile-get', {}, 'token') as any;
+    expect(result.id).toBe('me');
+  });
+
+  it('should throw for unknown action', async () => {
+    await expect(linkedinConnector.executeAction('unknown', {}, 'token')).rejects.toThrow('Unknown action');
+  });
+
+  it('should return empty events from pollTrigger', async () => {
+    const events = await linkedinConnector.pollTrigger!('new-message', 'token');
+    expect(events).toEqual([]);
+  });
+
+  it('should define triggers', () => {
+    expect(linkedinConnector.triggers).toHaveLength(2);
+    const triggerIds = linkedinConnector.triggers.map((t) => t.id);
+    expect(triggerIds).toContain('new-message');
+    expect(triggerIds).toContain('post-engagement');
+  });
+
+  it('should define entities', () => {
+    expect(linkedinConnector.entities).toHaveLength(2);
+    const entityIds = linkedinConnector.entities.map((e) => e.id);
+    expect(entityIds).toContain('post');
+    expect(entityIds).toContain('connection');
+  });
+});

package/tests/reddit.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { redditConnector } from '../src/reddit.js';
+
+let fetchMock: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function mockResponse(body: unknown) {
+  return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+/** Reddit listing format with empty children */
+function emptyListing() {
+  return { data: { children: [] } };
+}
+
+describe('Reddit Connector', () => {
+  it('should have correct metadata', () => {
+    expect(redditConnector.id).toBe('reddit');
+    expect(redditConnector.name).toBe('Reddit');
+    expect(redditConnector.version).toBe('1.0.0');
+    expect(redditConnector.category).toBe('social');
+  });
+
+  it('should use OAuth2 authentication', () => {
+    expect(redditConnector.auth.type).toBe('oauth2');
+    expect(redditConnector.auth.oauth2).toBeDefined();
+    expect(redditConnector.auth.oauth2!.authUrl).toBe('https://www.reddit.com/api/v1/authorize');
+    expect(redditConnector.auth.oauth2!.tokenUrl).toBe('https://www.reddit.com/api/v1/access_token');
+    expect(redditConnector.auth.oauth2!.scopes).toContain('submit');
+    expect(redditConnector.auth.oauth2!.scopes).toContain('vote');
+    expect(redditConnector.auth.oauth2!.scopes.length).toBe(6);
+  });
+
+  it('should define all 8 actions', () => {
+    expect(redditConnector.actions).toHaveLength(8);
+    const actionIds = redditConnector.actions.map((a) => a.id);
+    expect(actionIds).toContain('front-page');
+    expect(actionIds).toContain('subreddit-read');
+    expect(actionIds).toContain('post-submit');
+    expect(actionIds).toContain('comment');
+    expect(actionIds).toContain('inbox-read');
+    expect(actionIds).toContain('search');
+    expect(actionIds).toContain('save-post');
+    expect(actionIds).toContain('upvote');
+  });
+
+  it('should have correct trust levels', () => {
+    const readAction = redditConnector.actions.find((a) => a.id === 'front-page');
+    expect(readAction!.trustMinimum).toBe(1);
+
+    const submitAction = redditConnector.actions.find((a) => a.id === 'post-submit');
+    expect(submitAction!.trustMinimum).toBe(3);
+    expect(submitAction!.sideEffects).toBe(true);
+
+    const voteAction = redditConnector.actions.find((a) => a.id === 'upvote');
+    expect(voteAction!.trustMinimum).toBe(2);
+    expect(voteAction!.reversible).toBe(true);
+  });
+
+  it('should mark save-post as reversible', () => {
+    const saveAction = redditConnector.actions.find((a) => a.id === 'save-post');
+    expect(saveAction!.reversible).toBe(true);
+    expect(saveAction!.sideEffects).toBe(true);
+    expect(saveAction!.trustMinimum).toBe(1);
+  });
+
+  it('should execute front-page action', async () => {
+    // GET /best?limit=25 -> listing with no children
+    fetchMock.mockResolvedValueOnce(mockResponse(emptyListing()));
+    const result = await redditConnector.executeAction('front-page', {}, 'token');
+    expect(result).toEqual({ posts: [] });
+  });
+
+  it('should execute subreddit-read action', async () => {
+    // GET /r/typescript/hot?limit=25 -> listing with no children
+    fetchMock.mockResolvedValueOnce(mockResponse(emptyListing()));
+    const result = await redditConnector.executeAction('subreddit-read', { subreddit: 'typescript' }, 'token') as any;
+    expect(result.posts).toEqual([]);
+  });
+
+  it('should execute post-submit action', async () => {
+    // POST /api/submit -> { json: { data: { id: 'abc123' } } }
+    fetchMock.mockResolvedValueOnce(mockResponse({ json: { data: { id: 'abc123' } } }));
+    const result = await redditConnector.executeAction('post-submit', { subreddit: 'test', title: 'Title', body: 'Body' }, 'token') as any;
+    expect(result.status).toBe('submitted');
+    expect(result.postId).toBe('abc123');
+  });
+
+  it('should execute upvote action with default direction', async () => {
+    // POST /api/vote -> {}
+    fetchMock.mockResolvedValueOnce(mockResponse({}));
+    const result = await redditConnector.executeAction('upvote', { postId: 'p1' }, 'token') as any;
+    expect(result.status).toBe('voted');
+    expect(result.postId).toBe('p1');
+  });
+
+  it('should throw for unknown action', async () => {
+    await expect(redditConnector.executeAction('unknown', {}, 'token')).rejects.toThrow('Unknown action');
+  });
+
+  it('should return empty events from pollTrigger', async () => {
+    // GET /message/unread?limit=25 -> empty listing
+    fetchMock.mockResolvedValueOnce(mockResponse(emptyListing()));
+    const events = await redditConnector.pollTrigger!('new-inbox', 'token');
+    expect(events).toEqual([]);
+  });
+
+  it('should define triggers', () => {
+    expect(redditConnector.triggers).toHaveLength(2);
+    const triggerIds = redditConnector.triggers.map((t) => t.id);
+    expect(triggerIds).toContain('new-inbox');
+    expect(triggerIds).toContain('subreddit-new');
+  });
+
+  it('should define entities', () => {
+    expect(redditConnector.entities).toHaveLength(2);
+    const entityIds = redditConnector.entities.map((e) => e.id);
+    expect(entityIds).toContain('post');
+    expect(entityIds).toContain('comment');
+  });
+});