@palbase/backend 28.0.0 → 29.0.0

package/dist/engine/index.d.cts

@@ -1,8 +1,8 @@
-import '../index-DtISj9QX.cjs';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-9C3JHxg-.cjs';
+import '../index-ChvoVczS.cjs';
+export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-BZfmdRmh.cjs';
 import '../db/env.cjs';
 import '../stack.cjs';
 import 'zod';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.cjs';
-import '../registry-qIPM5BQe.cjs';
+import '../registry-B2KfKWv1.cjs';

package/dist/engine/index.d.ts

@@ -1,8 +1,8 @@
-import '../index-dTTLlHIn.js';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-BbvOoZFr.js';
+import '../index-BOe82fsK.js';
+export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-BYDUKexK.js';
 import '../db/env.js';
 import '../stack.js';
 import 'zod';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.js';
-import '../registry-JQNIX-eA.js';
+import '../registry-DaqHsOq8.js';

package/dist/engine/index.js

@@ -16,13 +16,13 @@ import {
   quoteIdent,
   scrubSecrets,
   withTables
-} from "../chunk-75YROPRZ.js";
+} from "../chunk-DHJ3SYAE.js";
 import {
   DECLARATION_REFUSAL,
   DeclarationRefused,
   isDeclarationRefused
-} from "../chunk-RVP6BTEZ.js";
-import "../chunk-SNDXY565.js";
+} from "../chunk-ESSQ3YML.js";
+import "../chunk-SG4UTNOP.js";
 import "../chunk-3TUJWHC2.js";
 import "../chunk-VVMJEVQP.js";
 import "../chunk-CGNN2PUH.js";

package/dist/{index-dTTLlHIn.d.ts → index-BOe82fsK.d.ts}

