@payez/next-mvp 4.8.1 → 4.8.3

package/src/vibe/errors.ts

@@ -1,209 +1,209 @@
-/**
- * =============================================================================
- * 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';
-  }
-}
-
-/**
- * PAY-1767 (NightHawk 64534): thrown when a NON-ATOMIC `createMany` fails part-way. It CARRIES what was
- * already created, so the caller can reconcile instead of guessing whether k-1 rows persisted. This is the
- * point of the class: a partial write whose extent is invisible is the hazard, not the partial write itself.
- */
-export class VibeBatchCreateError extends VibeError {
-  /** How many records were created before the failure. */
-  public readonly createdCount: number;
-  /** The document ids that were created before the failure. */
-  public readonly createdIds: Array<number | string>;
-
-  constructor(
-    message: string,
-    details: { createdCount: number; createdIds: Array<number | string>; failedIndex: number; total: number },
-    cause?: unknown,
-  ) {
-    super(message, 'BATCH_PARTIAL_FAILURE', 500, details);
-    this.name = 'VibeBatchCreateError';
-    this.createdCount = details.createdCount;
-    this.createdIds = details.createdIds;
-    if (cause !== undefined) (this as { cause?: unknown }).cause = cause;
-  }
-}
+/**
+ * =============================================================================
+ * 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';
+  }
+}
+
+/**
+ * PAY-1767 (NightHawk 64534): thrown when a NON-ATOMIC `createMany` fails part-way. It CARRIES what was
+ * already created, so the caller can reconcile instead of guessing whether k-1 rows persisted. This is the
+ * point of the class: a partial write whose extent is invisible is the hazard, not the partial write itself.
+ */
+export class VibeBatchCreateError extends VibeError {
+  /** How many records were created before the failure. */
+  public readonly createdCount: number;
+  /** The document ids that were created before the failure. */
+  public readonly createdIds: Array<number | string>;
+
+  constructor(
+    message: string,
+    details: { createdCount: number; createdIds: Array<number | string>; failedIndex: number; total: number },
+    cause?: unknown,
+  ) {
+    super(message, 'BATCH_PARTIAL_FAILURE', 500, details);
+    this.name = 'VibeBatchCreateError';
+    this.createdCount = details.createdCount;
+    this.createdIds = details.createdIds;
+    if (cause !== undefined) (this as { cause?: unknown }).cause = cause;
+  }
+}

package/src/vibe/filters.ts

@@ -0,0 +1,52 @@
+/**
+ * PAY-1810: the ONE place the package builds Vibe /query filters and orderBy, in the shapes Core's VibeQueryBuilder accepts.
+ *
+ * Core accepts exactly three filter forms (PayEz.Vibe.Public.Api VibeQueryModels / VibeQueryBuilder):
+ *   standard  { field: { op: value } } with AND / OR arrays
+ *   flat      { field, operator, value }
+ *   compound  { operator: 'and' | 'or', filters: [ ...nodes ] }        <- the key is `filters`, NOT `conditions`
+ * What goes wrong with the shapes this module replaces:
+ *   - { operator, conditions }  has no `filters` key, so Core reads `operator` / `conditions` as COLUMN names and returns ZERO rows
+ *     (a broken search; for revoke-all, "revoked 0 sessions" reported as success).
+ *   - operator 'like' is not a Core operator; in a flat filter it is DROPPED and the query returns ALL rows. Core's substring operator is
+ *     `contains` (ILIKE, case-insensitive); `ilike` is case-insensitive EQUALS.
+ *   - orderBy must be a { field: 'asc' | 'desc' } map (Core's model is Dictionary<string,string>); a bare string is rejected or ignored, never honoured.
+ */
+
+export type VibeOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startsWith' | 'endsWith' | 'ilike' | 'in' | 'notIn';
+
+export interface VibeFlatFilter {
+  field: string;
+  operator: VibeOperator;
+  value: unknown;
+}
+export interface VibeCompoundFilter {
+  operator: 'and' | 'or';
+  filters: VibeFilter[];
+}
+export type VibeFilter = VibeFlatFilter | VibeCompoundFilter;
+
+export const eq = (field: string, value: unknown): VibeFlatFilter => ({ field, operator: 'eq', value });
+export const gte = (field: string, value: unknown): VibeFlatFilter => ({ field, operator: 'gte', value });
+export const lte = (field: string, value: unknown): VibeFlatFilter => ({ field, operator: 'lte', value });
+/** Case-insensitive substring (Core `contains` = ILIKE). The value is the bare text: no % wildcards. */
+export const contains = (field: string, value: string): VibeFlatFilter => ({ field, operator: 'contains', value });
+
+/** AND of the given nodes: none -> undefined (no filter), one -> that node, several -> a compound with `filters`. */
+export function allOf(nodes: Array<VibeFilter | undefined | null>): VibeFilter | undefined {
+  const f = nodes.filter((n): n is VibeFilter => !!n);
+  if (f.length === 0) return undefined;
+  return f.length === 1 ? f[0] : { operator: 'and', filters: f };
+}
+
+/** OR of the given nodes: none -> undefined, one -> that node, several -> a compound with `filters`. */
+export function anyOf(nodes: Array<VibeFilter | undefined | null>): VibeFilter | undefined {
+  const f = nodes.filter((n): n is VibeFilter => !!n);
+  if (f.length === 0) return undefined;
+  return f.length === 1 ? f[0] : { operator: 'or', filters: f };
+}
+
+/** orderBy as Core binds it. */
+export function orderByMap(field: string, direction: 'asc' | 'desc' = 'desc'): Record<string, 'asc' | 'desc'> {
+  return { [field]: direction };
+}