@payez/next-mvp 3.0.0

package/src/vibe/errors.ts

@@ -0,0 +1,185 @@
+/**
+ * =============================================================================
+ * VIBE API ERROR CLASSES
+ * =============================================================================
+ *
+ * Typed error classes for Vibe API operations.
+ * These provide specific error handling for different failure scenarios.
+ *
+ * Usage:
+ *   try {
+ *     await vibe.users.findUnique({ where: { id: 123 } })
+ *   } catch (error) {
+ *     if (error instanceof VibeNotFoundError) {
+ *       // Handle 404
+ *     } else if (error instanceof VibeValidationError) {
+ *       // Handle validation errors
+ *     }
+ *   }
+ *
+ * =============================================================================
+ */
+
+/**
+ * Base error class for all Vibe API errors
+ */
+export class VibeError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    code: string,
+    status: number,
+    details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'VibeError';
+    this.code = code;
+    this.status = status;
+    this.details = details;
+
+    // Maintains proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, VibeError);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.status,
+      details: this.details,
+    };
+  }
+
+  static fromResponse(response: {
+    success: false;
+    error: { code: string; message: string; details?: Record<string, unknown> };
+  }, status: number): VibeError {
+    const { code, message, details } = response.error;
+
+    switch (code) {
+      case 'NOT_FOUND':
+      case 'DOCUMENT_NOT_FOUND':
+      case 'TABLE_NOT_FOUND':
+        return new VibeNotFoundError(message, code, details);
+
+      case 'VALIDATION_ERROR':
+      case 'INVALID_INPUT':
+        return new VibeValidationError(message, details);
+
+      case 'UNAUTHORIZED':
+      case 'INVALID_CREDENTIALS':
+      case 'INVALID_CLIENT_ID':
+        return new VibeAuthError(message, code, details);
+
+      case 'RATE_LIMITED':
+        return new VibeRateLimitError(message, details);
+
+      case 'CONFLICT':
+      case 'DUPLICATE_ENTRY':
+        return new VibeConflictError(message, details);
+
+      default:
+        return new VibeError(message, code, status, details);
+    }
+  }
+}
+
+/**
+ * Thrown when a requested resource is not found (404)
+ */
+export class VibeNotFoundError extends VibeError {
+  constructor(
+    message: string = 'Resource not found',
+    code: string = 'NOT_FOUND',
+    details?: Record<string, unknown>
+  ) {
+    super(message, code, 404, details);
+    this.name = 'VibeNotFoundError';
+  }
+}
+
+/**
+ * Thrown when input validation fails (400)
+ */
+export class VibeValidationError extends VibeError {
+  public readonly fieldErrors?: Record<string, string[]>;
+
+  constructor(
+    message: string = 'Validation failed',
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+    this.name = 'VibeValidationError';
+
+    // Extract field-level errors if present
+    if (details?.fieldErrors) {
+      this.fieldErrors = details.fieldErrors as Record<string, string[]>;
+    }
+  }
+}
+
+/**
+ * Thrown when authentication/authorization fails (401/403)
+ */
+export class VibeAuthError extends VibeError {
+  constructor(
+    message: string = 'Authentication required',
+    code: string = 'UNAUTHORIZED',
+    details?: Record<string, unknown>
+  ) {
+    super(message, code, 401, details);
+    this.name = 'VibeAuthError';
+  }
+}
+
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+export class VibeRateLimitError extends VibeError {
+  public readonly retryAfter?: number;
+
+  constructor(
+    message: string = 'Rate limit exceeded',
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'RATE_LIMITED', 429, details);
+    this.name = 'VibeRateLimitError';
+
+    // Extract retry-after if present
+    if (details?.retryAfter) {
+      this.retryAfter = details.retryAfter as number;
+    }
+  }
+}
+
+/**
+ * Thrown when there's a conflict (e.g., duplicate entry) (409)
+ */
+export class VibeConflictError extends VibeError {
+  constructor(
+    message: string = 'Resource conflict',
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'CONFLICT', 409, details);
+    this.name = 'VibeConflictError';
+  }
+}
+
+/**
+ * Thrown when the Vibe API is unavailable (503)
+ */
+export class VibeServiceError extends VibeError {
+  constructor(
+    message: string = 'Vibe service unavailable',
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'SERVICE_UNAVAILABLE', 503, details);
+    this.name = 'VibeServiceError';
+  }
+}

