@hasna/connectors 1.4.1 → 1.4.3

package/connectors/telegram/src/api/messages.test.ts

@@ -9,7 +9,10 @@ afterEach(() => {
 
 describe("Telegram messages API", () => {
   test("sends raw exclamation marks unless MarkdownV2 parse mode is requested", async () => {
-    const fetchMock = mock(async () =>
+    const fetchMock = mock(async (
+      _input: string | URL | Request,
+      _init?: RequestInit
+    ) =>
       Response.json({
         ok: true,
         result: {
@@ -37,7 +40,10 @@ describe("Telegram messages API", () => {
   });
 
   test("preserves raw text when HTML parse mode is explicit", async () => {
-    const fetchMock = mock(async () =>
+    const fetchMock = mock(async (
+      _input: string | URL | Request,
+      _init?: RequestInit
+    ) =>
       Response.json({
         ok: true,
         result: {

package/connectors/telegram/src/cli/files.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { resolveDownloadPath, writeDownloadedFile } from './files';
+
+let temporaryDirectory: string | undefined;
+
+afterEach(() => {
+  if (temporaryDirectory) {
+    rmSync(temporaryDirectory, { recursive: true, force: true });
+    temporaryDirectory = undefined;
+  }
+});
+
+describe('Telegram CLI file downloads', () => {
+  test('uses Telegram file name when the output is a directory', () => {
+    temporaryDirectory = mkdtempSync(join(tmpdir(), 'connect-telegram-'));
+
+    expect(resolveDownloadPath('photos/file_42.jpg', temporaryDirectory)).toBe(
+      join(temporaryDirectory, 'file_42.jpg')
+    );
+  });
+
+  test('creates parent directories without overwriting an existing file', () => {
+    temporaryDirectory = mkdtempSync(join(tmpdir(), 'connect-telegram-'));
+    const destination = join(temporaryDirectory, 'nested', 'file.bin');
+
+    writeDownloadedFile(destination, new Uint8Array([1, 2, 3]));
+    expect(new Uint8Array(readFileSync(destination))).toEqual(
+      new Uint8Array([1, 2, 3])
+    );
+    expect(() =>
+      writeDownloadedFile(destination, new Uint8Array([4, 5, 6]))
+    ).toThrow('Refusing to overwrite existing file');
+    expect(new Uint8Array(readFileSync(destination))).toEqual(
+      new Uint8Array([1, 2, 3])
+    );
+  });
+});

package/connectors/telegram/src/cli/files.ts

@@ -0,0 +1,38 @@
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, join, resolve, sep } from 'path';
+
+export function resolveDownloadPath(
+  telegramFilePath: string,
+  outputPath?: string
+): string {
+  const defaultName = basename(telegramFilePath);
+  if (!defaultName || defaultName === '.' || defaultName === sep) {
+    throw new Error('Telegram did not return a usable file name');
+  }
+
+  if (!outputPath) {
+    return resolve(defaultName);
+  }
+
+  const requestedPath = resolve(outputPath);
+  if (
+    (existsSync(requestedPath) && statSync(requestedPath).isDirectory()) ||
+    (!existsSync(requestedPath) && outputPath.endsWith(sep))
+  ) {
+    return join(requestedPath, defaultName);
+  }
+
+  return requestedPath;
+}
+
+export function writeDownloadedFile(
+  destinationPath: string,
+  data: Uint8Array
+): void {
+  if (existsSync(destinationPath)) {
+    throw new Error(`Refusing to overwrite existing file: ${destinationPath}`);
+  }
+
+  mkdirSync(dirname(destinationPath), { recursive: true });
+  writeFileSync(destinationPath, data, { flag: 'wx' });
+}

package/connectors/telegram/src/cli/index.ts

@@ -4,6 +4,8 @@ import chalk from 'chalk';
 import { readFileSync, existsSync } from 'fs';
 import { basename } from 'path';
 import { Telegram } from '../api';
+import { resolveDownloadPath, writeDownloadedFile } from './files';
+import { formatUpdate } from './updates';
 import {
   getBotToken,
   setBotToken,
@@ -455,36 +457,7 @@ program
         return;
       }
 
-      // Format updates for display
-      const formatted = updates.map(u => {
-        const result: Record<string, unknown> = {
-          update_id: u.update_id,
-        };
-
-        if (u.message) {
-          result.type = 'message';
-          result.from = u.message.from?.username || u.message.from?.first_name || 'unknown';
-          result.chat_id = u.message.chat.id;
-          result.text = u.message.text || '[media]';
-          result.date = new Date(u.message.date * 1000).toISOString();
-        } else if (u.callback_query) {
-          result.type = 'callback_query';
-          result.from = u.callback_query.from.username || u.callback_query.from.first_name;
-          result.data = u.callback_query.data;
-        } else if (u.inline_query) {
-          result.type = 'inline_query';
-          result.from = u.inline_query.from.username || u.inline_query.from.first_name;
-          result.query = u.inline_query.query;
-        } else if (u.edited_message) {
-          result.type = 'edited_message';
-          result.chat_id = u.edited_message.chat.id;
-        } else if (u.channel_post) {
-          result.type = 'channel_post';
-          result.chat_id = u.channel_post.chat.id;
-        }
-
-        return result;
-      });
+      const formatted = updates.map(formatUpdate);
 
       print(formatted, getFormat(program));
       info(`Showing ${updates.length} update(s). Last update_id: ${updates[updates.length - 1].update_id}`);
@@ -494,6 +467,30 @@ program
     }
   });
 
+program
+  .command('get-file <fileId>')
+  .description('Download a Telegram file by file ID')
+  .option('-o, --output <path>', 'Output file or directory (defaults to the Telegram file name)')
+  .action(async (fileId: string, opts: { output?: string }) => {
+    try {
+      const client = getClient();
+      const downloaded = await client.bot.downloadFile({ fileId });
+      const destination = resolveDownloadPath(downloaded.file.file_path!, opts.output);
+      writeDownloadedFile(destination, downloaded.data);
+
+      print({
+        file_id: downloaded.file.file_id,
+        file_unique_id: downloaded.file.file_unique_id,
+        file_path: downloaded.file.file_path,
+        output: destination,
+        bytes: downloaded.data.byteLength,
+      }, getFormat(program));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
 // ============================================
 // Chat Commands
 // ============================================

package/connectors/telegram/src/cli/updates.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test';
+import type { TelegramMessage, TelegramUpdate } from '../types';
+import { formatUpdate } from './updates';
+
+function updateWith(message: Partial<TelegramMessage>): TelegramUpdate {
+  return {
+    update_id: 428687256,
+    message: {
+      message_id: 42,
+      date: 1,
+      chat: { id: 123, type: 'private' },
+      from: {
+        id: 456,
+        is_bot: false,
+        first_name: 'Andrei',
+        username: 'andrei',
+      },
+      ...message,
+    },
+  };
+}
+
+describe('Telegram update formatting', () => {
+  test('exposes the largest incoming photo file ID and caption', () => {
+    const formatted = formatUpdate(updateWith({
+      caption: 'Please inspect this screenshot',
+      photo: [
+        {
+          file_id: 'small-photo-id',
+          file_unique_id: 'small-unique-id',
+          width: 90,
+          height: 90,
+          file_size: 100,
+        },
+        {
+          file_id: 'large-photo-id',
+          file_unique_id: 'large-unique-id',
+          width: 1280,
+          height: 720,
+          file_size: 5000,
+        },
+      ],
+    }));
+
+    expect(formatted).toMatchObject({
+      update_id: 428687256,
+      type: 'message',
+      message_id: 42,
+      caption: 'Please inspect this screenshot',
+      media: {
+        type: 'photo',
+        file_id: 'large-photo-id',
+        file_unique_id: 'large-unique-id',
+        width: 1280,
+        height: 720,
+        file_size: 5000,
+      },
+    });
+    expect(formatted).not.toHaveProperty('text', '[media]');
+  });
+
+  test('exposes actionable metadata for every typed downloadable media kind', () => {
+    const cases: Array<{
+      mediaType: string;
+      message: Partial<TelegramMessage>;
+      fileId: string;
+      expected: Record<string, unknown>;
+    }> = [
+      {
+        mediaType: 'animation',
+        fileId: 'animation-id',
+        message: {
+          animation: {
+            file_id: 'animation-id',
+            file_unique_id: 'animation-unique-id',
+            width: 640,
+            height: 360,
+            duration: 4,
+            file_name: 'instruction.gif',
+            mime_type: 'image/gif',
+            file_size: 2500,
+          },
+        },
+        expected: {
+          width: 640,
+          height: 360,
+          duration: 4,
+          file_name: 'instruction.gif',
+          mime_type: 'image/gif',
+        },
+      },
+      {
+        mediaType: 'document',
+        fileId: 'document-id',
+        message: {
+          document: {
+            file_id: 'document-id',
+            file_unique_id: 'document-unique-id',
+            file_name: 'instructions.pdf',
+            mime_type: 'application/pdf',
+            file_size: 1000,
+          },
+        },
+        expected: {
+          file_name: 'instructions.pdf',
+          mime_type: 'application/pdf',
+        },
+      },
+      {
+        mediaType: 'audio',
+        fileId: 'audio-id',
+        message: {
+          audio: {
+            file_id: 'audio-id',
+            file_unique_id: 'audio-unique-id',
+            duration: 12,
+            file_name: 'note.mp3',
+            mime_type: 'audio/mpeg',
+          },
+        },
+        expected: { duration: 12, file_name: 'note.mp3', mime_type: 'audio/mpeg' },
+      },
+      {
+        mediaType: 'video',
+        fileId: 'video-id',
+        message: {
+          video: {
+            file_id: 'video-id',
+            file_unique_id: 'video-unique-id',
+            width: 1920,
+            height: 1080,
+            duration: 8,
+            file_name: 'screen.mp4',
+            mime_type: 'video/mp4',
+          },
+        },
+        expected: { width: 1920, height: 1080, duration: 8, file_name: 'screen.mp4' },
+      },
+      {
+        mediaType: 'voice',
+        fileId: 'voice-id',
+        message: {
+          voice: {
+            file_id: 'voice-id',
+            file_unique_id: 'voice-unique-id',
+            duration: 5,
+            mime_type: 'audio/ogg',
+          },
+        },
+        expected: { duration: 5, mime_type: 'audio/ogg' },
+      },
+      {
+        mediaType: 'video_note',
+        fileId: 'video-note-id',
+        message: {
+          video_note: {
+            file_id: 'video-note-id',
+            file_unique_id: 'video-note-unique-id',
+            length: 384,
+            duration: 6,
+          },
+        },
+        expected: { length: 384, duration: 6 },
+      },
+    ];
+
+    for (const testCase of cases) {
+      const formatted = formatUpdate(updateWith(testCase.message));
+      expect(formatted.media).toMatchObject({
+        type: testCase.mediaType,
+        file_id: testCase.fileId,
+        ...testCase.expected,
+      });
+    }
+  });
+});

package/connectors/telegram/src/cli/updates.ts

@@ -0,0 +1,95 @@
+import type {
+  TelegramAnimation,
+  TelegramAudio,
+  TelegramDocument,
+  TelegramMessage,
+  TelegramPhotoSize,
+  TelegramUpdate,
+  TelegramVideo,
+  TelegramVideoNote,
+  TelegramVoice,
+} from '../types';
+
+type TelegramMedia =
+  | ({ type: 'photo' } & TelegramPhotoSize)
+  | ({ type: 'animation' } & TelegramAnimation)
+  | ({ type: 'document' } & TelegramDocument)
+  | ({ type: 'audio' } & TelegramAudio)
+  | ({ type: 'video' } & TelegramVideo)
+  | ({ type: 'voice' } & TelegramVoice)
+  | ({ type: 'video_note' } & TelegramVideoNote);
+
+export function getMessageMedia(message: TelegramMessage): TelegramMedia | undefined {
+  const photo = message.photo?.at(-1);
+  if (photo) {
+    return { type: 'photo', ...photo };
+  }
+  if (message.animation) {
+    return { type: 'animation', ...message.animation };
+  }
+  if (message.document) {
+    return { type: 'document', ...message.document };
+  }
+  if (message.audio) {
+    return { type: 'audio', ...message.audio };
+  }
+  if (message.video) {
+    return { type: 'video', ...message.video };
+  }
+  if (message.voice) {
+    return { type: 'voice', ...message.voice };
+  }
+  if (message.video_note) {
+    return { type: 'video_note', ...message.video_note };
+  }
+  return undefined;
+}
+
+function formatMessage(
+  result: Record<string, unknown>,
+  type: string,
+  message: TelegramMessage
+): void {
+  result.type = type;
+  result.message_id = message.message_id;
+  result.from = message.from?.username || message.from?.first_name || 'unknown';
+  result.chat_id = message.chat.id;
+  if (message.text !== undefined) {
+    result.text = message.text;
+  }
+  if (message.caption !== undefined) {
+    result.caption = message.caption;
+  }
+
+  const media = getMessageMedia(message);
+  if (media) {
+    result.media = media;
+  }
+  result.date = new Date(message.date * 1000).toISOString();
+}
+
+export function formatUpdate(update: TelegramUpdate): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    update_id: update.update_id,
+  };
+
+  if (update.message) {
+    formatMessage(result, 'message', update.message);
+  } else if (update.callback_query) {
+    result.type = 'callback_query';
+    result.from = update.callback_query.from.username || update.callback_query.from.first_name;
+    result.data = update.callback_query.data;
+  } else if (update.inline_query) {
+    result.type = 'inline_query';
+    result.from = update.inline_query.from.username || update.inline_query.from.first_name;
+    result.query = update.inline_query.query;
+  } else if (update.edited_message) {
+    formatMessage(result, 'edited_message', update.edited_message);
+  } else if (update.channel_post) {
+    formatMessage(result, 'channel_post', update.channel_post);
+  } else if (update.edited_channel_post) {
+    formatMessage(result, 'edited_channel_post', update.edited_channel_post);
+  }
+
+  return result;
+}

package/connectors/telegram/src/index.ts

@@ -6,6 +6,7 @@ export * from './types';
 
 // Re-export individual API classes for advanced usage
 export { TelegramClient, MessagesApi, ChatsApi, UpdatesApi, InlineApi, BotApi } from './api';
+export type { DownloadFileResult } from './api';
 
 // Export config utilities
 export {

package/connectors/telegram/src/types/index.ts

@@ -156,6 +156,7 @@ export interface TelegramMessage {
   entities?: TelegramMessageEntity[];
   caption?: string;
   caption_entities?: TelegramMessageEntity[];
+  animation?: TelegramAnimation;
   audio?: TelegramAudio;
   document?: TelegramDocument;
   photo?: TelegramPhotoSize[];
@@ -203,6 +204,18 @@ export interface TelegramPhotoSize {
   file_size?: number;
 }
 
+export interface TelegramAnimation {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  duration: number;
+  thumbnail?: TelegramPhotoSize;
+  file_name?: string;
+  mime_type?: string;
+  file_size?: number;
+}
+
 export interface TelegramAudio {
   file_id: string;
   file_unique_id: string;

package/connectors/terraform-cloud/package.json

@@ -47,6 +47,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }

package/connectors/tettra-api-platform/CLAUDE.md

@@ -4,7 +4,7 @@ Tettra Api Platform connector — knowledge items, events, and search API.
 
 ## API Details
 
-- **Base URL**: `https://api.tettraapiplatform.com/v1` (override via `TETTRA_API_PLATFORM_BASE_URL`)
+- **Base URL**: no default (must be configured) (override via `TETTRA_API_PLATFORM_BASE_URL`)
 - **Auth**: Bearer token (`Authorization: Bearer <api_key>`)
 - **Endpoints**: `GET /items`, `POST /items`, `GET /items/:itemId`, `GET /events`, `POST /search`
 

package/connectors/tettra-api-platform/README.md

@@ -1,6 +1,6 @@
 # @hasna/connect-tettra-api-platform
 
-TypeScript connector and CLI for the [Tettra Api Platform](https://api.tettraapiplatform.com/v1) API.
+TypeScript connector and CLI for the [Tettra Api Platform](configured.example.com/v1) API.
 
 ## Install
 
@@ -13,7 +13,7 @@ bun install
 ```bash
 export TETTRA_API_PLATFORM_API_KEY=your-api-key
 # optional
-export TETTRA_API_PLATFORM_BASE_URL=https://api.tettraapiplatform.com/v1
+export TETTRA_API_PLATFORM_BASE_URL=https://configured.example.com/v1
 ```
 
 Or use the CLI profile:

package/connectors/tettra-api-platform/src/api/client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { ConnectorClient, DEFAULT_BASE_URL } from './client';
+import { ConnectorClient } from './client';
 import { ItemsApi } from './items';
 import { ConnectorApiError } from '../types';
 
@@ -51,9 +51,8 @@ describe('ConnectorClient', () => {
     expect(() => new ConnectorClient({})).toThrow('API key or token is required');
   });
 
-  test('uses default base URL when not provided', () => {
-    const client = new ConnectorClient({ apiKey: 'key' });
-    expect(client.getBaseUrl()).toBe(DEFAULT_BASE_URL);
+    test('refuses to send without a configured base URL (no default endpoint)', () => {
+    expect(() => new ConnectorClient({ apiKey: 'test-key' })).toThrow(/baseUrl/);
   });
 
   test('uses custom base URL when provided', () => {
@@ -99,21 +98,21 @@ describe('ConnectorClient', () => {
 describe('ItemsApi', () => {
   test('listItems calls GET /items on default base URL', async () => {
     const recorded = installFetch(() => [{ id: '1' }]);
-    const client = new ConnectorClient({ apiKey: 'key' });
+    const client = new ConnectorClient({ apiKey: 'key', baseUrl: 'https://configured.example.com/v1' });
     const items = new ItemsApi(client);
     const result = await items.list();
 
-    expect(recorded[0].url).toBe(`${DEFAULT_BASE_URL}/items`);
+    expect(recorded[0].url).toBe(`https://configured.example.com/v1/items`);
     expect(recorded[0].headers.Authorization).toBe('Bearer key');
     expect(result).toEqual([{ id: '1' }]);
   });
 
   test('getItem calls GET /items/:itemId with encoded id', async () => {
     const recorded = installFetch(() => ({ id: 'abc/def' }));
-    const client = new ConnectorClient({ apiKey: 'key' });
+    const client = new ConnectorClient({ apiKey: 'key', baseUrl: 'https://configured.example.com/v1' });
     const items = new ItemsApi(client);
     await items.get('abc/def');
 
-    expect(recorded[0].url).toBe(`${DEFAULT_BASE_URL}/items/abc%2Fdef`);
+    expect(recorded[0].url).toBe(`https://configured.example.com/v1/items/abc%2Fdef`);
   });
 });

package/connectors/tettra-api-platform/src/api/client.ts

@@ -1,8 +1,6 @@
 import type { ConnectorConfig } from '../types';
 import { ConnectorApiError, parseApiError } from '../types';
 
-export const DEFAULT_BASE_URL = 'https://api.tettraapiplatform.com/v1';
-
 export interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
   params?: Record<string, string | number | boolean | undefined>;
@@ -22,7 +20,10 @@ export class ConnectorClient {
       throw new Error('API key or token is required');
     }
     this.apiKey = key;
-    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    if (!config.baseUrl) {
+      throw new Error('baseUrl is required: no default endpoint is configured; set baseUrl (profile, config, or the connector BASE_URL environment variable)');
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
   }
 
   getBaseUrl(): string {

package/connectors/tettra-api-platform/src/api/index.ts

@@ -45,7 +45,7 @@ export class Connector {
   }
 }
 
-export { ConnectorClient, DEFAULT_BASE_URL } from './client';
+export { ConnectorClient } from './client';
 export { ItemsApi } from './items';
 export { EventsApi } from './events';
 export { SearchApi } from './search';

package/connectors/tettra-api-platform/src/cli/index.ts

@@ -192,7 +192,7 @@ configCmd
     console.log(chalk.bold(`Active Profile: ${profileName}`));
     info(`Config directory: ${getConfigDir()}`);
     info(`API Key: ${apiKey ? `${apiKey.substring(0, 8)}...` : chalk.gray('not set')}`);
-    info(`Base URL: ${baseUrl || chalk.gray('https://api.tettraapiplatform.com/v1 (default)')}`);
+    info(`Base URL: ${baseUrl || chalk.gray('none configured')}`);
   });
 
 configCmd

package/connectors/tettra-api-platform/src/index.ts

@@ -1,4 +1,4 @@
-export { Connector, ConnectorClient, DEFAULT_BASE_URL, ItemsApi, EventsApi, SearchApi, RawApi } from './api';
+export { Connector, ConnectorClient, ItemsApi, EventsApi, SearchApi, RawApi } from './api';
 export * from './types';
 
 export {

package/connectors/textit/package.json

@@ -47,6 +47,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }

package/connectors/thousandeyes/package.json

@@ -46,6 +46,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }

package/connectors/ticket-tailor/package.json

@@ -46,6 +46,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }

package/connectors/ticketsource/package.json

@@ -46,6 +46,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }

package/connectors/tiktokads/README.md

@@ -1,6 +1,6 @@
 # connect-tiktokads
 
-TikTok Ads Marketing API connector for the open-connectors monorepo.
+TikTok Ads Marketing API connector for the connectors monorepo.
 
 This package targets the **Advertising** category (`tiktokads` slug) and covers campaign management, reporting, pixels, and creative assets via the [TikTok Marketing API](https://business-api.tiktok.com/portal/docs).
 

package/connectors/time-saved/package.json

@@ -49,6 +49,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/open-connectors.git"
+    "url": "git+https://github.com/hasna/apps.git"
   }
 }