@hasna/connectors 0.4.0 → 0.4.2

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

@@ -0,0 +1,231 @@
+import type { SupabaseConfig, OutputFormat, SupabaseErrorResponse } from '../types';
+import { SupabaseApiError } from '../types';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string | ArrayBuffer;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+  apiType?: 'rest' | 'auth' | 'storage' | 'functions';
+}
+
+export class SupabaseClient {
+  private readonly projectUrl: string;
+  private readonly serviceRoleKey?: string;
+  private readonly anonKey?: string;
+
+  constructor(config: SupabaseConfig) {
+    if (!config.projectUrl) {
+      throw new Error('Project URL is required');
+    }
+    if (!config.serviceRoleKey && !config.anonKey) {
+      throw new Error('Service role key or anon key is required');
+    }
+    this.projectUrl = config.projectUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.serviceRoleKey = config.serviceRoleKey;
+    this.anonKey = config.anonKey;
+  }
+
+  private getApiKey(): string {
+    return this.serviceRoleKey || this.anonKey || '';
+  }
+
+  private getBaseUrl(apiType: RequestOptions['apiType'] = 'rest'): string {
+    switch (apiType) {
+      case 'auth':
+        return `${this.projectUrl}/auth/v1`;
+      case 'storage':
+        return `${this.projectUrl}/storage/v1`;
+      case 'functions':
+        return `${this.projectUrl}/functions/v1`;
+      case 'rest':
+      default:
+        return `${this.projectUrl}/rest/v1`;
+    }
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>, apiType?: RequestOptions['apiType']): string {
+    const url = new URL(`${this.getBaseUrl(apiType)}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to Supabase API
+   * Uses apikey header and Bearer token authentication
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, apiType = 'rest' } = options;
+
+    const url = this.buildUrl(path, params, apiType);
+    const apiKey = this.getApiKey();
+
+    const requestHeaders: Record<string, string> = {
+      'apikey': apiKey,
+      'Authorization': `Bearer ${apiKey}`,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    // For service role operations, add admin flag
+    if (this.serviceRoleKey && apiType === 'auth') {
+      requestHeaders['Authorization'] = `Bearer ${this.serviceRoleKey}`;
+    }
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method) && !(body instanceof ArrayBuffer)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      if (body instanceof ArrayBuffer) {
+        fetchOptions.body = body;
+      } else {
+        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) {
+      let errorMessage: string;
+      let errorCode: string | undefined;
+      let hint: string | undefined;
+
+      if (typeof data === 'object' && data !== null) {
+        const errorData = data as SupabaseErrorResponse;
+        errorMessage = errorData.message || errorData.error_description || errorData.error || errorData.msg || JSON.stringify(data);
+        errorCode = errorData.code;
+        hint = errorData.hint;
+      } else {
+        errorMessage = String(data || response.statusText);
+      }
+
+      throw new SupabaseApiError(errorMessage, response.status, errorCode, hint);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, apiType?: RequestOptions['apiType']): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params, apiType });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, apiType?: RequestOptions['apiType']): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, apiType });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, apiType?: RequestOptions['apiType']): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, apiType });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, apiType?: RequestOptions['apiType']): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body: body as Record<string, unknown>, apiType });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>, apiType?: RequestOptions['apiType']): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params, apiType });
+  }
+
+  /**
+   * Upload file to storage
+   */
+  async uploadFile(bucket: string, path: string, content: ArrayBuffer, contentType?: string): Promise<{ Key: string }> {
+    const url = `${this.getBaseUrl('storage')}/object/${bucket}/${path}`;
+    const apiKey = this.getApiKey();
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'apikey': apiKey,
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': contentType || 'application/octet-stream',
+      },
+      body: content,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new SupabaseApiError(text, response.status);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Download file from storage
+   */
+  async downloadFile(bucket: string, path: string): Promise<ArrayBuffer> {
+    const url = `${this.getBaseUrl('storage')}/object/${bucket}/${path}`;
+    const apiKey = this.getApiKey();
+
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'apikey': apiKey,
+        'Authorization': `Bearer ${apiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new SupabaseApiError(text, response.status);
+    }
+
+    return response.arrayBuffer();
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    const key = this.getApiKey();
+    if (key.length > 10) {
+      return `${key.substring(0, 6)}...${key.substring(key.length - 4)}`;
+    }
+    return '***';
+  }
+
+  /**
+   * Get project URL
+   */
+  getProjectUrl(): string {
+    return this.projectUrl;
+  }
+}

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

@@ -0,0 +1,439 @@
+import type {
+  SupabaseConfig,
+  User,
+  Session,
+  AuthResponse,
+  AdminUserAttributes,
+  ListUsersResult,
+  Factor,
+  Bucket,
+  FileObject,
+  SignedUrl,
+  EdgeFunction,
+} from '../types';
+import { SupabaseClient } from './client';
+
+/**
+ * Supabase API wrapper
+ */
+export class Supabase {
+  private readonly client: SupabaseClient;
+
+  constructor(config: SupabaseConfig) {
+    this.client = new SupabaseClient(config);
+  }
+
+  /**
+   * Create a client from environment variables
+   */
+  static fromEnv(): Supabase {
+    const projectUrl = process.env.SUPABASE_URL || process.env.SUPABASE_PROJECT_URL;
+    const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_SERVICE_KEY;
+    const anonKey = process.env.SUPABASE_ANON_KEY || process.env.SUPABASE_KEY;
+
+    if (!projectUrl) {
+      throw new Error('SUPABASE_URL environment variable is required');
+    }
+    if (!serviceRoleKey && !anonKey) {
+      throw new Error('SUPABASE_SERVICE_ROLE_KEY or SUPABASE_ANON_KEY environment variable is required');
+    }
+    return new Supabase({ projectUrl, serviceRoleKey, anonKey });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): SupabaseClient {
+    return this.client;
+  }
+
+  /**
+   * Get project URL
+   */
+  getProjectUrl(): string {
+    return this.client.getProjectUrl();
+  }
+
+  // ============================================
+  // Auth Admin API
+  // ============================================
+
+  /**
+   * List all users (admin only)
+   */
+  async listUsers(params?: {
+    page?: number;
+    per_page?: number;
+  }): Promise<ListUsersResult> {
+    return this.client.get<ListUsersResult>('/admin/users', params, 'auth');
+  }
+
+  /**
+   * Get user by ID (admin only)
+   */
+  async getUserById(userId: string): Promise<User> {
+    return this.client.get<User>(`/admin/users/${userId}`, undefined, 'auth');
+  }
+
+  /**
+   * Create user (admin only)
+   */
+  async createUser(params: {
+    email?: string;
+    phone?: string;
+    password?: string;
+    email_confirm?: boolean;
+    phone_confirm?: boolean;
+    user_metadata?: Record<string, unknown>;
+    app_metadata?: Record<string, unknown>;
+    ban_duration?: string;
+  }): Promise<User> {
+    return this.client.post<User>('/admin/users', params, 'auth');
+  }
+
+  /**
+   * Update user (admin only)
+   */
+  async updateUser(userId: string, attributes: AdminUserAttributes): Promise<User> {
+    return this.client.put<User>(`/admin/users/${userId}`, attributes, 'auth');
+  }
+
+  /**
+   * Delete user (admin only)
+   */
+  async deleteUser(userId: string): Promise<void> {
+    await this.client.delete(`/admin/users/${userId}`, undefined, 'auth');
+  }
+
+  /**
+   * Invite user by email (admin only)
+   */
+  async inviteUserByEmail(email: string, options?: {
+    redirect_to?: string;
+    data?: Record<string, unknown>;
+  }): Promise<User> {
+    return this.client.post<User>('/admin/invite', { email, ...options }, 'auth');
+  }
+
+  /**
+   * Generate link for user (admin only)
+   */
+  async generateLink(params: {
+    type: 'signup' | 'invite' | 'magiclink' | 'recovery' | 'email_change_current' | 'email_change_new';
+    email: string;
+    password?: string;
+    new_email?: string;
+    redirect_to?: string;
+    data?: Record<string, unknown>;
+  }): Promise<{ action_link: string; email_otp?: string; hashed_token?: string; redirect_to?: string; verification_type?: string }> {
+    return this.client.post('/admin/generate_link', params, 'auth');
+  }
+
+  /**
+   * List user's MFA factors (admin only)
+   */
+  async listUserFactors(userId: string): Promise<Factor[]> {
+    return this.client.get<Factor[]>(`/admin/users/${userId}/factors`, undefined, 'auth');
+  }
+
+  /**
+   * Delete user's MFA factor (admin only)
+   */
+  async deleteUserFactor(userId: string, factorId: string): Promise<void> {
+    await this.client.delete(`/admin/users/${userId}/factors/${factorId}`, undefined, 'auth');
+  }
+
+  // ============================================
+  // Storage API
+  // ============================================
+
+  /**
+   * List all buckets
+   */
+  async listBuckets(): Promise<Bucket[]> {
+    return this.client.get<Bucket[]>('/bucket', undefined, 'storage');
+  }
+
+  /**
+   * Get bucket by ID
+   */
+  async getBucket(bucketId: string): Promise<Bucket> {
+    return this.client.get<Bucket>(`/bucket/${bucketId}`, undefined, 'storage');
+  }
+
+  /**
+   * Create bucket
+   */
+  async createBucket(params: {
+    id?: string;
+    name: string;
+    public?: boolean;
+    file_size_limit?: number;
+    allowed_mime_types?: string[];
+  }): Promise<{ name: string }> {
+    return this.client.post<{ name: string }>('/bucket', params, 'storage');
+  }
+
+  /**
+   * Update bucket
+   */
+  async updateBucket(bucketId: string, params: {
+    public?: boolean;
+    file_size_limit?: number;
+    allowed_mime_types?: string[];
+  }): Promise<{ message: string }> {
+    return this.client.put<{ message: string }>(`/bucket/${bucketId}`, params, 'storage');
+  }
+
+  /**
+   * Delete bucket (must be empty)
+   */
+  async deleteBucket(bucketId: string): Promise<{ message: string }> {
+    return this.client.delete<{ message: string }>(`/bucket/${bucketId}`, undefined, 'storage');
+  }
+
+  /**
+   * Empty bucket (delete all files)
+   */
+  async emptyBucket(bucketId: string): Promise<{ message: string }> {
+    return this.client.post<{ message: string }>(`/bucket/${bucketId}/empty`, {}, 'storage');
+  }
+
+  /**
+   * List files in bucket
+   */
+  async listFiles(bucket: string, params?: {
+    prefix?: string;
+    limit?: number;
+    offset?: number;
+    sortBy?: { column: string; order: 'asc' | 'desc' };
+    search?: string;
+  }): Promise<FileObject[]> {
+    return this.client.post<FileObject[]>(`/object/list/${bucket}`, params || {}, 'storage');
+  }
+
+  /**
+   * Upload file
+   */
+  async uploadFile(bucket: string, path: string, content: ArrayBuffer | Uint8Array, contentType?: string): Promise<{ Key: string }> {
+    const arrayBuffer = content instanceof Uint8Array ? content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength) : content;
+    return this.client.uploadFile(bucket, path, arrayBuffer, contentType);
+  }
+
+  /**
+   * Download file
+   */
+  async downloadFile(bucket: string, path: string): Promise<ArrayBuffer> {
+    return this.client.downloadFile(bucket, path);
+  }
+
+  /**
+   * Move/rename file
+   */
+  async moveFile(bucket: string, fromPath: string, toPath: string): Promise<{ message: string }> {
+    return this.client.post<{ message: string }>(`/object/move`, {
+      bucketId: bucket,
+      sourceKey: fromPath,
+      destinationKey: toPath,
+    }, 'storage');
+  }
+
+  /**
+   * Copy file
+   */
+  async copyFile(bucket: string, fromPath: string, toPath: string): Promise<{ Key: string }> {
+    return this.client.post<{ Key: string }>(`/object/copy`, {
+      bucketId: bucket,
+      sourceKey: fromPath,
+      destinationKey: toPath,
+    }, 'storage');
+  }
+
+  /**
+   * Delete files
+   */
+  async deleteFiles(bucket: string, paths: string[]): Promise<{ name: string }[]> {
+    return this.client.delete<{ name: string }[]>(`/object/${bucket}`, { prefixes: paths.join(',') }, 'storage');
+  }
+
+  /**
+   * Create signed URL for download
+   */
+  async createSignedUrl(bucket: string, path: string, expiresIn: number = 3600): Promise<SignedUrl> {
+    return this.client.post<SignedUrl>(`/object/sign/${bucket}/${path}`, { expiresIn }, 'storage');
+  }
+
+  /**
+   * Create signed URLs for multiple files
+   */
+  async createSignedUrls(bucket: string, paths: string[], expiresIn: number = 3600): Promise<SignedUrl[]> {
+    return this.client.post<SignedUrl[]>(`/object/sign/${bucket}`, { paths, expiresIn }, 'storage');
+  }
+
+  /**
+   * Get public URL for file (bucket must be public)
+   */
+  getPublicUrl(bucket: string, path: string): string {
+    return `${this.client.getProjectUrl()}/storage/v1/object/public/${bucket}/${path}`;
+  }
+
+  // ============================================
+  // Database REST API (PostgREST)
+  // ============================================
+
+  /**
+   * Select records from a table
+   */
+  async select<T = unknown>(table: string, params?: {
+    select?: string;
+    filter?: Record<string, string>;
+    order?: string;
+    limit?: number;
+    offset?: number;
+    single?: boolean;
+  }): Promise<T[]> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+
+    if (params?.select) {
+      queryParams.select = params.select;
+    }
+    if (params?.filter) {
+      Object.entries(params.filter).forEach(([key, value]) => {
+        queryParams[key] = value;
+      });
+    }
+    if (params?.order) {
+      queryParams.order = params.order;
+    }
+    if (params?.limit) {
+      queryParams.limit = params.limit;
+    }
+    if (params?.offset) {
+      queryParams.offset = params.offset;
+    }
+
+    const headers: Record<string, string> = {};
+    if (params?.single) {
+      headers['Accept'] = 'application/vnd.pgrst.object+json';
+    }
+
+    return this.client.request<T[]>(`/${table}`, {
+      method: 'GET',
+      params: queryParams,
+      headers,
+      apiType: 'rest',
+    });
+  }
+
+  /**
+   * Insert records into a table
+   */
+  async insert<T = unknown>(table: string, data: Record<string, unknown> | Record<string, unknown>[], options?: {
+    returning?: 'minimal' | 'representation';
+    onConflict?: string;
+    ignoreDuplicates?: boolean;
+  }): Promise<T[]> {
+    const headers: Record<string, string> = {};
+
+    if (options?.returning === 'minimal') {
+      headers['Prefer'] = 'return=minimal';
+    } else {
+      headers['Prefer'] = 'return=representation';
+    }
+
+    if (options?.onConflict) {
+      headers['Prefer'] = `${headers['Prefer'] || ''},resolution=merge-duplicates`;
+    }
+
+    if (options?.ignoreDuplicates) {
+      headers['Prefer'] = `${headers['Prefer'] || ''},resolution=ignore-duplicates`;
+    }
+
+    return this.client.request<T[]>(`/${table}`, {
+      method: 'POST',
+      body: data,
+      headers,
+      apiType: 'rest',
+    });
+  }
+
+  /**
+   * Update records in a table
+   */
+  async update<T = unknown>(table: string, data: Record<string, unknown>, filter: Record<string, string>, options?: {
+    returning?: 'minimal' | 'representation';
+  }): Promise<T[]> {
+    const queryParams: Record<string, string | number | boolean | undefined> = { ...filter };
+
+    const headers: Record<string, string> = {};
+    if (options?.returning === 'minimal') {
+      headers['Prefer'] = 'return=minimal';
+    } else {
+      headers['Prefer'] = 'return=representation';
+    }
+
+    return this.client.request<T[]>(`/${table}`, {
+      method: 'PATCH',
+      body: data,
+      params: queryParams,
+      headers,
+      apiType: 'rest',
+    });
+  }
+
+  /**
+   * Delete records from a table
+   */
+  async deleteRecords<T = unknown>(table: string, filter: Record<string, string>, options?: {
+    returning?: 'minimal' | 'representation';
+  }): Promise<T[]> {
+    const headers: Record<string, string> = {};
+    if (options?.returning === 'minimal') {
+      headers['Prefer'] = 'return=minimal';
+    } else {
+      headers['Prefer'] = 'return=representation';
+    }
+
+    return this.client.request<T[]>(`/${table}`, {
+      method: 'DELETE',
+      params: filter,
+      headers,
+      apiType: 'rest',
+    });
+  }
+
+  /**
+   * Call RPC function
+   */
+  async rpc<T = unknown>(functionName: string, params?: Record<string, unknown>): Promise<T> {
+    return this.client.post<T>(`/rpc/${functionName}`, params || {}, 'rest');
+  }
+
+  // ============================================
+  // Edge Functions API
+  // ============================================
+
+  /**
+   * Invoke an edge function
+   */
+  async invokeFunction<T = unknown>(functionName: string, options?: {
+    body?: Record<string, unknown> | string;
+    headers?: Record<string, string>;
+  }): Promise<T> {
+    return this.client.request<T>(`/${functionName}`, {
+      method: 'POST',
+      body: options?.body as Record<string, unknown>,
+      headers: options?.headers,
+      apiType: 'functions',
+    });
+  }
+}
+
+export { SupabaseClient } from './client';