package/src/vibe/generic.ts

@@ -0,0 +1,429 @@
+/**
+ * =============================================================================
+ * VIBE GENERIC CLIENT - DYNAMIC COLLECTION/TABLE ACCESS
+ * =============================================================================
+ *
+ * Provides dynamic access to any Vibe collection and table.
+ * Use this when you need to work with tables not predefined in the typed client.
+ *
+ * Usage:
+ *   import { vibeCollection, vibeTablePath, unwrapVibeDocument } from '@payez/next-mvp/vibe'
+ *
+ *   // Dynamic collection access
+ *   const idealResume = vibeCollection('ideal_resume');
+ *   const resumes = await idealResume.table('resumes').findMany();
+ *
+ *   // Path builders for custom fetch calls
+ *   const path = vibeTablePath('ideal_resume', 'resumes', 123);
+ *   // => '/v1/collections/ideal_resume/tables/resumes/123'
+ *
+ *   // Document unwrapping (Vibe stores data as JSON string in 'data' field)
+ *   const unwrapped = unwrapVibeDocument(rawDoc);
+ *
+ * =============================================================================
+ */
+
+import { VibeClient, VibeClientConfig, FindManyOptions, FindManyResult } from './client';
+import type { VibeResponse, VibeMeta } from './types';
+import { VibeError, VibeNotFoundError, VibeServiceError } from './errors';
+
+// -----------------------------------------------------------------------------
+// PATH BUILDERS
+// -----------------------------------------------------------------------------
+
+/**
+ * Build path for collection table operations.
+ * @param collection - Collection name (e.g., 'ideal_resume', 'vibe_app')
+ * @param table - Table name (e.g., 'resumes', 'users')
+ * @param id - Optional document ID
+ * @returns API path string
+ *
+ * @example
+ * vibeTablePath('ideal_resume', 'resumes')
+ * // => '/v1/collections/ideal_resume/tables/resumes'
+ *
+ * vibeTablePath('ideal_resume', 'resumes', 123)
+ * // => '/v1/collections/ideal_resume/tables/resumes/123'
+ */
+export function vibeTablePath(collection: string, table: string, id?: number): string {
+  const basePath = `/v1/collections/${collection}/tables/${table}`;
+  return id !== undefined ? `${basePath}/${id}` : basePath;
+}
+
+/**
+ * Build path for collection table query endpoint.
+ * @param collection - Collection name
+ * @param table - Table name
+ * @returns Query API path string
+ */
+export function vibeQueryPath(collection: string, table: string): string {
+  return `/v1/collections/${collection}/tables/${table}/query`;
+}
+
+/**
+ * Build path for collection table grid endpoint.
+ * @param collection - Collection name
+ * @param table - Table name
+ * @returns Grid API path string
+ */
+export function vibeGridPath(collection: string, table: string): string {
+  return `/v1/collections/${collection}/tables/${table}/grid`;
+}
+
+// -----------------------------------------------------------------------------
+// DOCUMENT UNWRAPPING
+// -----------------------------------------------------------------------------
+
+/**
+ * Vibe document wrapper structure.
+ * Vibe stores actual table data as JSON string in the 'data' field.
+ */
+export interface VibeDocumentWrapper {
+  document_id: number;
+  client_id?: number;
+  user_id?: number;
+  collection?: string;
+  table_name?: string;
+  data: string | Record<string, unknown>;
+  collection_schema_id?: number;
+  created_at?: string;
+  created_by?: number;
+  updated_at?: string | null;
+  updated_by?: number | null;
+  deleted_at?: string | null;
+}
+
+/**
+ * Unwrap a Vibe document response.
+ * Vibe returns documents with a wrapper where actual data is a JSON string.
+ *
+ * @param doc - Raw Vibe document (wrapper format)
+ * @returns Unwrapped document with id from document_id, or null if invalid
+ *
+ * @example
+ * const raw = { document_id: 123, data: '{"name":"John","email":"john@example.com"}' };
+ * const unwrapped = unwrapVibeDocument(raw);
+ * // => { id: 123, name: 'John', email: 'john@example.com' }
+ */
+export function unwrapVibeDocument<T extends Record<string, unknown> = Record<string, unknown>>(
+  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
+): (T & { id: number; document_id: number }) | null {
+  if (!doc) return null;
+
+  // Handle case where doc is already unwrapped (has id but no document_id)
+  if ('id' in doc && !('document_id' in doc)) {
+    return doc as T & { id: number; document_id: number };
+  }
+
+  const wrapper = doc as VibeDocumentWrapper;
+  let parsedData: Record<string, unknown> = {};
+
+  if (typeof wrapper.data === 'string') {
+    try {
+      parsedData = JSON.parse(wrapper.data);
+    } catch {
+      console.warn('[vibe-generic] Failed to parse document data JSON:', wrapper.data);
+      parsedData = {};
+    }
+  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
+    parsedData = wrapper.data;
+  }
+
+  const documentId = wrapper.document_id ?? (doc as any).id ?? 0;
+
+  return {
+    id: documentId,
+    document_id: documentId,
+    ...parsedData,
+  } as T & { id: number; document_id: number };
+}
+
+/**
+ * Extract and unwrap array of documents from Vibe response.
+ *
+ * @param responseData - Raw Vibe API response
+ * @returns Array of unwrapped documents
+ *
+ * @example
+ * const response = await fetch('/api/vibe/data/ideal_resume/resumes');
+ * const data = await response.json();
+ * const resumes = extractVibeDocuments(data);
+ */
+export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
+  responseData: unknown
+): Array<T & { id: number; document_id: number }> {
+  if (!responseData || typeof responseData !== 'object') {
+    return [];
+  }
+
+  const data = responseData as Record<string, unknown>;
+
+  // Try common response shapes
+  const docs =
+    data.data ??
+    data.items ??
+    data.documents ??
+    (Array.isArray(responseData) ? responseData : null);
+
+  if (!Array.isArray(docs)) {
+    return [];
+  }
+
+  return docs
+    .map((doc) => unwrapVibeDocument<T>(doc))
+    .filter((d): d is T & { id: number; document_id: number } => d !== null);
+}
+
+// -----------------------------------------------------------------------------
+// GENERIC TABLE DELEGATE
+// -----------------------------------------------------------------------------
+
+/**
+ * Generic table delegate for dynamic collection/table access.
+ * Provides Prisma-like methods for any table.
+ */
+export class GenericTableDelegate<T extends Record<string, unknown> = Record<string, unknown>> {
+  private collection: string;
+  private tableName: string;
+  private client: VibeClient;
+
+  constructor(collection: string, tableName: string, client: VibeClient) {
+    this.collection = collection;
+    this.tableName = tableName;
+    this.client = client;
+  }
+
+  /**
+   * Find multiple records with optional filtering and pagination.
+   */
+  async findMany(options?: FindManyOptions<T>): Promise<FindManyResult<T & { id: number; document_id: number }>> {
+    const params = new URLSearchParams();
+
+    // Build filter params
+    if (options?.where) {
+      for (const [key, value] of Object.entries(options.where)) {
+        if (value !== undefined && value !== null) {
+          if (typeof value === 'object' && !Array.isArray(value)) {
+            // Handle operator objects
+            for (const [op, val] of Object.entries(value as Record<string, unknown>)) {
+              if (Array.isArray(val)) {
+                val.forEach((v) => params.append(`filter[${key}][${op}][]`, String(v)));
+              } else {
+                params.append(`filter[${key}][${op}]`, String(val));
+              }
+            }
+          } else if (Array.isArray(value)) {
+            value.forEach((v) => params.append(`filter[${key}][]`, String(v)));
+          } else {
+            params.append(`filter[${key}]`, String(value));
+          }
+        }
+      }
+    }
+
+    // Pagination
+    if (options?.take !== undefined) {
+      params.append('limit', String(options.take));
+    }
+    if (options?.skip !== undefined) {
+      params.append('offset', String(options.skip));
+    }
+
+    // Sorting
+    if (options?.orderBy) {
+      const sortParts: string[] = [];
+      for (const [key, dir] of Object.entries(options.orderBy)) {
+        sortParts.push(dir === 'desc' ? `-${key}` : key);
+      }
+      if (sortParts.length > 0) {
+        params.append('sort', sortParts.join(','));
+      }
+    }
+
+    const queryString = params.toString();
+    const path = vibeTablePath(this.collection, this.tableName);
+    const url = `${this.client.getBaseUrl()}${path}${queryString ? `?${queryString}` : ''}`;
+
+    const response = await this.client.request<VibeDocumentWrapper[]>(url, 'GET');
+    const unwrapped = extractVibeDocuments<T>(response);
+
+    return {
+      data: unwrapped,
+      meta: response.meta || { total: unwrapped.length, limit: options?.take || 50, offset: options?.skip || 0 },
+    };
+  }
+
+  /**
+   * Find a single record by ID.
+   * Throws VibeNotFoundError if not found.
+   */
+  async findUnique(options: { where: { id: number } }): Promise<T & { id: number; document_id: number }> {
+    const path = vibeTablePath(this.collection, this.tableName, options.where.id);
+    const url = `${this.client.getBaseUrl()}${path}`;
+    const response = await this.client.request<VibeDocumentWrapper>(url, 'GET');
+    const unwrapped = unwrapVibeDocument<T>(response.data);
+    if (!unwrapped) {
+      throw new VibeNotFoundError(
+        `Document ${options.where.id} not found in ${this.collection}/${this.tableName}`,
+        'NOT_FOUND',
+        { collection: this.collection, table: this.tableName, id: options.where.id }
+      );
+    }
+    return unwrapped;
+  }
+
+  /**
+   * Find a single record by ID, returns null if not found.
+   */
+  async findUniqueOrNull(options: { where: { id: number } }): Promise<(T & { id: number; document_id: number }) | null> {
+    try {
+      return await this.findUnique(options);
+    } catch (error) {
+      if (error instanceof VibeNotFoundError) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Find the first record matching the filter.
+   */
+  async findFirst(options?: FindManyOptions<T>): Promise<(T & { id: number; document_id: number }) | null> {
+    const result = await this.findMany({ ...options, take: 1 });
+    return result.data[0] || null;
+  }
+
+  /**
+   * Create a new record.
+   */
+  async create(options: { data: Partial<T> }): Promise<T & { id: number; document_id: number }> {
+    const path = vibeTablePath(this.collection, this.tableName);
+    const url = `${this.client.getBaseUrl()}${path}`;
+    const response = await this.client.request<VibeDocumentWrapper>(url, 'POST', options.data);
+    const unwrapped = unwrapVibeDocument<T>(response.data);
+    if (!unwrapped) {
+      throw new VibeServiceError('Failed to parse created document');
+    }
+    return unwrapped;
+  }
+
+  /**
+   * Update an existing record by ID.
+   */
+  async update(options: { where: { id: number }; data: Partial<T> }): Promise<T & { id: number; document_id: number }> {
+    const path = vibeTablePath(this.collection, this.tableName, options.where.id);
+    const url = `${this.client.getBaseUrl()}${path}`;
+    const response = await this.client.request<VibeDocumentWrapper>(url, 'PUT', options.data);
+    const unwrapped = unwrapVibeDocument<T>(response.data);
+    if (!unwrapped) {
+      throw new VibeServiceError('Failed to parse updated document');
+    }
+    return unwrapped;
+  }
+
+  /**
+   * Delete a record by ID (soft delete).
+   */
+  async delete(options: { where: { id: number } }): Promise<T & { id: number; document_id: number }> {
+    const path = vibeTablePath(this.collection, this.tableName, options.where.id);
+    const url = `${this.client.getBaseUrl()}${path}`;
+    const response = await this.client.request<VibeDocumentWrapper>(url, 'DELETE');
+    const unwrapped = unwrapVibeDocument<T>(response.data);
+    if (!unwrapped) {
+      throw new VibeServiceError('Failed to parse deleted document');
+    }
+    return unwrapped;
+  }
+
+  /**
+   * Count records matching the filter.
+   */
+  async count(options?: { where?: FindManyOptions<T>['where'] }): Promise<number> {
+    const result = await this.findMany({ ...options, take: 0 });
+    return result.meta.total;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// GENERIC COLLECTION
+// -----------------------------------------------------------------------------
+
+/**
+ * Generic collection accessor for dynamic table access.
+ */
+export class GenericCollection {
+  private collectionName: string;
+  private client: VibeClient;
+
+  constructor(collectionName: string, client: VibeClient) {
+    this.collectionName = collectionName;
+    this.client = client;
+  }
+
+  /**
+   * Get a table delegate for the specified table.
+   *
+   * @example
+   * const idealResume = vibeCollection('ideal_resume');
+   * const resumes = await idealResume.table('resumes').findMany();
+   */
+  table<T extends Record<string, unknown> = Record<string, unknown>>(tableName: string): GenericTableDelegate<T> {
+    return new GenericTableDelegate<T>(this.collectionName, tableName, this.client);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// FACTORY FUNCTIONS
+// -----------------------------------------------------------------------------
+
+let defaultClient: VibeClient | null = null;
+
+function getDefaultClient(): VibeClient {
+  if (!defaultClient) {
+    defaultClient = new VibeClient();
+  }
+  return defaultClient;
+}
+
+/**
+ * Get a generic collection accessor for dynamic table access.
+ *
+ * @param collectionName - Name of the collection (e.g., 'ideal_resume', 'vibe_app')
+ * @param config - Optional client configuration
+ * @returns GenericCollection instance
+ *
+ * @example
+ * import { vibeCollection } from '@payez/next-mvp/vibe';
+ *
+ * const idealResume = vibeCollection('ideal_resume');
+ * const resumes = await idealResume.table('resumes').findMany({ take: 10 });
+ * const resume = await idealResume.table('resumes').findUnique({ where: { id: 123 } });
+ */
+export function vibeCollection(collectionName: string, config?: VibeClientConfig): GenericCollection {
+  const client = config ? new VibeClient(config) : getDefaultClient();
+  return new GenericCollection(collectionName, client);
+}
+
+/**
+ * Create a generic table delegate directly.
+ *
+ * @param collection - Collection name
+ * @param table - Table name
+ * @param config - Optional client configuration
+ * @returns GenericTableDelegate instance
+ *
+ * @example
+ * import { vibeTable } from '@payez/next-mvp/vibe';
+ *
+ * const resumes = vibeTable('ideal_resume', 'resumes');
+ * const allResumes = await resumes.findMany();
+ */
+export function vibeTable<T extends Record<string, unknown> = Record<string, unknown>>(
+  collection: string,
+  table: string,
+  config?: VibeClientConfig
+): GenericTableDelegate<T> {
+  const client = config ? new VibeClient(config) : getDefaultClient();
+  return new GenericTableDelegate<T>(collection, table, client);
+}