@payez/next-mvp 4.0.1 → 4.0.2

package/dist/vibe/enterprise-auth.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * =============================================================================
+ * VIBE ENTERPRISE AUTHENTICATION
+ * =============================================================================
+ *
+ * Server-side HMAC authentication for enterprise/service account requests.
+ * Validates incoming requests with X-Vibe-Client-Id, X-Vibe-Timestamp, and
+ * X-Vibe-Signature headers.
+ *
+ * Usage in Next.js API routes:
+ *   import { validateEnterpriseAuth, hasEnterpriseAuthHeaders } from '@payez/next-mvp/vibe/enterprise-auth'
+ *
+ *   export async function GET(request: NextRequest) {
+ *     if (hasEnterpriseAuthHeaders(request)) {
+ *       const auth = await validateEnterpriseAuth(request, ENTERPRISE_CLIENTS);
+ *       if (!auth.success) {
+ *         return NextResponse.json({ error: auth.error }, { status: 401 });
+ *       }
+ *       // Use auth.clientId for authenticated requests
+ *     }
+ *   }
+ *
+ * =============================================================================
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnterpriseAuth = validateEnterpriseAuth;
+exports.hasEnterpriseAuthHeaders = hasEnterpriseAuthHeaders;
+exports.generateBackendHmacSignature = generateBackendHmacSignature;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Validates enterprise HMAC authentication headers on incoming requests.
+ *
+ * Expected headers:
+ * - X-Vibe-Client-Id: The client identifier
+ * - X-Vibe-Timestamp: Unix timestamp in seconds
+ * - X-Vibe-Signature: HMAC-SHA256 signature of "{timestamp}|{method}|{path}"
+ *
+ * Security features:
+ * - Constant-time signature comparison (prevents timing attacks)
+ * - Timestamp validation with 5-minute window (prevents replay attacks)
+ * - Base64-encoded secret keys
+ *
+ * @param request - The Next.js request object
+ * @param enterpriseClients - Map of client IDs to secret keys
+ * @returns Authentication result with success status and client ID
+ *
+ * @example
+ * const CLIENTS = {
+ *   'vibe_abc123': 'base64SecretKey=='
+ * };
+ * const result = await validateEnterpriseAuth(request, CLIENTS);
+ * if (result.success) {
+ *   console.log(`Authenticated client: ${result.clientId}`);
+ * }
+ */
+async function validateEnterpriseAuth(request, enterpriseClients) {
+    // Check for required headers
+    const clientId = request.headers.get('X-Vibe-Client-Id');
+    const timestamp = request.headers.get('X-Vibe-Timestamp');
+    const signature = request.headers.get('X-Vibe-Signature');
+    // If any header is missing, this is not an enterprise auth request
+    if (!clientId || !timestamp || !signature) {
+        return {
+            success: false,
+            error: 'MISSING_ENTERPRISE_HEADERS'
+        };
+    }
+    // Validate client ID exists in configuration
+    const secretKey = enterpriseClients[clientId];
+    if (!secretKey) {
+        return {
+            success: false,
+            error: 'INVALID_CLIENT_ID'
+        };
+    }
+    // Validate timestamp is recent (within 5 minutes)
+    const now = Math.floor(Date.now() / 1000);
+    const requestTime = parseInt(timestamp, 10);
+    if (isNaN(requestTime)) {
+        return {
+            success: false,
+            error: 'INVALID_TIMESTAMP'
+        };
+    }
+    const timeDiff = Math.abs(now - requestTime);
+    if (timeDiff > 300) { // 5 minutes
+        return {
+            success: false,
+            error: 'TIMESTAMP_EXPIRED'
+        };
+    }
+    // Compute expected signature
+    // Format: "{timestamp}|{method}|{path}"
+    const method = request.method;
+    const url = new URL(request.url);
+    const path = url.pathname;
+    const message = `${timestamp}|${method}|${path}`;
+    const expectedSignature = crypto_1.default
+        .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+        .update(message)
+        .digest('base64');
+    // Compare signatures (constant-time comparison to prevent timing attacks)
+    if (!crypto_1.default.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+        return {
+            success: false,
+            error: 'INVALID_SIGNATURE'
+        };
+    }
+    // Enterprise auth successful
+    return {
+        success: true,
+        clientId
+    };
+}
+/**
+ * Checks if request has enterprise authentication headers.
+ * Does not validate - just checks if all required headers are present.
+ *
+ * @param request - The Next.js request object
+ * @returns True if all enterprise auth headers are present
+ *
+ * @example
+ * if (hasEnterpriseAuthHeaders(request)) {
+ *   // Validate the headers
+ *   const auth = await validateEnterpriseAuth(request, clients);
+ * } else {
+ *   // Fall back to user session auth
+ *   const token = await ensureFreshToken(request);
+ * }
+ */
+function hasEnterpriseAuthHeaders(request) {
+    return !!(request.headers.get('X-Vibe-Client-Id') &&
+        request.headers.get('X-Vibe-Timestamp') &&
+        request.headers.get('X-Vibe-Signature'));
+}
+/**
+ * Generates HMAC signature for backend API requests.
+ * Used when frontend needs to proxy enterprise auth requests to backend
+ * with a different path (e.g., /api/vibe/* -> /v1/collections/*).
+ *
+ * @param clientId - The Vibe client ID
+ * @param secretKey - Base64-encoded HMAC secret key
+ * @param timestamp - Unix timestamp (seconds) as string
+ * @param method - HTTP method (GET, POST, etc)
+ * @param backendPath - The backend API path (e.g., "/v1/collections/agent_mail/tables")
+ * @returns HMAC signature for the backend request
+ *
+ * @example
+ * // Frontend received request for /api/vibe/agent_mail/tables
+ * // Need to call backend at /v1/collections/agent_mail/tables
+ * const signature = generateBackendHmacSignature(
+ *   'vibe_abc123',
+ *   'base64SecretKey==',
+ *   '1234567890',
+ *   'GET',
+ *   '/v1/collections/agent_mail/tables'
+ * );
+ * // Use signature in backend request headers
+ */
+function generateBackendHmacSignature(clientId, secretKey, timestamp, method, backendPath) {
+    if (!secretKey) {
+        throw new Error(`No secret key provided for client ID: ${clientId}`);
+    }
+    const message = `${timestamp}|${method}|${backendPath}`;
+    return crypto_1.default
+        .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+        .update(message)
+        .digest('base64');
+}

