@payez/next-mvp 4.4.6 → 4.4.8

package/dist/vibe/client.d.ts

@@ -49,7 +49,13 @@ export interface VibeRetryConfig {
     retryOnRateLimit?: boolean;
 }
 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;
@@ -64,6 +70,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 */
@@ -92,7 +107,13 @@ export interface FindManyOptions<T> {
     take?: number;
     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;
@@ -102,14 +123,16 @@ export interface FindUniqueOptions {
 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;
@@ -122,8 +145,36 @@ 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;
 }
+/**
+ * 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 declare 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 declare const MAX_FIND_MANY_PAGE_SIZE = 100;
+/**
+ * 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 declare function buildVibeFilter(where: Record<string, unknown>, table: string): Record<string, unknown>;
 /**
  * Delegate class for table operations.
  * Provides Prisma-style methods for a specific table.
@@ -133,9 +184,33 @@ export declare class VibeTableDelegate<T extends VibeTableName> {
     private client;
     constructor(tableName: T, client: VibeClient);
     /**
-     * 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;
+    /**
+     * 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.
      */
     findMany(options?: FindManyOptions<VibeTableType<T>>): Promise<FindManyResult<VibeTableType<T>>>;
+    /**
+     * 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;
     /**
      * Find a single record by ID.
      * Throws VibeNotFoundError if not found.
@@ -147,8 +222,12 @@ export declare class VibeTableDelegate<T extends VibeTableName> {
      */
     findUniqueOrNull(options: FindUniqueOptions): Promise<VibeTableType<T> | null>;
     /**
-     * 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.
      */
     findFirst(options?: FindManyOptions<VibeTableType<T>>): Promise<VibeTableType<T> | null>;
     /**
@@ -163,19 +242,45 @@ export declare class VibeTableDelegate<T extends VibeTableName> {
     /**
      * 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.
      */
-    delete(options: DeleteOptions): Promise<VibeTableType<T>>;
+    delete(options: DeleteOptions): Promise<VibeTableType<T> | null>;
+    /** Unwrap a single-document response, or THROW - never return an empty object typed as a row. */
+    private requireRow;
     /**
      * 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.
      */
     count(options?: CountOptions<VibeTableType<T>>): Promise<number>;
     /**
-     * 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.
      */
     createMany(options: {
         data: CreateOptions<VibeTableType<T>>['data'][];
     }): Promise<{
         count: number;
+        ids: Array<number | string>;
     }>;
 }
 /**
@@ -205,9 +310,19 @@ export declare class VibeClient {
      * Message format: {timestamp}|{method}|{endpoint}
      */
     private generateProxySignature;
+    /**
+     * 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;
     /**
      * 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 requestViaProxy;
     /**
@@ -220,27 +335,28 @@ export declare 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
      */
-    request<T>(url: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown, authToken?: string): Promise<VibeResponse<T>>;
+    request<T>(urlOrPath: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown, authToken?: string): Promise<VibeResponse<T>>;
     /**
      * Parse error response body, handling non-JSON responses gracefully.
      */
     private parseErrorResponse;
     /**
      * 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.
      */
-    getSchema(): Promise<Record<string, {
-        columns: Array<{
-            name: string;
-            type: string;
-            nullable: boolean;
-        }>;
-    }>>;
+    getSchema(): Promise<Record<string, unknown>>;
 }
 /**
  * Default Vibe client instance.