@hasna/connectors 0.9.3 → 1.0.1

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

@@ -0,0 +1,180 @@
+import type { PhotosClient } from './client';
+import type {
+  Album,
+  AlbumsListResponse,
+  ListAlbumsOptions,
+  ShareAlbumRequest,
+  ShareAlbumResponse,
+  SharedAlbumOptions,
+} from '../types';
+
+export class AlbumsApi {
+  constructor(private client: PhotosClient) {}
+
+  /**
+   * List all albums in the user's library
+   */
+  async list(options: ListAlbumsOptions = {}): Promise<AlbumsListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      pageSize: options.pageSize || 50,
+      pageToken: options.pageToken,
+      excludeNonAppCreatedData: options.excludeNonAppCreatedData,
+    };
+
+    return this.client.get<AlbumsListResponse>('/albums', params);
+  }
+
+  /**
+   * Get all albums (handles pagination)
+   */
+  async listAll(options: Omit<ListAlbumsOptions, 'pageToken'> = {}): Promise<Album[]> {
+    const albums: Album[] = [];
+    let pageToken: string | undefined;
+
+    do {
+      const response = await this.list({ ...options, pageToken });
+      if (response.albums) {
+        albums.push(...response.albums);
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+
+    return albums;
+  }
+
+  /**
+   * Get a specific album by ID
+   */
+  async get(albumId: string): Promise<Album> {
+    return this.client.get<Album>(`/albums/${albumId}`);
+  }
+
+  /**
+   * Create a new album
+   */
+  async create(title: string): Promise<Album> {
+    return this.client.post<Album>('/albums', {
+      album: { title },
+    });
+  }
+
+  /**
+   * Add an enrichment (text, location, or map) to an album
+   */
+  async addEnrichment(
+    albumId: string,
+    enrichment: {
+      textEnrichment?: { text: string };
+      locationEnrichment?: {
+        location: {
+          locationName: string;
+          latlng?: { latitude: number; longitude: number };
+        };
+      };
+      mapEnrichment?: {
+        origin: {
+          locationName: string;
+          latlng?: { latitude: number; longitude: number };
+        };
+        destination: {
+          locationName: string;
+          latlng?: { latitude: number; longitude: number };
+        };
+      };
+    },
+    position: 'FIRST_IN_ALBUM' | 'LAST_IN_ALBUM' = 'LAST_IN_ALBUM'
+  ): Promise<{ enrichmentItem: { id: string } }> {
+    return this.client.post<{ enrichmentItem: { id: string } }>(
+      `/albums/${albumId}:addEnrichment`,
+      {
+        newEnrichmentItem: enrichment,
+        albumPosition: { position },
+      }
+    );
+  }
+
+  /**
+   * Share an album
+   */
+  async share(albumId: string, options?: SharedAlbumOptions): Promise<ShareAlbumResponse> {
+    const request: ShareAlbumRequest = {};
+    if (options) {
+      request.sharedAlbumOptions = options;
+    }
+    return this.client.post<ShareAlbumResponse>(`/albums/${albumId}:share`, request);
+  }
+
+  /**
+   * Unshare an album
+   */
+  async unshare(albumId: string): Promise<void> {
+    await this.client.post<void>(`/albums/${albumId}:unshare`, {});
+  }
+
+  /**
+   * List shared albums
+   */
+  async listShared(options: ListAlbumsOptions = {}): Promise<AlbumsListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      pageSize: options.pageSize || 50,
+      pageToken: options.pageToken,
+      excludeNonAppCreatedData: options.excludeNonAppCreatedData,
+    };
+
+    return this.client.get<AlbumsListResponse>('/sharedAlbums', params);
+  }
+
+  /**
+   * Join a shared album using a share token
+   */
+  async join(shareToken: string): Promise<Album> {
+    return this.client.post<Album>('/sharedAlbums:join', { shareToken });
+  }
+
+  /**
+   * Leave a shared album
+   */
+  async leave(shareToken: string): Promise<void> {
+    await this.client.post<void>('/sharedAlbums:leave', { shareToken });
+  }
+
+  /**
+   * Add media items to an album
+   */
+  async addMediaItems(albumId: string, mediaItemIds: string[]): Promise<void> {
+    await this.client.post<void>(`/albums/${albumId}:batchAddMediaItems`, {
+      mediaItemIds,
+    });
+  }
+
+  /**
+   * Remove media items from an album
+   */
+  async removeMediaItems(albumId: string, mediaItemIds: string[]): Promise<void> {
+    await this.client.post<void>(`/albums/${albumId}:batchRemoveMediaItems`, {
+      mediaItemIds,
+    });
+  }
+
+  /**
+   * Update album title (only for albums created by this app)
+   */
+  async updateTitle(albumId: string, title: string): Promise<Album> {
+    return this.client.patch<Album>(
+      `/albums/${albumId}`,
+      { title },
+      { updateMask: 'title' }
+    );
+  }
+
+  /**
+   * Update album cover photo (only for albums created by this app)
+   */
+  async updateCoverPhoto(albumId: string, coverPhotoMediaItemId: string): Promise<Album> {
+    return this.client.patch<Album>(
+      `/albums/${albumId}`,
+      { coverPhotoMediaItemId },
+      { updateMask: 'coverPhotoMediaItemId' }
+    );
+  }
+}

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

