@hasna/connectors 0.9.2 → 1.0.0

package/connectors/connect-googleperspective/src/utils/storage.ts

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from './config';
+
+// ============================================
+// Generic Data Storage Utility
+// ============================================
+
+/**
+ * Base interface for storable entities
+ * All stored entities should have an id field
+ */
+export interface Storable {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Get the storage directory for an entity type
+ */
+function getStorageDir(entityType: string): string {
+  const dir = join(getConfigDir(), 'data', entityType);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Convert an ID to a safe filename
+ */
+function idToFilename(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9]/g, '_') + '.json';
+}
+
+/**
+ * Get the file path for an entity
+ */
+function getEntityPath(entityType: string, id: string): string {
+  return join(getStorageDir(entityType), idToFilename(id));
+}
+
+/**
+ * Save an entity to storage
+ */
+export function saveEntity<T extends Storable>(entityType: string, entity: T): void {
+  const filepath = getEntityPath(entityType, entity.id);
+  const now = new Date().toISOString();
+
+  const existing = getEntity<T>(entityType, entity.id);
+
+  const data: T = {
+    ...entity,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+  };
+
+  writeFileSync(filepath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Get an entity by ID
+ */
+export function getEntity<T extends Storable>(entityType: string, id: string): T | null {
+  const filepath = getEntityPath(entityType, id);
+
+  if (!existsSync(filepath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if an entity exists
+ */
+export function entityExists(entityType: string, id: string): boolean {
+  return existsSync(getEntityPath(entityType, id));
+}
+
+/**
+ * Get all entities of a type
+ */
+export function getAllEntities<T extends Storable>(entityType: string): T[] {
+  const storageDir = getStorageDir(entityType);
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+
+  const entities: T[] = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(storageDir, file), 'utf-8');
+      entities.push(JSON.parse(content) as T);
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  return entities.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Delete an entity
+ */
+export function deleteEntity(entityType: string, id: string): boolean {
+  const filepath = getEntityPath(entityType, id);
+
+  if (existsSync(filepath)) {
+    unlinkSync(filepath);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Search entities by a predicate function
+ */
+export function searchEntities<T extends Storable>(
+  entityType: string,
+  predicate: (entity: T) => boolean
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  return all.filter(predicate);
+}
+
+/**
+ * Search entities by text match across all string fields
+ */
+export function searchEntitiesByText<T extends Storable>(
+  entityType: string,
+  query: string,
+  fields?: (keyof T)[]
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  const q = query.toLowerCase();
+
+  return all.filter(entity => {
+    const searchFields = fields || (Object.keys(entity) as (keyof T)[]);
+    return searchFields.some(field => {
+      const value = entity[field];
+      if (typeof value === 'string') {
+        return value.toLowerCase().includes(q);
+      }
+      return false;
+    });
+  });
+}
+
+/**
+ * Count entities of a type
+ */
+export function countEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+  return readdirSync(storageDir).filter(f => f.endsWith('.json')).length;
+}
+
+/**
+ * Clear all entities of a type
+ */
+export function clearEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    unlinkSync(join(storageDir, file));
+  }
+
+  return files.length;
+}
+
+/**
+ * Create a typed storage helper for a specific entity type
+ * This provides a cleaner API for working with a single entity type
+ */
+export function createStorage<T extends Storable>(entityType: string) {
+  return {
+    save: (entity: T) => saveEntity<T>(entityType, entity),
+    get: (id: string) => getEntity<T>(entityType, id),
+    exists: (id: string) => entityExists(entityType, id),
+    getAll: () => getAllEntities<T>(entityType),
+    delete: (id: string) => deleteEntity(entityType, id),
+    search: (predicate: (entity: T) => boolean) => searchEntities<T>(entityType, predicate),
+    searchByText: (query: string, fields?: (keyof T)[]) => searchEntitiesByText<T>(entityType, query, fields),
+    count: () => countEntities(entityType),
+    clear: () => clearEntities(entityType),
+  };
+}

package/connectors/connect-googleperspective/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-googlephotos/.env.example

@@ -0,0 +1,4 @@
+# Google Photos API OAuth2 credentials
+# Get these from Google Cloud Console: https://console.cloud.google.com/apis/credentials
+GOOGLE_PHOTOS_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_PHOTOS_CLIENT_SECRET=your-client-secret

package/connectors/connect-googlephotos/CLAUDE.md

@@ -0,0 +1,107 @@
+# Google Photos Connector
+
+A TypeScript CLI tool and library for interacting with the Google Photos Library API.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development mode
+bun run dev <command>
+
+# Build for production
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Setup
+
+1. Create a Google Cloud project and enable the Photos Library API
+2. Create OAuth 2.0 credentials (Desktop app type)
+3. Configure credentials:
+   ```bash
+   connect-googlephotos config set-credentials <client-id> <client-secret>
+   ```
+4. Login:
+   ```bash
+   connect-googlephotos auth login
+   ```
+
+## Multi-Profile Support
+
+The connector supports multiple Google accounts via profiles:
+
+```bash
+# List profiles
+connect-googlephotos profiles list
+
+# Switch profile
+connect-googlephotos profiles switch <name>
+
+# Use profile for single command
+connect-googlephotos -p <profile> media list
+```
+
+Profiles are stored in `~/.connect/connect-googlephotos/profiles/`.
+
+## Commands
+
+### Authentication
+- `auth login` - Login via OAuth2
+- `auth status` - Check auth status
+- `auth logout` - Clear tokens
+
+### Configuration
+- `config set-credentials <id> <secret>` - Set OAuth credentials
+- `config show` - Show current config
+- `config clear` - Clear all config
+
+### Albums
+- `albums list` - List all albums
+- `albums get <id>` - Get album details
+- `albums create <title>` - Create new album
+- `albums share <id>` - Share an album
+- `albums contents <id>` - List items in album
+
+### Media
+- `media list` - List media items
+- `media get <id>` - Get item details
+- `media search` - Search with filters
+- `media download <id>` - Download item
+- `media url <id>` - Get download URL
+
+### Upload
+- `upload file <path>` - Upload single file
+- `upload dir <path>` - Upload directory
+- `upload supported` - List supported file types
+
+## API Usage
+
+```typescript
+import { GooglePhotos } from '@hasna/connect-googlephotos';
+
+const photos = GooglePhotos.create();
+
+// List albums
+const albums = await photos.albums.listAll();
+
+// Get media items
+const items = await photos.media.list();
+
+// Upload a file
+const item = await photos.upload.uploadAndCreate('./photo.jpg');
+
+// Search favorites
+const favorites = await photos.media.getFavorites();
+```
+
+## Google Photos API Limitations
+
+- Can only edit/delete items created by this app
+- Upload quota: 75MB photos, 10GB videos
+- API rate limits apply
+- Some features require specific scopes

package/connectors/connect-googlephotos/README.md

@@ -0,0 +1,194 @@
+# connect-googlephotos
+
+A TypeScript CLI and library for the Google Photos Library API with OAuth2 authentication and multi-profile support.
+
+## Installation
+
+```bash
+# Global install
+bun install -g @hasna/connect-googlephotos
+
+# Or use with bunx
+bunx @hasna/connect-googlephotos
+```
+
+## Quick Start
+
+### 1. Get Google Cloud Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project or select an existing one
+3. Enable the **Photos Library API**
+4. Go to **Credentials** → **Create Credentials** → **OAuth client ID**
+5. Select **Desktop app** as the application type
+6. Download the credentials
+
+### 2. Configure the CLI
+
+```bash
+# Set your OAuth credentials
+connect-googlephotos config set-credentials <client-id> <client-secret>
+
+# Login (opens browser)
+connect-googlephotos auth login
+```
+
+### 3. Use the CLI
+
+```bash
+# List your albums
+connect-googlephotos albums list
+
+# List recent photos
+connect-googlephotos media list
+
+# Search for selfies
+connect-googlephotos media search --category SELFIES
+
+# Download a photo
+connect-googlephotos media download <media-id> -o photo.jpg
+
+# Upload a photo
+connect-googlephotos upload file photo.jpg
+
+# Upload a directory
+connect-googlephotos upload dir ./vacation-photos --album <album-id>
+```
+
+## Multi-Profile Support
+
+Manage multiple Google accounts:
+
+```bash
+# List all profiles
+connect-googlephotos profiles list
+
+# Show profile details
+connect-googlephotos profiles show
+
+# Switch to a different profile
+connect-googlephotos profiles switch myprofile
+
+# Use a specific profile for one command
+connect-googlephotos -p work albums list
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `auth login` | Login via OAuth2 (opens browser) |
+| `auth status` | Check authentication status |
+| `auth logout` | Clear stored tokens |
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `config set-credentials <id> <secret>` | Set OAuth credentials |
+| `config show` | Show current configuration |
+| `config clear` | Clear all configuration |
+
+### Albums
+
+| Command | Description |
+|---------|-------------|
+| `albums list` | List all albums |
+| `albums get <id>` | Get album details |
+| `albums create <title>` | Create a new album |
+| `albums share <id>` | Share an album |
+| `albums unshare <id>` | Unshare an album |
+| `albums contents <id>` | List items in an album |
+
+### Media
+
+| Command | Description |
+|---------|-------------|
+| `media list` | List media items |
+| `media get <id>` | Get media item details |
+| `media search` | Search with filters |
+| `media download <id>` | Download a media item |
+| `media url <id>` | Get download URL |
+
+### Upload
+
+| Command | Description |
+|---------|-------------|
+| `upload file <path>` | Upload a single file |
+| `upload dir <path>` | Upload all files from directory |
+| `upload supported` | List supported file types |
+
+## Programmatic Usage
+
+```typescript
+import { GooglePhotos } from '@hasna/connect-googlephotos';
+
+const photos = GooglePhotos.create();
+
+// List albums
+const albums = await photos.albums.listAll();
+console.log(`Found ${albums.length} albums`);
+
+// Get media items in an album
+const items = await photos.media.getInAlbum(albums[0].id);
+
+// Search for photos by category
+const selfies = await photos.media.searchByCategory(['SELFIES']);
+
+// Search favorites
+const favorites = await photos.media.getFavorites();
+
+// Upload a photo
+const uploaded = await photos.upload.uploadAndCreate('./photo.jpg', {
+  description: 'My vacation photo',
+  albumId: 'album-id',
+});
+
+// Download a photo
+const buffer = await photos.media.download(items[0]);
+```
+
+## Configuration Storage
+
+Configuration is stored in `~/.connect/connect-googlephotos/`:
+
+```
+~/.connect/connect-googlephotos/
+├── credentials.json          # OAuth client credentials (shared)
+├── current_profile           # Current active profile
+└── profiles/
+    ├── default/
+    │   ├── config.json       # Profile config
+    │   └── tokens.json       # OAuth tokens
+    └── work/
+        ├── config.json
+        └── tokens.json
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_PHOTOS_CLIENT_ID` | OAuth client ID |
+| `GOOGLE_PHOTOS_CLIENT_SECRET` | OAuth client secret |
+| `GOOGLE_PHOTOS_ACCESS_TOKEN` | Access token (optional override) |
+| `GOOGLE_PHOTOS_REFRESH_TOKEN` | Refresh token (optional override) |
+
+## Supported File Types
+
+**Images:** JPG, JPEG, PNG, GIF, WebP, HEIC, HEIF, BMP, TIFF, RAW, ICO
+
+**Videos:** MP4, MOV, AVI, MKV, WebM, M4V, 3GP, MPG, MPEG, WMV
+
+## API Limitations
+
+- Can only edit/delete media items created by this app
+- Maximum photo size: 75 MB
+- Maximum video size: 10 GB
+- API rate limits apply
+
+## License
+
+Apache-2.0

package/connectors/connect-googlephotos/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hasna/connect-googlephotos",
+  "version": "0.0.1",
+  "description": "Google Photos API connector CLI - A TypeScript wrapper for Google Photos with OAuth2 authentication",
+  "type": "module",
+  "bin": {
+    "connect-googlephotos": "./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",
+    "prepublishOnly": "bun run build",
+    "release": "bun run scripts/release.ts",
+    "release:dry": "bun run scripts/release.ts --dry-run"
+  },
+  "keywords": [
+    "google-photos",
+    "google",
+    "photos",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "oauth2"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "open": "^10.1.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

package/connectors/connect-googlephotos/scripts/publish.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const bumpType = args.find(arg => ['patch', 'minor', 'major'].includes(arg)) || 'patch';
+
+const packagePath = join(import.meta.dir, '..', 'package.json');
+const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+
+// Parse current version
+const [major, minor, patch] = pkg.version.split('.').map(Number);
+
+// Bump version
+let newVersion: string;
+switch (bumpType) {
+  case 'major':
+    newVersion = `${major + 1}.0.0`;
+    break;
+  case 'minor':
+    newVersion = `${major}.${minor + 1}.0`;
+    break;
+  case 'patch':
+  default:
+    newVersion = `${major}.${minor}.${patch + 1}`;
+    break;
+}
+
+console.log(`📦 ${pkg.name}`);
+console.log(`   Current version: ${pkg.version}`);
+console.log(`   New version: ${newVersion}`);
+console.log(`   Bump type: ${bumpType}`);
+console.log('');
+
+if (dryRun) {
+  console.log('🔍 Dry run - no changes will be made');
+  process.exit(0);
+}
+
+// Update package.json
+pkg.version = newVersion;
+writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + '\n');
+console.log('✅ Updated package.json');
+
+// Build
+console.log('📦 Building...');
+const buildProc = Bun.spawnSync(['bun', 'run', 'build'], {
+  cwd: join(import.meta.dir, '..'),
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+
+if (buildProc.exitCode !== 0) {
+  console.error('❌ Build failed');
+  process.exit(1);
+}
+console.log('✅ Build complete');
+
+// Publish
+console.log('📤 Publishing...');
+const publishProc = Bun.spawnSync(['npm', 'publish'], {
+  cwd: join(import.meta.dir, '..'),
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+
+if (publishProc.exitCode !== 0) {
+  console.error('❌ Publish failed');
+  process.exit(1);
+}
+
+console.log('');
+console.log(`✅ Published ${pkg.name}@${newVersion}`);