@hasna/connectors 0.4.0 → 0.4.2

package/connectors/connect-airtable/src/types/index.ts

@@ -0,0 +1,349 @@
+// Airtable Connector Types
+
+// ============================================
+// Configuration
+// ============================================
+
+export interface AirtableConfig {
+  accessToken: string;
+}
+
+// ============================================
+// Common Types
+// ============================================
+
+export type OutputFormat = 'json' | 'pretty';
+
+export type FieldType =
+  | 'singleLineText'
+  | 'email'
+  | 'url'
+  | 'multilineText'
+  | 'number'
+  | 'percent'
+  | 'currency'
+  | 'singleSelect'
+  | 'multipleSelects'
+  | 'singleCollaborator'
+  | 'multipleCollaborators'
+  | 'multipleRecordLinks'
+  | 'date'
+  | 'dateTime'
+  | 'phoneNumber'
+  | 'multipleAttachments'
+  | 'checkbox'
+  | 'formula'
+  | 'createdTime'
+  | 'rollup'
+  | 'count'
+  | 'lookup'
+  | 'multipleLookupValues'
+  | 'autoNumber'
+  | 'barcode'
+  | 'rating'
+  | 'richText'
+  | 'duration'
+  | 'lastModifiedTime'
+  | 'createdBy'
+  | 'lastModifiedBy'
+  | 'button'
+  | 'externalSyncSource'
+  | 'aiText';
+
+// ============================================
+// Base Types
+// ============================================
+
+export interface Base {
+  id: string;
+  name: string;
+  permissionLevel: 'none' | 'read' | 'comment' | 'edit' | 'create';
+}
+
+export interface ListBasesResult {
+  bases: Base[];
+  offset?: string;
+}
+
+export interface BaseSchema {
+  tables: Table[];
+}
+
+// ============================================
+// Table Types
+// ============================================
+
+export interface Table {
+  id: string;
+  name: string;
+  description?: string;
+  primaryFieldId: string;
+  fields: Field[];
+  views: View[];
+}
+
+export interface Field {
+  id: string;
+  name: string;
+  type: FieldType;
+  description?: string;
+  options?: FieldOptions;
+}
+
+export interface FieldOptions {
+  // Single/Multi select options
+  choices?: SelectChoice[];
+  // Number options
+  precision?: number;
+  // Currency options
+  symbol?: string;
+  // Linked record options
+  linkedTableId?: string;
+  inverseLinkFieldId?: string;
+  prefersSingleRecordLink?: boolean;
+  // Formula options
+  formula?: string;
+  result?: { type: FieldType };
+  // Rollup options
+  recordLinkFieldId?: string;
+  fieldIdInLinkedTable?: string;
+  referencedFieldIds?: string[];
+  // Date options
+  dateFormat?: { name: string; format: string };
+  timeFormat?: { name: string; format: string };
+  timeZone?: string;
+  // Rating options
+  max?: number;
+  icon?: string;
+  color?: string;
+  // Duration options
+  durationFormat?: string;
+  // Other options
+  [key: string]: unknown;
+}
+
+export interface SelectChoice {
+  id?: string;
+  name: string;
+  color?: string;
+}
+
+export interface View {
+  id: string;
+  name: string;
+  type: 'grid' | 'form' | 'calendar' | 'gallery' | 'kanban' | 'timeline' | 'block';
+}
+
+// ============================================
+// Record Types
+// ============================================
+
+export interface Record {
+  id: string;
+  createdTime: string;
+  fields: RecordFields;
+}
+
+export type RecordFields = { [fieldNameOrId: string]: FieldValue };
+
+export type FieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | string[]
+  | Attachment[]
+  | Collaborator
+  | Collaborator[]
+  | RecordLink
+  | RecordLink[]
+  | { [key: string]: unknown };
+
+export interface Attachment {
+  id: string;
+  url: string;
+  filename: string;
+  size: number;
+  type: string;
+  width?: number;
+  height?: number;
+  thumbnails?: {
+    small?: Thumbnail;
+    large?: Thumbnail;
+    full?: Thumbnail;
+  };
+}
+
+export interface Thumbnail {
+  url: string;
+  width: number;
+  height: number;
+}
+
+export interface Collaborator {
+  id: string;
+  email: string;
+  name?: string;
+}
+
+export interface RecordLink {
+  id: string;
+  name?: string;
+}
+
+export interface ListRecordsResult {
+  records: Record[];
+  offset?: string;
+}
+
+export interface CreateRecordResult {
+  id: string;
+  createdTime: string;
+  fields: RecordFields;
+}
+
+export interface UpdateRecordResult {
+  id: string;
+  createdTime: string;
+  fields: RecordFields;
+}
+
+export interface DeleteRecordResult {
+  deleted: boolean;
+  id: string;
+}
+
+export interface BatchCreateResult {
+  records: CreateRecordResult[];
+}
+
+export interface BatchUpdateResult {
+  records: UpdateRecordResult[];
+}
+
+export interface BatchDeleteResult {
+  records: DeleteRecordResult[];
+}
+
+// ============================================
+// Comment Types
+// ============================================
+
+export interface Comment {
+  id: string;
+  author: {
+    id: string;
+    email: string;
+    name?: string;
+  };
+  createdTime: string;
+  text: string;
+  mentioned?: { [userId: string]: string };
+}
+
+export interface ListCommentsResult {
+  comments: Comment[];
+  offset?: string;
+}
+
+// ============================================
+// Webhook Types
+// ============================================
+
+export interface Webhook {
+  id: string;
+  macSecretBase64: string;
+  notificationUrl?: string;
+  cursorForNextPayload?: number;
+  areNotificationsEnabled: boolean;
+  isHookEnabled: boolean;
+  expirationTime?: string;
+  specification: WebhookSpecification;
+}
+
+export interface WebhookSpecification {
+  options: {
+    filters: {
+      dataTypes?: ('tableData' | 'tableFields' | 'tableMetadata')[];
+      recordChangeScope?: string;
+      watchDataInFieldIds?: string[];
+      watchSchemasOfFieldIds?: string[];
+      sourceOptions?: {
+        formSubmission?: {
+          viewId: string;
+        };
+      };
+    };
+    includes?: {
+      includePreviousCellValues?: boolean;
+      includePreviousFieldDefinitions?: boolean;
+    };
+  };
+}
+
+export interface ListWebhooksResult {
+  webhooks: Webhook[];
+}
+
+export interface WebhookPayload {
+  timestamp: string;
+  baseTransactionNumber: number;
+  payloadFormat: 'v0';
+  actionMetadata: {
+    source: 'client' | 'automation' | 'formSubmission' | 'publicApi' | 'sync' | 'system';
+    sourceMetadata?: {
+      user?: { id: string; email: string; name?: string };
+      automation?: { id: string; name?: string };
+      view?: { id: string; name?: string };
+    };
+  };
+  changedTablesById: { [tableId: string]: TableChange };
+  createdTablesById?: { [tableId: string]: CreatedTable };
+  destroyedTableIds?: string[];
+}
+
+export interface TableChange {
+  changedRecordsById?: { [recordId: string]: RecordChange };
+  createdRecordsById?: { [recordId: string]: { cellValuesByFieldId: RecordFields; createdTime: string } };
+  destroyedRecordIds?: string[];
+  changedFieldsById?: { [fieldId: string]: { current: Field; previous?: Field } };
+  createdFieldsById?: { [fieldId: string]: Field };
+  destroyedFieldIds?: string[];
+  changedMetadata?: { current: { name?: string; description?: string }; previous?: { name?: string; description?: string } };
+}
+
+export interface RecordChange {
+  current: { cellValuesByFieldId: RecordFields };
+  previous?: { cellValuesByFieldId: RecordFields };
+  unchanged?: { cellValuesByFieldId: RecordFields };
+}
+
+export interface CreatedTable {
+  metadata: { name: string; description?: string };
+  fieldsById: { [fieldId: string]: Field };
+  recordsById: { [recordId: string]: { cellValuesByFieldId: RecordFields; createdTime: string } };
+}
+
+// ============================================
+// API Error Types
+// ============================================
+
+export interface AirtableErrorResponse {
+  error?: {
+    type: string;
+    message: string;
+  };
+}
+
+export class AirtableApiError extends Error {
+  public readonly statusCode: number;
+  public readonly errorType?: string;
+
+  constructor(message: string, statusCode: number, errorType?: string) {
+    super(message);
+    this.name = 'AirtableApiError';
+    this.statusCode = statusCode;
+    this.errorType = errorType;
+  }
+}

