@palbase/backend 22.0.1 → 22.1.0

package/dist/index.cjs

@@ -97,6 +97,7 @@ __export(src_exports, {
   buildModuleClients: () => buildModuleClients,
   buildProvider: () => buildProvider,
   dec: () => dec,
+  defineChannels: () => defineChannels,
   defineEgress: () => defineEgress,
   defineError: () => defineError,
   defineFlags: () => defineFlags,
@@ -126,8 +127,11 @@ __export(src_exports, {
   makeTypedDB: () => makeTypedDB,
   now: () => now,
   numeric: () => numeric,
+  openai: () => openai,
+  ownerOnly: () => ownerOnly,
   parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
+  publicChannel: () => publicChannel,
   raw: () => raw,
   recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
@@ -139,6 +143,7 @@ __export(src_exports, {
   toSchemaJSON: () => toSchemaJSON,
   uuid: () => uuid,
   validateUploadAgainstStorage: () => validateUploadAgainstStorage,
+  vector: () => vector,
   z: () => import_zod2.z
 });
 module.exports = __toCommonJS(src_exports);
@@ -595,7 +600,8 @@ function makeTablesAccessor(ops) {
           update: (id, data) => ops().update(name, id, data),
           delete: (id) => ops().delete(name, id),
           findById: (id) => ops().findById(name, id),
-          findMany: (query) => ops().findMany(name, query)
+          findMany: (query) => ops().findMany(name, query),
+          search: (params) => ops().search(name, params)
         };
       }
     }
@@ -610,7 +616,8 @@ function makeTypedSurface(raw2) {
     update: (table, id, data) => raw2.update(table, id, data),
     delete: (table, id) => raw2.delete(table, id),
     findById: (table, id) => raw2.findById(table, id),
-    findMany: (table, query) => raw2.findMany(table, query)
+    findMany: (table, query) => raw2.findMany(table, query),
+    search: (table, params) => raw2.search(table, params)
   };
   return Object.assign(ops, {
     tables: makeTablesAccessor(() => raw2),
@@ -1553,7 +1560,88 @@ function mintToken(secret2) {
 }
 function buildRealtimeClient(cfg) {
   const url = `${cfg.baseUrl}/realtime/api/broadcast`;
+  const stateUrl = `${cfg.baseUrl}/realtime/api/state`;
+  async function writeState(topic, key, value, del) {
+    if (typeof topic !== "string" || topic.length === 0) {
+      return {
+        data: null,
+        error: new PalbaseModuleError("invalid_argument", "topic must be a non-empty string", 400)
+      };
+    }
+    if (typeof key !== "string" || key.length === 0) {
+      return {
+        data: null,
+        error: new PalbaseModuleError("invalid_argument", "key must be a non-empty string", 400)
+      };
+    }
+    if (!cfg.apiJwtSecret) {
+      return {
+        data: null,
+        error: new PalbaseModuleError(
+          "realtime_unconfigured",
+          "Realtime.state is unavailable: realtime is not provisioned for this Environment (PALBASE_REALTIME_API_JWT_SECRET unset).",
+          503
+        )
+      };
+    }
+    let token;
+    try {
+      token = mintToken(cfg.apiJwtSecret);
+    } catch (err) {
+      return {
+        data: null,
+        error: new PalbaseModuleError(
+          "realtime_token_error",
+          err instanceof Error ? err.message : "token mint failed",
+          500
+        )
+      };
+    }
+    const op = del ? { topic, key, del: true } : { topic, key, value: value ?? {} };
+    const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+    let response;
+    try {
+      response = await doFetch(stateUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ ops: [op] })
+      });
+    } catch (err) {
+      return {
+        data: null,
+        error: new PalbaseModuleError(
+          "network_error",
+          err instanceof Error ? err.message : "state request failed",
+          0
+        )
+      };
+    }
+    if (response.status === 202 || response.status === 200) {
+      return { data: void 0, error: null };
+    }
+    const detail = await response.text().catch(() => "");
+    return {
+      data: null,
+      error: new PalbaseModuleError(
+        "realtime_state_failed",
+        `realtime state write returned ${response.status}${detail ? `: ${detail}` : ""}`,
+        response.status
+      )
+    };
+  }
   return {
+    state: {
+      /** Write one DURABLE entry on a channel's shared state.
+       *
+       * The difference from broadcast is WHO it reaches: a broadcast reaches
+       * whoever is listening at that instant, while state is also handed to
+       * whoever joins afterwards. "This value is now X" wants the second — a
+       * client connecting a second later should not have to wait for the next
+       * change to learn X. */
+      set: (topic, key, value) => writeState(topic, key, value, false),
+      /** Remove one entry. */
+      clear: (topic, key) => writeState(topic, key, void 0, true)
+    },
     async broadcast(channel, event, payload) {
       if (typeof channel !== "string" || channel.length === 0) {
         return {
@@ -1861,6 +1949,26 @@ function defineSchema(input) {
     if (table.raw !== void 0 && table.raw.length > 0) tableDef.raw = table.raw.slice();
     if (table.checks !== void 0 && table.checks.length > 0) tableDef.checks = table.checks.slice();
     if (table.indexes !== void 0 && table.indexes.length > 0) tableDef.indexes = table.indexes.slice();
+    if (table.search !== void 0) {
+      if (table.search.text === void 0 && table.search.vector === void 0) {
+        throw new Error(
+          `table ${String(name)}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
+        );
+      }
+      if (table.search.text !== void 0 && table.search.text.length === 0) {
+        throw new Error(`table ${String(name)}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
+      }
+      const legs = table.search.vector === void 0 ? [] : Array.isArray(table.search.vector) ? table.search.vector : [table.search.vector];
+      for (const leg of legs) {
+        if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
+          throw new Error(`table ${String(name)}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
+        }
+        if (leg.model === void 0 && leg.from !== void 0) {
+          throw new Error(`table ${String(name)}: search.vector.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin`);
+        }
+      }
+      tableDef.search = table.search;
+    }
     tables[name] = tableDef;
   }
   const extensions = [...new Set(input.extensions ?? [])];
@@ -1889,6 +1997,7 @@ function columnToJSON(column) {
   if (def.enumName !== void 0) out.enumName = def.enumName;
   if (def.enumValues !== void 0) out.enumValues = [...def.enumValues];
   if (def.unique === true) out.unique = true;
+  if (def.dimensions !== void 0) out.dimensions = def.dimensions;
   return out;
 }
 function policyToJSON(policy2) {
@@ -1904,6 +2013,30 @@ function policyToJSON(policy2) {
     permissive: policy2.permissive !== false
   };
 }
+function searchToJSON(search) {
+  const out = {};
+  if (search.text !== void 0 && search.text.length > 0) out.text = { columns: [...search.text] };
+  const legs = search.vector === void 0 ? [] : Array.isArray(search.vector) ? search.vector : [search.vector];
+  if (legs.length > 0) {
+    out.vector = legs.map((leg) => {
+      const v = { metric: leg.metric ?? "cosine" };
+      if (leg.column !== void 0) v.column = leg.column;
+      if (leg.staleness !== void 0) v.staleness = leg.staleness;
+      if (leg.model !== void 0) {
+        v.embed = {
+          provider: leg.model.provider,
+          model: leg.model.model,
+          from: [...leg.from ?? []],
+          ...leg.model.apiKeyName !== void 0 ? { apiKeyName: leg.model.apiKeyName } : {},
+          ...leg.model.dimensions !== void 0 ? { dimensions: leg.model.dimensions } : {},
+          ...leg.model.baseURL !== void 0 ? { baseURL: leg.model.baseURL } : {}
+        };
+      }
+      return v;
+    });
+  }
+  return out;
+}
 function tableToJSON(table) {
   const columns = {};
   for (const [name, column] of Object.entries(table.columns)) {
@@ -1939,6 +2072,10 @@ function tableToJSON(table) {
   if (table.indexes !== void 0 && table.indexes.length > 0) {
     out.indexes = table.indexes.map((i) => ({ name: i.name, columns: [...i.columns] }));
   }
+  if (table.search !== void 0) {
+    const sj = searchToJSON(table.search);
+    if (sj.text !== void 0 || sj.vector !== void 0) out.search = sj;
+  }
   return out;
 }
 function toSchemaJSON(schema) {
@@ -1950,6 +2087,63 @@ function toSchemaJSON(schema) {
   return { tables, extensions: [...new Set(schema.extensions ?? [])] };
 }
 
+// src/channels.ts
+var CHANNELS = /* @__PURE__ */ Symbol.for("palbase.backend.channels");
+function ownerOnly() {
+  return { kind: "owner" };
+}
+function publicChannel(opts = {}) {
+  return { kind: "public", publish: opts.publish ?? false, state: opts.state };
+}
+function paramCount(pattern) {
+  return pattern.split(":").filter((s) => s.startsWith("{") && s.endsWith("}")).length;
+}
+function defineChannels(map) {
+  const entries = [];
+  for (const [pattern, entry] of Object.entries(map)) {
+    if ("kind" in entry && entry.kind === "owner") {
+      if (paramCount(pattern) !== 1) {
+        throw new Error(
+          `defineChannels: ownerOnly() pattern "${pattern}" must carry exactly one {param} (its value is compared to the token subject)`
+        );
+      }
+      entries.push({ pattern, kind: "owner" });
+    } else if ("kind" in entry && entry.kind === "public") {
+      entries.push({ pattern, kind: "public", publish: entry.publish, state: entry.state });
+    } else {
+      const c = entry;
+      entries.push({ pattern, kind: "custom", authorize: c.authorize, handler: c.handler });
+    }
+  }
+  const def = { entries };
+  const carrier = globalThis;
+  const existing = carrier[CHANNELS];
+  if (existing && !sameDeclaration(existing, def)) {
+    throw new Error(
+      `defineChannels: channels were already declared (${existing.entries.length} pattern(s): ${existing.entries.map((e) => e.pattern).join(", ")}). A project declares its channels ONCE \u2014 a second call would overwrite the first, and channels nobody declared are refused.`
+    );
+  }
+  carrier[CHANNELS] = def;
+  return def;
+}
+function wireRow(e) {
+  return JSON.stringify([
+    e.pattern,
+    e.kind,
+    e.publish ?? false,
+    e.state?.read ?? false,
+    e.state?.write ?? false,
+    // The handler is compared by SOURCE, like authorize: two evaluations of one
+    // module give the same text, while different logic gives different text.
+    e.handler ? e.handler.toString() : "",
+    e.authorize ? e.authorize.toString() : ""
+  ]);
+}
+function sameDeclaration(a, b) {
+  if (a.entries.length !== b.entries.length) return false;
+  return a.entries.every((x, i) => wireRow(x) === wireRow(b.entries[i]));
+}
+
 // src/db/extensions.ts
 var PALBASE_EXTENSIONS = [
   // Search & text
@@ -1963,8 +2157,6 @@ var PALBASE_EXTENSIONS = [
   "citext",
   // case-insensitive text type
   // Geospatial / location
-  "postgis",
-  // geospatial types + queries (maps, "near me")
   "cube",
   // multi-dimensional cubes (dependency of earthdistance)
   "earthdistance",
@@ -1979,8 +2171,6 @@ var PALBASE_EXTENSIONS = [
   // GiST operator classes for scalar types — needed for EXCLUDE
   // constraints that mix "=" with a range/&& overlap (e.g. no-double-booking).
   // Scheduling
-  "pg_cron",
-  // schedule jobs inside the database
   // Crypto / ids (also installed by default; listable for explicitness)
   "pgcrypto",
   // cryptographic functions (hashing, encryption)
@@ -1995,6 +2185,11 @@ function isPalbaseExtension(name) {
 }
 
 // src/db/columns.ts
+function refuseOnVector(def, modifier) {
+  if (def.type === "vector") {
+    throw new Error(`vector column: .${modifier}() is not supported (FR-002 \u2014 allowed: nullable()/notNull())`);
+  }
+}
 var ColumnBuilder = class _ColumnBuilder {
   _def;
   constructor(type, existingDef) {
@@ -2006,6 +2201,7 @@ var ColumnBuilder = class _ColumnBuilder {
   }
   /** Mark this column as the primary key. */
   primaryKey() {
+    refuseOnVector(this._def, "primaryKey");
     this._def.primaryKey = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
@@ -2021,16 +2217,19 @@ var ColumnBuilder = class _ColumnBuilder {
   }
   /** Set a default value. */
   default(value) {
+    refuseOnVector(this._def, "default");
     this._def.defaultValue = value;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** UUID: generate a random default (gen_random_uuid()). */
   defaultRandom() {
+    refuseOnVector(this._def, "defaultRandom");
     this._def.defaultRandom = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Timestamp: default to now(). */
   defaultNow() {
+    refuseOnVector(this._def, "defaultNow");
     this._def.defaultNow = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
@@ -2051,6 +2250,7 @@ var ColumnBuilder = class _ColumnBuilder {
     return this;
   }
   references(table, column) {
+    refuseOnVector(this._def, "references");
     this._def.references = { table, column };
     return new _ColumnBuilder(this._def.type, this._def);
   }
@@ -2075,6 +2275,7 @@ var ColumnBuilder = class _ColumnBuilder {
    * as the real boundary; this signature is the compile-time DX mirror.
    */
   referencesAuthUser(onDelete) {
+    refuseOnVector(this._def, "referencesAuthUser");
     this._def.references = { table: "auth.users", column: "id" };
     this._def.onDeleteAction = onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
@@ -2098,6 +2299,7 @@ var ColumnBuilder = class _ColumnBuilder {
    * boundary; this signature is the compile-time DX mirror.
    */
   referencesInstallation(onDelete) {
+    refuseOnVector(this._def, "referencesInstallation");
     this._def.references = { table: "auth.installations", column: "id" };
     this._def.onDeleteAction = onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
@@ -2109,6 +2311,7 @@ var ColumnBuilder = class _ColumnBuilder {
   }
   /** Add a single-column UNIQUE constraint. */
   unique() {
+    refuseOnVector(this._def, "unique");
     this._def.unique = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
@@ -2143,12 +2346,33 @@ function enumType(name, values) {
   builder._def.enumValues = [...values];
   return builder;
 }
+function vector(dimensions) {
+  if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 2e3) {
+    throw new Error(`vector(): dimensions must be an integer in [1, 2000], got ${String(dimensions)}`);
+  }
+  const b = new ColumnBuilder("vector");
+  b._def.dimensions = dimensions;
+  return b;
+}
 
 // src/db/raw.ts
 function raw(name, up, opts) {
   return { name, up, ...opts?.down != null ? { down: opts.down } : {} };
 }
 
+// src/db/embedding.ts
+var openai = {
+  embedding(model, opts) {
+    return {
+      provider: "openai",
+      model,
+      apiKeyName: opts?.apiKeyName ?? "OPENAI_API_KEY",
+      ...opts?.dimensions !== void 0 ? { dimensions: opts.dimensions } : {},
+      ...opts?.baseURL !== void 0 ? { baseURL: opts.baseURL } : {}
+    };
+  }
+};
+
 // src/db/typed-db.ts
 function makeTypedTable(name, raw2) {
   return {
@@ -2208,6 +2432,11 @@ function baseTsType(def) {
       return "boolean";
     case "jsonb":
       return "unknown";
+    // FR-008: the authoring type of a pgvector column. The default `unknown`
+    // branch below STAYS — an unknown wire type is refused on the Go side
+    // (FR-005), never papered over here.
+    case "vector":
+      return "number[]";
     case "enum": {
       const values = def.enumValues ?? [];
       if (values.length === 0) return "string";
@@ -2289,6 +2518,10 @@ function tableBlock(table, children, indent) {
     `${indent}  };`,
     `${indent}  owner: ${owner === null ? "null" : JSON.stringify(owner)};`,
     `${indent}  children: {${childEntries === "" ? "" : ` ${childEntries} `}};`,
+    // searchable: vector kolonu YA DA search beyanı → EnvTypedTable'da search()
+    // üyesini açan yapısal bayrak (FR-013). Yokken satır hiç üretilmez ki
+    // mevcut şemaların d.ts'i bayt-aynı kalsın.
+    ...cols.some(([, b]) => b._def.type === "vector") || table.search !== void 0 ? [`${indent}  searchable: true;`] : [],
     `${indent}};`
   ].join("\n");
 }
@@ -3741,6 +3974,7 @@ var import_zod2 = require("zod");
   buildModuleClients,
   buildProvider,
   dec,
+  defineChannels,
   defineEgress,
   defineError,
   defineFlags,
@@ -3770,8 +4004,11 @@ var import_zod2 = require("zod");
   makeTypedDB,
   now,
   numeric,
+  openai,
+  ownerOnly,
   parseFileSizeLimit,
   policy,
+  publicChannel,
   raw,
   recordThrows,
   reservedSecretKey,
@@ -3783,6 +4020,7 @@ var import_zod2 = require("zod");
   toSchemaJSON,
   uuid,
   validateUploadAgainstStorage,
+  vector,
   z
 });
 //# sourceMappingURL=index.cjs.map