@ragable/sdk 0.6.20 → 0.6.21

package/dist/index.d.mts

@@ -313,6 +313,26 @@ type PostgrestResult<T> = {
     data: null;
     error: RagableError;
 };
+/** Discriminated result for easier TypeScript narrowing than `{ data, error }` after destructuring. */
+type RagableResult<T, E = RagableError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function toRagableResult<T>(r: PostgrestResult<T>): RagableResult<T>;
+/**
+ * Narrows a {@link PostgrestResult} after an `if (result.error)` guard.
+ * Prefer checking `result.error` on the result object (not destructured `{ data, error }`)
+ * so TypeScript narrows `data` automatically; use this when you need a throw or assertion.
+ */
+declare function assertPostgrestSuccess<T>(r: PostgrestResult<T>): asserts r is {
+    data: T;
+    error: null;
+};
+/** Returns `data` or throws `RagableError` / the failure case. */
+declare function unwrapPostgrest<T>(r: PostgrestResult<T>): T;
 declare function asPostgrestResponse<T>(fn: () => Promise<T>): Promise<PostgrestResult<T>>;
 type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "is" | "in";
 interface Filter {
@@ -991,7 +1011,34 @@ interface BrowserCollectionDefinition {
     createdAt: string;
     updatedAt: string;
 }
-type CollectionWhere<Row extends Record<string, unknown>> = Partial<Row> & Record<string, unknown>;
+/**
+ * Prisma-style operator object for a single field (server-supported ops).
+ * Typed loosely so schema-specific refinements can be added in app code.
+ */
+type WhereOperatorObject = {
+    eq?: unknown;
+    neq?: unknown;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    in?: unknown;
+    contains?: unknown;
+};
+/**
+ * `where` filters: equality on values, or per-field operator objects.
+ * Use `id`, `createdAt`, `updatedAt` to match the record envelope (DB columns), not `data` JSON
+ * (unless you also have those keys in your JSON — prefer envelope keys for `id`).
+ */
+type WhereInput<Row extends Record<string, unknown>> = {
+    [K in keyof Row]?: Row[K] | WhereOperatorObject | null;
+} & {
+    id?: string | WhereOperatorObject;
+    createdAt?: string | WhereOperatorObject;
+    updatedAt?: string | WhereOperatorObject;
+};
+/** @deprecated Use {@link WhereInput} — same shape. */
+type CollectionWhere<Row extends Record<string, unknown>> = WhereInput<Row>;
 type CollectionFilter<Row extends Record<string, unknown>> = {
     [Field in Extract<keyof Row, string>]: {
         field: Field;
@@ -999,8 +1046,22 @@ type CollectionFilter<Row extends Record<string, unknown>> = {
         value: Row[Field];
     };
 }[Extract<keyof Row, string>];
+type CollectionReturnMode = "envelope" | "flat";
+/**
+ * One row: JSON fields at the top level, envelope fields under `meta`
+ * (when using {@link BrowserCollectionApi.findMany} with `return: "flat"`).
+ */
+type CollectionRowWithMeta<Row extends Record<string, unknown> = Record<string, unknown>> = Row & {
+    meta: {
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+    };
+};
+declare function collectionRecordToRowWithMeta<Row extends Record<string, unknown>>(record: BrowserCollectionRecord<Row>): CollectionRowWithMeta<Row>;
+declare function collectionRecordsToRowWithMeta<Row extends Record<string, unknown>>(records: BrowserCollectionRecord<Row>[]): CollectionRowWithMeta<Row>[];
 type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<string, unknown>> = {
-    where?: CollectionWhere<Row>;
+    where?: WhereInput<Row>;
     filters?: Array<{
         field: Extract<keyof Row, string> | (string & {});
         op?: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "contains";
@@ -1008,24 +1069,69 @@ type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<st
     } | CollectionFilter<Row>>;
     limit?: number;
     offset?: number;
-    orderBy?: Extract<keyof Row, string> | (string & {});
+    orderBy?: Extract<keyof Row, string> | "id" | "createdAt" | "updatedAt" | (string & {});
     orderDirection?: "asc" | "desc";
+    /**
+     * - `envelope` (default): `Array<{ id, data, createdAt, updatedAt }>`
+     * - `flat`: {@link CollectionRowWithMeta} — row fields at top level + `meta` for `id` / timestamps
+     */
+    return?: CollectionReturnMode;
 };
+type CollectionRowData<Row extends Record<string, unknown> = Record<string, unknown>> = BrowserCollectionRowData<Row>;
+type RowD<Row extends Record<string, unknown>> = BrowserCollectionRowData<Row>;
 declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<string, unknown>, Insert extends Record<string, unknown> = Row, Update extends Record<string, unknown> = Partial<Row>> {
     private readonly database;
     private readonly name;
     private readonly databaseInstanceId?;
     constructor(database: RagableBrowserDatabaseClient<any>, name: string, databaseInstanceId?: string | undefined);
-    find: (whereOrParams?: CollectionWhere<BrowserCollectionRowData<Row>> | BrowserCollectionFindParams<BrowserCollectionRowData<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>[]>>;
-    insert: (data: BrowserCollectionInsertData<Row, Insert>) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>>>;
-    update: (where: CollectionWhere<BrowserCollectionRowData<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
+    private normalizeFindArgs;
+    private requestFind;
+    /**
+     * Query collection rows. Prefer this over the deprecated `find` alias.
+     * Use `return: "flat"` to get {@link CollectionRowWithMeta} without nested `.data`.
+     */
+    findMany: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    /**
+     * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
+     */
+    find: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    /**
+     * At most one row, `data` is the record or `null` if none match (not an error).
+     */
+    findFirst: (whereOrParams?: WhereInput<RowD<Row>> | Omit<BrowserCollectionFindParams<RowD<Row>>, "return">) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>> | null>>;
+    /**
+     * Lookup by primary key `id` (envelope). Equivalent to
+     * `findFirst({ where: { id }, limit: 1 })` with a typed `where.id`.
+     */
+    findUnique: (args: {
+        where: {
+            id: string;
+        } & Partial<WhereInput<RowD<Row>>>;
+    }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>> | null>>;
+    insert: (data: BrowserCollectionInsertData<Row, Insert>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>>>;
+    /**
+     * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
+     */
+    update: (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
+        limit?: number;
+    }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[]>>;
+    /**
+     * Like {@link BrowserCollectionApi.update} but the success payload includes
+     * `meta.count` (number of rows returned from the update, bounded by `limit`).
+     */
+    updateMany: (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
         limit?: number;
-    }) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>[]>>;
-    delete: (where: CollectionWhere<BrowserCollectionRowData<Row>>, options?: {
+    }) => Promise<PostgrestResult<{
+        records: BrowserCollectionRecord<RowD<Row>>[];
+        meta: {
+            count: number;
+        };
+    }>>;
+    delete: (where: WhereInput<RowD<Row>>, options?: {
         limit?: number;
     }) => Promise<PostgrestResult<{
         deleted: number;
-        records: BrowserCollectionRecord<BrowserCollectionRowData<Row>>[];
+        records: BrowserCollectionRecord<RowD<Row>>[];
     }>>;
 }
 type BrowserCollections<Database extends RagableDatabase = DefaultRagableDatabase> = [keyof Database["public"]["Tables"]] extends [never] ? Record<string, BrowserCollectionApi<Record<string, unknown>>> : {
@@ -1242,4 +1348,4 @@ declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream, toRagableResult, unwrapPostgrest };

package/dist/index.d.ts

@@ -313,6 +313,26 @@ type PostgrestResult<T> = {
     data: null;
     error: RagableError;
 };
+/** Discriminated result for easier TypeScript narrowing than `{ data, error }` after destructuring. */
+type RagableResult<T, E = RagableError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function toRagableResult<T>(r: PostgrestResult<T>): RagableResult<T>;
+/**
+ * Narrows a {@link PostgrestResult} after an `if (result.error)` guard.
+ * Prefer checking `result.error` on the result object (not destructured `{ data, error }`)
+ * so TypeScript narrows `data` automatically; use this when you need a throw or assertion.
+ */
+declare function assertPostgrestSuccess<T>(r: PostgrestResult<T>): asserts r is {
+    data: T;
+    error: null;
+};
+/** Returns `data` or throws `RagableError` / the failure case. */
+declare function unwrapPostgrest<T>(r: PostgrestResult<T>): T;
 declare function asPostgrestResponse<T>(fn: () => Promise<T>): Promise<PostgrestResult<T>>;
 type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "is" | "in";
 interface Filter {
@@ -991,7 +1011,34 @@ interface BrowserCollectionDefinition {
     createdAt: string;
     updatedAt: string;
 }
-type CollectionWhere<Row extends Record<string, unknown>> = Partial<Row> & Record<string, unknown>;
+/**
+ * Prisma-style operator object for a single field (server-supported ops).
+ * Typed loosely so schema-specific refinements can be added in app code.
+ */
+type WhereOperatorObject = {
+    eq?: unknown;
+    neq?: unknown;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    in?: unknown;
+    contains?: unknown;
+};
+/**
+ * `where` filters: equality on values, or per-field operator objects.
+ * Use `id`, `createdAt`, `updatedAt` to match the record envelope (DB columns), not `data` JSON
+ * (unless you also have those keys in your JSON — prefer envelope keys for `id`).
+ */
+type WhereInput<Row extends Record<string, unknown>> = {
+    [K in keyof Row]?: Row[K] | WhereOperatorObject | null;
+} & {
+    id?: string | WhereOperatorObject;
+    createdAt?: string | WhereOperatorObject;
+    updatedAt?: string | WhereOperatorObject;
+};
+/** @deprecated Use {@link WhereInput} — same shape. */
+type CollectionWhere<Row extends Record<string, unknown>> = WhereInput<Row>;
 type CollectionFilter<Row extends Record<string, unknown>> = {
     [Field in Extract<keyof Row, string>]: {
         field: Field;
@@ -999,8 +1046,22 @@ type CollectionFilter<Row extends Record<string, unknown>> = {
         value: Row[Field];
     };
 }[Extract<keyof Row, string>];
+type CollectionReturnMode = "envelope" | "flat";
+/**
+ * One row: JSON fields at the top level, envelope fields under `meta`
+ * (when using {@link BrowserCollectionApi.findMany} with `return: "flat"`).
+ */
+type CollectionRowWithMeta<Row extends Record<string, unknown> = Record<string, unknown>> = Row & {
+    meta: {
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+    };
+};
+declare function collectionRecordToRowWithMeta<Row extends Record<string, unknown>>(record: BrowserCollectionRecord<Row>): CollectionRowWithMeta<Row>;
+declare function collectionRecordsToRowWithMeta<Row extends Record<string, unknown>>(records: BrowserCollectionRecord<Row>[]): CollectionRowWithMeta<Row>[];
 type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<string, unknown>> = {
-    where?: CollectionWhere<Row>;
+    where?: WhereInput<Row>;
     filters?: Array<{
         field: Extract<keyof Row, string> | (string & {});
         op?: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "contains";
@@ -1008,24 +1069,69 @@ type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<st
     } | CollectionFilter<Row>>;
     limit?: number;
     offset?: number;
-    orderBy?: Extract<keyof Row, string> | (string & {});
+    orderBy?: Extract<keyof Row, string> | "id" | "createdAt" | "updatedAt" | (string & {});
     orderDirection?: "asc" | "desc";
+    /**
+     * - `envelope` (default): `Array<{ id, data, createdAt, updatedAt }>`
+     * - `flat`: {@link CollectionRowWithMeta} — row fields at top level + `meta` for `id` / timestamps
+     */
+    return?: CollectionReturnMode;
 };
+type CollectionRowData<Row extends Record<string, unknown> = Record<string, unknown>> = BrowserCollectionRowData<Row>;
+type RowD<Row extends Record<string, unknown>> = BrowserCollectionRowData<Row>;
 declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<string, unknown>, Insert extends Record<string, unknown> = Row, Update extends Record<string, unknown> = Partial<Row>> {
     private readonly database;
     private readonly name;
     private readonly databaseInstanceId?;
     constructor(database: RagableBrowserDatabaseClient<any>, name: string, databaseInstanceId?: string | undefined);
-    find: (whereOrParams?: CollectionWhere<BrowserCollectionRowData<Row>> | BrowserCollectionFindParams<BrowserCollectionRowData<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>[]>>;
-    insert: (data: BrowserCollectionInsertData<Row, Insert>) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>>>;
-    update: (where: CollectionWhere<BrowserCollectionRowData<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
+    private normalizeFindArgs;
+    private requestFind;
+    /**
+     * Query collection rows. Prefer this over the deprecated `find` alias.
+     * Use `return: "flat"` to get {@link CollectionRowWithMeta} without nested `.data`.
+     */
+    findMany: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    /**
+     * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
+     */
+    find: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    /**
+     * At most one row, `data` is the record or `null` if none match (not an error).
+     */
+    findFirst: (whereOrParams?: WhereInput<RowD<Row>> | Omit<BrowserCollectionFindParams<RowD<Row>>, "return">) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>> | null>>;
+    /**
+     * Lookup by primary key `id` (envelope). Equivalent to
+     * `findFirst({ where: { id }, limit: 1 })` with a typed `where.id`.
+     */
+    findUnique: (args: {
+        where: {
+            id: string;
+        } & Partial<WhereInput<RowD<Row>>>;
+    }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>> | null>>;
+    insert: (data: BrowserCollectionInsertData<Row, Insert>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>>>;
+    /**
+     * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
+     */
+    update: (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
+        limit?: number;
+    }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[]>>;
+    /**
+     * Like {@link BrowserCollectionApi.update} but the success payload includes
+     * `meta.count` (number of rows returned from the update, bounded by `limit`).
+     */
+    updateMany: (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
         limit?: number;
-    }) => Promise<PostgrestResult<BrowserCollectionRecord<BrowserCollectionRowData<Row>>[]>>;
-    delete: (where: CollectionWhere<BrowserCollectionRowData<Row>>, options?: {
+    }) => Promise<PostgrestResult<{
+        records: BrowserCollectionRecord<RowD<Row>>[];
+        meta: {
+            count: number;
+        };
+    }>>;
+    delete: (where: WhereInput<RowD<Row>>, options?: {
         limit?: number;
     }) => Promise<PostgrestResult<{
         deleted: number;
-        records: BrowserCollectionRecord<BrowserCollectionRowData<Row>>[];
+        records: BrowserCollectionRecord<RowD<Row>>[];
     }>>;
 }
 type BrowserCollections<Database extends RagableDatabase = DefaultRagableDatabase> = [keyof Database["public"]["Tables"]] extends [never] ? Record<string, BrowserCollectionApi<Record<string, unknown>>> : {
@@ -1242,4 +1348,4 @@ declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream, toRagableResult, unwrapPostgrest };

package/dist/index.js

@@ -56,7 +56,10 @@ __export(index_exports, {
   ShiftClient: () => ShiftClient,
   Transport: () => Transport,
   asPostgrestResponse: () => asPostgrestResponse,
+  assertPostgrestSuccess: () => assertPostgrestSuccess,
   bindFetch: () => bindFetch,
+  collectionRecordToRowWithMeta: () => collectionRecordToRowWithMeta,
+  collectionRecordsToRowWithMeta: () => collectionRecordsToRowWithMeta,
   createBrowserClient: () => createBrowserClient,
   createClient: () => createClient,
   createRagPipeline: () => createRagPipeline,
@@ -72,7 +75,9 @@ __export(index_exports, {
   normalizeBrowserApiBase: () => normalizeBrowserApiBase,
   parseSseDataLine: () => parseSseDataLine,
   parseTransportResponse: () => parseTransportResponse,
-  readSseStream: () => readSseStream
+  readSseStream: () => readSseStream,
+  toRagableResult: () => toRagableResult,
+  unwrapPostgrest: () => unwrapPostgrest
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -701,6 +706,17 @@ async function parseTransportResponse(response) {
 }
 
 // src/browser-postgrest.ts
+function toRagableResult(r) {
+  if (r.error) return { ok: false, error: r.error };
+  return { ok: true, value: r.data };
+}
+function assertPostgrestSuccess(r) {
+  if (r.error) throw r.error;
+}
+function unwrapPostgrest(r) {
+  if (r.error) throw r.error;
+  return r.data;
+}
 async function asPostgrestResponse(fn) {
   try {
     const data = await fn();
@@ -2286,24 +2302,71 @@ var RagableBrowserAuthClient = class {
     return this.auth.getSession();
   }
 };
+function collectionRecordToRowWithMeta(record) {
+  const { data, id, createdAt, updatedAt } = record;
+  return { ...data, meta: { id, createdAt, updatedAt } };
+}
+function collectionRecordsToRowWithMeta(records) {
+  return records.map(collectionRecordToRowWithMeta);
+}
+var FIND_QUERY_KEYS = [
+  "where",
+  "filters",
+  "limit",
+  "offset",
+  "orderBy",
+  "orderDirection",
+  "return"
+];
 var BrowserCollectionApi = class {
   constructor(database, name, databaseInstanceId) {
     this.database = database;
     this.name = name;
     this.databaseInstanceId = databaseInstanceId;
-    __publicField(this, "find", (whereOrParams = {}) => {
-      const hasQueryKeys = ["where", "filters", "limit", "offset", "orderBy", "orderDirection"].some(
-        (key) => Object.prototype.hasOwnProperty.call(whereOrParams, key)
-      );
-      const body = hasQueryKeys ? whereOrParams : { where: whereOrParams };
-      return asPostgrestResponse(
-        () => this.database._requestCollection(
-          "POST",
-          `/${encodeURIComponent(this.name)}/find`,
-          body,
-          this.databaseInstanceId
-        )
-      );
+    __publicField(this, "requestFind", (body) => asPostgrestResponse(
+      () => this.database._requestCollection(
+        "POST",
+        `/${encodeURIComponent(this.name)}/find`,
+        body,
+        this.databaseInstanceId
+      )
+    ));
+    /**
+     * Query collection rows. Prefer this over the deprecated `find` alias.
+     * Use `return: "flat"` to get {@link CollectionRowWithMeta} without nested `.data`.
+     */
+    __publicField(this, "findMany", async (whereOrParams = {}) => {
+      const { returnMode, body } = this.normalizeFindArgs(whereOrParams);
+      const res = await this.requestFind(body);
+      if (res.error) return res;
+      if (returnMode === "flat") {
+        return {
+          data: collectionRecordsToRowWithMeta(res.data),
+          error: null
+        };
+      }
+      return res;
+    });
+    /**
+     * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
+     */
+    __publicField(this, "find", (whereOrParams = {}) => this.findMany(whereOrParams));
+    /**
+     * At most one row, `data` is the record or `null` if none match (not an error).
+     */
+    __publicField(this, "findFirst", async (whereOrParams = {}) => {
+      const { body } = this.normalizeFindArgs(whereOrParams);
+      const withCap = { ...body, limit: 1, offset: body["offset"] ?? 0 };
+      const res = await this.requestFind(withCap);
+      if (res.error) return res;
+      return { data: res.data[0] ?? null, error: null };
+    });
+    /**
+     * Lookup by primary key `id` (envelope). Equivalent to
+     * `findFirst({ where: { id }, limit: 1 })` with a typed `where.id`.
+     */
+    __publicField(this, "findUnique", async (args) => {
+      return this.findFirst({ where: args.where });
     });
     __publicField(this, "insert", (data) => asPostgrestResponse(
       () => this.database._requestCollection(
@@ -2313,6 +2376,9 @@ var BrowserCollectionApi = class {
         this.databaseInstanceId
       )
     ));
+    /**
+     * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
+     */
     __publicField(this, "update", (where, patch, options) => asPostgrestResponse(
       () => this.database._requestCollection(
         "PATCH",
@@ -2321,6 +2387,15 @@ var BrowserCollectionApi = class {
         this.databaseInstanceId
       )
     ));
+    /**
+     * Like {@link BrowserCollectionApi.update} but the success payload includes
+     * `meta.count` (number of rows returned from the update, bounded by `limit`).
+     */
+    __publicField(this, "updateMany", async (where, patch, options) => {
+      const r = await this.update(where, patch, options);
+      if (r.error) return r;
+      return { data: { records: r.data, meta: { count: r.data.length } }, error: null };
+    });
     __publicField(this, "delete", (where, options) => asPostgrestResponse(
       () => this.database._requestCollection(
         "DELETE",
@@ -2330,6 +2405,15 @@ var BrowserCollectionApi = class {
       )
     ));
   }
+  normalizeFindArgs(whereOrParams) {
+    const hasQueryKeys = typeof whereOrParams === "object" && whereOrParams !== null && FIND_QUERY_KEYS.some(
+      (key) => Object.prototype.hasOwnProperty.call(whereOrParams, key)
+    );
+    const raw = hasQueryKeys ? { ...whereOrParams } : { where: whereOrParams };
+    const returnMode = raw["return"] === "flat" ? "flat" : "envelope";
+    delete raw["return"];
+    return { returnMode, body: raw };
+  }
 };
 var RagableBrowserDatabaseClient = class {
   constructor(options, ragableAuth = null) {
@@ -2923,7 +3007,10 @@ function createRagableServerClient(options) {
   ShiftClient,
   Transport,
   asPostgrestResponse,
+  assertPostgrestSuccess,
   bindFetch,
+  collectionRecordToRowWithMeta,
+  collectionRecordsToRowWithMeta,
   createBrowserClient,
   createClient,
   createRagPipeline,
@@ -2939,6 +3026,8 @@ function createRagableServerClient(options) {
   normalizeBrowserApiBase,
   parseSseDataLine,
   parseTransportResponse,
-  readSseStream
+  readSseStream,
+  toRagableResult,
+  unwrapPostgrest
 });
 //# sourceMappingURL=index.js.map