package/connectors/connect-airtable/src/utils/config.ts

@@ -0,0 +1,197 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONNECTOR_NAME = 'connect-airtable';
+const DEFAULT_PROFILE = 'default';
+
+export interface ProfileConfig {
+  accessToken?: string;
+}
+
+// Store for --profile flag override (set by CLI before commands run)
+let profileOverride: string | undefined;
+
+// Config directory: ~/.connect/{connector-name}/
+const CONFIG_DIR = join(homedir(), '.connect', CONNECTOR_NAME);
+const PROFILES_DIR = join(CONFIG_DIR, 'profiles');
+const CURRENT_PROFILE_FILE = join(CONFIG_DIR, 'current_profile');
+
+// ============================================
+// Profile Management
+// ============================================
+
+export function setProfileOverride(profile: string | undefined): void {
+  profileOverride = profile;
+}
+
+export function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  if (!existsSync(PROFILES_DIR)) {
+    mkdirSync(PROFILES_DIR, { recursive: true });
+  }
+}
+
+function getProfilePath(profile: string): string {
+  return join(PROFILES_DIR, `${profile}.json`);
+}
+
+/**
+ * Get the current active profile name
+ */
+export function getCurrentProfile(): string {
+  if (profileOverride) {
+    return profileOverride;
+  }
+
+  ensureConfigDir();
+
+  if (existsSync(CURRENT_PROFILE_FILE)) {
+    try {
+      const profile = readFileSync(CURRENT_PROFILE_FILE, 'utf-8').trim();
+      if (profile && profileExists(profile)) {
+        return profile;
+      }
+    } catch {
+      // Fall through to default
+    }
+  }
+
+  return DEFAULT_PROFILE;
+}
+
+/**
+ * Set the current active profile
+ */
+export function setCurrentProfile(profile: string): void {
+  ensureConfigDir();
+
+  if (!profileExists(profile) && profile !== DEFAULT_PROFILE) {
+    throw new Error(`Profile "${profile}" does not exist`);
+  }
+
+  writeFileSync(CURRENT_PROFILE_FILE, profile);
+}
+
+/**
+ * Check if a profile exists
+ */
+export function profileExists(profile: string): boolean {
+  return existsSync(getProfilePath(profile));
+}
+
+/**
+ * List all available profiles
+ */
+export function listProfiles(): string[] {
+  ensureConfigDir();
+
+  if (!existsSync(PROFILES_DIR)) {
+    return [];
+  }
+
+  return readdirSync(PROFILES_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''))
+    .sort();
+}
+
+/**
+ * Create a new profile
+ */
+export function createProfile(profile: string, config: ProfileConfig = {}): boolean {
+  ensureConfigDir();
+
+  if (profileExists(profile)) {
+    return false;
+  }
+
+  // Validate profile name
+  if (!/^[a-zA-Z0-9_-]+$/.test(profile)) {
+    throw new Error('Profile name can only contain letters, numbers, hyphens, and underscores');
+  }
+
+  writeFileSync(getProfilePath(profile), JSON.stringify(config, null, 2));
+  return true;
+}
+
+/**
+ * Delete a profile
+ */
+export function deleteProfile(profile: string): boolean {
+  if (profile === DEFAULT_PROFILE) {
+    return false;
+  }
+
+  if (!profileExists(profile)) {
+    return false;
+  }
+
+  // Switch to default if deleting current profile
+  if (getCurrentProfile() === profile) {
+    setCurrentProfile(DEFAULT_PROFILE);
+  }
+
+  rmSync(getProfilePath(profile));
+  return true;
+}
+
+/**
+ * Load profile config
+ */
+export function loadProfile(profile?: string): ProfileConfig {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  const profilePath = getProfilePath(profileName);
+
+  if (!existsSync(profilePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(profilePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save profile config
+ */
+export function saveProfile(config: ProfileConfig, profile?: string): void {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  writeFileSync(getProfilePath(profileName), JSON.stringify(config, null, 2));
+}
+
+// ============================================
+// Access Token Management
+// ============================================
+
+export function getAccessToken(): string | undefined {
+  return process.env.AIRTABLE_ACCESS_TOKEN || process.env.AIRTABLE_API_KEY || loadProfile().accessToken;
+}
+
+export function setAccessToken(accessToken: string): void {
+  const config = loadProfile();
+  config.accessToken = accessToken;
+  saveProfile(config);
+}
+
+// ============================================
+// Utility Functions
+// ============================================
+
+export function clearConfig(): void {
+  saveProfile({});
+}
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function getActiveProfileName(): string {
+  return getCurrentProfile();
+}

package/connectors/connect-airtable/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/connect-amplitude/.env.example

@@ -0,0 +1,11 @@
+# API Credentials
+# TODO: Update variable names and instructions for your API
+# Example: PERPLEXITY_API_KEY, OPENAI_API_KEY, etc.
+
+CONNECTOR_API_KEY=your-api-key-here
+
+# Optional: API secret (if your API requires it)
+# CONNECTOR_API_SECRET=your-api-secret-here
+
+# Optional: Custom base URL (if needed)
+# CONNECTOR_BASE_URL=https://api.example.com

package/connectors/connect-amplitude/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+connect-amplitude is a TypeScript connector for the Amplitude Analytics API. It provides a CLI and library for tracking events, searching users, managing cohorts, and accessing analytics data.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+
+# Run specific commands
+bun run dev auth status
+bun run dev events track --type "test" --user "user123"
+bun run dev users search "user123"
+bun run dev cohorts list
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Minimal dependencies: commander, chalk only
+- Type annotations required everywhere
+- Use interfaces for all API types
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with Basic Auth
+│   └── index.ts      # Amplitude API wrapper
+├── cli/
+│   └── index.ts      # CLI commands
+├── types/
+│   └── index.ts      # Type definitions
+├── utils/
+│   └── config.ts     # Multi-profile configuration
+└── index.ts          # Library exports
+```
+
+## API Authentication
+
+Amplitude uses Basic Auth with API Key and Secret Key:
+- `Authorization: Basic base64(apiKey:secretKey)`
+
+Two API endpoints:
+- `amplitude.com/api/2` - Most API operations
+- `api2.amplitude.com/2` - Batch event uploads
+
+## Key Patterns
+
+### Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-amplitude/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- Environment variables override profile config
+
+### API Categories
+
+- **Events**: Track and upload events (batch)
+- **Users**: Search users, get user activity
+- **Cohorts**: List cohorts, get membership
+- **Charts**: Query chart data
+- **Taxonomy**: Event types, event properties, user properties
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AMPLITUDE_API_KEY` | API key |
+| `AMPLITUDE_SECRET_KEY` | Secret key |
+
+## CLI Commands
+
+- `auth set-key/set-secret/status/clear` - Authentication
+- `profile list/use/create/delete/show` - Profile management
+- `events track` - Track events
+- `users search/activity` - User operations
+- `cohorts list/get/members` - Cohort operations
+- `charts get` - Chart data
+- `taxonomy events/event-properties/user-properties` - Taxonomy
+
+## Data Storage
+
+```
+~/.connect/connect-amplitude/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+Profile JSON structure:
+```json
+{
+  "apiKey": "your-api-key",
+  "secretKey": "your-secret-key"
+}
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling