@payez/next-mvp 4.8.1 → 4.8.3

package/src/vibe/client.ts

@@ -1,877 +1,878 @@
-/**
- * =============================================================================
- * VIBE CLIENT - PRISMA-STYLE QUERY BUILDER
- * =============================================================================
- *
- * A typed query builder for the Vibe App API.
- * Provides Prisma-like DX for CRUD operations on Vibe tables.
- *
- * Usage:
- *   import { vibe } from '@payez/next-mvp/vibe'
- *
- *   // Find many with filters
- *   const users = await vibe.users.findMany({
- *     where: { status: 'active' },
- *     take: 10,
- *     skip: 0,
- *     orderBy: { created_at: 'desc' }
- *   })
- *
- *   // Find one by ID
- *   const user = await vibe.users.findUnique({ where: { id: 123 } })
- *
- *   // Create
- *   const newUser = await vibe.users.create({
- *     data: { email: 'test@example.com', name: 'Test' }
- *   })
- *
- *   // Update
- *   const updated = await vibe.users.update({
- *     where: { id: 123 },
- *     data: { name: 'Updated' }
- *   })
- *
- *   // Delete (soft delete)
- *   await vibe.users.delete({ where: { id: 123 } })
- *
- * =============================================================================
- */
-
-import {
-  VibeError,
-  VibeNotFoundError,
-  VibeServiceError,
-  VibeValidationError,
-  VibeBatchCreateError,
-} from './errors';
-import { unwrapVibeDocument, extractVibeDocuments } from './document-unwrap';
-import type { VibeDocumentWrapper } from './document-unwrap';
-import type {
-  VibeMeta,
-  VibeResponse,
-  VibeErrorResponse,
-  VibeTableName,
-  VibeTableType,
-} from './types';
-
-// Re-export from types for convenience
-export type { VibeTableName, VibeTableType } from './types';
-
-// -----------------------------------------------------------------------------
-// CONFIGURATION
-// -----------------------------------------------------------------------------
-
-export interface VibeRetryConfig {
-  /** Max retries for 5xx errors (default: 3) */
-  maxRetries?: number;
-  /** Base delay in ms for exponential backoff (default: 1000) */
-  baseDelay?: number;
-  /** Max delay in ms (default: 10000) */
-  maxDelay?: number;
-  /** Whether to retry on 429 with Retry-After header (default: true) */
-  retryOnRateLimit?: boolean;
-}
-
-export interface VibeClientConfig {
-  /**
-   * 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;
-  /**
-   * IDP URL for proxy requests (defaults to IDP_URL env var)
-   * Used with appSigningKey for secure proxy-based Vibe access.
-   */
-  idpUrl?: string;
-  /**
-   * Vibe HMAC key for proxy authentication (defaults to VIBE_HMAC_KEY env var)
-   * Base64-encoded signing key from Vibe Credentials tab.
-   * 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 */
-  retry?: VibeRetryConfig;
-}
-
-// -----------------------------------------------------------------------------
-// QUERY TYPES
-// -----------------------------------------------------------------------------
-
-/** Comparison operators for filters */
-export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'nin';
-
-/** Filter value - can be simple value or operator object */
-export type FilterValue<T> = T | { [K in FilterOperator]?: T };
-
-/** Where clause for queries */
-export type WhereClause<T> = {
-  [K in keyof T]?: FilterValue<T[K]>;
-};
-
-/** Order direction */
-export type OrderDirection = 'asc' | 'desc';
-
-/** Order by clause */
-export type OrderByClause<T> = {
-  [K in keyof T]?: OrderDirection;
-};
-
-/** Options for findMany */
-export interface FindManyOptions<T> {
-  where?: WhereClause<T>;
-  orderBy?: OrderByClause<T>;
-  take?: number;
-  skip?: number;
-}
-
-/**
- * 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 };
-}
-
-/** Options for create */
-export interface CreateOptions<T> {
-  data: Omit<T, 'id' | 'created_at' | 'updated_at'>;
-}
-
-/**
- * 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. `where.id` is the DOCUMENT id (see FindUniqueOptions). */
-export interface DeleteOptions {
-  where: { id: number };
-}
-
-/** Options for count */
-export interface CountOptions<T> {
-  where?: WhereClause<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;
-}
-
-// -----------------------------------------------------------------------------
-// RETRY HELPERS
-// -----------------------------------------------------------------------------
-
-const DEFAULT_RETRY_CONFIG: Required<VibeRetryConfig> = {
-  maxRetries: 3,
-  baseDelay: 1000,
-  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).
- */
-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));
-}
-
-/** Calculate exponential backoff delay with jitter */
-function getBackoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
-  // Exponential backoff: baseDelay * 2^attempt
-  const exponentialDelay = baseDelay * Math.pow(2, attempt);
-  // Add jitter (±25%) to prevent thundering herd
-  const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
-  return Math.min(exponentialDelay + jitter, maxDelay);
-}
-
-// -----------------------------------------------------------------------------
-// TABLE DELEGATE
-// -----------------------------------------------------------------------------
-
-/**
- * Delegate class for table operations.
- * Provides Prisma-style methods for a specific table.
- */
-export class VibeTableDelegate<T extends VibeTableName> {
-  private tableName: T;
-  private client: VibeClient;
-
-  constructor(tableName: T, client: VibeClient) {
-    this.tableName = tableName;
-    this.client = client;
-  }
-
-  /**
-   * 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 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;
-    }
-
-    if (options?.take !== undefined) {
-      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;
-    }
-
-    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 });
-      }
-      // 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;
-    }
-
-    return body;
-  }
-
-  /**
-   * Find a single record by ID.
-   * Throws VibeNotFoundError if not found.
-   */
-  async findUnique(options: FindUniqueOptions): Promise<VibeTableType<T>> {
-    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>;
-  }
-
-  /**
-   * Find a single record by ID.
-   * Returns null if not found (instead of throwing).
-   */
-  async findUniqueOrNull(options: FindUniqueOptions): Promise<VibeTableType<T> | null> {
-    try {
-      return await this.findUnique(options);
-    } catch (error) {
-      if (error instanceof VibeNotFoundError) {
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * 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);
-    return result.data[0] || null;
-  }
-
-  /**
-   * Create a new record.
-   */
-  async create(options: CreateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
-    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');
-  }
-
-  /**
-   * Update an existing record by ID.
-   * Throws VibeNotFoundError if not found.
-   */
-  async update(options: UpdateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
-    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> | 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> {
-    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.
-   *
-   * 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; 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 };
-  }
-}
-
-// -----------------------------------------------------------------------------
-// VIBE CLIENT
-// -----------------------------------------------------------------------------
-
-/**
- * Main Vibe client class.
- * Provides access to all Vibe App tables via table delegates.
- */
-export class VibeClient {
-  private config: {
-    baseUrl: string;
-    clientId: string;
-    idpUrl: string;
-    appSigningKey: string;
-    /** PAY-1767: the collection the table delegates address. */
-    collection: string;
-    fetch: typeof fetch;
-    retry: Required<VibeRetryConfig>;
-  };
-
-  // Table delegates
-  public users: VibeTableDelegate<'users'>;
-  public login_sessions: VibeTableDelegate<'login_sessions'>;
-  public profiles: VibeTableDelegate<'profiles'>;
-  public settings: VibeTableDelegate<'settings'>;
-  public files: VibeTableDelegate<'files'>;
-  public notifications: VibeTableDelegate<'notifications'>;
-  public activity_log: VibeTableDelegate<'activity_log'>;
-  public tags: VibeTableDelegate<'tags'>;
-  public comments: VibeTableDelegate<'comments'>;
-  public site_logs: VibeTableDelegate<'site_logs'>;
-
-  constructor(config: VibeClientConfig = {}) {
-    this.config = {
-      baseUrl: config.baseUrl || process.env.VIBE_API_URL || '',
-      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 },
-    };
-
-    // Initialize table delegates
-    this.users = new VibeTableDelegate('users', this);
-    this.login_sessions = new VibeTableDelegate('login_sessions', this);
-    this.profiles = new VibeTableDelegate('profiles', this);
-    this.settings = new VibeTableDelegate('settings', this);
-    this.files = new VibeTableDelegate('files', this);
-    this.notifications = new VibeTableDelegate('notifications', this);
-    this.activity_log = new VibeTableDelegate('activity_log', this);
-    this.tags = new VibeTableDelegate('tags', this);
-    this.comments = new VibeTableDelegate('comments', this);
-    this.site_logs = new VibeTableDelegate('site_logs', this);
-  }
-
-  /**
-   * Check if the client is configured to use proxy mode (IDP proxy).
-   * MVP always uses proxy mode - direct Vibe access is not supported.
-   */
-  private useProxyMode(): boolean {
-    return !!this.config.appSigningKey && !!this.config.idpUrl;
-  }
-
-  /**
-   * Generate HMAC-SHA256 signature for IDP proxy authentication.
-   * Message format: {timestamp}|{method}|{endpoint}
-   */
-  private async generateProxySignature(timestamp: number, method: string, endpoint: string): Promise<string> {
-    const message = `${timestamp}|${method}|${endpoint}`;
-    const keyBuffer = Buffer.from(this.config.appSigningKey, 'base64');
-
-    // Use Web Crypto API for browser/edge compatibility, fall back to Node crypto
-    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
-      const encoder = new TextEncoder();
-      const key = await globalThis.crypto.subtle.importKey(
-        'raw',
-        keyBuffer,
-        { name: 'HMAC', hash: 'SHA-256' },
-        false,
-        ['sign']
-      );
-      const signature = await globalThis.crypto.subtle.sign('HMAC', key, encoder.encode(message));
-      return Buffer.from(signature).toString('base64');
-    } else {
-      // Node.js fallback
-      const crypto = await import('crypto');
-      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: 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>(
-    endpoint: string,
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
-    body?: unknown,
-    authToken?: string
-  ): Promise<VibeResponse<T>> {
-    const timestamp = Math.floor(Date.now() / 1000);
-    const signature = await this.generateProxySignature(timestamp, method, endpoint);
-
-    const proxyUrl = `${this.config.idpUrl}/api/vibe/proxy`;
-
-    const headers: HeadersInit = {
-      'Content-Type': 'application/json',
-      'X-Vibe-Client-Id': this.config.clientId,
-      'X-Vibe-Timestamp': String(timestamp),
-      'X-Vibe-Signature': signature,
-    };
-
-    // Pass through auth token if provided (for user context)
-    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 && { data: body }),
-    };
-
-    const response = await this.config.fetch(proxyUrl, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(proxyBody),
-    });
-
-    if (!response.ok) {
-      const errorBody = await this.parseErrorResponse(response);
-      throw VibeError.fromResponse(errorBody, response.status);
-    }
-
-    // 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>;
-    }
-
-    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);
-    }
-
-    return responseData as VibeResponse<T>;
-  }
-
-  /**
-   * Get the configured base URL.
-   */
-  getBaseUrl(): string {
-    return this.config.baseUrl;
-  }
-
-  /**
-   * Make an authenticated request to the Vibe API with smart retry logic.
-   *
-   * 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<T>(
-    urlOrPath: string,
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
-    body?: unknown,
-    authToken?: string
-  ): Promise<VibeResponse<T>> {
-    if (!this.config.clientId) {
-      throw new VibeServiceError('VIBE_CLIENT_ID is not configured');
-    }
-
-    // Check if we should use proxy mode
-    if (this.useProxyMode()) {
-      if (!this.config.idpUrl) {
-        throw new VibeServiceError('IDP_URL is not configured (required for proxy mode)');
-      }
-      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>(endpoint, method, body, authToken);
-    }
-
-    // MVP requires proxy mode - direct Vibe access is not supported
-    throw new VibeServiceError(
-      'Vibe proxy not configured. Set VIBE_HMAC_KEY + IDP_URL for proxy mode.'
-    );
-  }
-
-  /**
-   * Parse error response body, handling non-JSON responses gracefully.
-   */
-  private async parseErrorResponse(response: Response): Promise<VibeErrorResponse> {
-    try {
-      return await response.json();
-    } catch {
-      // Non-JSON error response
-      const text = await response.text().catch(() => 'Unknown error');
-      return {
-        success: false,
-        error: {
-          code: `HTTP_${response.status}`,
-          message: text || response.statusText,
-        },
-      };
-    }
-  }
-
-  /**
-   * 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, unknown>> {
-    const endpoint = `/v1/mvp/schemas/${this.config.collection}`;
-    const response = await this.request<Record<string, unknown>>(endpoint, 'GET');
-    return response.data;
-  }
-}
-
-// -----------------------------------------------------------------------------
-// SINGLETON INSTANCE
-// -----------------------------------------------------------------------------
-
-/**
- * Default Vibe client instance.
- * Uses environment variables for configuration.
- *
- * Usage:
- *   import { vibe } from '@payez/next-mvp/vibe'
- *   const users = await vibe.users.findMany()
- */
-export const vibe = new VibeClient();
-
-/**
- * Create a new Vibe client with custom configuration.
- *
- * Usage:
- *   import { createVibeClient } from '@payez/next-mvp/vibe'
- *   const customVibe = createVibeClient({ baseUrl: 'https://custom-api.example.com' })
- */
-export function createVibeClient(config: VibeClientConfig): VibeClient {
-  return new VibeClient(config);
-}
+/**
+ * =============================================================================
+ * VIBE CLIENT - PRISMA-STYLE QUERY BUILDER
+ * =============================================================================
+ *
+ * A typed query builder for the Vibe App API.
+ * Provides Prisma-like DX for CRUD operations on Vibe tables.
+ *
+ * Usage:
+ *   import { vibe } from '@payez/next-mvp/vibe'
+ *
+ *   // Find many with filters
+ *   const users = await vibe.users.findMany({
+ *     where: { status: 'active' },
+ *     take: 10,
+ *     skip: 0,
+ *     orderBy: { created_at: 'desc' }
+ *   })
+ *
+ *   // Find one by ID
+ *   const user = await vibe.users.findUnique({ where: { id: 123 } })
+ *
+ *   // Create
+ *   const newUser = await vibe.users.create({
+ *     data: { email: 'test@example.com', name: 'Test' }
+ *   })
+ *
+ *   // Update
+ *   const updated = await vibe.users.update({
+ *     where: { id: 123 },
+ *     data: { name: 'Updated' }
+ *   })
+ *
+ *   // Delete (soft delete)
+ *   await vibe.users.delete({ where: { id: 123 } })
+ *
+ * =============================================================================
+ */
+
+import {
+  VibeError,
+  VibeNotFoundError,
+  VibeServiceError,
+  VibeValidationError,
+  VibeBatchCreateError,
+} from './errors';
+import { unwrapVibeDocument, extractVibeDocuments } from './document-unwrap';
+import type { VibeDocumentWrapper } from './document-unwrap';
+import type {
+  VibeMeta,
+  VibeResponse,
+  VibeErrorResponse,
+  VibeTableName,
+  VibeTableType,
+} from './types';
+
+// Re-export from types for convenience
+export type { VibeTableName, VibeTableType } from './types';
+
+// -----------------------------------------------------------------------------
+// CONFIGURATION
+// -----------------------------------------------------------------------------
+
+export interface VibeRetryConfig {
+  /** Max retries for 5xx errors (default: 3) */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default: 1000) */
+  baseDelay?: number;
+  /** Max delay in ms (default: 10000) */
+  maxDelay?: number;
+  /** Whether to retry on 429 with Retry-After header (default: true) */
+  retryOnRateLimit?: boolean;
+}
+
+export interface VibeClientConfig {
+  /**
+   * 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;
+  /**
+   * IDP URL for proxy requests (defaults to IDP_URL env var)
+   * Used with appSigningKey for secure proxy-based Vibe access.
+   */
+  idpUrl?: string;
+  /**
+   * Vibe HMAC key for proxy authentication (defaults to VIBE_HMAC_KEY env var)
+   * Base64-encoded signing key from Vibe Credentials tab.
+   * 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 */
+  retry?: VibeRetryConfig;
+}
+
+// -----------------------------------------------------------------------------
+// QUERY TYPES
+// -----------------------------------------------------------------------------
+
+/** Comparison operators for filters */
+export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'nin';
+
+/** Filter value - can be simple value or operator object */
+export type FilterValue<T> = T | { [K in FilterOperator]?: T };
+
+/** Where clause for queries */
+export type WhereClause<T> = {
+  [K in keyof T]?: FilterValue<T[K]>;
+};
+
+/** Order direction */
+export type OrderDirection = 'asc' | 'desc';
+
+/** Order by clause */
+export type OrderByClause<T> = {
+  [K in keyof T]?: OrderDirection;
+};
+
+/** Options for findMany */
+export interface FindManyOptions<T> {
+  where?: WhereClause<T>;
+  orderBy?: OrderByClause<T>;
+  take?: number;
+  skip?: number;
+}
+
+/**
+ * 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 };
+}
+
+/** Options for create */
+export interface CreateOptions<T> {
+  data: Omit<T, 'id' | 'created_at' | 'updated_at'>;
+}
+
+/**
+ * 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. `where.id` is the DOCUMENT id (see FindUniqueOptions). */
+export interface DeleteOptions {
+  where: { id: number };
+}
+
+/** Options for count */
+export interface CountOptions<T> {
+  where?: WhereClause<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;
+}
+
+// -----------------------------------------------------------------------------
+// RETRY HELPERS
+// -----------------------------------------------------------------------------
+
+const DEFAULT_RETRY_CONFIG: Required<VibeRetryConfig> = {
+  maxRetries: 3,
+  baseDelay: 1000,
+  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).
+ */
+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));
+}
+
+/** Calculate exponential backoff delay with jitter */
+function getBackoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
+  // Exponential backoff: baseDelay * 2^attempt
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  // Add jitter (±25%) to prevent thundering herd
+  const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+  return Math.min(exponentialDelay + jitter, maxDelay);
+}
+
+// -----------------------------------------------------------------------------
+// TABLE DELEGATE
+// -----------------------------------------------------------------------------
+
+/**
+ * Delegate class for table operations.
+ * Provides Prisma-style methods for a specific table.
+ */
+export class VibeTableDelegate<T extends VibeTableName> {
+  private tableName: T;
+  private client: VibeClient;
+
+  constructor(tableName: T, client: VibeClient) {
+    this.tableName = tableName;
+    this.client = client;
+  }
+
+  /**
+   * 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 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;
+    }
+
+    if (options?.take !== undefined) {
+      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;
+    }
+
+    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 });
+      }
+      // 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;
+    }
+
+    return body;
+  }
+
+  /**
+   * Find a single record by ID.
+   * Throws VibeNotFoundError if not found.
+   */
+  async findUnique(options: FindUniqueOptions): Promise<VibeTableType<T>> {
+    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>;
+  }
+
+  /**
+   * Find a single record by ID.
+   * Returns null if not found (instead of throwing).
+   */
+  async findUniqueOrNull(options: FindUniqueOptions): Promise<VibeTableType<T> | null> {
+    try {
+      return await this.findUnique(options);
+    } catch (error) {
+      if (error instanceof VibeNotFoundError) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 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);
+    return result.data[0] || null;
+  }
+
+  /**
+   * Create a new record.
+   */
+  async create(options: CreateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
+    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');
+  }
+
+  /**
+   * Update an existing record by ID.
+   * Throws VibeNotFoundError if not found.
+   */
+  async update(options: UpdateOptions<VibeTableType<T>>): Promise<VibeTableType<T>> {
+    const endpoint = this.tableEndpoint(options.where.id);
+    // PAY-2041: PATCH, not PUT. Core PUT REPLACES the document (UpdateAsync SET data = body), and `data` here is Partial, so PUT erased every field not named. PATCH merges (DocumentsController.Patch).
+    const response = await this.client.request<VibeDocumentWrapper>(endpoint, 'PATCH', 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> | 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> {
+    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.
+   *
+   * 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; 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 };
+  }
+}
+
+// -----------------------------------------------------------------------------
+// VIBE CLIENT
+// -----------------------------------------------------------------------------
+
+/**
+ * Main Vibe client class.
+ * Provides access to all Vibe App tables via table delegates.
+ */
+export class VibeClient {
+  private config: {
+    baseUrl: string;
+    clientId: string;
+    idpUrl: string;
+    appSigningKey: string;
+    /** PAY-1767: the collection the table delegates address. */
+    collection: string;
+    fetch: typeof fetch;
+    retry: Required<VibeRetryConfig>;
+  };
+
+  // Table delegates
+  public users: VibeTableDelegate<'users'>;
+  public login_sessions: VibeTableDelegate<'login_sessions'>;
+  public profiles: VibeTableDelegate<'profiles'>;
+  public settings: VibeTableDelegate<'settings'>;
+  public files: VibeTableDelegate<'files'>;
+  public notifications: VibeTableDelegate<'notifications'>;
+  public activity_log: VibeTableDelegate<'activity_log'>;
+  public tags: VibeTableDelegate<'tags'>;
+  public comments: VibeTableDelegate<'comments'>;
+  public site_logs: VibeTableDelegate<'site_logs'>;
+
+  constructor(config: VibeClientConfig = {}) {
+    this.config = {
+      baseUrl: config.baseUrl || process.env.VIBE_API_URL || '',
+      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 },
+    };
+
+    // Initialize table delegates
+    this.users = new VibeTableDelegate('users', this);
+    this.login_sessions = new VibeTableDelegate('login_sessions', this);
+    this.profiles = new VibeTableDelegate('profiles', this);
+    this.settings = new VibeTableDelegate('settings', this);
+    this.files = new VibeTableDelegate('files', this);
+    this.notifications = new VibeTableDelegate('notifications', this);
+    this.activity_log = new VibeTableDelegate('activity_log', this);
+    this.tags = new VibeTableDelegate('tags', this);
+    this.comments = new VibeTableDelegate('comments', this);
+    this.site_logs = new VibeTableDelegate('site_logs', this);
+  }
+
+  /**
+   * Check if the client is configured to use proxy mode (IDP proxy).
+   * MVP always uses proxy mode - direct Vibe access is not supported.
+   */
+  private useProxyMode(): boolean {
+    return !!this.config.appSigningKey && !!this.config.idpUrl;
+  }
+
+  /**
+   * Generate HMAC-SHA256 signature for IDP proxy authentication.
+   * Message format: {timestamp}|{method}|{endpoint}
+   */
+  private async generateProxySignature(timestamp: number, method: string, endpoint: string): Promise<string> {
+    const message = `${timestamp}|${method}|${endpoint}`;
+    const keyBuffer = Buffer.from(this.config.appSigningKey, 'base64');
+
+    // Use Web Crypto API for browser/edge compatibility, fall back to Node crypto
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
+      const encoder = new TextEncoder();
+      const key = await globalThis.crypto.subtle.importKey(
+        'raw',
+        keyBuffer,
+        { name: 'HMAC', hash: 'SHA-256' },
+        false,
+        ['sign']
+      );
+      const signature = await globalThis.crypto.subtle.sign('HMAC', key, encoder.encode(message));
+      return Buffer.from(signature).toString('base64');
+    } else {
+      // Node.js fallback
+      const crypto = await import('crypto');
+      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: 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>(
+    endpoint: string,
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    body?: unknown,
+    authToken?: string
+  ): Promise<VibeResponse<T>> {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signature = await this.generateProxySignature(timestamp, method, endpoint);
+
+    const proxyUrl = `${this.config.idpUrl}/api/vibe/proxy`;
+
+    const headers: HeadersInit = {
+      'Content-Type': 'application/json',
+      'X-Vibe-Client-Id': this.config.clientId,
+      'X-Vibe-Timestamp': String(timestamp),
+      'X-Vibe-Signature': signature,
+    };
+
+    // Pass through auth token if provided (for user context)
+    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 && { data: body }),
+    };
+
+    const response = await this.config.fetch(proxyUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(proxyBody),
+    });
+
+    if (!response.ok) {
+      const errorBody = await this.parseErrorResponse(response);
+      throw VibeError.fromResponse(errorBody, response.status);
+    }
+
+    // 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>;
+    }
+
+    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);
+    }
+
+    return responseData as VibeResponse<T>;
+  }
+
+  /**
+   * Get the configured base URL.
+   */
+  getBaseUrl(): string {
+    return this.config.baseUrl;
+  }
+
+  /**
+   * Make an authenticated request to the Vibe API with smart retry logic.
+   *
+   * 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<T>(
+    urlOrPath: string,
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    body?: unknown,
+    authToken?: string
+  ): Promise<VibeResponse<T>> {
+    if (!this.config.clientId) {
+      throw new VibeServiceError('VIBE_CLIENT_ID is not configured');
+    }
+
+    // Check if we should use proxy mode
+    if (this.useProxyMode()) {
+      if (!this.config.idpUrl) {
+        throw new VibeServiceError('IDP_URL is not configured (required for proxy mode)');
+      }
+      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>(endpoint, method, body, authToken);
+    }
+
+    // MVP requires proxy mode - direct Vibe access is not supported
+    throw new VibeServiceError(
+      'Vibe proxy not configured. Set VIBE_HMAC_KEY + IDP_URL for proxy mode.'
+    );
+  }
+
+  /**
+   * Parse error response body, handling non-JSON responses gracefully.
+   */
+  private async parseErrorResponse(response: Response): Promise<VibeErrorResponse> {
+    try {
+      return await response.json();
+    } catch {
+      // Non-JSON error response
+      const text = await response.text().catch(() => 'Unknown error');
+      return {
+        success: false,
+        error: {
+          code: `HTTP_${response.status}`,
+          message: text || response.statusText,
+        },
+      };
+    }
+  }
+
+  /**
+   * 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, unknown>> {
+    const endpoint = `/v1/mvp/schemas/${this.config.collection}`;
+    const response = await this.request<Record<string, unknown>>(endpoint, 'GET');
+    return response.data;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// SINGLETON INSTANCE
+// -----------------------------------------------------------------------------
+
+/**
+ * Default Vibe client instance.
+ * Uses environment variables for configuration.
+ *
+ * Usage:
+ *   import { vibe } from '@payez/next-mvp/vibe'
+ *   const users = await vibe.users.findMany()
+ */
+export const vibe = new VibeClient();
+
+/**
+ * Create a new Vibe client with custom configuration.
+ *
+ * Usage:
+ *   import { createVibeClient } from '@payez/next-mvp/vibe'
+ *   const customVibe = createVibeClient({ baseUrl: 'https://custom-api.example.com' })
+ */
+export function createVibeClient(config: VibeClientConfig): VibeClient {
+  return new VibeClient(config);
+}