@payez/next-mvp 4.4.5 → 4.4.7

package/src/vibe/client.ts

@@ -41,7 +41,11 @@ import {
   VibeError,
   VibeNotFoundError,
   VibeServiceError,
+  VibeValidationError,
+  VibeBatchCreateError,
 } from './errors';
+import { unwrapVibeDocument, extractVibeDocuments } from './document-unwrap';
+import type { VibeDocumentWrapper } from './document-unwrap';
 import type {
   VibeMeta,
   VibeResponse,
@@ -69,7 +73,13 @@ export interface VibeRetryConfig {
 }
 
 export interface VibeClientConfig {
-  /** Base URL for the Vibe API (defaults to VIBE_API_URL env var) */
+  /**
+   * Base URL for the Vibe API (defaults to VIBE_API_URL env var).
+   *
+   * PAY-1767: proxy mode does NOT need this. Every request is sent to the IDP proxy as an endpoint
+   * PATH (`/v1/collections/...`), which is what the proxy validates and signs - it never builds a
+   * Vibe URL from this value. It is retained only for compatibility with consumers that still read it.
+   */
   baseUrl?: string;
   /** Vibe Client ID (defaults to VIBE_CLIENT_ID env var) */
   clientId?: string;
@@ -84,6 +94,15 @@ export interface VibeClientConfig {
    * When set, requests are routed through the IDP proxy instead of directly to Vibe.
    */
   appSigningKey?: string;
+  /**
+   * PAY-1767: which COLLECTION the table delegates address (defaults to VIBE_COLLECTION, then 'vibe_app').
+   *
+   * The Vibe API route is `/v1/collections/{collection}/tables/{table}`. This client used to hardcode
+   * `/api/v1/vibe_app/{table}` - a collection baked into the path with no route behind it. Pin the
+   * collection explicitly at the call site when your tables do not live in `vibe_app` (the UMI
+   * VIBE_COLLECTION-double-duty lesson, POST-INSTALL.md item 16).
+   */
+  collection?: string;
   /** Custom fetch function (for testing or custom auth) */
   fetch?: typeof fetch;
   /** Retry configuration for transient errors */
@@ -121,7 +140,13 @@ export interface FindManyOptions<T> {
   skip?: number;
 }
 
-/** Options for findUnique */
+/**
+ * Options for findUnique.
+ *
+ * PAY-1767 (NightHawk 64534 MUST 2): `where.id` is the DOCUMENT id - the storage-layer primary key the
+ * route constrains (`{id:int}`), NOT a row's own `id` column. The unwrapped row exposes it as
+ * `_vibe_doc_id`; use THAT value for a subsequent update/delete.
+ */
 export interface FindUniqueOptions {
   where: { id: number };
 }
@@ -131,13 +156,15 @@ export interface CreateOptions<T> {
   data: Omit<T, 'id' | 'created_at' | 'updated_at'>;
 }
 
-/** Options for update */
+/**
+ * Options for update. `where.id` is the DOCUMENT id (see FindUniqueOptions), not a row's own id column.
+ */
 export interface UpdateOptions<T> {
   where: { id: number };
   data: Partial<Omit<T, 'id' | 'created_at' | 'updated_at'>>;
 }
 
-/** Options for delete */
+/** Options for delete. `where.id` is the DOCUMENT id (see FindUniqueOptions). */
 export interface DeleteOptions {
   where: { id: number };
 }
@@ -150,6 +177,11 @@ export interface CountOptions<T> {
 /** Result of findMany with metadata */
 export interface FindManyResult<T> {
   data: T[];
+  /**
+   * PAY-1767 (NightHawk 64552 item B): true when `data` is a PAGE of a larger population. Read from Core's
+   * `pagination.totalCount`; a caller must not treat `data.length` as the table's size.
+   */
+  hasMore?: boolean;
   meta: VibeMeta;
 }
 
@@ -164,6 +196,93 @@ const DEFAULT_RETRY_CONFIG: Required<VibeRetryConfig> = {
   retryOnRateLimit: true,
 };
 
+/**
+ * PAY-1767: the most records `createMany` will create in one call. It is per-record and NOT atomic, so a
+ * ceiling bounds the blast radius of a partial failure. 50 is the house's only batch ceiling (Vibe's own
+ * DecryptController BATCH_TOO_LARGE = 50).
+ */
+export const MAX_BATCH_CREATE_ROWS = 50;
+
+/**
+ * PAY-1767: the default page size findMany asks the query route for. Core clamps pageSize/limit to 100
+ * (DocumentsController.Query), so this is the most one call returns.
+ */
+export const MAX_FIND_MANY_PAGE_SIZE = 100;
+
+/**
+ * PAY-1767: the body POST /v1/collections/{c}/tables/{t}/query binds (Core QueryRequest). `filter` is a
+ * VibeFilterNode OBJECT - `{ "<field>": { "<operator>": value } }` - NOT the array sessions.ts sends.
+ */
+interface QueryRequestBody {
+  filter?: Record<string, unknown>;
+  orderBy?: Record<string, string>;
+  page: number;
+  pageSize: number;
+  /** QueryRequest.Limit is an alias for PageSize; findMany sets it so take:0 means count-only. */
+  limit?: number;
+}
+
+/** The operators Core's VibeQueryBuilder accepts, from VibeOperators.All. */
+const VIBE_OPERATORS = new Set(['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'isNull', 'isNotNull', 'ilike']);
+
+/**
+ * PAY-1767: map a Prisma-style `where` to Core's VibeFilterNode OBJECT.
+ *
+ *   { status: 'active' }            -> { 'status': { eq: 'active' } }
+ *   { score: { gt: 5 } }            -> { 'score': { gt: 5 } }
+ *   { status: 'a', tier: { in: [] } } -> { AND: [ {status:{eq:'a'}}, {tier:{in:[]}} ] }
+ *
+ * A field name is used as-is: a top-level document column (document_id, created_at...) or a JSONB path
+ * (Core treats an unknown name as data->>'name'; a nested path like 'data.x' is honoured explicitly).
+ * An unknown OPERATOR throws - dropping an operator would widen the result silently.
+ */
+export function buildVibeFilter(where: Record<string, unknown>, table: string): Record<string, unknown> {
+  const leaves: Record<string, unknown>[] = [];
+
+  for (const [field, value] of Object.entries(where)) {
+    if (value === undefined) continue;
+
+    const conditions: Record<string, unknown> = {};
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      for (const [op, val] of Object.entries(value as Record<string, unknown>)) {
+        if (!VIBE_OPERATORS.has(op)) {
+          throw new VibeValidationError(
+            `where.${field} uses unsupported operator '${op}'. Core accepts: ${[...VIBE_OPERATORS].join(', ')}.`,
+            { table, field, operator: op },
+          );
+        }
+        conditions[op] = val;
+      }
+      if (Object.keys(conditions).length === 0) {
+        throw new VibeValidationError(`where.${field} has no operator`, { table, field });
+      }
+    } else if (Array.isArray(value)) {
+      // SHOULD (NightHawk 64610): a bare array is a set membership, NOT equality. `{ id: [1,2] }` as
+      // eq:[1,2] compares a scalar to an array and matches nothing; map it to Core's `in`.
+      conditions.in = value;
+    } else if (value === null) {
+      // SHOULD (NightHawk 64610): `{ x: null }` as eq:null compares against JSON null; Core has a dedicated
+      // isNull operator, so map it rather than emit an equality that silently misses.
+      conditions.isNull = true;
+    } else {
+      // A bare value is equality.
+      conditions.eq = value;
+    }
+    leaves.push({ [field]: conditions });
+  }
+
+  if (leaves.length === 0) return {};
+  if (leaves.length === 1) return leaves[0];
+  // Multiple fields default to AND (Core's VibeFilterNode AND group).
+  return { AND: leaves };
+}
+
+/** Read the total from whichever pagination shape Core returned (DocumentListResponse.pagination). */
+function readPaginationTotal(response: VibeResponse<unknown>): number | undefined {
+  const r = response as unknown as { pagination?: { totalCount?: number; total?: number }; meta?: { total?: number } };
+  return r.pagination?.totalCount ?? r.pagination?.total ?? r.meta?.total;
+}
+
 /** Sleep for a given number of milliseconds */
 function sleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -196,63 +315,117 @@ export class VibeTableDelegate<T extends VibeTableName> {
   }
 
   /**
-   * Find multiple records with optional filtering and pagination.
+   * PAY-1767: the Vibe API route for this table's document collection.
+   * `/v1/collections/{collection}/tables/{table}` (Core DocumentsController.cs:15) - the same shape
+   * generic.ts and sessions.ts already use. The OLD `/api/v1/vibe_app/{table}` had no route behind it.
+   */
+  private tableEndpoint(id?: number | string): string {
+    return this.client.tableEndpoint(this.tableName, id);
+  }
+
+  /**
+   * Find multiple records, WITH filtering, sorting and paging honoured.
+   *
+   * PAY-1767 (NightHawk 64534 MUST 1, QAPert 64530, BAPert 64535). The GET list route
+   * (`GET /v1/collections/{c}/tables/{t}`, Core DocumentsController.List :44-48) binds ONLY `page` and
+   * `pageSize` - it reads no filter, sort or offset, so sending where/orderBy/take/skip there DROPPED them
+   * silently. Through the proxy that is worse than loud: a proxied MVP service account is ADMIN mode
+   * (HasValidContext), so the ownership filter is bypassed and an unfiltered page is 20 ARBITRARY rows of
+   * the tenant - caller code doing `rows[0]` gets the WRONG record with no error.
+   *
+   * So this now goes to `POST .../tables/{t}/query`, which binds QueryRequest (Filter / OrderBy / Page /
+   * PageSize / Limit). The FILTER is a VibeFilterNode OBJECT - `{ "<field>": { "<op>": value } }` - NOT the
+   * filter ARRAY that sessions.ts sends: QueryRequest.Filter is typed VibeFilterNode, which has no array
+   * form (measured at Core origin/master; CliInitProjectService.cs:197 builds the same object shape). An
+   * unmappable option THROWS rather than being dropped.
    */
   async findMany(options?: FindManyOptions<VibeTableType<T>>): Promise<FindManyResult<VibeTableType<T>>> {
-    const params = new URLSearchParams();
-
-    // Build filter params
-    if (options?.where) {
-      for (const [key, value] of Object.entries(options.where)) {
-        if (value !== undefined) {
-          if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            // Handle operator objects (e.g., { gt: 5 }, { in: [1,2,3] })
-            for (const [op, val] of Object.entries(value)) {
-              if (Array.isArray(val)) {
-                // Handle array values for in/nin operators
-                val.forEach(v => params.append(`filter[${key}][${op}][]`, String(v)));
-              } else {
-                params.append(`filter[${key}][${op}]`, String(val));
-              }
-            }
-          } else if (Array.isArray(value)) {
-            // Handle direct array values
-            value.forEach(v => params.append(`filter[${key}][]`, String(v)));
-          } else {
-            params.append(`filter[${key}]`, String(value));
-          }
-        }
+    const body = this.buildQueryBody(options);
+    const endpoint = `${this.tableEndpoint()}/query`;
+
+    const response = await this.client.request<VibeDocumentWrapper[]>(endpoint, 'POST', body);
+    // MUST 2: the rows come back as document WRAPPERS; unwrap to the row's own fields.
+    const rows = extractVibeDocuments(response.data) as unknown as VibeTableType<T>[];
+    // item B (NightHawk 64552): the TRUE population is Core's pagination.totalCount, NOT a page size.
+    const total = readPaginationTotal(response) ?? rows.length;
+    const limit = body.limit ?? body.pageSize;
+
+    const offset = (body.page - 1) * limit;
+    return {
+      data: rows,
+      // item B: `hasMore` so a caller cannot mistake a page for the whole table.
+      // MUST 2 (NightHawk 64610): it must account for the OFFSET - on the last page `rows.length < total`
+      // was still true, so a caller paging until hasMore is false never stopped.
+      hasMore: offset + rows.length < total,
+      meta: { total, limit, offset },
+    };
+  }
+
+  /**
+   * PAY-1767: map the Prisma-style findMany options onto Core's QueryRequest body. THROWS on anything the
+   * query endpoint cannot express, so nothing is silently dropped.
+   */
+  private buildQueryBody(options?: FindManyOptions<VibeTableType<T>>): QueryRequestBody {
+    const body: QueryRequestBody = { page: 1, pageSize: MAX_FIND_MANY_PAGE_SIZE };
+
+    if (options?.where && Object.keys(options.where).length > 0) {
+      body.filter = buildVibeFilter(options.where, this.tableName);
+    }
+
+    if (options?.orderBy && Object.keys(options.orderBy).length > 0) {
+      const orderBy: Record<string, string> = {};
+      for (const [field, dir] of Object.entries(options.orderBy)) {
+        orderBy[field] = dir === 'desc' ? 'desc' : 'asc';
       }
+      body.orderBy = orderBy;
     }
 
-    // Pagination
     if (options?.take !== undefined) {
-      params.append('limit', String(options.take));
-    }
-    if (options?.skip !== undefined) {
-      params.append('offset', String(options.skip));
+      if (!Number.isInteger(options.take) || options.take < 0) {
+        throw new VibeValidationError(`take must be a non-negative integer (got ${options.take})`, { table: this.tableName });
+      }
+      // MUST 1 (NightHawk 64610): Core CLAMPS pageSize to 100 (DocumentsController.Query:
+      // `if (pageSize > 100) pageSize = 100`), so take > 100 would return 100 rows while meta.limit claimed
+      // the larger size - and a skip computed from a 250 size would land on Core's page 2 of size 100
+      // (rows 100-199), not rows 250-499. Refuse it rather than return the wrong rows silently.
+      if (options.take > MAX_FIND_MANY_PAGE_SIZE) {
+        throw new VibeValidationError(
+          `take ${options.take} exceeds the maximum page size ${MAX_FIND_MANY_PAGE_SIZE}; the query endpoint ` +
+          `CLAMPS pageSize to ${MAX_FIND_MANY_PAGE_SIZE}, so a larger take returns a short page while ` +
+          `reporting the larger limit. Page with take ${MAX_FIND_MANY_PAGE_SIZE} and a skip multiple.`,
+          { table: this.tableName, take: options.take, max: MAX_FIND_MANY_PAGE_SIZE },
+        );
+      }
+      body.limit = options.take;
+      body.pageSize = options.take === 0 ? 0 : options.take;
     }
 
-    // Sorting
-    if (options?.orderBy) {
-      const sortParts: string[] = [];
-      for (const [key, dir] of Object.entries(options.orderBy)) {
-        sortParts.push(dir === 'desc' ? `-${key}` : key);
+    if (options?.skip !== undefined) {
+      if (!Number.isInteger(options.skip) || options.skip < 0) {
+        throw new VibeValidationError(`skip must be a non-negative integer (got ${options.skip})`, { table: this.tableName });
       }
-      if (sortParts.length > 0) {
-        params.append('sort', sortParts.join(','));
+      // The query endpoint PAGES (page + pageSize); it cannot express a bare row offset. A skip that is a
+      // whole number of pages can be expressed exactly; anything else would return rows BEFORE the offset
+      // and look correct. Refuse it.
+      const size = body.limit ?? body.pageSize;
+      if (body.limit === undefined && options.take === undefined && options.skip % size !== 0) {
+        throw new VibeValidationError(
+          `skip ${options.skip} is not a multiple of the default page size ${size}; pass a take so the page ` +
+          `size is explicit, or use a multiple (the query endpoint pages, it has no bare offset)`,
+          { table: this.tableName, skip: options.skip },
+        );
       }
+      if (size <= 0 || options.skip % size !== 0) {
+        throw new VibeValidationError(
+          `skip ${options.skip} cannot be expressed as a page of size ${size} (the query endpoint pages; ` +
+          `skip must be a multiple of take)`,
+          { table: this.tableName, skip: options.skip, take: options.take },
+        );
+      }
+      body.page = options.skip / size + 1;
     }
 
-    const queryString = params.toString();
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}${queryString ? `?${queryString}` : ''}`;
-
-    const response = await this.client.request<VibeTableType<T>[]>(url, 'GET');
-
-    return {
-      data: response.data,
-      meta: response.meta || { total: response.data.length, limit: options?.take || 50, offset: options?.skip || 0 },
-    };
+    return body;
   }
 
   /**
@@ -260,9 +433,18 @@ export class VibeTableDelegate<T extends VibeTableName> {
    * Throws VibeNotFoundError if not found.
    */
   async findUnique(options: FindUniqueOptions): Promise<VibeTableType<T>> {
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-    const response = await this.client.request<VibeTableType<T>>(url, 'GET');
-    return response.data;
+    const endpoint = this.tableEndpoint(options.where.id);
+    const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'GET');
+    // PAY-1767: unwrap the document wrapper so the caller gets the row's own fields.
+    const row = unwrapVibeDocument<VibeTableType<T>>(response.data);
+    if (!row) {
+      throw new VibeNotFoundError(
+        `Document ${options.where.id} not found in ${this.tableName}`,
+        'NOT_FOUND',
+        { table: this.tableName, id: options.where.id },
+      );
+    }
+    return row as VibeTableType<T>;
   }
 
   /**
@@ -281,11 +463,15 @@ export class VibeTableDelegate<T extends VibeTableName> {
   }
 
   /**
-   * Find the first record matching the filter.
+   * Find the first record.
    * Returns null if none found.
+   *
+   * PAY-1767: takes the first row of the (caller-owned, created_at-ordered) list. Any where/orderBy in
+   * `options` is passed through to findMany, which REFUSES them on this route rather than dropping them,
+   * so this cannot pretend to filter.
    */
   async findFirst(options?: FindManyOptions<VibeTableType<T>>): Promise<VibeTableType<T> | null> {
-    const result = await this.findMany({ ...options, take: 1 });
+    const result = await this.findMany(options);
     return result.data[0] || null;
   }
 
@@ -293,9 +479,10 @@ export class VibeTableDelegate<T extends VibeTableName> {
    * Create a new record.
    */
   async create(options: CreateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}`;
-    const response = await this.client.request<VibeTableType<T>>(url, 'POST', options.data);
-    return response.data;
+    const endpoint = this.tableEndpoint();
+    const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'POST', options.data);
+    // SHOULD (NightHawk 64534): unwrap; a success with no data THROWS rather than returning {} typed as a row.
+    return this.requireRow(response.data, 'create');
   }
 
   /**
@@ -303,43 +490,93 @@ export class VibeTableDelegate<T extends VibeTableName> {
    * Throws VibeNotFoundError if not found.
    */
   async update(options: UpdateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-    const response = await this.client.request<VibeTableType<T>>(url, 'PUT', options.data);
-    return response.data;
+    const endpoint = this.tableEndpoint(options.where.id);
+    const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'PUT', options.data);
+    return this.requireRow(response.data, 'update');
   }
 
   /**
    * Delete a record by ID (soft delete).
    * Throws VibeNotFoundError if not found.
+   *
+   * PAY-1767 (NightHawk 64578 item 2): Core answers DELETE with **204 No Content** (DocumentsController
+   * Delete returns NoContent()), so a SUCCESSFUL delete carries NO document - and there is none to unwrap.
+   * This must therefore NOT go through requireRow (that is the create/update rule: "a success WITH no
+   * document throws"). A 2xx with no body is the success here; the request layer already resolves it to an
+   * empty success. Returns null when the server sent no document.
    */
-  async delete(options: DeleteOptions): Promise<VibeTableType<T>> {
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-    const response = await this.client.request<VibeTableType<T>>(url, 'DELETE');
-    return response.data;
+  async delete(options: DeleteOptions): Promise<VibeTableType<T> | null> {
+    const endpoint = this.tableEndpoint(options.where.id);
+    const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'DELETE');
+    return response?.data ? (unwrapVibeDocument<VibeTableType<T>>(response.data) as VibeTableType<T>) : null;
+  }
+
+  /** Unwrap a single-document response, or THROW - never return an empty object typed as a row. */
+  private requireRow(wire: VibeDocumentWrapper | undefined, op: string): VibeTableType<T> {
+    const row = wire ? unwrapVibeDocument<VibeTableType<T>>(wire) : null;
+    if (!row) {
+      throw new VibeNotFoundError(
+        `${op} on ${this.tableName} returned no document data`,
+        'NOT_FOUND',
+        { table: this.tableName, op },
+      );
+    }
+    return row as VibeTableType<T>;
   }
 
   /**
    * Count records matching the filter.
+   *
+   * PAY-1767 (NightHawk 64534): goes to POST /query with limit:0, which is Core's COUNT-ONLY mode
+   * (DocumentsController.Query returns an empty Data array plus Pagination.TotalCount). So this is the
+   * true population of the filter, not the first page's size.
    */
   async count(options?: CountOptions<VibeTableType<T>>): Promise<number> {
-    // Use findMany with limit 0 to get just the count
-    const result = await this.findMany({ ...options, take: 0 });
-    return result.meta.total;
+    const body = this.buildQueryBody({ where: options?.where, take: 0 } as FindManyOptions<VibeTableType<T>>);
+    const endpoint = `${this.tableEndpoint()}/query`;
+    const response = await this.client.request<VibeDocumentWrapper[]>(endpoint, 'POST', body);
+    return readPaginationTotal(response) ?? 0;
   }
 
   /**
-   * Create multiple records in a batch.
+   * Create multiple records.
+   *
+   * PAY-1767: the old path `/api/v1/vibe_app/batch` has no route (there is no documents batch endpoint in
+   * Core's Vibe Public API), so this CANNOT be atomic here. Until a Core batch route exists, this creates
+   * each record against the REAL table endpoint in turn.
+   *
+   * BOUNDED ON PURPOSE (BAPert 64527). Non-atomic is tolerable only while the blast radius is small, so a
+   * request above MAX_BATCH_CREATE_ROWS is REFUSED before anything is sent. 50 matches the house's only
+   * batch ceiling (Vibe's DecryptController BATCH_TOO_LARGE).
+   *
+   * PARTIAL FAILURE IS REPORTED, NOT SWALLOWED (NightHawk 64534 condition (a)). A failure at item k throws
+   * a VibeBatchCreateError that CARRIES the count and the document ids already created - a cap cannot fix
+   * partial failure, only reporting it can. The created rows are unwrapped (MUST 2) so their own fields are
+   * present, not the wrapper's.
    */
-  async createMany(options: { data: CreateOptions<VibeTableType<T>>['data'][] }): Promise<{ count: number }> {
-    const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/batch`;
-    const response = await this.client.request<{ count: number }>(url, 'POST', {
-      operations: options.data.map(item => ({
-        table: this.tableName,
-        operation: 'create',
-        data: item,
-      })),
-    });
-    return response.data;
+  async createMany(options: { data: CreateOptions<VibeTableType<T>>['data'][] }): Promise<{ count: number; ids: Array<number | string> }> {
+    if (options.data.length > MAX_BATCH_CREATE_ROWS) {
+      throw new VibeServiceError(
+        `createMany accepts at most ${MAX_BATCH_CREATE_ROWS} records per call (got ${options.data.length}); ` +
+        `it is NOT atomic, so a larger batch could leave a partial write`,
+      );
+    }
+    const endpoint = this.tableEndpoint();
+    const created: Array<number | string> = [];
+    for (let i = 0; i < options.data.length; i++) {
+      try {
+        const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'POST', options.data[i]);
+        const row = unwrapVibeDocument<{ _vibe_doc_id?: number | string }>(response.data);
+        if (row?._vibe_doc_id != null) created.push(row._vibe_doc_id);
+      } catch (err) {
+        throw new VibeBatchCreateError(
+          `createMany created ${created.length} of ${options.data.length} records before failing at index ${i}`,
+          { createdCount: created.length, createdIds: created, failedIndex: i, total: options.data.length },
+          err,
+        );
+      }
+    }
+    return { count: created.length, ids: created };
   }
 }
 
@@ -357,6 +594,8 @@ export class VibeClient {
     clientId: string;
     idpUrl: string;
     appSigningKey: string;
+    /** PAY-1767: the collection the table delegates address. */
+    collection: string;
     fetch: typeof fetch;
     retry: Required<VibeRetryConfig>;
   };
@@ -379,6 +618,9 @@ export class VibeClient {
       clientId: config.clientId || process.env.VIBE_CLIENT_ID || '',
       idpUrl: config.idpUrl || process.env.IDP_URL || '',
       appSigningKey: config.appSigningKey || process.env.VIBE_HMAC_KEY || '',
+      // PAY-1767: which collection the table delegates address. Library default is correct ('vibe_app');
+      // pinning it per-call avoids the VIBE_COLLECTION-global-retarget trap (POST-INSTALL.md item 16).
+      collection: config.collection || process.env.VIBE_COLLECTION || 'vibe_app',
       fetch: config.fetch || globalThis.fetch,
       retry: { ...DEFAULT_RETRY_CONFIG, ...config.retry },
     };
@@ -431,20 +673,30 @@ export class VibeClient {
     }
   }
 
+  /**
+   * PAY-1767: the Vibe API endpoint PATH for a table in this client's collection.
+   * `/v1/collections/{collection}/tables/{table}[/{id}]` - what the IDP proxy validates, signs and forwards.
+   * Returned as a PATH, not a URL: proxy mode needs no VIBE_API_URL (the proxy owns the base).
+   */
+  tableEndpoint(table: string, id?: number | string): string {
+    const base = `/v1/collections/${this.config.collection}/tables/${table}`;
+    return id === undefined ? base : `${base}/${id}`;
+  }
+
   /**
    * Make a request through the IDP Vibe proxy.
    * The proxy handles credential injection securely.
+   *
+   * PAY-1767: `endpoint` is the RAW path (+query) to forward. It is what gets signed and sent, so this
+   * takes a path directly rather than parsing one out of a URL - proxy mode is complete without a Vibe
+   * base URL, which is exactly what an endpoint-path call needs.
    */
   private async requestViaProxy<T>(
-    url: string,
+    endpoint: string,
     method: 'GET' | 'POST' | 'PUT' | 'DELETE',
     body?: unknown,
     authToken?: string
   ): Promise<VibeResponse<T>> {
-    // Extract the endpoint path from the full URL
-    const urlObj = new URL(url);
-    const endpoint = urlObj.pathname + urlObj.search;
-
     const timestamp = Math.floor(Date.now() / 1000);
     const signature = await this.generateProxySignature(timestamp, method, endpoint);
 
@@ -462,10 +714,12 @@ export class VibeClient {
       headers['Authorization'] = `Bearer ${authToken}`;
     }
 
+    // PAY-1767: the proxy binds Endpoint / Method / Data (Core VibeProxyController :376-391), so a write
+    // goes out as `data` - sending `body` (as this used to) arrived as data:null.
     const proxyBody = {
       method,
       endpoint,
-      ...(body !== undefined && { body }),
+      ...(body !== undefined && { data: body }),
     };
 
     const response = await this.config.fetch(proxyUrl, {
@@ -479,9 +733,30 @@ export class VibeClient {
       throw VibeError.fromResponse(errorBody, response.status);
     }
 
-    const responseData = await response.json();
+    // PAY-1767 (NightHawk 64578 item 2): a 204 No Content (or any 2xx with an EMPTY body) is a SUCCESS with
+    // no payload - e.g. a successful DELETE. Parsing it as JSON throws, which surfaced a successful delete as
+    // an error. Return an empty success here; this is distinct from the SHOULD rule (that one throws when a
+    // create/update answers success but carries NO DOCUMENT), which lives in the delegates.
+    if (response.status === 204) {
+      return { success: true } as unknown as VibeResponse<T>;
+    }
+    const raw = await response.text();
+    if (raw.trim() === '') {
+      return { success: true } as unknown as VibeResponse<T>;
+    }
 
-    if (!responseData.success) {
+    let responseData: unknown;
+    try {
+      responseData = JSON.parse(raw);
+    } catch {
+      // A non-empty 2xx body that is not JSON is not a shape we can trust - fail rather than pretend.
+      throw new VibeServiceError(
+        `Vibe API answered ${response.status} with a body that is not JSON`,
+        { status: response.status, bodyLength: raw.length },
+      );
+    }
+
+    if (!(responseData as VibeResponse<T>).success) {
       throw VibeError.fromResponse(responseData as VibeErrorResponse, response.status);
     }
 
@@ -501,6 +776,10 @@ export class VibeClient {
    * Routing:
    * - All requests route through the IDP proxy (requires VIBE_HMAC_KEY + IDP_URL)
    *
+   * PAY-1767: `urlOrPath` is EITHER a full URL or a bare Vibe path ('/v1/collections/...'). Proxy mode
+   * signs and forwards the PATH either way, so a caller with only a path (the table delegates) needs no
+   * Vibe base URL - VIBE_API_URL is not required to make a proxied call.
+   *
    * Retry behavior:
    * - 5xx errors: Retry up to maxRetries times with exponential backoff
    * - 429 errors: Retry once after Retry-After delay (if retryOnRateLimit enabled)
@@ -508,7 +787,7 @@ export class VibeClient {
    * - Network errors: Retry with backoff
    */
   async request<T>(
-    url: string,
+    urlOrPath: string,
     method: 'GET' | 'POST' | 'PUT' | 'DELETE',
     body?: unknown,
     authToken?: string
@@ -525,8 +804,13 @@ export class VibeClient {
       if (!this.config.appSigningKey) {
         throw new VibeServiceError('VIBE_HMAC_KEY is not configured (required for proxy mode)');
       }
+      // PAY-1767: a bare path is used as-is; a full URL is reduced to its path+query. Both sign identically.
+      const endpoint = urlOrPath.startsWith('/') ? urlOrPath : (() => {
+        const u = new URL(urlOrPath);
+        return u.pathname + u.search;
+      })();
       // Route through IDP proxy
-      return this.requestViaProxy<T>(url, method, body, authToken);
+      return this.requestViaProxy<T>(endpoint, method, body, authToken);
     }
 
     // MVP requires proxy mode - direct Vibe access is not supported
@@ -556,10 +840,13 @@ export class VibeClient {
 
   /**
    * Fetch the schema for type generation.
+   *
+   * PAY-1767: the old path `/api/v1/vibe_app/schema` has no route. The real per-collection schema route is
+   * `/v1/mvp/schemas/{collection}` (Core MvpSchemaController.cs:65). Returns the collection schema DTO.
    */
-  async getSchema(): Promise<Record<string, { columns: Array<{ name: string; type: string; nullable: boolean }> }>> {
-    const url = `${this.config.baseUrl}/api/v1/vibe_app/schema`;
-    const response = await this.request<Record<string, { columns: Array<{ name: string; type: string; nullable: boolean }> }>>(url, 'GET');
+  async getSchema(): Promise<Record<string, unknown>> {
+    const endpoint = `/v1/mvp/schemas/${this.config.collection}`;
+    const response = await this.request<Record<string, unknown>>(endpoint, 'GET');
     return response.data;
   }
 }