@hasna/connectors 1.3.43 → 1.3.45

package/connectors/takecareos/src/utils/output.ts

@@ -0,0 +1,71 @@
+import chalk from "chalk";
+
+export type OutputFormat = "json" | "pretty";
+
+let verboseMode = false;
+
+export function setVerboseMode(enabled: boolean): void {
+  verboseMode = enabled;
+}
+
+export function isVerboseMode(): boolean {
+  return verboseMode;
+}
+
+export function debug(message: string, data?: unknown): void {
+  if (!verboseMode) return;
+  console.error(chalk.dim(`[debug] ${message}`));
+  if (data !== undefined) {
+    console.error(chalk.gray(typeof data === "object" ? JSON.stringify(data, null, 2) : String(data)));
+  }
+}
+
+export function formatOutput(data: unknown, format: OutputFormat = "pretty"): string {
+  if (format === "json") return JSON.stringify(data, null, 2);
+  return formatPretty(data);
+}
+
+function formatPretty(data: unknown): string {
+  if (Array.isArray(data)) {
+    return data.map((item, i) => `${chalk.cyan(`[${i + 1}]`)} ${formatPrettyItem(item)}`).join("\n\n");
+  }
+  return formatPrettyItem(data);
+}
+
+function formatPrettyItem(item: unknown, indent = 0): string {
+  if (item === null || item === undefined) return chalk.gray("null");
+  if (typeof item !== "object") return String(item);
+
+  const spaces = "  ".repeat(indent);
+  return Object.entries(item as Record<string, unknown>)
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        if (value.length === 0) return `${spaces}${chalk.blue(key)}: ${chalk.gray("[]")}`;
+        if (typeof value[0] === "object") {
+          return `${spaces}${chalk.blue(key)}:\n${value.map((v) => formatPrettyItem(v, indent + 1)).join("\n")}`;
+        }
+        return `${spaces}${chalk.blue(key)}: ${value.join(", ")}`;
+      }
+      if (typeof value === "object" && value !== null) {
+        return `${spaces}${chalk.blue(key)}:\n${formatPrettyItem(value, indent + 1)}`;
+      }
+      return `${spaces}${chalk.blue(key)}: ${chalk.white(String(value))}`;
+    })
+    .join("\n");
+}
+
+export function success(message: string): void {
+  console.log(chalk.green("✓"), message);
+}
+
+export function error(message: string): void {
+  console.error(chalk.red("✗"), message);
+}
+
+export function info(message: string): void {
+  console.log(chalk.blue("ℹ"), message);
+}
+
+export function print(data: unknown, format: OutputFormat = "pretty"): void {
+  console.log(formatOutput(data, format));
+}

package/connectors/takecareos/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/talend-api-platform/.env.example

