@payez/next-mvp 4.4.6 → 4.4.7

package/src/vibe/document-unwrap.ts

@@ -0,0 +1,103 @@
+/**
+ * Vibe document wrapper + unwrapping.
+ *
+ * PAY-1767: extracted from generic.ts into its own module so the typed client (client.ts) can unwrap
+ * reads WITHOUT importing generic.ts - generic.ts imports client.ts, so a shared helper there would be
+ * a cycle. This module imports nothing from the vibe client.
+ *
+ * Vibe stores a row's own fields as a JSON STRING under the wrapper's `data` field, alongside storage
+ * columns (document_id, owner, timestamps). A caller that renders `response.data` directly sees the
+ * wrapper, so `row.name` is undefined. unwrapVibeDocument flattens the row out and keeps the storage
+ * document_id as `_vibe_doc_id` for update/delete paths.
+ */
+
+/** Vibe document wrapper structure. Vibe stores actual table data as a 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.
+ *
+ * @param doc - Raw Vibe document (wrapper format)
+ * @returns Unwrapped document with schema fields only; storage document_id preserved as `_vibe_doc_id`
+ *          for update/delete paths. See PayEz-Core/docs/vibe-primary-key-standard.md
+ *
+ * @example
+ * const raw = { document_id: 123, data: '{"user_id":15,"name":"John"}' };
+ * unwrapVibeDocument(raw); // => { user_id: 15, name: 'John', _vibe_doc_id: 123 }
+ */
+export function unwrapVibeDocument<T extends object = Record<string, unknown>>(
+  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
+): (T & { _vibe_doc_id?: number }) | null {
+  if (!doc) return null;
+
+  // Handle case where doc is already unwrapped (has schema fields directly)
+  if (!('document_id' in doc) && !('data' in doc)) {
+    return doc as T & { _vibe_doc_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-document] Failed to parse document data JSON:', wrapper.data);
+      parsedData = {};
+    }
+  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
+    parsedData = wrapper.data;
+  }
+
+  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
+  const documentId = wrapper.document_id ?? (doc as { document_id?: number }).document_id;
+  if (documentId != null) {
+    parsedData._vibe_doc_id = documentId;
+  }
+
+  return parsedData as T & { _vibe_doc_id?: number };
+}
+
+/**
+ * Extract and unwrap an array of documents from a Vibe response.
+ *
+ * @param responseData - Raw Vibe API response ({ data: [...] }, { items: [...] }, { documents: [...] } or a bare array)
+ * @returns Array of unwrapped documents
+ */
+export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
+  responseData: unknown
+): Array<T & { _vibe_doc_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 & { _vibe_doc_id?: number } => d !== null);
+}

package/src/vibe/errors.ts

@@ -183,3 +183,27 @@ export class VibeServiceError extends VibeError {
     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/generic.ts

@@ -72,109 +72,17 @@ export function vibeGridPath(collection: string, table: string): string {
 
 // -----------------------------------------------------------------------------
 // DOCUMENT UNWRAPPING
+//
+// PAY-1767: the wrapper type and the two helpers MOVED to ./document-unwrap, so the typed client
+// (client.ts) can unwrap reads without importing this module (which imports client.ts). Re-exported
+// here so every existing `from './generic'` / package import keeps working unchanged.
 // -----------------------------------------------------------------------------
 
-/**
- * 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 schema fields only.
- *          Storage-layer document_id preserved as _vibe_doc_id for update/delete paths.
- *          See PayEz-Core/docs/vibe-primary-key-standard.md
- *
- * @example
- * const raw = { document_id: 123, data: '{"user_id":15,"name":"John","email":"john@example.com"}' };
- * const unwrapped = unwrapVibeDocument(raw);
- * // => { user_id: 15, name: 'John', email: 'john@example.com', _vibe_doc_id: 123 }
- */
-export function unwrapVibeDocument<T extends Record<string, unknown> = Record<string, unknown>>(
-  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
-): (T & { _vibe_doc_id?: number }) | null {
-  if (!doc) return null;
-
-  // Handle case where doc is already unwrapped (has schema fields directly)
-  if (!('document_id' in doc) && !('data' in doc)) {
-    return doc as T & { _vibe_doc_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;
-  }
+export { unwrapVibeDocument, extractVibeDocuments } from './document-unwrap';
+export type { VibeDocumentWrapper } from './document-unwrap';
 
-  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
-  const documentId = wrapper.document_id ?? (doc as any).document_id;
-  if (documentId != null) {
-    parsedData._vibe_doc_id = documentId;
-  }
-
-  return parsedData as T & { _vibe_doc_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 & { _vibe_doc_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 & { _vibe_doc_id?: number } => d !== null);
-}
+import { unwrapVibeDocument, extractVibeDocuments } from './document-unwrap';
+import type { VibeDocumentWrapper } from './document-unwrap';
 
 // -----------------------------------------------------------------------------
 // GENERIC TABLE DELEGATE

package/src/vibe/index.ts

@@ -89,6 +89,7 @@ export {
   VibeRateLimitError,
   VibeConflictError,
   VibeServiceError,
+  VibeBatchCreateError,
 } from './errors';
 
 // Session management exports