package/dist/vibe/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * =============================================================================
+ * 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 declare class VibeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, status: number, details?: Record<string, unknown>);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        status: number;
+        details: Record<string, unknown> | undefined;
+    };
+    static fromResponse(response: {
+        success: false;
+        error: {
+            code: string;
+            message: string;
+            details?: Record<string, unknown>;
+        };
+    }, status: number): VibeError;
+}
+/**
+ * Thrown when a requested resource is not found (404)
+ */
+export declare class VibeNotFoundError extends VibeError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when input validation fails (400)
+ */
+export declare class VibeValidationError extends VibeError {
+    readonly fieldErrors?: Record<string, string[]>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when authentication/authorization fails (401/403)
+ */
+export declare class VibeAuthError extends VibeError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+export declare class VibeRateLimitError extends VibeError {
+    readonly retryAfter?: number;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when there's a conflict (e.g., duplicate entry) (409)
+ */
+export declare class VibeConflictError extends VibeError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when the Vibe API is unavailable (503)
+ */
+export declare class VibeServiceError extends VibeError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}

package/dist/vibe/errors.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * =============================================================================
+ * 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
+ *     }
+ *   }
+ *
+ * =============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VibeServiceError = exports.VibeConflictError = exports.VibeRateLimitError = exports.VibeAuthError = exports.VibeValidationError = exports.VibeNotFoundError = exports.VibeError = void 0;
+/**
+ * Base error class for all Vibe API errors
+ */
+class VibeError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, code, status, details) {
+        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, status) {
+        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);
+        }
+    }
+}
+exports.VibeError = VibeError;
+/**
+ * Thrown when a requested resource is not found (404)
+ */
+class VibeNotFoundError extends VibeError {
+    constructor(message = 'Resource not found', code = 'NOT_FOUND', details) {
+        super(message, code, 404, details);
+        this.name = 'VibeNotFoundError';
+    }
+}
+exports.VibeNotFoundError = VibeNotFoundError;
+/**
+ * Thrown when input validation fails (400)
+ */
+class VibeValidationError extends VibeError {
+    fieldErrors;
+    constructor(message = 'Validation failed', details) {
+        super(message, 'VALIDATION_ERROR', 400, details);
+        this.name = 'VibeValidationError';
+        // Extract field-level errors if present
+        if (details?.fieldErrors) {
+            this.fieldErrors = details.fieldErrors;
+        }
+    }
+}
+exports.VibeValidationError = VibeValidationError;
+/**
+ * Thrown when authentication/authorization fails (401/403)
+ */
+class VibeAuthError extends VibeError {
+    constructor(message = 'Authentication required', code = 'UNAUTHORIZED', details) {
+        super(message, code, 401, details);
+        this.name = 'VibeAuthError';
+    }
+}
+exports.VibeAuthError = VibeAuthError;
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+class VibeRateLimitError extends VibeError {
+    retryAfter;
+    constructor(message = 'Rate limit exceeded', details) {
+        super(message, 'RATE_LIMITED', 429, details);
+        this.name = 'VibeRateLimitError';
+        // Extract retry-after if present
+        if (details?.retryAfter) {
+            this.retryAfter = details.retryAfter;
+        }
+    }
+}
+exports.VibeRateLimitError = VibeRateLimitError;
+/**
+ * Thrown when there's a conflict (e.g., duplicate entry) (409)
+ */
+class VibeConflictError extends VibeError {
+    constructor(message = 'Resource conflict', details) {
+        super(message, 'CONFLICT', 409, details);
+        this.name = 'VibeConflictError';
+    }
+}
+exports.VibeConflictError = VibeConflictError;
+/**
+ * Thrown when the Vibe API is unavailable (503)
+ */
+class VibeServiceError extends VibeError {
+    constructor(message = 'Vibe service unavailable', details) {
+        super(message, 'SERVICE_UNAVAILABLE', 503, details);
+        this.name = 'VibeServiceError';
+    }
+}
+exports.VibeServiceError = VibeServiceError;