@@ -0,0 +1,12 @@
+# Talend API Platform connector configuration
+# Copy to .env and fill in real values. Do NOT commit real tokens.
+
+# Personal access token generated in Talend Cloud
+# (Profile preferences > Personal access tokens > Add token)
+TALEND_API_TOKEN=[REDACTED]
+
+# Talend Cloud data-center region: us | eu | ap (default: us)
+TALEND_REGION=us
+
+# Optional: full API base URL override (private/dedicated deployments)
+# TALEND_BASE_URL=https://api.us.cloud.talend.com/tmc/v1.2

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

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in the `connect-talend-api-platform` connector.
+
+## Overview
+
+`@hasna/connect-talend-api-platform` is a TypeScript CLI + library for the
+**Talend Cloud Management Console Public API** (base path `/tmc/v1.2`). It wraps
+the executables (tasks/plans/promotions) and executions endpoints with a real
+`fetch`-based client authenticated with a personal access token (Bearer).
+
+The API host is region-specific:
+- US: `https://api.us.cloud.talend.com/tmc/v1.2`
+- EU: `https://api.eu.cloud.talend.com/tmc/v1.2`
+- AP: `https://api.ap.cloud.talend.com/tmc/v1.2`
+
+## Commands
+
+```bash
+bun install
+bun run dev <command>   # run CLI from source
+bun run typecheck       # tsc --noEmit
+bun test                # bun:test suite
+bun run build           # emit dist/ (lib) and bin/ (CLI)
+```
+
+## Structure
+
+```
+src/
+├── api/
+│   ├── client.ts        # TalendClient — base URL, Bearer auth, request()
+│   ├── index.ts         # TalendApiPlatform — high-level operations + fromEnv()
+│   └── talend.test.ts   # client + operations tests (mocked fetch)
+├── cli/index.ts         # Commander CLI (profile/config/task/plan/promotion/execution)
+├── types/index.ts       # config + entity types + TalendApiError
+├── utils/
+│   ├── config.ts        # multi-profile config (~/.hasna/connectors/…)
+│   └── output.ts        # pretty/table/json formatting
+└── index.ts             # library exports
+```
+
+## Conventions
+
+- ESM, TypeScript strict mode. Dependencies limited to `commander` + `chalk`.
+- All API calls go through `TalendClient.request()`; list endpoints tolerate both
+  bare arrays and paginated `{ items: [...] }` envelopes (see `unwrap`).
+- Credentials resolve from env first (`TALEND_API_TOKEN`, `TALEND_REGION`,
+  `TALEND_BASE_URL`), then the active profile.
+- Never hardcode tokens; `.env.example` holds placeholders only.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TALEND_API_TOKEN` | Personal access token (required) |
+| `TALEND_REGION` | `us`, `eu`, or `ap` (default `us`) |
+| `TALEND_BASE_URL` | Full API base URL override |

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

@@ -0,0 +1,98 @@
+# @hasna/connect-talend-api-platform
+
+A TypeScript CLI and library for the [Talend Cloud Management Console Public API](https://api.us.cloud.talend.com/tmc/) (`/tmc/v1.2`). Manage Talend Cloud **tasks** (executables), **plans**, and **promotions**, run them, and track **executions** — all with a real REST client and Bearer (personal access token) authentication.
+
+## Features
+
+- Real Talend Cloud Management Console Public API client (no scraping)
+- Region-aware base URLs (US, EU, AP) with a base-URL override
+- Multi-profile configuration (switch between tenants/accounts)
+- Task / plan / promotion listing and retrieval
+- Task & plan execution plus execution status/stop
+- Pretty, table, and JSON output formats
+
+## Install
+
+```bash
+bun install
+```
+
+## Authentication
+
+Generate a personal access token in Talend Cloud:
+**Profile preferences → Personal access tokens → Add token**.
+
+Provide it via environment variable or the CLI config:
+
+```bash
+export TALEND_API_TOKEN=your-personal-access-token
+export TALEND_REGION=us   # us | eu | ap (default: us)
+
+# or persist it in a profile
+connect-talend-api-platform config set-token your-personal-access-token
+connect-talend-api-platform config set-region eu
+```
+
+## CLI Usage
+
+```bash
+# Tasks (executables)
+connect-talend-api-platform task list --limit 20
+connect-talend-api-platform task get <executableId>
+connect-talend-api-platform task run <executableId> --param key=value --log-level INFO
+
+# Plans
+connect-talend-api-platform plan list
+connect-talend-api-platform plan run <planId>
+
+# Promotions
+connect-talend-api-platform promotion list
+
+# Executions
+connect-talend-api-platform execution status <executionId>
+connect-talend-api-platform execution stop <executionId>
+```
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `-t, --token <token>` | Personal access token (overrides config) |
+| `-r, --region <region>` | Region: `us`, `eu`, `ap` |
+| `--base-url <url>` | API base URL override |
+| `-f, --format <format>` | Output format: `pretty`, `table`, `json` |
+| `-p, --profile <name>` | Use a specific profile |
+
+## Library Usage
+
+```typescript
+import { TalendApiPlatform } from '@hasna/connect-talend-api-platform';
+
+const talend = TalendApiPlatform.fromEnv(); // uses TALEND_API_TOKEN / TALEND_REGION
+
+const tasks = await talend.listTasks({ limit: 50 });
+const { executionId } = await talend.runTask({ executable: tasks[0].executable });
+const status = await talend.getExecution(executionId);
+console.log(status.status); // e.g. RUNNING, EXECUTED
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TALEND_API_TOKEN` | Personal access token (required) |
+| `TALEND_REGION` | `us`, `eu`, or `ap` (default `us`) |
+| `TALEND_BASE_URL` | Full API base URL override |
+
+## Development
+
+```bash
+bun run dev <command>   # run the CLI from source
+bun run typecheck       # type-check
+bun test                # run tests
+bun run build           # build dist/ and bin/
+```
+
+## License
+
+Apache-2.0

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

@@ -0,0 +1,54 @@
+{
+  "name": "@hasna/connect-talend-api-platform",
+  "version": "0.1.0",
+  "description": "Talend API Platform connector - A TypeScript CLI for the Talend Cloud Management Console Public API",
+  "type": "module",
+  "bin": {
+    "connect-talend-api-platform": "./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",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "api",
+    "connector",
+    "talend",
+    "talend-cloud",
+    "management-console",
+    "etl",
+    "integration",
+    "cli",
+    "typescript",
+    "bun",
+    "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

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

@@ -0,0 +1,104 @@
+import type { TalendConfig, TalendRegion } from '../types';
+import { TalendApiError } from '../types';
+
+// Talend Cloud Management Console Public API — base path is /tmc/v1.2.
+// Each data-center region is served from a distinct host.
+const REGION_HOSTS: Record<TalendRegion, string> = {
+  us: 'https://api.us.cloud.talend.com',
+  eu: 'https://api.eu.cloud.talend.com',
+  ap: 'https://api.ap.cloud.talend.com',
+};
+
+const API_PATH = '/tmc/v1.2';
+
+export interface RequestOptions {
+  method?: string;
+  body?: Record<string, unknown>;
+  params?: Record<string, string | number | boolean | undefined>;
+}
+
+/**
+ * Low-level HTTP client for the Talend Cloud Management Console Public API.
+ * Handles base-URL resolution, Bearer authentication, query building, and
+ * error normalization.
+ */
+export class TalendClient {
+  private readonly token: string;
+  readonly baseUrl: string;
+
+  constructor(config: TalendConfig) {
+    if (!config.token) {
+      throw new Error('Talend personal access token is required');
+    }
+    this.token = config.token;
+
+    if (config.baseUrl) {
+      this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    } else {
+      const region = config.region ?? 'us';
+      const host = REGION_HOSTS[region];
+      if (!host) {
+        throw new Error(`Unknown Talend region "${region}". Expected one of: ${Object.keys(REGION_HOSTS).join(', ')}`);
+      }
+      this.baseUrl = `${host}${API_PATH}`;
+    }
+  }
+
+  /**
+   * Make an authenticated request against the Talend API.
+   * `path` is relative to the resolved base URL (e.g. "/executables").
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', body, params } = options;
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) url.searchParams.append(key, String(value));
+      }
+    }
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      Accept: 'application/json',
+    };
+    const fetchOptions: RequestInit = { method, headers, signal: AbortSignal.timeout(30000) };
+    if (body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      headers['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url.toString(), fetchOptions);
+
+    if (response.status === 204) return {} as T;
+
+    const text = await response.text();
+    const data = text ? safeJsonParse(text) : {};
+
+    if (!response.ok) {
+      const detail = data as { error?: string; errorCode?: string; message?: string };
+      throw new TalendApiError(
+        detail?.error || detail?.message || response.statusText || `HTTP ${response.status}`,
+        response.status,
+        detail?.errorCode,
+      );
+    }
+
+    return data as T;
+  }
+
+  /** Preview of the token for display/debugging without leaking it. */
+  getTokenPreview(): string {
+    if (this.token.length > 10) {
+      return `${this.token.substring(0, 6)}...${this.token.substring(this.token.length - 4)}`;
+    }
+    return '***';
+  }
+}
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}

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

@@ -0,0 +1,148 @@
+// Talend API Platform Connector — Talend Cloud Management Console Public API
+import { TalendClient } from './client';
+import type {
+  TalendConfig,
+  Executable,
+  Plan,
+  Promotion,
+  Execution,
+  ExecutionRef,
+  ExecutionRequest,
+  Paginated,
+} from '../types';
+
+export { TalendClient } from './client';
+
+/**
+ * High-level client for the Talend Cloud Management Console Public API.
+ * Groups the executables (tasks/plans/promotions) and executions endpoints.
+ */
+export class TalendApiPlatform {
+  private readonly client: TalendClient;
+
+  constructor(config: TalendConfig) {
+    this.client = new TalendClient(config);
+  }
+
+  /**
+   * Build a connector from environment variables.
+   * Reads TALEND_API_TOKEN, TALEND_REGION (default 'us'), TALEND_BASE_URL.
+   */
+  static fromEnv(): TalendApiPlatform {
+    const token = process.env.TALEND_API_TOKEN;
+    if (!token) {
+      throw new Error('TALEND_API_TOKEN environment variable is required');
+    }
+    const region = process.env.TALEND_REGION as TalendConfig['region'] | undefined;
+    const baseUrl = process.env.TALEND_BASE_URL;
+    return new TalendApiPlatform({ token, region, baseUrl });
+  }
+
+  // ============================================
+  // Executables — tasks
+  // ============================================
+
+  /** List tasks (executables). GET /executables */
+  async listTasks(options?: { limit?: number; offset?: number; environmentId?: string; workspaceId?: string }): Promise<Executable[]> {
+    const data = await this.client.request<Paginated<Executable> | Executable[]>('/executables', {
+      params: {
+        limit: options?.limit,
+        offset: options?.offset,
+        environmentId: options?.environmentId,
+        workspaceId: options?.workspaceId,
+      },
+    });
+    return unwrap(data);
+  }
+
+  /** Get a single task by executable id. GET /executables/{id} */
+  async getTask(id: string): Promise<Executable> {
+    return this.client.request<Executable>(`/executables/${encodeURIComponent(id)}`);
+  }
+
+  // ============================================
+  // Executables — plans
+  // ============================================
+
+  /** List plans. GET /executables/plans */
+  async listPlans(options?: { limit?: number; offset?: number }): Promise<Plan[]> {
+    const data = await this.client.request<Paginated<Plan> | Plan[]>('/executables/plans', {
+      params: { limit: options?.limit, offset: options?.offset },
+    });
+    return unwrap(data);
+  }
+
+  /** Get a plan by id. GET /executables/plans/{id} */
+  async getPlan(id: string): Promise<Plan> {
+    return this.client.request<Plan>(`/executables/plans/${encodeURIComponent(id)}`);
+  }
+
+  // ============================================
+  // Executables — promotions
+  // ============================================
+
+  /** List promotions. GET /executables/promotions */
+  async listPromotions(options?: { limit?: number; offset?: number }): Promise<Promotion[]> {
+    const data = await this.client.request<Paginated<Promotion> | Promotion[]>('/executables/promotions', {
+      params: { limit: options?.limit, offset: options?.offset },
+    });
+    return unwrap(data);
+  }
+
+  /** Get a promotion by id. GET /executables/promotions/{id} */
+  async getPromotion(id: string): Promise<Promotion> {
+    return this.client.request<Promotion>(`/executables/promotions/${encodeURIComponent(id)}`);
+  }
+
+  // ============================================
+  // Executions
+  // ============================================
+
+  /** Execute a task. POST /executions */
+  async runTask(request: ExecutionRequest): Promise<ExecutionRef> {
+    return this.client.request<ExecutionRef>('/executions', {
+      method: 'POST',
+      body: request as unknown as Record<string, unknown>,
+    });
+  }
+
+  /** Get task execution status. GET /executions/{id} */
+  async getExecution(executionId: string): Promise<Execution> {
+    return this.client.request<Execution>(`/executions/${encodeURIComponent(executionId)}`);
+  }
+
+  /** Terminate a running task execution. DELETE /executions/{id} */
+  async stopExecution(executionId: string): Promise<void> {
+    await this.client.request(`/executions/${encodeURIComponent(executionId)}`, { method: 'DELETE' });
+  }
+
+  /** Execute a plan. POST /executions/plans */
+  async runPlan(planId: string): Promise<ExecutionRef> {
+    return this.client.request<ExecutionRef>('/executions/plans', {
+      method: 'POST',
+      body: { executable: planId },
+    });
+  }
+
+  /** Get plan execution status. GET /executions/plans/{id} */
+  async getPlanExecution(executionId: string): Promise<Execution> {
+    return this.client.request<Execution>(`/executions/plans/${encodeURIComponent(executionId)}`);
+  }
+
+  /** Token preview for display/debugging. */
+  getTokenPreview(): string {
+    return this.client.getTokenPreview();
+  }
+
+  /** Access the underlying HTTP client for advanced/direct calls. */
+  getClient(): TalendClient {
+    return this.client;
+  }
+}
+
+/** Normalize list responses that may be a bare array or a paginated envelope. */
+function unwrap<T>(data: Paginated<T> | T[]): T[] {
+  if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.items)) return data.items;
+  return [];
+}