@hasna/connectors 1.3.22 → 1.3.23

package/connectors/connect-googlephotos/src/api/bulk.ts

@@ -0,0 +1,455 @@
+import type { PhotosClient } from './client';
+import type { MediaItem, MediaItemsListResponse, Album } from '../types';
+
+// ============================================
+// Bulk Operation Types
+// ============================================
+
+export interface BulkOperationOptions {
+  /** Filter by album ID */
+  albumId?: string;
+  /** Filter by media type (PHOTO, VIDEO) */
+  mediaType?: 'PHOTO' | 'VIDEO';
+  /** Include archived media */
+  includeArchived?: boolean;
+  /** Only favorites */
+  favoritesOnly?: boolean;
+  /** Maximum items to process (default: 100) */
+  maxResults?: number;
+  /** Maximum concurrent API calls (default: 10) */
+  concurrency?: number;
+  /** Dry run - don't actually modify */
+  dryRun?: boolean;
+  /** Progress callback */
+  onProgress?: (current: number, total: number, item: MediaSummary) => void;
+  /** Error callback */
+  onError?: (error: Error, item: MediaSummary) => void;
+}
+
+export interface BulkAddToAlbumOptions extends BulkOperationOptions {
+  /** Album ID to add items to */
+  targetAlbumId: string;
+  /** Media item IDs to add (or use filters above to discover) */
+  mediaItemIds?: string[];
+}
+
+export interface BulkRemoveFromAlbumOptions {
+  /** Album ID to remove items from */
+  albumId: string;
+  /** Media item IDs to remove (or use filters to discover) */
+  mediaItemIds?: string[];
+  /** Filter options if mediaItemIds not provided */
+  albumId?: string;
+  mediaType?: 'PHOTO' | 'VIDEO';
+  maxResults?: number;
+  concurrency?: number;
+  dryRun?: boolean;
+  onProgress?: (current: number, total: number, item: MediaSummary) => void;
+  onError?: (error: Error, item: MediaSummary) => void;
+}
+
+export interface BulkCreateAlbumsOptions {
+  /** Album titles to create */
+  titles: string[];
+  concurrency?: number;
+  dryRun?: boolean;
+  onProgress?: (current: number, total: number, title: string) => void;
+  onError?: (error: Error, title: string) => void;
+}
+
+export interface MediaSummary {
+  id: string;
+  filename: string;
+  mimeType: string;
+  created: string;
+  productUrl: string;
+}
+
+export interface BulkOperationResult {
+  total: number;
+  success: number;
+  failed: number;
+  skipped: number;
+  errors: Array<{ mediaId: string; error: string }>;
+  processedItems: MediaSummary[];
+}
+
+export interface PreviewResult {
+  items: MediaSummary[];
+  total: number;
+}
+
+export interface BulkCreateAlbumsResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ title: string; error: string }>;
+  createdAlbums: Album[];
+}
+
+// ============================================
+// Bulk Operations API
+// ============================================
+
+export class BulkApi {
+  private readonly client: PhotosClient;
+
+  constructor(client: PhotosClient) {
+    this.client = client;
+  }
+
+  // ============================================
+  // Preview
+  // ============================================
+
+  /**
+   * Preview media items matching filters
+   */
+  async preview(options?: {
+    albumId?: string;
+    mediaType?: 'PHOTO' | 'VIDEO';
+    favoritesOnly?: boolean;
+    maxResults?: number;
+  }): Promise<PreviewResult> {
+    const items = await this.fetchMediaItems({
+      albumId: options?.albumId,
+      mediaType: options?.mediaType,
+      favoritesOnly: options?.favoritesOnly,
+      maxResults: options?.maxResults || 50,
+    });
+    return { items, total: items.length };
+  }
+
+  // ============================================
+  // Delete (Archive)
+  // ============================================
+
+  /**
+   * Note: Google Photos API doesn't support direct delete.
+   * This archives media items by moving them out of albums.
+   * For true deletion, users must use the Google Photos UI.
+   */
+  async removeFromAlbums(options: {
+    albumIds: string[];
+    mediaItemIds?: string[];
+    maxResults?: number;
+    concurrency?: number;
+    dryRun?: boolean;
+    onProgress?: (current: number, total: number, item: MediaSummary) => void;
+    onError?: (error: Error, item: MediaSummary) => void;
+  }): Promise<BulkOperationResult> {
+    const { albumIds, mediaItemIds, ...rest } = options;
+
+    let items: MediaSummary[];
+    if (mediaItemIds && mediaItemIds.length > 0) {
+      items = mediaItemIds.map(id => ({
+        id,
+        filename: id,
+        mimeType: 'unknown',
+        created: '',
+        productUrl: '',
+      }));
+    } else {
+      items = await this.fetchMediaItems({
+        albumId: albumIds[0],
+        maxResults: rest.maxResults || 100,
+      });
+    }
+
+    return this.executeBatch(items, {
+      dryRun: rest.dryRun || false,
+      concurrency: rest.concurrency || 10,
+      onProgress: rest.onProgress,
+      onError: rest.onError,
+      operation: async (item) => {
+        for (const albumId of albumIds) {
+          await this.client.post<void>(`/albums/${albumId}:batchRemoveMediaItems`, {
+            mediaItemIds: [item.id],
+          });
+        }
+      },
+    });
+  }
+
+  // ============================================
+  // Add to Album
+  // ============================================
+
+  /**
+   * Bulk add media items to an album
+   */
+  async addToAlbum(options: BulkAddToAlbumOptions): Promise<BulkOperationResult> {
+    let itemIds = options.mediaItemIds;
+
+    if (!itemIds || itemIds.length === 0) {
+      const items = await this.fetchMediaItems({
+        albumId: options.albumId,
+        mediaType: options.mediaType,
+        favoritesOnly: options.favoritesOnly,
+        includeArchived: options.includeArchived,
+        maxResults: options.maxResults || 100,
+      });
+      itemIds = items.map(i => i.id);
+    }
+
+    const summaries = itemIds.map(id => ({
+      id,
+      filename: id,
+      mimeType: 'unknown',
+      created: '',
+      productUrl: '',
+    }));
+
+    return this.executeBatch(summaries, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (item) => {
+        await this.client.post<void>(`/albums/${options.targetAlbumId}:batchAddMediaItems`, {
+          mediaItemIds: [item.id],
+        });
+      },
+    });
+  }
+
+  // ============================================
+  // Remove from Album
+  // ============================================
+
+  /**
+   * Bulk remove media items from an album
+   */
+  async removeFromAlbum(options: {
+    albumId: string;
+    mediaItemIds?: string[];
+    maxResults?: number;
+    concurrency?: number;
+    dryRun?: boolean;
+    onProgress?: (current: number, total: number, item: MediaSummary) => void;
+    onError?: (error: Error, item: MediaSummary) => void;
+  }): Promise<BulkOperationResult> {
+    let itemIds = options.mediaItemIds;
+
+    if (!itemIds || itemIds.length === 0) {
+      const items = await this.fetchMediaItems({
+        albumId: options.albumId,
+        maxResults: options.maxResults || 100,
+      });
+      itemIds = items.map(i => i.id);
+    }
+
+    const summaries = itemIds.map(id => ({
+      id,
+      filename: id,
+      mimeType: 'unknown',
+      created: '',
+      productUrl: '',
+    }));
+
+    return this.executeBatch(summaries, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (item) => {
+        await this.client.post<void>(`/albums/${options.albumId}:batchRemoveMediaItems`, {
+          mediaItemIds: [item.id],
+        });
+      },
+    });
+  }
+
+  // ============================================
+  // Create Albums
+  // ============================================
+
+  /**
+   * Bulk create albums from a list of titles
+   */
+  async createAlbums(options: BulkCreateAlbumsOptions): Promise<BulkCreateAlbumsResult> {
+    const { titles, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkCreateAlbumsResult = {
+      total: titles.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      createdAlbums: [],
+    };
+
+    if (titles.length === 0) return result;
+
+    const chunks = this.chunkArray(titles, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (title) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const album = await this.client.post<Album>('/albums', { album: { title } });
+              result.success++;
+              result.createdAlbums.push(album);
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, title);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ title, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), title);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Favorite / Unfavorite
+  // ============================================
+
+  /**
+   * Note: Google Photos API doesn't support setting favorite status via API.
+   * This is read-only through the featureFilter. Listed for completeness.
+   */
+  async listFavorites(options?: { maxResults?: number }): Promise<PreviewResult> {
+    const items = await this.fetchMediaItems({
+      favoritesOnly: true,
+      maxResults: options?.maxResults || 100,
+    });
+    return { items, total: items.length };
+  }
+
+  // ============================================
+  // Helper Methods
+  // ============================================
+
+  /**
+   * Fetch media items matching filters
+   */
+  async fetchMediaItems(params: {
+    albumId?: string;
+    mediaType?: 'PHOTO' | 'VIDEO';
+    favoritesOnly?: boolean;
+    includeArchived?: boolean;
+    maxResults?: number;
+  }): Promise<MediaSummary[]> {
+    const items: MediaSummary[] = [];
+    let pageToken: string | undefined;
+    const max = params.maxResults || 100;
+
+    while (items.length < max) {
+      const body: Record<string, unknown> = {
+        pageSize: Math.min(100, max - items.length),
+      };
+
+      if (params.albumId) {
+        body.albumId = params.albumId;
+      }
+
+      const filters: Record<string, unknown> = {};
+      if (params.mediaType) {
+        filters.mediaTypeFilter = { mediaTypes: [params.mediaType] };
+      }
+      if (params.favoritesOnly) {
+        filters.featureFilter = { includedFeatures: ['FAVORITES'] };
+      }
+      if (params.includeArchived) {
+        filters.includeArchivedMedia = true;
+      }
+      if (Object.keys(filters).length > 0) {
+        body.filters = filters;
+      }
+
+      if (pageToken) {
+        body.pageToken = pageToken;
+      }
+
+      const response = await this.client.post<MediaItemsListResponse>('/mediaItems:search', body);
+
+      if (!response.mediaItems || response.mediaItems.length === 0) break;
+
+      for (const item of response.mediaItems) {
+        items.push({
+          id: item.id,
+          filename: item.filename,
+          mimeType: item.mimeType,
+          created: item.mediaMetadata.creationTime,
+          productUrl: item.productUrl,
+        });
+      }
+
+      pageToken = response.nextPageToken;
+      if (!pageToken) break;
+    }
+
+    return items;
+  }
+
+  /**
+   * Execute operations in batches with concurrency control
+   */
+  private async executeBatch(
+    items: MediaSummary[],
+    options: {
+      dryRun: boolean;
+      concurrency: number;
+      onProgress?: (current: number, total: number, item: MediaSummary) => void;
+      onError?: (error: Error, item: MediaSummary) => void;
+      operation: (item: MediaSummary) => Promise<void>;
+    }
+  ): Promise<BulkOperationResult> {
+    const { dryRun, concurrency, onProgress, onError, operation } = options;
+
+    const result: BulkOperationResult = {
+      total: items.length,
+      success: 0,
+      failed: 0,
+      skipped: 0,
+      errors: [],
+      processedItems: [],
+    };
+
+    if (items.length === 0) return result;
+
+    const chunks = this.chunkArray(items, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (item) => {
+          try {
+            if (dryRun) {
+              result.success++;
+              result.processedItems.push(item);
+            } else {
+              await operation(item);
+              result.success++;
+              result.processedItems.push(item);
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, item);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ mediaId: item.id, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), item);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  private chunkArray<T>(array: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+}

package/connectors/connect-googlephotos/src/api/index.ts

@@ -2,11 +2,13 @@ import { PhotosClient } from './client';
 import { AlbumsApi } from './albums';
 import { MediaApi } from './media';
 import { UploadApi } from './upload';
+import { BulkApi } from './bulk';
 
 export { PhotosClient } from './client';
 export { AlbumsApi } from './albums';
 export { MediaApi } from './media';
 export { UploadApi } from './upload';
+export { BulkApi } from './bulk';
 
 /**
  * Main Google Photos API client
@@ -30,11 +32,17 @@ export class GooglePhotos {
    */
   public readonly upload: UploadApi;
 
+  /**
+   * Bulk API - batch operations on media items and albums
+   */
+  public readonly bulk: BulkApi;
+
   constructor() {
     this.client = new PhotosClient();
     this.albums = new AlbumsApi(this.client);
     this.media = new MediaApi(this.client);
     this.upload = new UploadApi(this.client);
+    this.bulk = new BulkApi(this.client);
   }
 
   /**

package/connectors/connect-googlephotos/src/cli/index.ts

@@ -5,6 +5,7 @@ import open from 'open';
 import { writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, basename } from 'path';
 import { GooglePhotos } from '../api';
+import { BulkApi } from '../api/bulk';
 import {
   getClientId,
   getClientSecret,
@@ -750,5 +751,189 @@ uploadCmd
     info(extensions.join(', '));
   });
 
+// ============================================
+// Bulk Commands
+// ============================================
+const bulkCmd = program
+  .command('bulk')
+  .description('Bulk operations on media items and albums');
+
+function makeProgress(total: number) {
+  let last = 0;
+  return (current: number) => {
+    if (current !== last) {
+      process.stdout.write(`\r  Progress: ${current}/${total}`);
+      last = current;
+    }
+  };
+}
+
+bulkCmd
+  .command('preview')
+  .description('Preview media items matching filters')
+  .option('--album-id <albumId>', 'Filter by album')
+  .option('--type <type>', 'Filter by media type (PHOTO, VIDEO)')
+  .option('--favorites', 'Only show favorites')
+  .option('-n, --max <number>', 'Maximum results', '50')
+  .action(async (opts) => {
+    try {
+      const photos = requireAuth();
+      const bulk = new BulkApi(photos.getClient());
+      const result = await bulk.preview({
+        albumId: opts.albumId,
+        mediaType: opts.type,
+        favoritesOnly: opts.favorites,
+        maxResults: parseInt(opts.max),
+      });
+      success(`Found ${result.total} item(s):`);
+      print(result.items, getFormat(bulkCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('add-to-album <albumId>')
+  .description('Bulk add media items to an album')
+  .option('--query-album-id <albumId>', 'Filter by album to discover items')
+  .option('--type <type>', 'Filter by media type')
+  .option('--favorites', 'Only favorites')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without adding')
+  .action(async (albumId: string, opts) => {
+    try {
+      const photos = requireAuth();
+      const bulk = new BulkApi(photos.getClient());
+      const result = await bulk.addToAlbum({
+        targetAlbumId: albumId,
+        albumId: opts.queryAlbumId,
+        mediaType: opts.type,
+        favoritesOnly: opts.favorites,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, item) => { warn(`Failed: ${item.filename} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would add ${result.success} item(s) to album`);
+      } else {
+        success(`Added ${result.success} item(s) to album, ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('remove-from-album <albumId>')
+  .description('Bulk remove media items from an album')
+  .option('--media-ids <ids>', 'Comma-separated media item IDs')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without removing')
+  .action(async (albumId: string, opts) => {
+    try {
+      const photos = requireAuth();
+      const bulk = new BulkApi(photos.getClient());
+      const mediaItemIds = opts.mediaIds ? opts.mediaIds.split(',') : undefined;
+      const result = await bulk.removeFromAlbum({
+        albumId,
+        mediaItemIds,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, item) => { warn(`Failed: ${item.filename} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would remove ${result.success} item(s) from album`);
+      } else {
+        success(`Removed ${result.success} item(s) from album, ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('create-albums')
+  .description('Bulk create albums from titles')
+  .option('--titles <titles>', 'Comma-separated album titles')
+  .option('--titles-file <path>', 'File with one title per line')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without creating')
+  .action(async (opts) => {
+    let titles: string[] = [];
+    if (opts.titles) {
+      titles = opts.titles.split(',').map((t: string) => t.trim()).filter(Boolean);
+    } else if (opts.titlesFile) {
+      if (!existsSync(opts.titlesFile)) {
+        error(`File not found: ${opts.titlesFile}`);
+        process.exit(1);
+      }
+      titles = require('fs').readFileSync(opts.titlesFile, 'utf-8')
+        .split('\n')
+        .map((t: string) => t.trim())
+        .filter(Boolean);
+    }
+    if (titles.length === 0) {
+      error('Provide --titles or --titles-file');
+      process.exit(1);
+    }
+    try {
+      const photos = requireAuth();
+      const bulk = new BulkApi(photos.getClient());
+      const result = await bulk.createAlbums({
+        titles,
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, title) => { warn(`Failed: ${title} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would create ${result.success} album(s)`);
+      } else {
+        success(`Created ${result.success} album(s), ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('favorites')
+  .description('List favorite media items')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .action(async (opts) => {
+    try {
+      const photos = requireAuth();
+      const bulk = new BulkApi(photos.getClient());
+      const result = await bulk.listFavorites({ maxResults: parseInt(opts.max) });
+      success(`Found ${result.total} favorite(s):`);
+      print(result.items, getFormat(bulkCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
 // Parse and run
 program.parse();