@@ -51,12 +51,24 @@ interface User {
 interface AuthConfig {
     /** Whether authentication is required. Defaults to true. */
     required: boolean;
-    /** Required role for access. If undefined, any authenticated user is allowed.
+    /** Required application role for access. If undefined, any authenticated user is allowed.
      *
-     * Matched against the caller's `metadata.role` — NOT `user.role`, which is the
-     * database role RLS reads and is always "authenticated" for a signed-in user.
-     * Not signed in → 401; signed in with a different or missing role → 403. */
+     * Matched against the caller's rows in `auth.user_roles` — NOT against the
+     * `role` claim, which is the DATABASE role RLS reads and is the literal
+     * string "authenticated" for every signed-in user. Reading it from the table
+     * is what makes a revoked role take effect on the very NEXT request instead
+     * of whenever the token happens to expire.
+     *
+     * Not signed in → 401; signed in without the role → 403. */
     role?: string;
+    /** Required permission for access, as `resource.action` (e.g. "posts.delete_any").
+     *
+     * Resolved through `auth.has_permission(...)`, which answers from the roles
+     * the caller holds and the permissions those roles carry. The query runs in
+     * the request's own transaction, so it costs no extra connection.
+     *
+     * Signed in without the permission → 403. */
+    permission?: string;
     /** Require a confirmed email address. An unverified caller gets 403
      * `email_not_verified`. Fences a whole controller; for a partial rule read
      * `user.emailVerified` in the handler instead. */
@@ -2864,11 +2876,33 @@ interface TypedTable<T extends TableDef> {
      * if (row === undefined) throw new Conflict("yetersiz bakiye");
      * ```
      */
-    updateMany(q: MutateInput<RowShape<T>, InsertShape<T>>): Promise<RowShape<T>[]>;
+    updateMany<const Q extends MutateInput<RowShape<T>, InsertShape<T>>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : RowShape<T>[]>;
     /** Delete every matching row; resolves to how many. Empty filter refused. */
     deleteMany(q: {
         where: WhereFilter<RowShape<T>> | SqlFragment;
     }): Promise<number>;
+    /**
+     * Toplama — `sum` / `avg` / `min` / `max` / `count`, isteğe bağlı `groupBy`.
+     *
+     * ```ts
+     * const r = await Database.public.entries.aggregate({
+     *   where: { account_id },
+     *   sum: ["amount_kurus"],
+     *   count: true,
+     * });
+     * r.sum.amount_kurus;   // string | null — KAYIPSIZ
+     * r.count;              // number
+     * ```
+     *
+     * `sum`/`avg` yalnız sayısal kolonlarda ve HER ZAMAN `string` döner: para JS
+     * `number`'ına uğradığı anda kesinliğini kaybeder. `| null` çünkü Postgres
+     * boş kümede NULL döndürür — "hiç satır yoktu" ile "toplam sıfırdı" farklı.
+     *
+     * `groupBy` verilirse dönüş bir DİZİ ve her satır grup kolonlarını taşır.
+     */
+    aggregate<const Q extends AggregateInput<RowShape<T>>>(q: Q): Promise<AggregateResult<Q, RowShape<T>>>;
     /** How many rows match. An empty filter is legitimate: counting is a read. */
     count(q?: {
         where?: WhereFilter<RowShape<T>> | SqlFragment;
@@ -3020,7 +3054,26 @@ type ColumnsComparableTo<Row, V> = {
  * `findMany`'nin `Row`'u bilmediği yolların ve jsonb kolonlarının hâli, ve
  * ikisinde de tipin söyleyebileceği bir şey yok.
  */
-type ColRefOf<Row, V = unknown> = [keyof Row] extends [never] ? never : [unknown] extends [V] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
+/**
+ * "Kısıt verilmedi" için AYRI bir işaret — `unknown` DEĞİL.
+ *
+ * Eskiden varsayılan `unknown`'dı ve dal `[unknown] extends [V]` ile
+ * seçiliyordu. Ama `jsonb` kolonlarının DEĞER TİPİ de `unknown`: yani gerçek
+ * bir jsonb kolonu "kısıt verilmedi" sanılıp TÜM kolonlarla karşılaştırılabilir
+ * hâle geliyordu. D-021 bunu "jsonb ↔ text derleniyor" diye kaydetmişti ve PG
+ * markası tek başına kapatmadı — `unknown & X` kesişimi `X`'e çöktüğü için
+ * jsonb markalanamıyor (markalamak kolonu daraltıp meşru yazmaları kırdı,
+ * gerçek projede ölçüldü).
+ *
+ * Ayrı bir işaretle iki durum artık ayrışıyor: kısıtsız yol kısıtsız kalıyor,
+ * jsonb ise KENDİ ailesine düşüyor — yani yalnız başka bir jsonb ile
+ * karşılaştırılabiliyor.
+ */
+declare const NO_CONSTRAINT: unique symbol;
+type NoColConstraint = {
+    readonly [NO_CONSTRAINT]: true;
+};
+type ColRefOf<Row, V = NoColConstraint> = [keyof Row] extends [never] ? never : [V] extends [NoColConstraint] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
 /**
  * Doğrulanmış, GÖMÜLEBİLİR bir SQL parçası (FR-018, FR-019).
  *
@@ -3281,6 +3334,15 @@ type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
 type MutateInput<Row, Insert, Rels = unknown> = {
     where: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
     set: SetShape<Insert>;
+    /**
+     * `false` verilirse SATIRLAR değil SAYI döner — `deleteMany` ile aynı şekil.
+     *
+     * ÖLÇÜLDÜ (200 bin satır, canlı pg16): `RETURNING *` sunucuda %55 daha
+     * pahalı (7,2 sn → 11,1 sn) ve JS'te 45 MB yığın tutuyor — satır başına 236
+     * bayt, yani bir milyon satırda 225 MB. Çoğu çağrı için dönen diziyi okumak
+     * DOĞRU ve varsayılan odur; toplu bir iş için çıkış yolu olması gerekiyordu.
+     */
+    returning?: boolean;
 };
 /**
  * `set`'e yazılabilen değer (FR-012): kolonun kendi tipi ya da — sayısal
@@ -3391,6 +3453,64 @@ type RecommendParamsTyped<T extends TableTypes> = SimilarParamsTyped<T> & {
 type RelsOf<T> = T extends {
     relations: infer R;
 } ? R : unknown;
+/**
+ * TOPLAMA — dönüş tipi PG markasından TÜRETİLİR, tahmin edilmez.
+ *
+ * Para bu SDK'dan geçecek, ve toplamada kaybedilecek tek şey kesinliktir:
+ * `sum(numeric)` Postgres'te `numeric`, `sum(integer)` `bigint` — İKİSİ DE JS
+ * `number`'ında kayıplı. Bu yüzden `sum`/`avg` HER ZAMAN `string` döner ve
+ * motor `::text` ile döker. D-007'nin kapattığı hata buydu:
+ * 41.00821234567890123 canlıda 41.0082123456789 oluyordu.
+ *
+ * `| null` bir süs değil: Postgres BOŞ kümede NULL döndürür, 0 değil. "Hiç
+ * satır yoktu" ile "toplam sıfırdı" farklı şeyler, ve tip bunu sormaya
+ * ZORLUYOR.
+ */
+type SummableCols<Row> = {
+    [K in keyof Row]-?: "?" extends PgTag<Row[K]> ? NonNullable<Row[K]> extends number | string ? K : never : PgKind<PgTag<Row[K]>> extends "num" ? K : never;
+}[keyof Row];
+/** `min`/`max` sıralanabilir her kolonda — jsonb ve vektör hariç. */
+type OrderableCols<Row> = {
+    [K in keyof Row]-?: "?" extends PgTag<Row[K]> ? NonNullable<Row[K]> extends number | string | Date ? K : never : PgTag<Row[K]> extends "jsonb" | "vector" ? never : K;
+}[keyof Row];
+type AggCols<Row> = Extract<SummableCols<Row>, string>;
+type AggOrderCols<Row> = Extract<OrderableCols<Row>, string>;
+type AggregateInput<Row, Rels = unknown> = {
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
+    /** Toplam — yalnız sayısal kolonlarda; sonuç `string | null` (kayıpsız). */
+    sum?: readonly AggCols<Row>[];
+    /** Ortalama — sonuç `numeric`, yani `string | null`. */
+    avg?: readonly AggCols<Row>[];
+    min?: readonly AggOrderCols<Row>[];
+    max?: readonly AggOrderCols<Row>[];
+    /** Kaç satır — `count()` ile aynı sayı, ama AYNI turda. */
+    count?: boolean;
+    /** Verilirse SATIRLAR döner ve her satır grup kolonlarını taşır. */
+    groupBy?: readonly Extract<keyof Row, string>[];
+};
+type AggPart<Q, Row, F extends "sum" | "avg" | "min" | "max"> = Q extends {
+    [K in F]: readonly (infer C extends keyof Row)[];
+} ? {
+    [P in C]: F extends "sum" | "avg" ? string | null : Row[P] | null;
+} : never;
+type AggBody<Q, Row> = ([AggPart<Q, Row, "sum">] extends [never] ? unknown : {
+    sum: AggPart<Q, Row, "sum">;
+}) & ([AggPart<Q, Row, "avg">] extends [never] ? unknown : {
+    avg: AggPart<Q, Row, "avg">;
+}) & ([AggPart<Q, Row, "min">] extends [never] ? unknown : {
+    min: AggPart<Q, Row, "min">;
+}) & ([AggPart<Q, Row, "max">] extends [never] ? unknown : {
+    max: AggPart<Q, Row, "max">;
+}) & (Q extends {
+    count: true;
+} ? {
+    count: number;
+} : unknown);
+type AggregateResult<Q, Row> = Q extends {
+    groupBy: readonly (infer G extends keyof Row)[];
+} ? ({
+    [P in G]: Row[P];
+} & AggBody<Q, Row>)[] : AggBody<Q, Row>;
 /** Temel tablo erişimcisi — search'süz beş op. */
 interface EnvTypedTableBase<T extends TableTypes> {
     insert(data: InsertValues<T["insert"]>): Promise<T["row"]>;
@@ -3489,11 +3609,34 @@ interface EnvTypedTableBase<T extends TableTypes> {
      * if (row === undefined) throw new Conflict("yetersiz bakiye");
      * ```
      */
-    updateMany(q: MutateInput<T["row"], T["insert"], RelsOf<T>>): Promise<T["row"][]>;
+    updateMany<const Q extends MutateInput<T["row"], T["insert"], RelsOf<T>>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : T["row"][]>;
     /** Delete every matching row; resolves to how many. Empty filter refused. */
     deleteMany(q: {
         where: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
     }): Promise<number>;
+    /**
+     * Toplama — `sum` / `avg` / `min` / `max` / `count`, isteğe bağlı `groupBy`.
+     *
+     * ```ts
+     * const r = await Database.public.entries.aggregate({
+     *   where: { account_id },
+     *   sum: ["amount_kurus"],
+     *   count: true,
+     * });
+     * r.sum.amount_kurus;   // string | null — KAYIPSIZ
+     * r.count;              // number
+     * ```
+     *
+     * `sum`/`avg` yalnız sayısal kolonlarda ve HER ZAMAN `string` döner: para JS
+     * `number`'ına uğradığı anda kesinliğini kaybeder. `| null` çünkü Postgres
+     * boş kümede NULL döndürür — "hiç satır yoktu" ile "toplam sıfırdı" farklı
+     * şeyler ve tip bunu sormaya zorluyor.
+     *
+     * `groupBy` verilirse dönüş bir DİZİ ve her satır grup kolonlarını taşır.
+     */
+    aggregate<const Q extends AggregateInput<T["row"], RelsOf<T>>>(q: Q): Promise<AggregateResult<Q, T["row"]>>;
     /** How many rows match. An empty filter is legitimate: counting is a read. */
     count(q?: {
         where?: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
@@ -4441,6 +4584,15 @@ interface DBOps {
     /** Çok satır, TEK statement. Satırların anahtar kümesi aynı olmalı — kolon
      *  listesi paylaşıldığı için farklı şekilli bir satırın kolonu sessizce
      *  yazılmazdı. */
+    aggregate(table: string, q: {
+        where?: Record<string, unknown>;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: {
         onConflict: readonly string[];
         action?: "ignore" | "update";
@@ -4518,7 +4670,9 @@ interface DBOps {
      * yetmedi) — ikisini ayıran tek şey dönen dizidir. Çağrı hata fırlatmadı diye
      * işlem oldu SAYILAMAZ; kontrol çağıranın işi.
      */
-    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>, opts?: {
+        returning?: boolean;
+    }): Promise<Record<string, unknown>[] | number>;
     /**
      * Bir idempotency anahtarını sahiplen (FR-033).
      *

package/dist/{index-BbvOoZFr.d.ts → index-BYDUKexK.d.ts}

@@ -1,6 +1,6 @@
-import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-dTTLlHIn.js';
+import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-BOe82fsK.js';
 import { T as Token } from './module-Dl1KFVtc.js';
-import { R as RouteMeta } from './registry-JQNIX-eA.js';
+import { R as RouteMeta } from './registry-DaqHsOq8.js';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -291,7 +291,9 @@ declare function createOps(tx: TxLike): {
      * should not silently succeed. Callers who mean every row say so with a
      * predicate that is true for every row.
      */
-    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    updateMany(table: string, where: Row, set: Row, opts?: {
+        returning?: boolean;
+    }): Promise<Row[] | number>;
     /**
      * Delete every row the filter matches, in ONE statement; resolves to how
      * many went. Same filter language, same empty-filter refusal as
@@ -307,6 +309,27 @@ declare function createOps(tx: TxLike): {
      * An empty filter is legitimate HERE: counting a whole table is a read, and
      * reads do not destroy anything.
      */
+    /**
+     * Toplama — `count`'un yanına `sum`/`avg`/`min`/`max` ve `groupBy`.
+     *
+     * Var olma nedeni: bunlar olmadan "bu hesabın toplamı" ya `$query`'ye ya da
+     * TÜM satırları çekip JS'te toplamaya düşüyor. İkincisi hem N+1 hem de para
+     * için YANLIŞ — `numeric` JS `number`'ına uğradığı anda kesinliğini
+     * kaybeder.
+     *
+     * `groupBy` verilirse SATIRLAR döner, verilmezse TEK sonuç. Boş kümede
+     * Postgres NULL döndürür, 0 değil — ve bu SDK onu `null` olarak geçiriyor:
+     * "hiç satır yoktu" ile "toplam sıfırdı" farklı şeyler.
+     */
+    aggregate(table: string, q?: {
+        where?: Row;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
@@ -809,6 +832,9 @@ declare class AuthVerifier {
 interface EffectiveAuth {
     required: boolean;
     role?: string;
+    /** The permission the route demands, as `resource.action`. Resolved against
+     * `auth.has_permission(...)` at the gate — see AuthConfig.permission. */
+    permission?: string;
     verifiedEmail: boolean;
 }
 /**
@@ -1028,10 +1054,6 @@ interface App {
      */
     readonly container: Container;
 }
-/**
- * Build the app. Fails fast: the database is reached here, at boot, rather than
- * on the first request that needs it.
- */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
 export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };

package/dist/{index-9C3JHxg-.d.cts → index-BZfmdRmh.d.cts}

@@ -1,6 +1,6 @@
-import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DtISj9QX.cjs';
+import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-ChvoVczS.cjs';
 import { T as Token } from './module-Dl1KFVtc.cjs';
-import { R as RouteMeta } from './registry-qIPM5BQe.cjs';
+import { R as RouteMeta } from './registry-B2KfKWv1.cjs';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -291,7 +291,9 @@ declare function createOps(tx: TxLike): {
      * should not silently succeed. Callers who mean every row say so with a
      * predicate that is true for every row.
      */
-    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    updateMany(table: string, where: Row, set: Row, opts?: {
+        returning?: boolean;
+    }): Promise<Row[] | number>;
     /**
      * Delete every row the filter matches, in ONE statement; resolves to how
      * many went. Same filter language, same empty-filter refusal as
@@ -307,6 +309,27 @@ declare function createOps(tx: TxLike): {
      * An empty filter is legitimate HERE: counting a whole table is a read, and
      * reads do not destroy anything.
      */
+    /**
+     * Toplama — `count`'un yanına `sum`/`avg`/`min`/`max` ve `groupBy`.
+     *
+     * Var olma nedeni: bunlar olmadan "bu hesabın toplamı" ya `$query`'ye ya da
+     * TÜM satırları çekip JS'te toplamaya düşüyor. İkincisi hem N+1 hem de para
+     * için YANLIŞ — `numeric` JS `number`'ına uğradığı anda kesinliğini
+     * kaybeder.
+     *
+     * `groupBy` verilirse SATIRLAR döner, verilmezse TEK sonuç. Boş kümede
+     * Postgres NULL döndürür, 0 değil — ve bu SDK onu `null` olarak geçiriyor:
+     * "hiç satır yoktu" ile "toplam sıfırdı" farklı şeyler.
+     */
+    aggregate(table: string, q?: {
+        where?: Row;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
@@ -809,6 +832,9 @@ declare class AuthVerifier {
 interface EffectiveAuth {
     required: boolean;
     role?: string;
+    /** The permission the route demands, as `resource.action`. Resolved against
+     * `auth.has_permission(...)` at the gate — see AuthConfig.permission. */
+    permission?: string;
     verifiedEmail: boolean;
 }
 /**
@@ -1028,10 +1054,6 @@ interface App {
      */
     readonly container: Container;
 }
-/**
- * Build the app. Fails fast: the database is reached here, at boot, rather than
- * on the first request that needs it.
- */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
 export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };

package/dist/{index-DtISj9QX.d.cts → index-ChvoVczS.d.cts}

@@ -51,12 +51,24 @@ interface User {
 interface AuthConfig {
     /** Whether authentication is required. Defaults to true. */
     required: boolean;
-    /** Required role for access. If undefined, any authenticated user is allowed.
+    /** Required application role for access. If undefined, any authenticated user is allowed.
      *
-     * Matched against the caller's `metadata.role` — NOT `user.role`, which is the
-     * database role RLS reads and is always "authenticated" for a signed-in user.
-     * Not signed in → 401; signed in with a different or missing role → 403. */
+     * Matched against the caller's rows in `auth.user_roles` — NOT against the
+     * `role` claim, which is the DATABASE role RLS reads and is the literal
+     * string "authenticated" for every signed-in user. Reading it from the table
+     * is what makes a revoked role take effect on the very NEXT request instead
+     * of whenever the token happens to expire.
+     *
+     * Not signed in → 401; signed in without the role → 403. */
     role?: string;
+    /** Required permission for access, as `resource.action` (e.g. "posts.delete_any").
+     *
+     * Resolved through `auth.has_permission(...)`, which answers from the roles
+     * the caller holds and the permissions those roles carry. The query runs in
+     * the request's own transaction, so it costs no extra connection.
+     *
+     * Signed in without the permission → 403. */
+    permission?: string;
     /** Require a confirmed email address. An unverified caller gets 403
      * `email_not_verified`. Fences a whole controller; for a partial rule read
      * `user.emailVerified` in the handler instead. */
@@ -2864,11 +2876,33 @@ interface TypedTable<T extends TableDef> {
      * if (row === undefined) throw new Conflict("yetersiz bakiye");
      * ```
      */
-    updateMany(q: MutateInput<RowShape<T>, InsertShape<T>>): Promise<RowShape<T>[]>;
+    updateMany<const Q extends MutateInput<RowShape<T>, InsertShape<T>>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : RowShape<T>[]>;
     /** Delete every matching row; resolves to how many. Empty filter refused. */
     deleteMany(q: {
         where: WhereFilter<RowShape<T>> | SqlFragment;
     }): Promise<number>;
+    /**
+     * Toplama — `sum` / `avg` / `min` / `max` / `count`, isteğe bağlı `groupBy`.
+     *
+     * ```ts
+     * const r = await Database.public.entries.aggregate({
+     *   where: { account_id },
+     *   sum: ["amount_kurus"],
+     *   count: true,
+     * });
+     * r.sum.amount_kurus;   // string | null — KAYIPSIZ
+     * r.count;              // number
+     * ```
+     *
+     * `sum`/`avg` yalnız sayısal kolonlarda ve HER ZAMAN `string` döner: para JS
+     * `number`'ına uğradığı anda kesinliğini kaybeder. `| null` çünkü Postgres
+     * boş kümede NULL döndürür — "hiç satır yoktu" ile "toplam sıfırdı" farklı.
+     *
+     * `groupBy` verilirse dönüş bir DİZİ ve her satır grup kolonlarını taşır.
+     */
+    aggregate<const Q extends AggregateInput<RowShape<T>>>(q: Q): Promise<AggregateResult<Q, RowShape<T>>>;
     /** How many rows match. An empty filter is legitimate: counting is a read. */
     count(q?: {
         where?: WhereFilter<RowShape<T>> | SqlFragment;
@@ -3020,7 +3054,26 @@ type ColumnsComparableTo<Row, V> = {
  * `findMany`'nin `Row`'u bilmediği yolların ve jsonb kolonlarının hâli, ve
  * ikisinde de tipin söyleyebileceği bir şey yok.
  */
-type ColRefOf<Row, V = unknown> = [keyof Row] extends [never] ? never : [unknown] extends [V] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
+/**
+ * "Kısıt verilmedi" için AYRI bir işaret — `unknown` DEĞİL.
+ *
+ * Eskiden varsayılan `unknown`'dı ve dal `[unknown] extends [V]` ile
+ * seçiliyordu. Ama `jsonb` kolonlarının DEĞER TİPİ de `unknown`: yani gerçek
+ * bir jsonb kolonu "kısıt verilmedi" sanılıp TÜM kolonlarla karşılaştırılabilir
+ * hâle geliyordu. D-021 bunu "jsonb ↔ text derleniyor" diye kaydetmişti ve PG
+ * markası tek başına kapatmadı — `unknown & X` kesişimi `X`'e çöktüğü için
+ * jsonb markalanamıyor (markalamak kolonu daraltıp meşru yazmaları kırdı,
+ * gerçek projede ölçüldü).
+ *
+ * Ayrı bir işaretle iki durum artık ayrışıyor: kısıtsız yol kısıtsız kalıyor,
+ * jsonb ise KENDİ ailesine düşüyor — yani yalnız başka bir jsonb ile
+ * karşılaştırılabiliyor.
+ */
+declare const NO_CONSTRAINT: unique symbol;
+type NoColConstraint = {
+    readonly [NO_CONSTRAINT]: true;
+};
+type ColRefOf<Row, V = NoColConstraint> = [keyof Row] extends [never] ? never : [V] extends [NoColConstraint] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
 /**
  * Doğrulanmış, GÖMÜLEBİLİR bir SQL parçası (FR-018, FR-019).
  *
@@ -3281,6 +3334,15 @@ type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
 type MutateInput<Row, Insert, Rels = unknown> = {
     where: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
     set: SetShape<Insert>;
+    /**
+     * `false` verilirse SATIRLAR değil SAYI döner — `deleteMany` ile aynı şekil.
+     *
+     * ÖLÇÜLDÜ (200 bin satır, canlı pg16): `RETURNING *` sunucuda %55 daha
+     * pahalı (7,2 sn → 11,1 sn) ve JS'te 45 MB yığın tutuyor — satır başına 236
+     * bayt, yani bir milyon satırda 225 MB. Çoğu çağrı için dönen diziyi okumak
+     * DOĞRU ve varsayılan odur; toplu bir iş için çıkış yolu olması gerekiyordu.
+     */
+    returning?: boolean;
 };
 /**
  * `set`'e yazılabilen değer (FR-012): kolonun kendi tipi ya da — sayısal
@@ -3391,6 +3453,64 @@ type RecommendParamsTyped<T extends TableTypes> = SimilarParamsTyped<T> & {
 type RelsOf<T> = T extends {
     relations: infer R;
 } ? R : unknown;
+/**
+ * TOPLAMA — dönüş tipi PG markasından TÜRETİLİR, tahmin edilmez.
+ *
+ * Para bu SDK'dan geçecek, ve toplamada kaybedilecek tek şey kesinliktir:
+ * `sum(numeric)` Postgres'te `numeric`, `sum(integer)` `bigint` — İKİSİ DE JS
+ * `number`'ında kayıplı. Bu yüzden `sum`/`avg` HER ZAMAN `string` döner ve
+ * motor `::text` ile döker. D-007'nin kapattığı hata buydu:
+ * 41.00821234567890123 canlıda 41.0082123456789 oluyordu.
+ *
+ * `| null` bir süs değil: Postgres BOŞ kümede NULL döndürür, 0 değil. "Hiç
+ * satır yoktu" ile "toplam sıfırdı" farklı şeyler, ve tip bunu sormaya
+ * ZORLUYOR.
+ */
+type SummableCols<Row> = {
+    [K in keyof Row]-?: "?" extends PgTag<Row[K]> ? NonNullable<Row[K]> extends number | string ? K : never : PgKind<PgTag<Row[K]>> extends "num" ? K : never;
+}[keyof Row];
+/** `min`/`max` sıralanabilir her kolonda — jsonb ve vektör hariç. */
+type OrderableCols<Row> = {
+    [K in keyof Row]-?: "?" extends PgTag<Row[K]> ? NonNullable<Row[K]> extends number | string | Date ? K : never : PgTag<Row[K]> extends "jsonb" | "vector" ? never : K;
+}[keyof Row];
+type AggCols<Row> = Extract<SummableCols<Row>, string>;
+type AggOrderCols<Row> = Extract<OrderableCols<Row>, string>;
+type AggregateInput<Row, Rels = unknown> = {
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
+    /** Toplam — yalnız sayısal kolonlarda; sonuç `string | null` (kayıpsız). */
+    sum?: readonly AggCols<Row>[];
+    /** Ortalama — sonuç `numeric`, yani `string | null`. */
+    avg?: readonly AggCols<Row>[];
+    min?: readonly AggOrderCols<Row>[];
+    max?: readonly AggOrderCols<Row>[];
+    /** Kaç satır — `count()` ile aynı sayı, ama AYNI turda. */
+    count?: boolean;
+    /** Verilirse SATIRLAR döner ve her satır grup kolonlarını taşır. */
+    groupBy?: readonly Extract<keyof Row, string>[];
+};
+type AggPart<Q, Row, F extends "sum" | "avg" | "min" | "max"> = Q extends {
+    [K in F]: readonly (infer C extends keyof Row)[];
+} ? {
+    [P in C]: F extends "sum" | "avg" ? string | null : Row[P] | null;
+} : never;
+type AggBody<Q, Row> = ([AggPart<Q, Row, "sum">] extends [never] ? unknown : {
+    sum: AggPart<Q, Row, "sum">;
+}) & ([AggPart<Q, Row, "avg">] extends [never] ? unknown : {
+    avg: AggPart<Q, Row, "avg">;
+}) & ([AggPart<Q, Row, "min">] extends [never] ? unknown : {
+    min: AggPart<Q, Row, "min">;
+}) & ([AggPart<Q, Row, "max">] extends [never] ? unknown : {
+    max: AggPart<Q, Row, "max">;
+}) & (Q extends {
+    count: true;
+} ? {
+    count: number;
+} : unknown);
+type AggregateResult<Q, Row> = Q extends {
+    groupBy: readonly (infer G extends keyof Row)[];
+} ? ({
+    [P in G]: Row[P];
+} & AggBody<Q, Row>)[] : AggBody<Q, Row>;
 /** Temel tablo erişimcisi — search'süz beş op. */
 interface EnvTypedTableBase<T extends TableTypes> {
     insert(data: InsertValues<T["insert"]>): Promise<T["row"]>;
@@ -3489,11 +3609,34 @@ interface EnvTypedTableBase<T extends TableTypes> {
      * if (row === undefined) throw new Conflict("yetersiz bakiye");
      * ```
      */
-    updateMany(q: MutateInput<T["row"], T["insert"], RelsOf<T>>): Promise<T["row"][]>;
+    updateMany<const Q extends MutateInput<T["row"], T["insert"], RelsOf<T>>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : T["row"][]>;
     /** Delete every matching row; resolves to how many. Empty filter refused. */
     deleteMany(q: {
         where: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
     }): Promise<number>;
+    /**
+     * Toplama — `sum` / `avg` / `min` / `max` / `count`, isteğe bağlı `groupBy`.
+     *
+     * ```ts
+     * const r = await Database.public.entries.aggregate({
+     *   where: { account_id },
+     *   sum: ["amount_kurus"],
+     *   count: true,
+     * });
+     * r.sum.amount_kurus;   // string | null — KAYIPSIZ
+     * r.count;              // number
+     * ```
+     *
+     * `sum`/`avg` yalnız sayısal kolonlarda ve HER ZAMAN `string` döner: para JS
+     * `number`'ına uğradığı anda kesinliğini kaybeder. `| null` çünkü Postgres
+     * boş kümede NULL döndürür — "hiç satır yoktu" ile "toplam sıfırdı" farklı
+     * şeyler ve tip bunu sormaya zorluyor.
+     *
+     * `groupBy` verilirse dönüş bir DİZİ ve her satır grup kolonlarını taşır.
+     */
+    aggregate<const Q extends AggregateInput<T["row"], RelsOf<T>>>(q: Q): Promise<AggregateResult<Q, T["row"]>>;
     /** How many rows match. An empty filter is legitimate: counting is a read. */
     count(q?: {
         where?: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
@@ -4441,6 +4584,15 @@ interface DBOps {
     /** Çok satır, TEK statement. Satırların anahtar kümesi aynı olmalı — kolon
      *  listesi paylaşıldığı için farklı şekilli bir satırın kolonu sessizce
      *  yazılmazdı. */
+    aggregate(table: string, q: {
+        where?: Record<string, unknown>;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: {
         onConflict: readonly string[];
         action?: "ignore" | "update";
@@ -4518,7 +4670,9 @@ interface DBOps {
      * yetmedi) — ikisini ayıran tek şey dönen dizidir. Çağrı hata fırlatmadı diye
      * işlem oldu SAYILAMAZ; kontrol çağıranın işi.
      */
-    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>, opts?: {
+        returning?: boolean;
+    }): Promise<Record<string, unknown>[] | number>;
     /**
      * Bir idempotency anahtarını sahiplen (FR-033).
      *