@@ -0,0 +1,159 @@
+import { PhotosApiError } from '../types';
+import { getValidAccessToken } from '../utils/auth';
+
+const PHOTOS_API_BASE = 'https://photoslibrary.googleapis.com/v1';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+}
+
+export class PhotosClient {
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${PHOTOS_API_BASE}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    // Get fresh access token (handles refresh automatically)
+    const accessToken = await getValidAccessToken();
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Bearer ${accessToken}`,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      if (typeof body === 'string') {
+        // For binary uploads, Content-Type should be set by caller
+        if (!requestHeaders['Content-Type']) {
+          requestHeaders['Content-Type'] = 'application/octet-stream';
+        }
+      } else {
+        requestHeaders['Content-Type'] = 'application/json';
+      }
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorData = data as { error?: { message?: string; code?: number; status?: string; details?: unknown[] } };
+      const errorMessage = errorData?.error?.message || String(data || response.statusText);
+      const errorStatus = errorData?.error?.status || 'UNKNOWN';
+      throw new PhotosApiError(
+        errorMessage,
+        response.status,
+        errorStatus,
+        errorData?.error?.details as PhotosApiError['details']
+      );
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[], params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Upload binary data to Google Photos
+   * Returns an upload token that can be used to create media items
+   */
+  async uploadBytes(data: Buffer | Uint8Array, mimeType: string, filename?: string): Promise<string> {
+    const accessToken = await getValidAccessToken();
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/octet-stream',
+      'X-Goog-Upload-Content-Type': mimeType,
+      'X-Goog-Upload-Protocol': 'raw',
+    };
+
+    if (filename) {
+      headers['X-Goog-Upload-File-Name'] = filename;
+    }
+
+    const response = await fetch('https://photoslibrary.googleapis.com/v1/uploads', {
+      method: 'POST',
+      headers,
+      body: data,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new PhotosApiError(
+        `Upload failed: ${text}`,
+        response.status,
+        'UPLOAD_FAILED'
+      );
+    }
+
+    // Response body is the upload token (plain text)
+    const uploadToken = await response.text();
+    return uploadToken;
+  }
+}

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

@@ -0,0 +1,53 @@
+import { PhotosClient } from './client';
+import { AlbumsApi } from './albums';
+import { MediaApi } from './media';
+import { UploadApi } from './upload';
+
+export { PhotosClient } from './client';
+export { AlbumsApi } from './albums';
+export { MediaApi } from './media';
+export { UploadApi } from './upload';
+
+/**
+ * Main Google Photos API client
+ * Provides access to all Google Photos Library API functionality
+ */
+export class GooglePhotos {
+  private client: PhotosClient;
+
+  /**
+   * Albums API - manage photo albums
+   */
+  public readonly albums: AlbumsApi;
+
+  /**
+   * Media API - access and search media items
+   */
+  public readonly media: MediaApi;
+
+  /**
+   * Upload API - upload photos and videos
+   */
+  public readonly upload: UploadApi;
+
+  constructor() {
+    this.client = new PhotosClient();
+    this.albums = new AlbumsApi(this.client);
+    this.media = new MediaApi(this.client);
+    this.upload = new UploadApi(this.client);
+  }
+
+  /**
+   * Create a new GooglePhotos instance
+   */
+  static create(): GooglePhotos {
+    return new GooglePhotos();
+  }
+
+  /**
+   * Get the underlying HTTP client for advanced usage
+   */
+  getClient(): PhotosClient {
+    return this.client;
+  }
+}

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

@@ -0,0 +1,238 @@
+import type { PhotosClient } from './client';
+import type {
+  MediaItem,
+  MediaItemsListResponse,
+  ListMediaItemsOptions,
+  SearchMediaItemsRequest,
+  Filters,
+  ContentCategory,
+  MediaType,
+} from '../types';
+
+export class MediaApi {
+  constructor(private client: PhotosClient) {}
+
+  /**
+   * List media items in the user's library
+   */
+  async list(options: ListMediaItemsOptions = {}): Promise<MediaItemsListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      pageSize: options.pageSize || 25,
+      pageToken: options.pageToken,
+    };
+
+    return this.client.get<MediaItemsListResponse>('/mediaItems', params);
+  }
+
+  /**
+   * Get all media items (handles pagination)
+   */
+  async listAll(options: Omit<ListMediaItemsOptions, 'pageToken'> = {}, maxItems?: number): Promise<MediaItem[]> {
+    const items: MediaItem[] = [];
+    let pageToken: string | undefined;
+
+    do {
+      const response = await this.list({ ...options, pageToken });
+      if (response.mediaItems) {
+        items.push(...response.mediaItems);
+        if (maxItems && items.length >= maxItems) {
+          return items.slice(0, maxItems);
+        }
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+
+    return items;
+  }
+
+  /**
+   * Get a specific media item by ID
+   */
+  async get(mediaItemId: string): Promise<MediaItem> {
+    return this.client.get<MediaItem>(`/mediaItems/${mediaItemId}`);
+  }
+
+  /**
+   * Get multiple media items by IDs
+   */
+  async batchGet(mediaItemIds: string[]): Promise<{ mediaItemResults: Array<{ mediaItem?: MediaItem; status?: { message: string } }> }> {
+    const params: Record<string, string> = {};
+    mediaItemIds.forEach((id, index) => {
+      params[`mediaItemIds[${index}]`] = id;
+    });
+
+    return this.client.get<{ mediaItemResults: Array<{ mediaItem?: MediaItem; status?: { message: string } }> }>(
+      '/mediaItems:batchGet',
+      params
+    );
+  }
+
+  /**
+   * Search for media items
+   */
+  async search(options: SearchMediaItemsRequest = {}): Promise<MediaItemsListResponse> {
+    const body: SearchMediaItemsRequest = {
+      pageSize: options.pageSize || 25,
+      pageToken: options.pageToken,
+    };
+
+    if (options.albumId) {
+      body.albumId = options.albumId;
+    }
+
+    if (options.filters) {
+      body.filters = options.filters;
+    }
+
+    if (options.orderBy) {
+      body.orderBy = options.orderBy;
+    }
+
+    return this.client.post<MediaItemsListResponse>('/mediaItems:search', body);
+  }
+
+  /**
+   * Search all media items (handles pagination)
+   */
+  async searchAll(options: Omit<SearchMediaItemsRequest, 'pageToken'> = {}, maxItems?: number): Promise<MediaItem[]> {
+    const items: MediaItem[] = [];
+    let pageToken: string | undefined;
+
+    do {
+      const response = await this.search({ ...options, pageToken });
+      if (response.mediaItems) {
+        items.push(...response.mediaItems);
+        if (maxItems && items.length >= maxItems) {
+          return items.slice(0, maxItems);
+        }
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+
+    return items;
+  }
+
+  /**
+   * Search for photos/videos by date
+   */
+  async searchByDate(
+    startDate: { year: number; month: number; day: number },
+    endDate?: { year: number; month: number; day: number },
+    options: Omit<SearchMediaItemsRequest, 'filters' | 'pageToken'> = {}
+  ): Promise<MediaItem[]> {
+    const filters: Filters = {
+      dateFilter: endDate
+        ? { ranges: [{ startDate, endDate }] }
+        : { dates: [startDate] },
+    };
+
+    return this.searchAll({ ...options, filters });
+  }
+
+  /**
+   * Search for photos/videos by content category
+   */
+  async searchByCategory(
+    categories: ContentCategory[],
+    options: Omit<SearchMediaItemsRequest, 'filters' | 'pageToken'> = {}
+  ): Promise<MediaItem[]> {
+    const filters: Filters = {
+      contentFilter: {
+        includedContentCategories: categories,
+      },
+    };
+
+    return this.searchAll({ ...options, filters });
+  }
+
+  /**
+   * Search for only photos or only videos
+   */
+  async searchByMediaType(
+    mediaTypes: MediaType[],
+    options: Omit<SearchMediaItemsRequest, 'filters' | 'pageToken'> = {}
+  ): Promise<MediaItem[]> {
+    const filters: Filters = {
+      mediaTypeFilter: { mediaTypes },
+    };
+
+    return this.searchAll({ ...options, filters });
+  }
+
+  /**
+   * Get favorites
+   */
+  async getFavorites(options: Omit<SearchMediaItemsRequest, 'filters' | 'pageToken'> = {}): Promise<MediaItem[]> {
+    const filters: Filters = {
+      featureFilter: {
+        includedFeatures: ['FAVORITES'],
+      },
+    };
+
+    return this.searchAll({ ...options, filters });
+  }
+
+  /**
+   * Get media items in an album
+   */
+  async getInAlbum(albumId: string, options: Omit<SearchMediaItemsRequest, 'albumId' | 'pageToken'> = {}): Promise<MediaItem[]> {
+    return this.searchAll({ ...options, albumId });
+  }
+
+  /**
+   * Get the download URL for a media item
+   * @param mediaItem The media item
+   * @param width Optional width for photos (default: original)
+   * @param height Optional height for photos (default: original)
+   */
+  getDownloadUrl(mediaItem: MediaItem, width?: number, height?: number): string {
+    let url = mediaItem.baseUrl;
+
+    // For photos, append size parameters
+    if (mediaItem.mediaMetadata.photo) {
+      if (width && height) {
+        url += `=w${width}-h${height}`;
+      } else if (width) {
+        url += `=w${width}`;
+      } else if (height) {
+        url += `=h${height}`;
+      } else {
+        // Original size
+        url += `=d`;
+      }
+    }
+
+    // For videos, append download parameter
+    if (mediaItem.mediaMetadata.video) {
+      url += '=dv';
+    }
+
+    return url;
+  }
+
+  /**
+   * Download a media item to a buffer
+   */
+  async download(mediaItem: MediaItem, width?: number, height?: number): Promise<Buffer> {
+    const url = this.getDownloadUrl(mediaItem, width, height);
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to download media item: ${response.statusText}`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Update description of a media item (only for items created by this app)
+   */
+  async updateDescription(mediaItemId: string, description: string): Promise<MediaItem> {
+    return this.client.patch<MediaItem>(
+      `/mediaItems/${mediaItemId}`,
+      { description },
+      { updateMask: 'description' }
+    );
+  }
+}