@palbase/backend 22.0.1 → 23.0.0

package/dist/db/index.js

@@ -10,12 +10,14 @@ import {
   isPalbaseExtension,
   jsonb,
   makeTypedDB,
+  openai,
   policy,
   raw,
   text,
   timestamp,
-  uuid
-} from "../chunk-SSGAMC26.js";
+  uuid,
+  vector
+} from "../chunk-HAF67F2H.js";
 import {
   TxPlanError,
   TxRefError,
@@ -41,10 +43,12 @@ export {
   jsonb,
   makeTypedDB,
   now,
+  openai,
   policy,
   raw,
   text,
   timestamp,
-  uuid
+  uuid,
+  vector
 };
 //# sourceMappingURL=index.js.map

package/dist/{endpoint-B0LpZixz.d.cts → endpoint-BavvbW4P.d.ts}

@@ -1,4 +1,5 @@
 import { ZodSchema, z } from 'zod';
+import { PalbaseFlagKey, PalbaseSecretName } from './stack.js';
 
 /** Supported HTTP methods for endpoints. */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -1471,11 +1472,11 @@ interface PalbaseFlagsServiceClient {
      * Set (or replace) a single feature-flag override for one user. The override
      * shadows the project (system) default for that user until cleared.
      */
-    setOverrideForUser(userId: string, key: string, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    setOverrideForUser(userId: string, key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
     /** Set multiple overrides for one user in a single call. */
     setOverridesForUser(userId: string, values: Record<string, PalbaseFlagValue>): Promise<PalbaseResult<PalbaseSetOverridesResult>>;
     /** Clear one override for a user, restoring the project (system) default. */
-    clearOverrideForUser(userId: string, key: string): Promise<PalbaseResult<PalbaseClearOverrideResult>>;
+    clearOverrideForUser(userId: string, key: PalbaseFlagKey): Promise<PalbaseResult<PalbaseClearOverrideResult>>;
     /** Clear all overrides for a user, restoring project (system) defaults. */
     clearAllOverridesForUser(userId: string): Promise<PalbaseResult<PalbaseClearAllOverridesResult>>;
     /** Apply override writes across many users in one request (max 1000 ops). */
@@ -1499,9 +1500,9 @@ interface PalbaseFlagsServiceClient {
  */
 interface PalbaseFlagsClient {
     /** Is a flag enabled for the given context? */
-    isEnabled(flagName: string, context?: PalbaseFlagContext): Promise<PalbaseResult<boolean>>;
+    isEnabled(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<boolean>>;
     /** Get the active variant of a multivariate flag. */
-    getVariant(flagName: string, context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagVariant>>;
+    getVariant(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagVariant>>;
     /** Get all flags for the project. */
     getAll(context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlag[]>>;
     /**
@@ -1518,7 +1519,7 @@ interface PalbaseFlagsClient {
      * `Documents.doc(...)` — declared and never implemented — seen from the other
      * side, and moving the implementation into this package is what surfaced it.
      */
-    get(flagName: string, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagValue>>;
+    get(flagName: PalbaseFlagKey, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagValue>>;
     /**
      * Set (or replace) a single feature-flag override for the CURRENT REQUEST
      * USER. No userId argument — the override is bound to the signed-in user the
@@ -1533,7 +1534,7 @@ interface PalbaseFlagsClient {
      * @example
      * await Flags.setOverride("new_checkout", true);
      */
-    setOverride(key: string, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    setOverride(key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
     /**
      * Return the cross-user admin write surface ({@link PalbaseFlagsServiceClient}).
      * Use sparingly and explicitly — the default `Flags.setOverride(...)` path is
@@ -1562,6 +1563,22 @@ interface PalbaseFlagsClient {
  * await Realtime.broadcast("room:42", "message", { text, from: user.id });
  */
 interface PalbaseRealtimeClient {
+    /**
+     * A channel's SHARED STATE — a keyed map every subscriber sees, including
+     * the ones that join later.
+     *
+     * That is the whole difference from `broadcast`: a broadcast reaches whoever
+     * is listening at that instant, and a client connecting a second afterwards
+     * learns nothing until the next one. State is handed to every joiner in the
+     * snapshot they get, so "the score is 3-1" or "this flag is now on" arrives
+     * even for a client that was not there when it changed.
+     */
+    state: {
+        /** Write one entry. Fire-and-forget, like `broadcast`. */
+        set(topic: string, key: string, value: Record<string, unknown>): Promise<PalbaseResult<void>>;
+        /** Remove one entry. */
+        clear(topic: string, key: string): Promise<PalbaseResult<void>>;
+    };
     /**
      * Broadcast `event` with `payload` to everyone subscribed to `channel`.
      *
@@ -1811,7 +1828,72 @@ interface DBOps {
     update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
+    /** Hibrit arama (FR-013/014) — tek SQL, RRF; engine implement eder (T017). */
+    search(table: string, params?: {
+        query?: string;
+        vector?: number[];
+        where?: Record<string, unknown>;
+        limit?: number;
+        using?: string;
+        mode?: "hybrid" | "text" | "vector";
+        /** Nihai (RRF-sonrası) skor alt eşiği (FR-001). */
+        minScore?: number;
+        /** RRF-sonrası üstel tazelik çürümesi (FR-004; feed/haber düğmesi). */
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        /** Chunk-modunda satır başına en iyi blok sayısı (FR-015). */
+        blocksPerRow?: number;
+        /** Kolon başına top-20 değer sayacı — dönüş dizisinin `_facets` özelliği (FR-027). */
+        facets?: string[];
+        /** Satır-modunda ts_headline vurgusu: satırlara `_highlight` (FR-025; chunk-modda no-op). */
+        highlight?: boolean;
+        /** Validity'li tabloda zaman penceresi: vars. yalnız güncel; "all" tümü; {asOf} o an (FR-029). */
+        validity?: "all" | {
+            asOf: string;
+        };
+        /** Alan-boost (FR-030): skor * (1 + w·x/(1+x)) — sınırlı çarpan, dış servissiz. */
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** Validity'li tabloda satırın yeni versiyonu — eski kapanır (valid_to/superseded_by),
+     * yenisi eklenir; TEK savepoint, dönüş yeni satır (FR-029, C-9). */
+    supersede(table: string, id: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /** "Bu satıra benzer satırlar" (FR-022) — satır-modunda kolon vektörüyle,
+     * chunk-modunda chunk-ortalamasıyla; kendisi hariç. */
+    similar(table: string, id: string, opts?: {
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** Çok-örnekli öneri (FR-023): avg(pos) + (avg(pos) − avg(neg)); positive'ler sonuç dışı. */
+    recommend(table: string, opts: {
+        positive: string[];
+        negative?: string[];
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
 }
 /** Database client interface injected into endpoint context. */
 interface DBClient extends DBOps {
@@ -1868,7 +1950,20 @@ interface Logger {
  * a restart and a hot path pays a map lookup.
  */
 interface SecretsService {
-    get(name: string): Promise<string | null>;
+    /**
+     * A secret's value, or `null` when this backend's vault holds no value under
+     * that name.
+     *
+     * The name is a `PalbaseSecretName`, not a `string`: it comes from the
+     * generated `palbase-stack.d.ts`, so a secret the stack does not hold cannot
+     * be spelled here at all. THE GATE IS THE COMPILER.
+     *
+     * That gate replaced a declaration. `config/secrets.ts` used to restate, in
+     * the repo, names the vault already held, and the push compared the two lists
+     * — a check that only ran at deploy, and only if the author remembered to
+     * declare. The type runs on every keystroke and cannot be forgotten.
+     */
+    get(name: PalbaseSecretName): Promise<string | null>;
 }
 interface CacheClient {
     /** Read a value. Returns `null` on a cache miss. */
@@ -1963,19 +2058,26 @@ interface PalbaseDocsClient {
 }
 /** Calling-client metadata, derived from request headers.
  *
- * Populated from the `X-Palbase-*-Version` / platform headers the client SDKs
- * send. All fields are nullable: a request may come from a non-SDK caller
- * (curl, server-to-server) that sends none of them. The semver comparison
- * helpers (`appVersionAtLeast`, …) arrive in Phase 2 — Phase 1 surfaces only
- * the raw data fields. */
+ * Every header is named here, because the previous version of this comment named
+ * only two of the four and the next reader invented `X-Palbase-Platform` for the
+ * third. The four are canonical across the platform — the same names the Go
+ * side reads in user-flags/internal/middleware/clientcontext.go — and the deploy
+ * gate REFUSES an `@Headers` schema that declares an `x-palbase-*` key, which
+ * makes `@Client()` the only sanctioned way to read them.
+ *
+ * All fields are nullable: a request may come from a non-SDK caller (curl,
+ * server-to-server) that sends none of them. Note that the web SDK does not
+ * send `X-Palbase-Sdk-Version` at all, so `sdkVersion` is null for every browser
+ * caller. The semver comparison helpers (`appVersionAtLeast`, …) arrive in
+ * Phase 2 — Phase 1 surfaces only the raw data fields. */
 interface ClientInfo {
     /** Palbase SDK version (`X-Palbase-Sdk-Version`), or null. */
     sdkVersion: string | null;
     /** Calling app's own version (`X-Palbase-Client-Version`), or null. */
     appVersion: string | null;
-    /** Platform identifier (e.g. "ios", "android", "web"), or null. */
+    /** Platform identifier (`X-Platform`, e.g. "ios", "android", "web"), or null. */
     platform: string | null;
-    /** OS version string, or null. */
+    /** OS version string (`X-OS-Version`), or null. */
     osVersion: string | null;
 }
 /** Palbase module clients, as a structural bundle.

package/dist/{endpoint-B0LpZixz.d.ts → endpoint-i8TTCohk.d.cts}

@@ -1,4 +1,5 @@
 import { ZodSchema, z } from 'zod';
+import { PalbaseFlagKey, PalbaseSecretName } from './stack.cjs';
 
 /** Supported HTTP methods for endpoints. */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -1471,11 +1472,11 @@ interface PalbaseFlagsServiceClient {
      * Set (or replace) a single feature-flag override for one user. The override
      * shadows the project (system) default for that user until cleared.
      */
-    setOverrideForUser(userId: string, key: string, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    setOverrideForUser(userId: string, key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
     /** Set multiple overrides for one user in a single call. */
     setOverridesForUser(userId: string, values: Record<string, PalbaseFlagValue>): Promise<PalbaseResult<PalbaseSetOverridesResult>>;
     /** Clear one override for a user, restoring the project (system) default. */
-    clearOverrideForUser(userId: string, key: string): Promise<PalbaseResult<PalbaseClearOverrideResult>>;
+    clearOverrideForUser(userId: string, key: PalbaseFlagKey): Promise<PalbaseResult<PalbaseClearOverrideResult>>;
     /** Clear all overrides for a user, restoring project (system) defaults. */
     clearAllOverridesForUser(userId: string): Promise<PalbaseResult<PalbaseClearAllOverridesResult>>;
     /** Apply override writes across many users in one request (max 1000 ops). */
@@ -1499,9 +1500,9 @@ interface PalbaseFlagsServiceClient {
  */
 interface PalbaseFlagsClient {
     /** Is a flag enabled for the given context? */
-    isEnabled(flagName: string, context?: PalbaseFlagContext): Promise<PalbaseResult<boolean>>;
+    isEnabled(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<boolean>>;
     /** Get the active variant of a multivariate flag. */
-    getVariant(flagName: string, context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagVariant>>;
+    getVariant(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagVariant>>;
     /** Get all flags for the project. */
     getAll(context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlag[]>>;
     /**
@@ -1518,7 +1519,7 @@ interface PalbaseFlagsClient {
      * `Documents.doc(...)` — declared and never implemented — seen from the other
      * side, and moving the implementation into this package is what surfaced it.
      */
-    get(flagName: string, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagValue>>;
+    get(flagName: PalbaseFlagKey, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagValue>>;
     /**
      * Set (or replace) a single feature-flag override for the CURRENT REQUEST
      * USER. No userId argument — the override is bound to the signed-in user the
@@ -1533,7 +1534,7 @@ interface PalbaseFlagsClient {
      * @example
      * await Flags.setOverride("new_checkout", true);
      */
-    setOverride(key: string, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    setOverride(key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
     /**
      * Return the cross-user admin write surface ({@link PalbaseFlagsServiceClient}).
      * Use sparingly and explicitly — the default `Flags.setOverride(...)` path is
@@ -1562,6 +1563,22 @@ interface PalbaseFlagsClient {
  * await Realtime.broadcast("room:42", "message", { text, from: user.id });
  */
 interface PalbaseRealtimeClient {
+    /**
+     * A channel's SHARED STATE — a keyed map every subscriber sees, including
+     * the ones that join later.
+     *
+     * That is the whole difference from `broadcast`: a broadcast reaches whoever
+     * is listening at that instant, and a client connecting a second afterwards
+     * learns nothing until the next one. State is handed to every joiner in the
+     * snapshot they get, so "the score is 3-1" or "this flag is now on" arrives
+     * even for a client that was not there when it changed.
+     */
+    state: {
+        /** Write one entry. Fire-and-forget, like `broadcast`. */
+        set(topic: string, key: string, value: Record<string, unknown>): Promise<PalbaseResult<void>>;
+        /** Remove one entry. */
+        clear(topic: string, key: string): Promise<PalbaseResult<void>>;
+    };
     /**
      * Broadcast `event` with `payload` to everyone subscribed to `channel`.
      *
@@ -1811,7 +1828,72 @@ interface DBOps {
     update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
+    /** Hibrit arama (FR-013/014) — tek SQL, RRF; engine implement eder (T017). */
+    search(table: string, params?: {
+        query?: string;
+        vector?: number[];
+        where?: Record<string, unknown>;
+        limit?: number;
+        using?: string;
+        mode?: "hybrid" | "text" | "vector";
+        /** Nihai (RRF-sonrası) skor alt eşiği (FR-001). */
+        minScore?: number;
+        /** RRF-sonrası üstel tazelik çürümesi (FR-004; feed/haber düğmesi). */
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        /** Chunk-modunda satır başına en iyi blok sayısı (FR-015). */
+        blocksPerRow?: number;
+        /** Kolon başına top-20 değer sayacı — dönüş dizisinin `_facets` özelliği (FR-027). */
+        facets?: string[];
+        /** Satır-modunda ts_headline vurgusu: satırlara `_highlight` (FR-025; chunk-modda no-op). */
+        highlight?: boolean;
+        /** Validity'li tabloda zaman penceresi: vars. yalnız güncel; "all" tümü; {asOf} o an (FR-029). */
+        validity?: "all" | {
+            asOf: string;
+        };
+        /** Alan-boost (FR-030): skor * (1 + w·x/(1+x)) — sınırlı çarpan, dış servissiz. */
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** Validity'li tabloda satırın yeni versiyonu — eski kapanır (valid_to/superseded_by),
+     * yenisi eklenir; TEK savepoint, dönüş yeni satır (FR-029, C-9). */
+    supersede(table: string, id: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /** "Bu satıra benzer satırlar" (FR-022) — satır-modunda kolon vektörüyle,
+     * chunk-modunda chunk-ortalamasıyla; kendisi hariç. */
+    similar(table: string, id: string, opts?: {
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** Çok-örnekli öneri (FR-023): avg(pos) + (avg(pos) − avg(neg)); positive'ler sonuç dışı. */
+    recommend(table: string, opts: {
+        positive: string[];
+        negative?: string[];
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
 }
 /** Database client interface injected into endpoint context. */
 interface DBClient extends DBOps {
@@ -1868,7 +1950,20 @@ interface Logger {
  * a restart and a hot path pays a map lookup.
  */
 interface SecretsService {
-    get(name: string): Promise<string | null>;
+    /**
+     * A secret's value, or `null` when this backend's vault holds no value under
+     * that name.
+     *
+     * The name is a `PalbaseSecretName`, not a `string`: it comes from the
+     * generated `palbase-stack.d.ts`, so a secret the stack does not hold cannot
+     * be spelled here at all. THE GATE IS THE COMPILER.
+     *
+     * That gate replaced a declaration. `config/secrets.ts` used to restate, in
+     * the repo, names the vault already held, and the push compared the two lists
+     * — a check that only ran at deploy, and only if the author remembered to
+     * declare. The type runs on every keystroke and cannot be forgotten.
+     */
+    get(name: PalbaseSecretName): Promise<string | null>;
 }
 interface CacheClient {
     /** Read a value. Returns `null` on a cache miss. */
@@ -1963,19 +2058,26 @@ interface PalbaseDocsClient {
 }
 /** Calling-client metadata, derived from request headers.
  *
- * Populated from the `X-Palbase-*-Version` / platform headers the client SDKs
- * send. All fields are nullable: a request may come from a non-SDK caller
- * (curl, server-to-server) that sends none of them. The semver comparison
- * helpers (`appVersionAtLeast`, …) arrive in Phase 2 — Phase 1 surfaces only
- * the raw data fields. */
+ * Every header is named here, because the previous version of this comment named
+ * only two of the four and the next reader invented `X-Palbase-Platform` for the
+ * third. The four are canonical across the platform — the same names the Go
+ * side reads in user-flags/internal/middleware/clientcontext.go — and the deploy
+ * gate REFUSES an `@Headers` schema that declares an `x-palbase-*` key, which
+ * makes `@Client()` the only sanctioned way to read them.
+ *
+ * All fields are nullable: a request may come from a non-SDK caller (curl,
+ * server-to-server) that sends none of them. Note that the web SDK does not
+ * send `X-Palbase-Sdk-Version` at all, so `sdkVersion` is null for every browser
+ * caller. The semver comparison helpers (`appVersionAtLeast`, …) arrive in
+ * Phase 2 — Phase 1 surfaces only the raw data fields. */
 interface ClientInfo {
     /** Palbase SDK version (`X-Palbase-Sdk-Version`), or null. */
     sdkVersion: string | null;
     /** Calling app's own version (`X-Palbase-Client-Version`), or null. */
     appVersion: string | null;
-    /** Platform identifier (e.g. "ios", "android", "web"), or null. */
+    /** Platform identifier (`X-Platform`, e.g. "ios", "android", "web"), or null. */
     platform: string | null;
-    /** OS version string, or null. */
+    /** OS version string (`X-OS-Version`), or null. */
     osVersion: string | null;
 }
 /** Palbase module clients, as a structural bundle.