@hasna/connectors 1.3.42 → 1.3.43

package/connectors/teamwork/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/telnyx/.env.example

@@ -0,0 +1,2 @@
+# Telnyx API key (create one at https://portal.telnyx.com under Account > API Keys)
+TELNYX_API_KEY=your-telnyx-api-key

package/connectors/telnyx/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with this repository.
+
+## Project Overview
+
+Telnyx API connector CLI — a TypeScript wrapper for the Telnyx v2 API
+(`https://api.telnyx.com/v2`). Covers messaging, phone numbers, number search,
+messaging profiles, and number lookup.
+
+## Build & Run Commands
+
+```bash
+bun install        # Install dependencies
+bun run dev        # Run CLI in development
+bun run build      # Build for distribution
+bun run typecheck  # Type check
+bun test           # Run tests
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts              # HTTP client: Bearer auth, JSON body, error parsing
+│   ├── messages.ts            # send / get
+│   ├── phone-numbers.ts       # list / get owned numbers
+│   ├── available-numbers.ts   # search numbers to purchase
+│   ├── messaging-profiles.ts  # list / get
+│   ├── number-lookup.ts       # carrier / caller lookup
+│   └── index.ts               # Telnyx aggregate class
+├── cli/index.ts               # CLI commands
+├── types/index.ts             # Types + TelnyxApiError
+├── utils/
+│   ├── config.ts              # Multi-profile configuration
+│   └── output.ts              # CLI output formatting
+└── index.ts                   # Library exports
+```
+
+## Authentication
+
+Bearer token: `Authorization: Bearer <api_key>`. The key resolves from the
+`TELNYX_API_KEY` env var, the `--api-key` flag, or the profile config.
+
+## API Notes
+
+- Requests and responses are JSON. List/single responses use a `{ data, meta }`
+  envelope; array filters are repeated query params (e.g. `filter[features]=sms`).
+- Errors follow `{ "errors": [{ code, title, detail }] }` and are surfaced as
+  `TelnyxApiError` (see `src/types/index.ts`). This differs from other connectors
+  (e.g. Twilio's `{ message, code, more_info }`) — do not copy that parsing here.
+- Telnyx has no "list messages" endpoint; only send and retrieve-by-id exist.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TELNYX_API_KEY` | Telnyx API key |
+
+## Data Storage
+
+```
+~/.hasna/connectors/connect-telnyx/
+├── current_profile   # Active profile name
+└── profiles/
+    └── <name>/config.json
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/telnyx/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+Telnyx API connector CLI — a TypeScript wrapper for the Telnyx v2 API
+(`https://api.telnyx.com/v2`). Covers messaging, phone numbers, number search,
+messaging profiles, and number lookup.
+
+## Build & Run Commands
+
+```bash
+bun install        # Install dependencies
+bun run dev        # Run CLI in development
+bun run build      # Build for distribution
+bun run typecheck  # Type check
+bun test           # Run tests
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts              # HTTP client: Bearer auth, JSON body, error parsing
+│   ├── messages.ts            # send / get
+│   ├── phone-numbers.ts       # list / get owned numbers
+│   ├── available-numbers.ts   # search numbers to purchase
+│   ├── messaging-profiles.ts  # list / get
+│   ├── number-lookup.ts       # carrier / caller lookup
+│   └── index.ts               # Telnyx aggregate class
+├── cli/index.ts               # CLI commands
+├── types/index.ts             # Types + TelnyxApiError
+├── utils/
+│   ├── config.ts              # Multi-profile configuration
+│   └── output.ts              # CLI output formatting
+└── index.ts                   # Library exports
+```
+
+## Authentication
+
+Bearer token: `Authorization: Bearer <api_key>`. The key resolves from the
+`TELNYX_API_KEY` env var, the `--api-key` flag, or the profile config.
+
+## API Notes
+
+- Requests and responses are JSON. List/single responses use a `{ data, meta }`
+  envelope; array filters are repeated query params (e.g. `filter[features]=sms`).
+- Errors follow `{ "errors": [{ code, title, detail }] }` and are surfaced as
+  `TelnyxApiError` (see `src/types/index.ts`). This differs from other connectors
+  (e.g. Twilio's `{ message, code, more_info }`) — do not copy that parsing here.
+- Telnyx has no "list messages" endpoint; only send and retrieve-by-id exist.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TELNYX_API_KEY` | Telnyx API key |
+
+## Data Storage
+
+```
+~/.hasna/connectors/connect-telnyx/
+├── current_profile   # Active profile name
+└── profiles/
+    └── <name>/config.json
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/telnyx/README.md

@@ -0,0 +1,103 @@
+# connect-telnyx
+
+Telnyx API connector CLI — a TypeScript wrapper for the [Telnyx v2 API](https://developers.telnyx.com/api). Send SMS/MMS, manage and search phone numbers, list messaging profiles, and run carrier/caller number lookups, with multi-profile credential support.
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-telnyx
+```
+
+## Quick Start
+
+```bash
+# Set your API key (create one in the Telnyx portal under Account > API Keys)
+connect-telnyx config set-api-key YOUR_API_KEY
+
+# Or use an environment variable
+export TELNYX_API_KEY=YOUR_API_KEY
+```
+
+## CLI Commands
+
+```bash
+# Configuration
+connect-telnyx config set-api-key <key>   # Store the API key
+connect-telnyx config show                # Show config (API key masked)
+connect-telnyx config clear               # Clear stored credentials
+
+# Profiles
+connect-telnyx profile list               # List profiles
+connect-telnyx profile use <name>         # Switch profile
+connect-telnyx profile create <name>      # Create a profile
+
+# Messages
+connect-telnyx message send --to +15551230000 --from +15550001111 --body "Hello"
+connect-telnyx message get <message-id>
+
+# Phone numbers
+connect-telnyx numbers list
+connect-telnyx numbers get <phone-number-id>
+connect-telnyx numbers search --country-code US --national-destination-code 415 --feature sms
+
+# Messaging profiles
+connect-telnyx profiles list
+connect-telnyx profiles get <messaging-profile-id>
+
+# Number lookup
+connect-telnyx lookup +15551230000 --type carrier
+```
+
+Add `--format json` (or `table`) to any command to change the output format, and `--profile <name>` to target a specific profile for a single command.
+
+## Programmatic Usage
+
+```ts
+import { Telnyx } from '@hasna/connect-telnyx';
+
+const telnyx = new Telnyx({ apiKey: process.env.TELNYX_API_KEY! });
+
+const message = await telnyx.messages.send({
+  from: '+15550001111',
+  to: '+15551230000',
+  text: 'Hello from Telnyx',
+});
+
+const numbers = await telnyx.availableNumbers.search({
+  country_code: 'US',
+  features: ['sms', 'mms'],
+});
+```
+
+## API Coverage
+
+| Module | Method | Endpoint |
+|--------|--------|----------|
+| `messages` | `send` | `POST /messages` |
+| `messages` | `get` | `GET /messages/{id}` |
+| `phoneNumbers` | `list` | `GET /phone_numbers` |
+| `phoneNumbers` | `get` | `GET /phone_numbers/{id}` |
+| `availableNumbers` | `search` | `GET /available_phone_numbers` |
+| `messagingProfiles` | `list` | `GET /messaging_profiles` |
+| `messagingProfiles` | `get` | `GET /messaging_profiles/{id}` |
+| `numberLookup` | `lookup` | `GET /number_lookup/{phone_number}` |
+
+## Authentication
+
+All requests use `Authorization: Bearer <TELNYX_API_KEY>`. The key is read from
+(in priority order) the `TELNYX_API_KEY` environment variable, the `--api-key`
+flag, or the active profile config in `~/.hasna/connectors/connect-telnyx/`.
+
+## Development
+
+```bash
+bun install
+bun run dev --help
+bun run typecheck
+bun test
+bun run build
+```
+
+## License
+
+Apache-2.0

package/connectors/telnyx/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hasna/connect-telnyx",
+  "version": "0.0.1",
+  "description": "Telnyx API connector CLI - send messages, manage numbers, and look up carrier data with multi-profile support",
+  "type": "module",
+  "bin": {
+    "connect-telnyx": "bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  },
+  "homepage": "https://github.com/hasna/connectors#readme",
+  "bugs": {
+    "url": "https://github.com/hasna/connectors/issues"
+  },
+  "keywords": [
+    "telnyx",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "sms",
+    "voice",
+    "messaging",
+    "number-lookup",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/connectors/telnyx/src/api/available-numbers.ts

@@ -0,0 +1,42 @@
+import type { TelnyxClient } from './client';
+import type {
+  AvailablePhoneNumber,
+  SearchAvailableNumbersParams,
+  TelnyxListResponse,
+} from '../types';
+
+/**
+ * Telnyx Number Search API — find phone numbers available to purchase.
+ * `GET /available_phone_numbers`. A `country_code` filter is required upstream.
+ */
+export class AvailableNumbersApi {
+  constructor(private readonly client: TelnyxClient) {}
+
+  /**
+   * Search for available phone numbers matching the given filters.
+   */
+  async search(
+    params: SearchAvailableNumbersParams = {}
+  ): Promise<TelnyxListResponse<AvailablePhoneNumber>> {
+    const query: Record<string, unknown> = {
+      'filter[country_code]': params.country_code,
+      'filter[phone_number][starts_with]': params.starts_with,
+      'filter[phone_number][ends_with]': params.ends_with,
+      'filter[phone_number][contains]': params.contains,
+      'filter[locality]': params.locality,
+      'filter[administrative_area]': params.administrative_area,
+      'filter[national_destination_code]': params.national_destination_code,
+      'filter[phone_number_type]': params.phone_number_type,
+      'filter[features]': params.features,
+      'filter[limit]': params.limit,
+      'filter[best_effort]': params.best_effort,
+      'filter[quickship]': params.quickship,
+      'filter[reservable]': params.reservable,
+      'filter[exclude_held_numbers]': params.exclude_held_numbers,
+    };
+    return this.client.get<TelnyxListResponse<AvailablePhoneNumber>>(
+      '/available_phone_numbers',
+      query
+    );
+  }
+}

package/connectors/telnyx/src/api/client.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { Telnyx } from './index';
+import { TelnyxApiError } from '../types';
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe('Telnyx client', () => {
+  test('sends a Bearer token and JSON body when sending a message', async () => {
+    const fetchMock = mock(async () =>
+      Response.json({ data: { id: 'msg-1', to: [{ phone_number: '+15551230000' }] } })
+    );
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telnyx = new Telnyx({ apiKey: 'KEY_test_123456' });
+    await telnyx.messages.send({
+      from: '+15550001111',
+      to: '+15551230000',
+      text: 'Hi from Telnyx',
+    });
+
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.telnyx.com/v2/messages');
+    expect(init.method).toBe('POST');
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe('Bearer KEY_test_123456');
+    expect(headers['Content-Type']).toBe('application/json');
+    expect(JSON.parse(String(init.body))).toMatchObject({
+      from: '+15550001111',
+      to: '+15551230000',
+      text: 'Hi from Telnyx',
+    });
+  });
+
+  test('parses the Telnyx error envelope into TelnyxApiError', async () => {
+    const fetchMock = mock(async () =>
+      Response.json(
+        {
+          errors: [
+            {
+              code: '10015',
+              title: 'Invalid API key',
+              detail: 'The API key provided is not valid.',
+            },
+          ],
+        },
+        { status: 401 }
+      )
+    );
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telnyx = new Telnyx({ apiKey: 'bad-key' });
+
+    let caught: unknown;
+    try {
+      await telnyx.messages.get('msg-1');
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(TelnyxApiError);
+    const apiError = caught as TelnyxApiError;
+    expect(apiError.status).toBe(401);
+    expect(apiError.code).toBe('10015');
+    expect(apiError.message).toBe('Invalid API key: The API key provided is not valid.');
+    expect(apiError.isAuthError()).toBe(true);
+  });
+
+  test('builds repeated query params for array filters', async () => {
+    const fetchMock = mock(async () => Response.json({ data: [] }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const telnyx = new Telnyx({ apiKey: 'KEY_test' });
+    await telnyx.availableNumbers.search({ country_code: 'US', features: ['sms', 'mms'] });
+
+    const [url] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toBe('/v2/available_phone_numbers');
+    expect(parsed.searchParams.get('filter[country_code]')).toBe('US');
+    expect(parsed.searchParams.getAll('filter[features]')).toEqual(['sms', 'mms']);
+  });
+
+  test('requires from or messaging_profile_id when sending', async () => {
+    const telnyx = new Telnyx({ apiKey: 'KEY_test' });
+    await expect(telnyx.messages.send({ to: '+15551230000', text: 'hi' })).rejects.toThrow(
+      /from.*messaging_profile_id/
+    );
+  });
+});

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

@@ -0,0 +1,142 @@
+import type { TelnyxConfig, TelnyxErrorDetail } from '../types';
+import { TelnyxApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.telnyx.com/v2';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  params?: Record<string, unknown>;
+  body?: Record<string, unknown>;
+  headers?: Record<string, string>;
+}
+
+/**
+ * HTTP client for the Telnyx v2 API.
+ *
+ * Auth: `Authorization: Bearer <API_KEY>`.
+ * Requests and responses are JSON. Errors follow Telnyx's shape:
+ * `{ "errors": [{ "code", "title", "detail", ... }] }`.
+ */
+export class TelnyxClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: TelnyxConfig) {
+    if (!config.apiKey) {
+      throw new Error('Telnyx API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+  }
+
+  private buildUrl(path: string, params?: Record<string, unknown>): string {
+    const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '') {
+          continue;
+        }
+        // Telnyx array filters are repeated: filter[features][]=sms
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item !== undefined && item !== null && item !== '') {
+              url.searchParams.append(key, String(item));
+            }
+          }
+        } else {
+          url.searchParams.append(key, String(value));
+        }
+      }
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to the Telnyx API.
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      ...headers,
+    };
+
+    const fetchOptions: RequestInit = { method, headers: requestHeaders };
+
+    if (body !== undefined && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const text = await response.text();
+    let data: unknown = undefined;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+
+    if (!response.ok) {
+      throw this.toApiError(response.status, response.statusText, data);
+    }
+
+    return data as T;
+  }
+
+  private toApiError(status: number, statusText: string, data: unknown): TelnyxApiError {
+    const errors: TelnyxErrorDetail[] =
+      data && typeof data === 'object' && Array.isArray((data as { errors?: unknown }).errors)
+        ? ((data as { errors: TelnyxErrorDetail[] }).errors)
+        : [];
+
+    const first = errors[0];
+    const message =
+      [first?.title, first?.detail].filter(Boolean).join(': ') ||
+      first?.title ||
+      first?.detail ||
+      statusText ||
+      `Telnyx API request failed with status ${status}`;
+
+    return new TelnyxApiError(message, status, errors);
+  }
+
+  async get<T>(path: string, params?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+
+  /**
+   * Masked preview of the API key for display/debugging.
+   */
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

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

@@ -0,0 +1,63 @@
+import type { TelnyxConfig } from '../types';
+import { TelnyxClient } from './client';
+import { MessagesApi } from './messages';
+import { PhoneNumbersApi } from './phone-numbers';
+import { AvailableNumbersApi } from './available-numbers';
+import { MessagingProfilesApi } from './messaging-profiles';
+import { NumberLookupApi } from './number-lookup';
+
+/**
+ * Main Telnyx connector class.
+ * Aggregates the individual Telnyx v2 API modules.
+ */
+export class Telnyx {
+  private readonly client: TelnyxClient;
+
+  public readonly messages: MessagesApi;
+  public readonly phoneNumbers: PhoneNumbersApi;
+  public readonly availableNumbers: AvailableNumbersApi;
+  public readonly messagingProfiles: MessagingProfilesApi;
+  public readonly numberLookup: NumberLookupApi;
+
+  constructor(config: TelnyxConfig) {
+    this.client = new TelnyxClient(config);
+
+    this.messages = new MessagesApi(this.client);
+    this.phoneNumbers = new PhoneNumbersApi(this.client);
+    this.availableNumbers = new AvailableNumbersApi(this.client);
+    this.messagingProfiles = new MessagingProfilesApi(this.client);
+    this.numberLookup = new NumberLookupApi(this.client);
+  }
+
+  /**
+   * Create a client from the `TELNYX_API_KEY` environment variable.
+   */
+  static fromEnv(): Telnyx {
+    const apiKey = process.env.TELNYX_API_KEY;
+    if (!apiKey) {
+      throw new Error('TELNYX_API_KEY environment variable is required');
+    }
+    return new Telnyx({ apiKey });
+  }
+
+  /**
+   * Get the underlying client for direct API access.
+   */
+  getClient(): TelnyxClient {
+    return this.client;
+  }
+
+  /**
+   * Masked preview of the configured API key.
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+}
+
+export { TelnyxClient } from './client';
+export { MessagesApi } from './messages';
+export { PhoneNumbersApi } from './phone-numbers';
+export { AvailableNumbersApi } from './available-numbers';
+export { MessagingProfilesApi } from './messaging-profiles';
+export { NumberLookupApi } from './number-lookup';