package/dist/vibe/generic.d.ts

@@ -0,0 +1,234 @@
+/**
+ * =============================================================================
+ * 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';
+/**
+ * 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 declare function vibeTablePath(collection: string, table: string, id?: number): string;
+/**
+ * Build path for collection table query endpoint.
+ * @param collection - Collection name
+ * @param table - Table name
+ * @returns Query API path string
+ */
+export declare function vibeQueryPath(collection: string, table: string): string;
+/**
+ * Build path for collection table grid endpoint.
+ * @param collection - Collection name
+ * @param table - Table name
+ * @returns Grid API path string
+ */
+export declare function vibeGridPath(collection: string, table: string): string;
+/**
+ * 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 declare function unwrapVibeDocument<T extends Record<string, unknown> = Record<string, unknown>>(doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined): (T & {
+    id: number;
+    document_id: number;
+}) | null;
+/**
+ * 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 declare function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(responseData: unknown): Array<T & {
+    id: number;
+    document_id: number;
+}>;
+/**
+ * Generic table delegate for dynamic collection/table access.
+ * Provides Prisma-like methods for any table.
+ */
+export declare class GenericTableDelegate<T extends Record<string, unknown> = Record<string, unknown>> {
+    private collection;
+    private tableName;
+    private client;
+    constructor(collection: string, tableName: string, client: VibeClient);
+    /**
+     * Find multiple records with optional filtering and pagination.
+     */
+    findMany(options?: FindManyOptions<T>): Promise<FindManyResult<T & {
+        id: number;
+        document_id: number;
+    }>>;
+    /**
+     * Find a single record by ID.
+     * Throws VibeNotFoundError if not found.
+     */
+    findUnique(options: {
+        where: {
+            id: number;
+        };
+    }): Promise<T & {
+        id: number;
+        document_id: number;
+    }>;
+    /**
+     * Find a single record by ID, returns null if not found.
+     */
+    findUniqueOrNull(options: {
+        where: {
+            id: number;
+        };
+    }): Promise<(T & {
+        id: number;
+        document_id: number;
+    }) | null>;
+    /**
+     * Find the first record matching the filter.
+     */
+    findFirst(options?: FindManyOptions<T>): Promise<(T & {
+        id: number;
+        document_id: number;
+    }) | null>;
+    /**
+     * Create a new record.
+     */
+    create(options: {
+        data: Partial<T>;
+    }): Promise<T & {
+        id: number;
+        document_id: number;
+    }>;
+    /**
+     * Update an existing record by ID.
+     */
+    update(options: {
+        where: {
+            id: number;
+        };
+        data: Partial<T>;
+    }): Promise<T & {
+        id: number;
+        document_id: number;
+    }>;
+    /**
+     * Delete a record by ID (soft delete).
+     */
+    delete(options: {
+        where: {
+            id: number;
+        };
+    }): Promise<T & {
+        id: number;
+        document_id: number;
+    }>;
+    /**
+     * Count records matching the filter.
+     */
+    count(options?: {
+        where?: FindManyOptions<T>['where'];
+    }): Promise<number>;
+}
+/**
+ * Generic collection accessor for dynamic table access.
+ */
+export declare class GenericCollection {
+    private collectionName;
+    private client;
+    constructor(collectionName: string, client: VibeClient);
+    /**
+     * 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>;
+}
+/**
+ * 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 declare function vibeCollection(collectionName: string, config?: VibeClientConfig): GenericCollection;
+/**
+ * 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 declare function vibeTable<T extends Record<string, unknown> = Record<string, unknown>>(collection: string, table: string, config?: VibeClientConfig): GenericTableDelegate<T>;