@hasna/connectors 1.4.1 → 1.4.3

package/connectors/stop-and-error/src/api/client.test.ts

@@ -51,11 +51,11 @@ afterEach(() => {
 describe('StopAndErrorClient', () => {
   const mockConfig = {
     apiKey: 'test-api-key-12345',
-    baseUrl: 'https://api.stop-and-error.com/v1',
+    baseUrl: 'https://configured.example.com/v1',
   };
 
   test('throws when api key is missing', () => {
-    expect(() => new StopAndErrorClient({ apiKey: '' })).toThrow('API key is required');
+    expect(() => new StopAndErrorClient({ apiKey: '', baseUrl: 'https://configured.example.com/v1' })).toThrow('API key is required');
   });
 
   test('getApiKeyPreview masks long keys', () => {
@@ -65,7 +65,7 @@ describe('StopAndErrorClient', () => {
 
   test('listErrors GET /errors with bearer auth', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/errors?limit=10');
+      expect(req.url).toBe('https://configured.example.com/v1/errors?limit=10');
       expect(req.method).toBe('GET');
       expect(req.headers.authorization).toBe('Bearer test-api-key-12345');
       return { data: [{ id: 'err_1', message: 'boom' }] };
@@ -78,7 +78,7 @@ describe('StopAndErrorClient', () => {
 
   test('getError GET /errors/{id}', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/errors/err_42');
+      expect(req.url).toBe('https://configured.example.com/v1/errors/err_42');
       expect(req.method).toBe('GET');
       return { id: 'err_42', message: 'failed node' };
     });
@@ -90,7 +90,7 @@ describe('StopAndErrorClient', () => {
 
   test('createError POST /errors with body', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/errors');
+      expect(req.url).toBe('https://configured.example.com/v1/errors');
       expect(req.method).toBe('POST');
       expect(req.headers.authorization).toBe('Bearer test-api-key-12345');
       const body = JSON.parse(req.body!);
@@ -106,7 +106,7 @@ describe('StopAndErrorClient', () => {
 
   test('listEvents GET /events', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/events?errorId=err_1');
+      expect(req.url).toBe('https://configured.example.com/v1/events?errorId=err_1');
       expect(req.method).toBe('GET');
       return { data: [{ id: 'evt_1', type: 'error.created' }] };
     });
@@ -118,7 +118,7 @@ describe('StopAndErrorClient', () => {
 
   test('search POST /search with query body', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/search');
+      expect(req.url).toBe('https://configured.example.com/v1/search');
       expect(req.method).toBe('POST');
       const body = JSON.parse(req.body!);
       expect(body.query).toBe('timeout');
@@ -147,7 +147,7 @@ describe('StopAndErrorClient', () => {
 
   test('rawRequest supports custom path and method', async () => {
     const recorded = installFetch((req) => {
-      expect(req.url).toBe('https://api.stop-and-error.com/v1/custom?foo=bar');
+      expect(req.url).toBe('https://configured.example.com/v1/custom?foo=bar');
       expect(req.method).toBe('PUT');
       return { ok: true };
     });
@@ -155,4 +155,8 @@ describe('StopAndErrorClient', () => {
     await connector.rawRequest({ method: 'PUT', path: '/custom', params: { foo: 'bar' } });
     expect(recorded).toHaveLength(1);
   });
+
+  test('refuses to send without a configured base URL (no default endpoint)', () => {
+    expect(() => new StopAndErrorClient({ apiKey: 'test-key' })).toThrow(/baseUrl/);
+  });
 });

package/connectors/stop-and-error/src/api/client.ts

@@ -1,8 +1,6 @@
 import type { StopAndErrorConfig } from '../types';
 import { StopAndErrorApiError } from '../types';
 
-const DEFAULT_BASE_URL = 'https://api.stop-and-error.com/v1';
-
 export interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
   params?: Record<string, string | number | boolean | undefined>;
@@ -19,7 +17,10 @@ export class StopAndErrorClient {
       throw new Error('API key is required');
     }
     this.apiKey = config.apiKey;
-    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(/\/$/, '');
   }
 
   private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {

package/connectors/stop-and-error/src/cli/index.ts

@@ -167,7 +167,7 @@ configCmd
     console.log(chalk.bold(`Active Profile: ${getCurrentProfile()}`));
     info(`Config directory: ${getConfigDir()}`);
     info(`API Key: ${apiKey ? `${apiKey.substring(0, 8)}...` : chalk.gray('not set')}`);
-    info(`Base URL: ${getBaseUrl() || chalk.gray('default (https://api.stop-and-error.com/v1)')}`);
+    info(`Base URL: ${getBaseUrl() || chalk.gray('none configured')}`);
   });
 
 configCmd
@@ -187,7 +187,7 @@ statusCmd.action(() => {
   console.log(chalk.bold('StopAndError Connector Status'));
   info(`Profile: ${getCurrentProfile()}`);
   info(`API Key: ${apiKey ? client!.getApiKeyPreview() : chalk.gray('not set')}`);
-  info(`Base URL: ${getBaseUrl() || 'https://api.stop-and-error.com/v1'}`);
+  info(`Base URL: ${getBaseUrl() || 'none configured'}`);
 });
 
 const errorsCmd = program.command('errors').description('Workflow error operations');

package/connectors/stoplight/package.json

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

package/connectors/stoplight-api-platform/package.json

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

package/connectors/strand-ai/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-Strand AI connector for the open-connectors monorepo.
+Strand AI connector for the connectors monorepo.
 
 ## Overview
 

package/connectors/stripe-financial-connections/.env.example

@@ -1,5 +1,5 @@
 # Stripe Financial Connections API credentials
 STRIPE_FINANCIAL_CONNECTIONS_API_KEY=your-api-key-here
 
-# Optional: override API base URL (default: https://api.stripefinancialconnections.com/v1)
+# Optional: override API base URL (no default - must be configured)
 # STRIPE_FINANCIAL_CONNECTIONS_BASE_URL=https://api.stripefinancialconnections.com/v1

package/connectors/stripe-financial-connections/CLAUDE.md

@@ -54,7 +54,7 @@ connect-stripe-financial-connections raw --path /items --method GET
 
 ## Authentication
 
-Bearer Token authentication. API base URL defaults to `https://api.stripefinancialconnections.com/v1`.
+Bearer Token authentication. API base URL has no default (must be configured).
 
 ## Data Storage
 
@@ -70,7 +70,7 @@ Profile JSON structure:
 ```json
 {
   "apiKey": "your-api-key",
-  "baseUrl": "https://api.stripefinancialconnections.com/v1"
+  "baseUrl": "configured.example.com/v1"
 }
 ```
 

package/connectors/stripe-financial-connections/package.json

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

package/connectors/stripe-financial-connections/src/api/client.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { StripeFinancialConnectionsClient } from './client';
+
+const realFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('StripeFinancialConnectionsClient transport', () => {
+  test('refuses to send without a configured base URL (no default endpoint)', () => {
+    expect(() => new StripeFinancialConnectionsClient({ apiKey: 'test-key' })).toThrow(/baseUrl/);
+  });
+
+  test('sends the API key only to the configured base URL', async () => {
+    const recorded: string[] = [];
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      recorded.push(typeof input === 'string' ? input : input.toString());
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        async text() { return JSON.stringify({ ok: true }); },
+        async json() { return { ok: true }; },
+      } as Response;
+    }) as typeof fetch;
+    const client = new StripeFinancialConnectionsClient({ apiKey: 'test-key', baseUrl: 'https://configured.example.com/v1' });
+    await client.request('/ping');
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].startsWith('https://configured.example.com/v1/')).toBe(true);
+    expect(recorded[0]).not.toContain('api.stripefinancialconnections.com');
+  });
+});

package/connectors/stripe-financial-connections/src/api/client.ts

@@ -1,8 +1,6 @@
 import type { StripeFinancialConnectionsConfig, OutputFormat } from '../types';
 import { StripeFinancialConnectionsApiError } from '../types';
 
-export const DEFAULT_BASE_URL = 'https://api.stripefinancialconnections.com/v1';
-
 export interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
   params?: Record<string, string | number | boolean | undefined>;
@@ -20,7 +18,10 @@ export class StripeFinancialConnectionsClient {
       throw new Error('API key is required');
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    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;
   }
 
   private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {

package/connectors/stripe-financial-connections/src/cli/index.ts

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

package/connectors/stripe-terminal/package.json

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

package/connectors/stytch/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"
   }
 }

package/connectors/sucuri-api-platform/.env.example

@@ -1,5 +1,5 @@
 # Sucuri API Platform credentials (placeholder values only)
 SUCURI_API_PLATFORM_API_KEY=your-api-key-here
 
-# Optional: override the API base URL (default https://api.sucuriapiplatform.com/v1)
+# Optional: override the API base URL (no default - must be configured)
 # SUCURI_API_PLATFORM_BASE_URL=https://api.sucuriapiplatform.com/v1

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

@@ -27,7 +27,7 @@ bun run dev raw request --path /items --method GET
 
 ## API Details
 
-- **Base URL**: `https://api.sucuriapiplatform.com/v1` (override via `SUCURI_API_PLATFORM_BASE_URL` or profile `baseUrl`)
+- **Base URL**: no default (must be configured) (override via `SUCURI_API_PLATFORM_BASE_URL` or profile `baseUrl`)
 - **Auth**: Bearer token (`Authorization: Bearer <api_key>`)
 - **Endpoints**:
   - `GET /items` — list items

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

@@ -1,6 +1,6 @@
 # @hasna/connect-sucuri-api-platform
 
-TypeScript connector and CLI for the [Sucuri API Platform](https://api.sucuriapiplatform.com/v1).
+TypeScript connector and CLI for the [Sucuri API Platform](configured.example.com/v1).
 
 ## Install
 
@@ -13,7 +13,7 @@ bun add @hasna/connect-sucuri-api-platform
 ```bash
 export SUCURI_API_PLATFORM_API_KEY=your-api-key
 # optional
-export SUCURI_API_PLATFORM_BASE_URL=https://api.sucuriapiplatform.com/v1
+export SUCURI_API_PLATFORM_BASE_URL=https://configured.example.com/v1
 ```
 
 Or use the CLI profile/config commands:

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

@@ -1,11 +1,11 @@
 import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
-import { ConnectorClient, DEFAULT_BASE_URL } from './client';
+import { ConnectorClient } from './client';
 import { ConnectorApiError } from '../types';
 
 describe('ConnectorClient', () => {
   const mockConfig = {
     apiKey: 'test-api-key-12345',
-    baseUrl: 'https://api.sucuriapiplatform.com/v1',
+    baseUrl: 'https://configured.example.com/v1',
   };
 
   describe('constructor', () => {
@@ -18,14 +18,16 @@ describe('ConnectorClient', () => {
       expect(client).toBeInstanceOf(ConnectorClient);
     });
 
-    test('uses default base URL when not provided', () => {
-      const client = new ConnectorClient({ apiKey: 'token' });
-      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('strips trailing slash from base URL', () => {
       const client = new ConnectorClient({
         apiKey: 'token',
+        baseUrl: 'https://configured.example.com/v1',
+        baseUrl: 'https://configured.example.com/v1',
+        baseUrl: 'https://configured.example.com/v1',
         baseUrl: 'https://custom.example.com/v1/',
       });
       expect(client.getBaseUrl()).toBe('https://custom.example.com/v1');
@@ -72,7 +74,7 @@ describe('ConnectorClient', () => {
 
       expect(global.fetch).toHaveBeenCalledTimes(1);
       const [url, options] = (global.fetch as ReturnType<typeof mock>).mock.calls[0];
-      expect(url).toBe('https://api.sucuriapiplatform.com/v1/items');
+      expect(url).toBe('https://configured.example.com/v1/items');
       expect(options.method).toBe('GET');
       expect(options.headers.Authorization).toBe('Bearer test-api-key-12345');
       expect(options.headers.Accept).toBe('application/json');

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

@@ -1,8 +1,6 @@
 import type { ConnectorConfig, OutputFormat } from '../types';
 import { ConnectorApiError, parseApiError } from '../types';
 
-export const DEFAULT_BASE_URL = 'https://api.sucuriapiplatform.com/v1';
-
 export interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
   params?: Record<string, string | number | boolean | undefined>;
@@ -23,7 +21,10 @@ export class ConnectorClient {
       throw new Error('Sucuri API Platform API key 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(/\/$/, '');
   }
 
   private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {

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

@@ -49,7 +49,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/sucuri-api-platform/src/cli/index.ts

@@ -187,7 +187,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.sucuriapiplatform.com/v1 (default)')}`);
+    info(`Base URL: ${baseUrl || chalk.gray('none configured')}`);
   });
 
 configCmd

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

@@ -3,7 +3,7 @@
 export { Connector } from './api';
 export * from './types';
 
-export { ConnectorClient, ItemsApi, EventsApi, SearchApi, DEFAULT_BASE_URL } from './api';
+export { ConnectorClient, ItemsApi, EventsApi, SearchApi } from './api';
 
 export {
   getApiKey,

package/connectors/sumo-logic/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"
   }
 }

package/connectors/supabase/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/supabase-api-platform/package.json

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

package/connectors/sysdig/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"
   }
 }

package/connectors/tableau/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/takecareos/README.md

@@ -1,6 +1,6 @@
 # @hasna/connect-takecareos
 
-TakeCareOS connector for the [open-connectors](https://github.com/hasna/open-connectors) registry.
+TakeCareOS connector for the [connectors](https://github.com/hasna/apps) registry.
 
 TakeCareOS is a home-care agency operating system. This connector wraps its public
 REST API to manage clients (care recipients), caregivers, shifts, incident reports,
@@ -18,7 +18,7 @@ The connector authenticates with a Bearer API key. Provide it via environment
 variable, a CLI flag, or a stored profile:
 
 ```bash
-export TAKECAREOS_API_KEY=your-api-key
+export TAKECAREOS_API_KEY=<your-api-key>
 # optional, for a dedicated/regional host
 export TAKECAREOS_BASE_URL=https://api.takecareos.com/v1
 ```

package/connectors/takecareos/package.json

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

package/connectors/telegram/src/api/bot.ts

@@ -59,6 +59,11 @@ export interface GetFileOptions {
   fileId: string;
 }
 
+export interface DownloadFileResult {
+  file: TelegramFile;
+  data: Uint8Array;
+}
+
 export interface BotName {
   name: string;
 }
@@ -220,4 +225,19 @@ export class BotApi {
       },
     });
   }
+
+  /**
+   * Resolve and download a Telegram file
+   */
+  async downloadFile(options: GetFileOptions): Promise<DownloadFileResult> {
+    const file = await this.getFile(options);
+    if (!file.file_path) {
+      throw new Error('Telegram did not return a downloadable file path');
+    }
+
+    return {
+      file,
+      data: await this.client.downloadFile(file.file_path),
+    };
+  }
 }

package/connectors/telegram/src/api/client.ts

@@ -118,6 +118,38 @@ export class TelegramClient {
     return this.request<T>(method, { body: formData });
   }
 
+  /**
+   * Download a file returned by the Telegram Bot API
+   */
+  async downloadFile(filePath: string): Promise<Uint8Array> {
+    const normalizedPath = filePath.replace(/^\/+/, '');
+    if (!normalizedPath) {
+      throw new Error('Telegram file path is required');
+    }
+
+    const encodedPath = normalizedPath
+      .split('/')
+      .map(segment => encodeURIComponent(segment))
+      .join('/');
+    const url = `${TELEGRAM_API_BASE}/file/bot${this.botToken}/${encodedPath}`;
+
+    let response: Response;
+    try {
+      response = await fetch(url);
+    } catch {
+      throw new Error('Failed to download Telegram file');
+    }
+
+    if (!response.ok) {
+      throw new TelegramApiError(
+        `Telegram file download failed with HTTP ${response.status}`,
+        response.status
+      );
+    }
+
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
   /**
    * Get a preview of the bot token (for display/debugging)
    */

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

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { Telegram } from './index';
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe('Telegram files API', () => {
+  test('resolves a file ID and downloads its bytes from the authenticated file URL', async () => {
+    const botToken = '123456:test-token';
+    const fetchMock = mock(async (
+      input: string | URL | Request,
+      _init?: RequestInit
+    ) => {
+      const url = String(input);
+      if (url.endsWith('/getFile')) {
+        return Response.json({
+          ok: true,
+          result: {
+            file_id: 'incoming-file-id',
+            file_unique_id: 'unique-file-id',
+            file_size: 4,
+            file_path: 'documents/report 1.pdf',
+          },
+        });
+      }
+
+      return new Response(new Uint8Array([1, 2, 3, 4]));
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telegram = new Telegram({ botToken });
+    const downloaded = await telegram.bot.downloadFile({
+      fileId: 'incoming-file-id',
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+      `https://api.telegram.org/bot${botToken}/getFile`
+    );
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      file_id: 'incoming-file-id',
+    });
+    expect(String(fetchMock.mock.calls[1]?.[0])).toBe(
+      `https://api.telegram.org/file/bot${botToken}/documents/report%201.pdf`
+    );
+    expect(downloaded.file.file_path).toBe('documents/report 1.pdf');
+    expect(downloaded.data).toEqual(new Uint8Array([1, 2, 3, 4]));
+  });
+
+  test('fails explicitly when Telegram does not return a file path', async () => {
+    const fetchMock = mock(async () =>
+      Response.json({
+        ok: true,
+        result: {
+          file_id: 'incoming-file-id',
+          file_unique_id: 'unique-file-id',
+        },
+      })
+    );
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telegram = new Telegram({ botToken: '123456:test-token' });
+
+    expect(
+      telegram.bot.downloadFile({ fileId: 'incoming-file-id' })
+    ).rejects.toThrow('Telegram did not return a downloadable file path');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test('does not expose the bot token in download errors', async () => {
+    const botToken = '123456:must-not-leak';
+    const fetchMock = mock(async (
+      input: string | URL | Request,
+      _init?: RequestInit
+    ) => {
+      if (String(input).endsWith('/getFile')) {
+        return Response.json({
+          ok: true,
+          result: {
+            file_id: 'incoming-file-id',
+            file_unique_id: 'unique-file-id',
+            file_path: 'photos/file.jpg',
+          },
+        });
+      }
+      return new Response('not found', { status: 404 });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telegram = new Telegram({ botToken });
+
+    try {
+      await telegram.bot.downloadFile({ fileId: 'incoming-file-id' });
+      throw new Error('Expected download to fail');
+    } catch (err) {
+      expect(String(err)).toContain('Telegram file download failed');
+      expect(String(err)).not.toContain(botToken);
+    }
+  });
+});

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

@@ -64,3 +64,4 @@ export { ChatsApi } from './chats';
 export { UpdatesApi } from './updates';
 export { InlineApi } from './inline';
 export { BotApi } from './bot';
+export type { DownloadFileResult } from './bot';