@payez/next-mvp 4.4.6 → 4.4.8

package/dist/vibe/client.js

@@ -71,9 +71,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.vibe = exports.VibeClient = exports.VibeTableDelegate = void 0;
+exports.vibe = exports.VibeClient = exports.VibeTableDelegate = exports.MAX_FIND_MANY_PAGE_SIZE = exports.MAX_BATCH_CREATE_ROWS = void 0;
+exports.buildVibeFilter = buildVibeFilter;
 exports.createVibeClient = createVibeClient;
 const errors_1 = require("./errors");
+const document_unwrap_1 = require("./document-unwrap");
 // -----------------------------------------------------------------------------
 // RETRY HELPERS
 // -----------------------------------------------------------------------------
@@ -83,6 +85,75 @@ const DEFAULT_RETRY_CONFIG = {
     maxDelay: 10000,
     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).
+ */
+exports.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.
+ */
+exports.MAX_FIND_MANY_PAGE_SIZE = 100;
+/** 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.
+ */
+function buildVibeFilter(where, table) {
+    const leaves = [];
+    for (const [field, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        const conditions = {};
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            for (const [op, val] of Object.entries(value)) {
+                if (!VIBE_OPERATORS.has(op)) {
+                    throw new errors_1.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 errors_1.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) {
+    const r = response;
+    return r.pagination?.totalCount ?? r.pagination?.total ?? r.meta?.total;
+}
 /** Sleep for a given number of milliseconds */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
@@ -110,69 +181,113 @@ class VibeTableDelegate {
         this.client = client;
     }
     /**
-     * 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.
+     */
+    tableEndpoint(id) {
+        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) {
-        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(endpoint, 'POST', body);
+        // MUST 2: the rows come back as document WRAPPERS; unwrap to the row's own fields.
+        const rows = (0, document_unwrap_1.extractVibeDocuments)(response.data);
+        // 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.
+     */
+    buildQueryBody(options) {
+        const body = { page: 1, pageSize: exports.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 = {};
+            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 (!Number.isInteger(options.take) || options.take < 0) {
+                throw new errors_1.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 > exports.MAX_FIND_MANY_PAGE_SIZE) {
+                throw new errors_1.VibeValidationError(`take ${options.take} exceeds the maximum page size ${exports.MAX_FIND_MANY_PAGE_SIZE}; the query endpoint ` +
+                    `CLAMPS pageSize to ${exports.MAX_FIND_MANY_PAGE_SIZE}, so a larger take returns a short page while ` +
+                    `reporting the larger limit. Page with take ${exports.MAX_FIND_MANY_PAGE_SIZE} and a skip multiple.`, { table: this.tableName, take: options.take, max: exports.MAX_FIND_MANY_PAGE_SIZE });
+            }
+            body.limit = options.take;
+            body.pageSize = options.take === 0 ? 0 : options.take;
         }
         if (options?.skip !== undefined) {
-            params.append('offset', String(options.skip));
-        }
-        // Sorting
-        if (options?.orderBy) {
-            const sortParts = [];
-            for (const [key, dir] of Object.entries(options.orderBy)) {
-                sortParts.push(dir === 'desc' ? `-${key}` : key);
+            if (!Number.isInteger(options.skip) || options.skip < 0) {
+                throw new errors_1.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 errors_1.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 errors_1.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(url, 'GET');
-        return {
-            data: response.data,
-            meta: response.meta || { total: response.data.length, limit: options?.take || 50, offset: options?.skip || 0 },
-        };
+        return body;
     }
     /**
      * Find a single record by ID.
      * Throws VibeNotFoundError if not found.
      */
     async findUnique(options) {
-        const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-        const response = await this.client.request(url, 'GET');
-        return response.data;
+        const endpoint = this.tableEndpoint(options.where.id);
+        const response = await this.client.request(endpoint, 'GET');
+        // PAY-1767: unwrap the document wrapper so the caller gets the row's own fields.
+        const row = (0, document_unwrap_1.unwrapVibeDocument)(response.data);
+        if (!row) {
+            throw new errors_1.VibeNotFoundError(`Document ${options.where.id} not found in ${this.tableName}`, 'NOT_FOUND', { table: this.tableName, id: options.where.id });
+        }
+        return row;
     }
     /**
      * Find a single record by ID.
@@ -190,60 +305,106 @@ class VibeTableDelegate {
         }
     }
     /**
-     * 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) {
-        const result = await this.findMany({ ...options, take: 1 });
+        const result = await this.findMany(options);
         return result.data[0] || null;
     }
     /**
      * Create a new record.
      */
     async create(options) {
-        const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}`;
-        const response = await this.client.request(url, 'POST', options.data);
-        return response.data;
+        const endpoint = this.tableEndpoint();
+        const response = await this.client.request(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');
     }
     /**
      * Update an existing record by ID.
      * Throws VibeNotFoundError if not found.
      */
     async update(options) {
-        const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-        const response = await this.client.request(url, 'PUT', options.data);
-        return response.data;
+        const endpoint = this.tableEndpoint(options.where.id);
+        const response = await this.client.request(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) {
-        const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/${this.tableName}/${options.where.id}`;
-        const response = await this.client.request(url, 'DELETE');
-        return response.data;
+        const endpoint = this.tableEndpoint(options.where.id);
+        const response = await this.client.request(endpoint, 'DELETE');
+        return response?.data ? (0, document_unwrap_1.unwrapVibeDocument)(response.data) : null;
+    }
+    /** Unwrap a single-document response, or THROW - never return an empty object typed as a row. */
+    requireRow(wire, op) {
+        const row = wire ? (0, document_unwrap_1.unwrapVibeDocument)(wire) : null;
+        if (!row) {
+            throw new errors_1.VibeNotFoundError(`${op} on ${this.tableName} returned no document data`, 'NOT_FOUND', { table: this.tableName, op });
+        }
+        return row;
     }
     /**
      * 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) {
-        // 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 });
+        const endpoint = `${this.tableEndpoint()}/query`;
+        const response = await this.client.request(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) {
-        const url = `${this.client.getBaseUrl()}/api/v1/vibe_app/batch`;
-        const response = await this.client.request(url, 'POST', {
-            operations: options.data.map(item => ({
-                table: this.tableName,
-                operation: 'create',
-                data: item,
-            })),
-        });
-        return response.data;
+        if (options.data.length > exports.MAX_BATCH_CREATE_ROWS) {
+            throw new errors_1.VibeServiceError(`createMany accepts at most ${exports.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 = [];
+        for (let i = 0; i < options.data.length; i++) {
+            try {
+                const response = await this.client.request(endpoint, 'POST', options.data[i]);
+                const row = (0, document_unwrap_1.unwrapVibeDocument)(response.data);
+                if (row?._vibe_doc_id != null)
+                    created.push(row._vibe_doc_id);
+            }
+            catch (err) {
+                throw new errors_1.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 };
     }
 }
 exports.VibeTableDelegate = VibeTableDelegate;
@@ -273,6 +434,9 @@ 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 },
         };
@@ -315,14 +479,24 @@ class VibeClient {
             return crypto.createHmac('sha256', keyBuffer).update(message).digest('base64');
         }
     }
+    /**
+     * 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, id) {
+        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.
      */
-    async requestViaProxy(url, method, body, authToken) {
-        // Extract the endpoint path from the full URL
-        const urlObj = new URL(url);
-        const endpoint = urlObj.pathname + urlObj.search;
+    async requestViaProxy(endpoint, method, body, authToken) {
         const timestamp = Math.floor(Date.now() / 1000);
         const signature = await this.generateProxySignature(timestamp, method, endpoint);
         const proxyUrl = `${this.config.idpUrl}/api/vibe/proxy`;
@@ -336,10 +510,12 @@ class VibeClient {
         if (authToken) {
             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, {
             method: 'POST',
@@ -350,7 +526,25 @@ class VibeClient {
             const errorBody = await this.parseErrorResponse(response);
             throw errors_1.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 };
+        }
+        const raw = await response.text();
+        if (raw.trim() === '') {
+            return { success: true };
+        }
+        let responseData;
+        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 errors_1.VibeServiceError(`Vibe API answered ${response.status} with a body that is not JSON`, { status: response.status, bodyLength: raw.length });
+        }
         if (!responseData.success) {
             throw errors_1.VibeError.fromResponse(responseData, response.status);
         }
@@ -368,13 +562,17 @@ 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)
      * - 401/403 errors: No retry (auth errors)
      * - Network errors: Retry with backoff
      */
-    async request(url, method, body, authToken) {
+    async request(urlOrPath, method, body, authToken) {
         if (!this.config.clientId) {
             throw new errors_1.VibeServiceError('VIBE_CLIENT_ID is not configured');
         }
@@ -386,8 +584,13 @@ class VibeClient {
             if (!this.config.appSigningKey) {
                 throw new errors_1.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(url, method, body, authToken);
+            return this.requestViaProxy(endpoint, method, body, authToken);
         }
         // MVP requires proxy mode - direct Vibe access is not supported
         throw new errors_1.VibeServiceError('Vibe proxy not configured. Set VIBE_HMAC_KEY + IDP_URL for proxy mode.');
@@ -413,10 +616,13 @@ 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() {
-        const url = `${this.config.baseUrl}/api/v1/vibe_app/schema`;
-        const response = await this.request(url, 'GET');
+        const endpoint = `/v1/mvp/schemas/${this.config.collection}`;
+        const response = await this.request(endpoint, 'GET');
         return response.data;
     }
 }

package/dist/vibe/document-unwrap.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare function unwrapVibeDocument<T extends object = Record<string, unknown>>(doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined): (T & {
+    _vibe_doc_id?: number;
+}) | null;
+/**
+ * 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 declare function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(responseData: unknown): Array<T & {
+    _vibe_doc_id?: number;
+}>;

package/dist/vibe/document-unwrap.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapVibeDocument = unwrapVibeDocument;
+exports.extractVibeDocuments = extractVibeDocuments;
+/**
+ * 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 }
+ */
+function unwrapVibeDocument(doc) {
+    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;
+    }
+    const wrapper = doc;
+    let parsedData = {};
+    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.document_id;
+    if (documentId != null) {
+        parsedData._vibe_doc_id = documentId;
+    }
+    return parsedData;
+}
+/**
+ * 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
+ */
+function extractVibeDocuments(responseData) {
+    if (!responseData || typeof responseData !== 'object') {
+        return [];
+    }
+    const data = responseData;
+    // 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(doc))
+        .filter((d) => d !== null);
+}