@ragable/sdk 0.8.1 → 0.8.3

package/dist/index.mjs

@@ -1749,6 +1749,824 @@ var PostgrestTableApi = class {
   }
 };
 
+// src/collection-query.ts
+function flattenRecord(record) {
+  return {
+    ...record.data,
+    id: record.id,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  };
+}
+function parseColumns(columns) {
+  const trimmed = (columns ?? "*").trim();
+  if (trimmed.includes("(")) {
+    throw new RagableError(
+      "Embeds and aggregates are only supported in .select() queries, not in a mutation's returning .select(). Use plain column names here.",
+      400,
+      { code: "SDK_COLLECTION_SELECT_PLAIN_ONLY" }
+    );
+  }
+  if (!trimmed || trimmed === "*") return null;
+  const fields = trimmed.split(",").map((c) => c.trim()).filter(Boolean).filter((c) => c !== "*");
+  return fields.length > 0 ? fields : null;
+}
+var IDENT = "[A-Za-z_][A-Za-z0-9_]*";
+var AGGREGATE_RE = new RegExp(
+  `^(?:(${IDENT}):)?(?:(${IDENT})\\.)?(count|sum|avg|min|max)\\(\\)$`
+);
+var EMBED_RE = new RegExp(`^(?:(${IDENT}):)?(${IDENT})(?:!(${IDENT}))?\\(([^()]*)\\)$`);
+var FIELD_RE = new RegExp(`^${IDENT}$`);
+function parseSelectExpression(columns) {
+  const trimmed = (columns ?? "*").trim();
+  const result = { fields: null, embeds: [], aggregates: [] };
+  if (!trimmed || trimmed === "*") return result;
+  const fields = [];
+  let sawStar = false;
+  for (const segment of splitTopLevel(trimmed)) {
+    if (segment === "*") {
+      sawStar = true;
+      continue;
+    }
+    const agg = AGGREGATE_RE.exec(segment);
+    if (agg) {
+      const [, alias, field, fn] = agg;
+      if (fn !== "count" && !field) {
+        throw new RagableError(
+          `.select(): "${segment}" \u2014 ${fn}() needs a field, e.g. "amount.${fn}()".`,
+          400,
+          { code: "SDK_COLLECTION_AGGREGATE_FIELD_REQUIRED" }
+        );
+      }
+      const resolvedAlias = alias ?? (fn === "count" && !field ? "count" : fn);
+      if (result.aggregates.some((a) => a.alias === resolvedAlias)) {
+        throw new RagableError(
+          `.select(): duplicate aggregate key "${resolvedAlias}" \u2014 alias each function, e.g. "total:amount.sum()".`,
+          400,
+          { code: "SDK_COLLECTION_AGGREGATE_DUPLICATE_ALIAS" }
+        );
+      }
+      result.aggregates.push({
+        fn,
+        ...field ? { field } : {},
+        alias: resolvedAlias
+      });
+      continue;
+    }
+    const embed = EMBED_RE.exec(segment);
+    if (embed) {
+      const [, alias, collection, hint, cols] = embed;
+      const inner = (cols ?? "").trim();
+      const embedColumns = !inner || inner === "*" ? null : inner.split(",").map((c) => c.trim()).filter(Boolean).filter((c) => c !== "*");
+      result.embeds.push({
+        alias: alias ?? collection,
+        collection,
+        ...hint ? { hint } : {},
+        columns: embedColumns && embedColumns.length > 0 ? embedColumns : null
+      });
+      continue;
+    }
+    if (FIELD_RE.test(segment)) {
+      fields.push(segment);
+      continue;
+    }
+    throw new RagableError(
+      `.select(): could not parse "${segment}". Expected a column name, an embed like "author:users!author_id(name)", or an aggregate like "count()" / "total:amount.sum()".`,
+      400,
+      { code: "SDK_COLLECTION_SELECT_SYNTAX" }
+    );
+  }
+  if (result.aggregates.length > 0) {
+    if (result.embeds.length > 0) {
+      throw new RagableError(
+        ".select(): aggregates and embeds cannot be combined \u2014 run them as separate queries.",
+        400,
+        { code: "SDK_COLLECTION_AGGREGATE_WITH_EMBED" }
+      );
+    }
+    if (sawStar) {
+      throw new RagableError(
+        '.select(): "*" cannot be combined with aggregates \u2014 list the group-by fields explicitly, e.g. .select("category, count()").',
+        400,
+        { code: "SDK_COLLECTION_AGGREGATE_WITH_STAR" }
+      );
+    }
+  }
+  result.fields = sawStar || fields.length === 0 ? null : fields;
+  if (result.aggregates.length > 0) result.fields = fields.length > 0 ? fields : null;
+  return result;
+}
+function projectRow(row, fields) {
+  if (!fields) return row;
+  const out = {
+    id: row.id,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt
+  };
+  for (const field of fields) {
+    if (field in row) out[field] = row[field];
+  }
+  return out;
+}
+var FILTER_OPS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "ilike",
+  "startsWith",
+  "endsWith",
+  "in",
+  "nin",
+  "contains",
+  "is",
+  "exists"
+]);
+function splitTopLevel(input) {
+  const parts = [];
+  let depth = 0;
+  let inQuotes = false;
+  let current = "";
+  for (const ch of input) {
+    if (ch === '"') inQuotes = !inQuotes;
+    if (!inQuotes) {
+      if (ch === "(") depth++;
+      else if (ch === ")") depth = Math.max(0, depth - 1);
+      if (ch === "," && depth === 0) {
+        parts.push(current);
+        current = "";
+        continue;
+      }
+    }
+    current += ch;
+  }
+  parts.push(current);
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+function coerceOrValue(raw) {
+  const v = raw.trim();
+  if (v === "true") return true;
+  if (v === "false") return false;
+  if (v === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) return v.slice(1, -1);
+  return v;
+}
+function orSyntaxError(segment) {
+  return new RagableError(
+    `.or(): could not parse "${segment}". Expected "field.op.value" segments separated by commas, e.g. .or('done.eq.true,priority.gte.3') or .or('and(a.eq.1,b.eq.2),c.is.null'). Ops: ${[...FILTER_OPS].join(", ")} (prefix with "not." to negate).`,
+    400,
+    { code: "SDK_COLLECTION_OR_SYNTAX" }
+  );
+}
+function mergeCondition(group, field, op, value, negate) {
+  const condition = negate ? { not: { [op]: value } } : { [op]: value };
+  const existing = group[field];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    const prev = existing;
+    if (negate && prev.not && typeof prev.not === "object" && !Array.isArray(prev.not)) {
+      group[field] = {
+        ...prev,
+        not: { ...prev.not, [op]: value }
+      };
+      return;
+    }
+    group[field] = { ...prev, ...condition };
+    return;
+  }
+  group[field] = condition;
+}
+function parseOrCondition(segment, group) {
+  const firstDot = segment.indexOf(".");
+  if (firstDot <= 0) throw orSyntaxError(segment);
+  const field = segment.slice(0, firstDot);
+  let rest = segment.slice(firstDot + 1);
+  let negate = false;
+  if (rest.startsWith("not.")) {
+    negate = true;
+    rest = rest.slice(4);
+  }
+  const opDot = rest.indexOf(".");
+  if (opDot <= 0) throw orSyntaxError(segment);
+  const op = rest.slice(0, opDot);
+  const rawValue = rest.slice(opDot + 1);
+  if (!FILTER_OPS.has(op)) throw orSyntaxError(segment);
+  let value;
+  if (op === "in" || op === "nin") {
+    const inner = rawValue.replace(/^\(/, "").replace(/\)$/, "");
+    value = inner.trim().length === 0 ? [] : inner.split(",").map(coerceOrValue);
+  } else {
+    value = coerceOrValue(rawValue);
+  }
+  mergeCondition(group, field, op, value, negate);
+}
+function parseOrString(input) {
+  const groups = [];
+  for (const segment of splitTopLevel(input)) {
+    if (/^and\(/.test(segment) && segment.endsWith(")")) {
+      const inner = segment.slice(segment.indexOf("(") + 1, -1);
+      const group = {};
+      for (const condition of splitTopLevel(inner)) parseOrCondition(condition, group);
+      if (Object.keys(group).length === 0) throw orSyntaxError(segment);
+      groups.push(group);
+    } else {
+      const group = {};
+      parseOrCondition(segment, group);
+      groups.push(group);
+    }
+  }
+  if (groups.length === 0) throw orSyntaxError(input);
+  return groups;
+}
+var CollectionConditionBuilder = class {
+  constructor() {
+    __publicField(this, "filters", []);
+    __publicField(this, "orGroups", null);
+    __publicField(this, "signal");
+  }
+  /** `field = value` (or `IS NULL` when value is null). */
+  eq(field, value) {
+    return this.push(field, "eq", value);
+  }
+  /** `field != value` (null-aware). */
+  neq(field, value) {
+    return this.push(field, "neq", value);
+  }
+  gt(field, value) {
+    return this.push(field, "gt", value);
+  }
+  gte(field, value) {
+    return this.push(field, "gte", value);
+  }
+  lt(field, value) {
+    return this.push(field, "lt", value);
+  }
+  lte(field, value) {
+    return this.push(field, "lte", value);
+  }
+  /** SQL LIKE — you supply the `%` wildcards, e.g. `.like("title", "%report%")`. */
+  like(field, pattern) {
+    return this.push(field, "like", pattern);
+  }
+  /** Case-insensitive LIKE. */
+  ilike(field, pattern) {
+    return this.push(field, "ilike", pattern);
+  }
+  /** Prefix match; wildcard characters in `value` are matched literally. */
+  startsWith(field, value) {
+    return this.push(field, "startsWith", value);
+  }
+  /** Suffix match; wildcard characters in `value` are matched literally. */
+  endsWith(field, value) {
+    return this.push(field, "endsWith", value);
+  }
+  /** Value is one of `values`. */
+  in(field, values) {
+    return this.push(field, "in", values);
+  }
+  /** Value is NOT one of `values`. */
+  nin(field, values) {
+    return this.push(field, "nin", values);
+  }
+  /**
+   * JSONB containment: array fields contain the given element(s), object
+   * fields contain the given key/value pairs.
+   * `.contains("tags", ["urgent"])`, `.contains("meta", { plan: "pro" })`.
+   */
+  contains(field, value) {
+    return this.push(field, "contains", value);
+  }
+  /** Strict null / boolean check: `.is("archivedAt", null)`, `.is("done", true)`. */
+  is(field, value) {
+    return this.push(field, "is", value);
+  }
+  /** Whether the JSON key is present at all: `.exists("avatarUrl", false)`. */
+  exists(field, present = true) {
+    return this.push(field, "exists", present);
+  }
+  /** Negated condition: `.not("status", "eq", "archived")`. */
+  not(field, op, value) {
+    this.assertOp(op);
+    this.filters.push({ field: String(field), op, value, not: true });
+    return this;
+  }
+  /** Generic escape hatch, mirroring Supabase `.filter(column, op, value)`. */
+  filter(field, op, value) {
+    this.assertOp(op);
+    return this.push(field, op, value);
+  }
+  /** Equality on every key of `query` (null values become IS NULL). */
+  match(query) {
+    for (const [field, value] of Object.entries(query)) {
+      this.push(field, "eq", value);
+    }
+    return this;
+  }
+  /**
+   * OR conditions, ANDed with the other filters. Accepts the Supabase string
+   * grammar — `.or('done.eq.true,priority.gte.3')`, with `and(...)` for a
+   * multi-condition branch — or an array of where-style objects:
+   * `.or([{ done: true }, { priority: { gte: 3 } }])`.
+   *
+   * One `.or()` per query: the wire format carries a single disjunction.
+   */
+  or(conditions) {
+    if (this.orGroups) {
+      throw new RagableError(
+        ".or() can only be used once per query. Combine branches in a single call: .or('a.eq.1,b.eq.2').",
+        400,
+        { code: "SDK_COLLECTION_OR_TWICE" }
+      );
+    }
+    this.orGroups = typeof conditions === "string" ? parseOrString(conditions) : conditions;
+    if (!Array.isArray(this.orGroups) || this.orGroups.length === 0) {
+      throw new RagableError(
+        ".or() requires at least one condition.",
+        400,
+        { code: "SDK_COLLECTION_OR_EMPTY" }
+      );
+    }
+    return this;
+  }
+  abortSignal(signal) {
+    this.signal = signal;
+    return this;
+  }
+  get hasConditions() {
+    return this.filters.length > 0 || (this.orGroups?.length ?? 0) > 0;
+  }
+  wireFilters() {
+    return this.filters.map((f) => ({
+      field: f.field,
+      op: f.op,
+      value: f.value,
+      ...f.not ? { not: true } : {}
+    }));
+  }
+  assertOp(op) {
+    if (!FILTER_OPS.has(op)) {
+      throw new RagableError(
+        `Unknown filter operator "${op}". Use one of: ${[...FILTER_OPS].join(", ")}.`,
+        400,
+        { code: "SDK_COLLECTION_BAD_OP" }
+      );
+    }
+  }
+  push(field, op, value) {
+    this.filters.push({ field: String(field), op, value });
+    return this;
+  }
+};
+var CollectionSelectBuilder = class extends CollectionConditionBuilder {
+  constructor(request, columns, options) {
+    super();
+    this.request = request;
+    __publicField(this, "_limit");
+    __publicField(this, "_offset");
+    __publicField(this, "_order", []);
+    __publicField(this, "parsed");
+    __publicField(this, "wantCount");
+    __publicField(this, "headOnly");
+    this.parsed = parseSelectExpression(columns);
+    this.wantCount = options?.count === "exact";
+    this.headOnly = options?.head === true;
+    if (this.parsed.aggregates.length > 0 && (this.wantCount || this.headOnly)) {
+      throw new RagableError(
+        'Aggregate selects compute their own results \u2014 drop { count: "exact" } / { head: true }.',
+        400,
+        { code: "SDK_COLLECTION_AGGREGATE_WITH_COUNT" }
+      );
+    }
+  }
+  /** Sort by a field. Call again to add secondary sort keys (max 4). */
+  order(field, options) {
+    this._order.push({
+      field: String(field),
+      direction: options?.ascending === true ? "asc" : "desc"
+    });
+    return this;
+  }
+  limit(n) {
+    this._limit = n;
+    return this;
+  }
+  offset(n) {
+    this._offset = n;
+    return this;
+  }
+  /** Rows `from`..`to` inclusive (zero-based), like Supabase `.range()`. */
+  range(from, to) {
+    this._offset = from;
+    this._limit = Math.max(0, to - from + 1);
+    return this;
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  /**
+   * Exactly one row. 0 or >1 matching rows is an error (code PGRST116),
+   * mirroring Supabase `.single()`.
+   */
+  async single() {
+    const res = await this.executeRows(2);
+    if (res.error) return { data: null, error: res.error };
+    const rows = res.rows;
+    if (rows.length !== 1) {
+      return {
+        data: null,
+        error: new RagableError(
+          "JSON object requested, multiple (or no) rows returned",
+          406,
+          { code: "PGRST116", details: `The result contains ${rows.length} rows` }
+        )
+      };
+    }
+    return { data: rows[0], error: null };
+  }
+  /** One row or `null` — only >1 matching rows is an error. */
+  async maybeSingle() {
+    const res = await this.executeRows(2);
+    if (res.error) return { data: null, error: res.error };
+    const rows = res.rows;
+    if (rows.length > 1) {
+      return {
+        data: null,
+        error: new RagableError(
+          "JSON object requested, multiple (or no) rows returned",
+          406,
+          { code: "PGRST116", details: `The result contains ${rows.length} rows` }
+        )
+      };
+    }
+    return { data: rows[0] ?? null, error: null };
+  }
+  buildBody(limitOverride) {
+    const body = {};
+    const filters = this.wireFilters();
+    if (filters.length > 0) body.filters = filters;
+    if (this.orGroups) body.or = this.orGroups;
+    const limit = limitOverride ?? (this.headOnly ? 0 : this._limit);
+    if (limit !== void 0) body.limit = limit;
+    if (this._offset !== void 0 && this._offset > 0) body.offset = this._offset;
+    if (this._order.length === 1) {
+      body.orderBy = this._order[0].field;
+      body.orderDirection = this._order[0].direction;
+    } else if (this._order.length > 1) {
+      body.orderBy = this._order.map((o) => ({
+        field: o.field,
+        direction: o.direction
+      }));
+    }
+    if (this.wantCount) body.count = true;
+    if (this.parsed.embeds.length > 0) {
+      body.embed = this.parsed.embeds.map((e) => ({
+        alias: e.alias,
+        collection: e.collection,
+        ...e.hint ? { hint: e.hint } : {}
+      }));
+    }
+    if (this.parsed.aggregates.length > 0) {
+      body.aggregate = {
+        groupBy: this.parsed.fields ?? [],
+        functions: this.parsed.aggregates.map((a) => ({
+          fn: a.fn,
+          ...a.field ? { field: a.field } : {},
+          alias: a.alias
+        }))
+      };
+    }
+    return body;
+  }
+  /** Flatten the envelope and apply column + embedded-column projection. */
+  shapeRow(record) {
+    const flat = flattenRecord(record);
+    for (const embed of this.parsed.embeds) {
+      if (!embed.columns) continue;
+      const value = flat[embed.alias];
+      if (Array.isArray(value)) {
+        flat[embed.alias] = value.map(
+          (v) => projectEmbeddedObject(v, embed.columns)
+        );
+      } else if (value && typeof value === "object") {
+        flat[embed.alias] = projectEmbeddedObject(value, embed.columns);
+      }
+    }
+    if (!this.parsed.fields) return flat;
+    const out = {
+      id: flat.id,
+      createdAt: flat.createdAt,
+      updatedAt: flat.updatedAt
+    };
+    for (const field of this.parsed.fields) {
+      if (field in flat) out[field] = flat[field];
+    }
+    for (const embed of this.parsed.embeds) {
+      if (embed.alias in flat) out[embed.alias] = flat[embed.alias];
+    }
+    return out;
+  }
+  async executeRows(limitOverride) {
+    if (this.parsed.aggregates.length > 0) {
+      const result2 = await asPostgrestResponse(
+        () => this.request(
+          "POST",
+          "/find",
+          this.buildBody(limitOverride),
+          this.signal
+        )
+      );
+      if (result2.error) return { error: result2.error, rows: null, total: null };
+      return { error: null, rows: result2.data ?? [], total: null };
+    }
+    const result = await asPostgrestResponse(
+      () => this.request(
+        "POST",
+        "/find",
+        this.buildBody(limitOverride),
+        this.signal
+      )
+    );
+    if (result.error) return { error: result.error, rows: null, total: null };
+    const payload = result.data;
+    const records = Array.isArray(payload) ? payload : payload?.records ?? [];
+    const total = Array.isArray(payload) ? null : payload?.total ?? null;
+    const rows = records.map((r) => this.shapeRow(r));
+    return { error: null, rows, total };
+  }
+  async execute() {
+    const res = await this.executeRows();
+    if (res.error) return { data: null, error: res.error, count: null };
+    return {
+      data: this.headOnly ? [] : res.rows,
+      error: null,
+      count: res.total
+    };
+  }
+};
+function projectEmbeddedObject(value, columns) {
+  const source = value;
+  const out = {};
+  for (const key of ["id", "createdAt", "updatedAt"]) {
+    if (key in source) out[key] = source[key];
+  }
+  for (const column of columns) {
+    if (column in source) out[column] = source[column];
+  }
+  return out;
+}
+var CollectionMutationReturning = class {
+  constructor(run, columns) {
+    this.run = run;
+    this.columns = columns;
+  }
+  then(onfulfilled, onrejected) {
+    return this.executeMany().then(onfulfilled, onrejected);
+  }
+  async executeMany() {
+    const res = await this.run();
+    if (res.error) return { data: null, error: res.error };
+    const rows = (res.data ?? []).map(
+      (r) => projectRow(flattenRecord(r), this.columns)
+    );
+    return { data: rows, error: null };
+  }
+  async single() {
+    const many = await this.executeMany();
+    if (many.error) return { data: null, error: many.error };
+    const rows = many.data ?? [];
+    if (rows.length !== 1) {
+      return {
+        data: null,
+        error: new RagableError(
+          "JSON object requested, multiple (or no) rows returned",
+          406,
+          { code: "PGRST116", details: `The result contains ${rows.length} rows` }
+        )
+      };
+    }
+    return { data: rows[0], error: null };
+  }
+  async maybeSingle() {
+    const many = await this.executeMany();
+    if (many.error) return { data: null, error: many.error };
+    const rows = many.data ?? [];
+    if (rows.length > 1) {
+      return {
+        data: null,
+        error: new RagableError(
+          "JSON object requested, multiple (or no) rows returned",
+          406,
+          { code: "PGRST116", details: `The result contains ${rows.length} rows` }
+        )
+      };
+    }
+    return { data: rows[0] ?? null, error: null };
+  }
+};
+var CollectionUpdateBuilder = class extends CollectionConditionBuilder {
+  constructor(request, patch) {
+    super();
+    this.request = request;
+    this.patch = patch;
+    __publicField(this, "_limit");
+  }
+  limit(n) {
+    this._limit = n;
+    return this;
+  }
+  select(columns = "*") {
+    return new CollectionMutationReturning(
+      () => this.execute(),
+      parseColumns(columns)
+    );
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(
+      (res) => res.error ? { data: null, error: res.error } : { data: null, error: null }
+    ).then(onfulfilled, onrejected);
+  }
+  async execute() {
+    if (!this.hasConditions) {
+      return {
+        data: null,
+        error: new RagableError(
+          "update() requires at least one filter \u2014 add .eq()/.match()/.or() before awaiting. To update every record, filter on a condition that always holds, e.g. .neq('id', null).",
+          400,
+          { code: "SDK_COLLECTION_UPDATE_NO_FILTER" }
+        )
+      };
+    }
+    return asPostgrestResponse(
+      () => this.request(
+        "PATCH",
+        "/records",
+        {
+          where: {},
+          filters: this.wireFilters(),
+          ...this.orGroups ? { or: this.orGroups } : {},
+          patch: this.patch,
+          ...this._limit !== void 0 ? { limit: this._limit } : {}
+        },
+        this.signal
+      )
+    );
+  }
+};
+var CollectionDeleteBuilder = class extends CollectionConditionBuilder {
+  constructor(request) {
+    super();
+    this.request = request;
+    __publicField(this, "_limit");
+  }
+  limit(n) {
+    this._limit = n;
+    return this;
+  }
+  select(columns = "*") {
+    return new CollectionMutationReturning(
+      () => this.execute(),
+      parseColumns(columns)
+    );
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(
+      (res) => res.error ? { data: null, error: res.error } : { data: null, error: null }
+    ).then(onfulfilled, onrejected);
+  }
+  async execute() {
+    if (!this.hasConditions) {
+      return {
+        data: null,
+        error: new RagableError(
+          "delete() requires at least one filter \u2014 add .eq()/.match()/.or() before awaiting. To clear a collection, filter on a condition that always holds, e.g. .neq('id', null).",
+          400,
+          { code: "SDK_COLLECTION_DELETE_NO_FILTER" }
+        )
+      };
+    }
+    const res = await asPostgrestResponse(
+      () => this.request(
+        "DELETE",
+        "/records",
+        {
+          where: {},
+          filters: this.wireFilters(),
+          ...this.orGroups ? { or: this.orGroups } : {},
+          ...this._limit !== void 0 ? { limit: this._limit } : {}
+        },
+        this.signal
+      )
+    );
+    if (res.error) return { data: null, error: res.error };
+    return { data: res.data.records ?? [], error: null };
+  }
+};
+var CollectionInsertChain = class {
+  constructor(request, rows, single) {
+    this.request = request;
+    this.rows = rows;
+    this.single = single;
+    __publicField(this, "_signal");
+  }
+  abortSignal(signal) {
+    this._signal = signal;
+    return this;
+  }
+  select(columns = "*") {
+    return new CollectionMutationReturning(
+      async () => {
+        const res = await this.executeEnvelopes();
+        if (res.error) return { data: null, error: res.error };
+        return { data: res.data, error: null };
+      },
+      parseColumns(columns)
+    );
+  }
+  then(onfulfilled, onrejected) {
+    return this.executeEnvelopes().then((res) => {
+      if (res.error) return { data: null, error: res.error };
+      const envelopes = res.data;
+      const resolved = this.single ? envelopes[0] ?? null : envelopes;
+      return { data: resolved, error: null };
+    }).then(onfulfilled, onrejected);
+  }
+  async executeEnvelopes() {
+    if (this.rows.length === 0) return { data: [], error: null };
+    if (this.single) {
+      const res = await asPostgrestResponse(
+        () => this.request(
+          "POST",
+          "/records",
+          { data: this.rows[0] },
+          this._signal
+        )
+      );
+      if (res.error) return { data: null, error: res.error };
+      return { data: [res.data], error: null };
+    }
+    return asPostgrestResponse(
+      () => this.request(
+        "POST",
+        "/records/batch",
+        { items: this.rows },
+        this._signal
+      )
+    );
+  }
+};
+var CollectionUpsertBuilder = class {
+  constructor(request, rows, options) {
+    this.request = request;
+    this.rows = rows;
+    this.options = options;
+    __publicField(this, "_signal");
+  }
+  abortSignal(signal) {
+    this._signal = signal;
+    return this;
+  }
+  select(columns = "*") {
+    return new CollectionMutationReturning(
+      async () => {
+        const res = await this.execute();
+        if (res.error) return { data: null, error: res.error };
+        return { data: res.data.records, error: null };
+      },
+      parseColumns(columns)
+    );
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then((res) => {
+      if (res.error) return { data: null, error: res.error };
+      const { inserted, updated, skipped } = res.data;
+      return { data: { inserted, updated, skipped }, error: null };
+    }).then(onfulfilled, onrejected);
+  }
+  async execute() {
+    if (this.rows.length === 0) {
+      return {
+        data: { records: [], inserted: 0, updated: 0, skipped: 0 },
+        error: null
+      };
+    }
+    return asPostgrestResponse(
+      () => this.request(
+        "POST",
+        "/records/upsert",
+        {
+          items: this.rows,
+          onConflict: this.options.onConflict ?? "id",
+          ...this.options.ignoreDuplicates ? { ignoreDuplicates: true } : {}
+        },
+        this._signal
+      )
+    );
+  }
+};
+
 // src/auth-storage.ts
 var LocalStorageAdapter = class {
   getItem(key) {
@@ -2043,6 +2861,109 @@ var RagableAuth = class {
     this.emit("SIGNED_OUT", null);
     return { error: null };
   }
+  // ── Password recovery & magic links ────────────────────────────────────────
+  /**
+   * Email a password-recovery link. The link points at `redirectTo` (or the
+   * site's deployed domain when omitted) with `?token_hash=…&type=recovery`
+   * appended. On that page, either:
+   * - call {@link resetPassword} with the token and the new password, or
+   * - call {@link verifyOtp} to sign the user in, then `updateUser({ password })`.
+   *
+   * Always resolves successfully for well-formed requests — whether the email
+   * has an account is never revealed.
+   */
+  async resetPasswordForEmail(email, options) {
+    return asPostgrestResponse(async () => {
+      await this.fetchAuth("/forgot-password", "POST", {
+        email,
+        ...options?.redirectTo ? { redirectTo: options.redirectTo } : {}
+      });
+      return {};
+    });
+  }
+  /**
+   * Email a one-click sign-in (magic) link — passwordless auth. New addresses
+   * get an account automatically unless `shouldCreateUser: false`. The emailed
+   * link carries `?token_hash=…&type=magiclink`; complete sign-in on that page
+   * with {@link verifyOtp}.
+   */
+  async signInWithOtp(params) {
+    return asPostgrestResponse(async () => {
+      await this.fetchAuth("/magic-link", "POST", {
+        email: params.email,
+        ...params.options?.emailRedirectTo ? { redirectTo: params.options.emailRedirectTo } : {},
+        ...params.options?.shouldCreateUser === false ? { createUser: false } : {}
+      });
+      return { user: null, session: null };
+    });
+  }
+  /**
+   * Exchange an emailed `token_hash` for a session. Reads the token from the
+   * URL your recovery / magic-link page receives:
+   *
+   * ```ts
+   * const qs = new URLSearchParams(window.location.search);
+   * const { data, error } = await client.auth.verifyOtp({
+   *   token_hash: qs.get("token_hash")!,
+   *   type: qs.get("type") as "recovery" | "magiclink",
+   * });
+   * ```
+   *
+   * Emits `SIGNED_IN` (and `PASSWORD_RECOVERY` for recovery tokens — listen
+   * for it to route to your "choose a new password" screen).
+   */
+  async verifyOtp(params) {
+    return asPostgrestResponse(async () => {
+      const token = (params.token_hash ?? params.tokenHash ?? "").trim();
+      if (!token) {
+        throw new RagableError(
+          "verifyOtp requires the token_hash from the emailed link.",
+          400,
+          { code: "SDK_AUTH_MISSING_TOKEN_HASH" }
+        );
+      }
+      const type = params.type === "email" ? "magiclink" : params.type;
+      const raw = await this.fetchAuth("/verify-token", "POST", { token, type });
+      const session = this.rawToSession(raw);
+      await this.setSessionInternal(session, "SIGNED_IN");
+      if (type === "recovery") this.emit("PASSWORD_RECOVERY", session);
+      return { user: session.user, session };
+    });
+  }
+  /**
+   * One-shot recovery: verify the emailed recovery token, set the new
+   * password, and sign the user in — no intermediate session juggling.
+   *
+   * ```ts
+   * const qs = new URLSearchParams(window.location.search);
+   * const { data, error } = await client.auth.resetPassword({
+   *   tokenHash: qs.get("token_hash")!,
+   *   newPassword: form.password,
+   * });
+   * ```
+   *
+   * Recovery links are single-use: once the password changes, the same link
+   * is rejected.
+   */
+  async resetPassword(params) {
+    return asPostgrestResponse(async () => {
+      const token = (params.tokenHash ?? params.token_hash ?? "").trim();
+      if (!token) {
+        throw new RagableError(
+          "resetPassword requires the token_hash from the recovery email link.",
+          400,
+          { code: "SDK_AUTH_MISSING_TOKEN_HASH" }
+        );
+      }
+      const raw = await this.fetchAuth("/reset-password", "POST", {
+        token,
+        password: params.newPassword
+      });
+      const session = this.rawToSession(raw);
+      await this.setSessionInternal(session, "SIGNED_IN");
+      return { user: session.user, session };
+    });
+  }
   async refreshSession(refreshToken) {
     return asPostgrestResponse(async () => {
       const token = refreshToken ?? this.currentSession?.refresh_token;
@@ -3254,6 +4175,22 @@ var RagableBrowserAuthClient = class {
   async signOut(_options) {
     return this.auth.signOut(_options);
   }
+  /** Email a password-recovery link — see {@link RagableAuth.resetPasswordForEmail}. */
+  async resetPasswordForEmail(email, options) {
+    return this.auth.resetPasswordForEmail(email, options);
+  }
+  /** Email a magic sign-in link — see {@link RagableAuth.signInWithOtp}. */
+  async signInWithOtp(params) {
+    return this.auth.signInWithOtp(params);
+  }
+  /** Exchange an emailed token_hash for a session — see {@link RagableAuth.verifyOtp}. */
+  async verifyOtp(params) {
+    return this.auth.verifyOtp(params);
+  }
+  /** Verify a recovery token and set a new password in one call — see {@link RagableAuth.resetPassword}. */
+  async resetPassword(params) {
+    return this.auth.resetPassword(params);
+  }
   async register(body) {
     return this.auth.register(body);
   }
@@ -3305,6 +4242,45 @@ var BrowserCollectionApi = class {
     this.database = database;
     this.name = name;
     this.databaseInstanceId = databaseInstanceId;
+    /** Transport for the chainable builders, bound to this collection. */
+    __publicField(this, "chainRequest", (method, path, body, signal) => this.database._requestCollection(
+      method,
+      `/${encodeURIComponent(this.name)}${path}`,
+      body,
+      this.databaseInstanceId,
+      signal
+    ));
+    /**
+     * Supabase-style chainable query. Rows come back flat (`id`, `createdAt`,
+     * `updatedAt` merged into the document fields).
+     *
+     * ```ts
+     * const { data, error, count } = await collections.todos
+     *   .select("*", { count: "exact" })
+     *   .eq("done", false)
+     *   .or("priority.gte.3,starred.eq.true")
+     *   .order("createdAt", { ascending: false })
+     *   .range(0, 19);
+     * ```
+     *
+     * Relation embeds (one level): `select("*, author:users!author_id(name), comments(*)")`
+     * — to-one embeds become an object (or null), to-many an array. Aggregations:
+     * `select("category, count(), total:amount.sum()")` groups by the plain
+     * columns; pass a type argument for the result shape:
+     * `select<{ category: string; count: number }>("category, count()")`.
+     */
+    __publicField(this, "select", (columns, options) => new CollectionSelectBuilder(this.chainRequest, columns, options));
+    /**
+     * Insert-or-update matched on `onConflict` (`"id"` by default, or any data
+     * field, e.g. `{ onConflict: "slug" }`). Chain `.select()` for the affected
+     * rows. Match-based (no unique indexes): concurrent upserts of the same new
+     * value can both insert.
+     */
+    __publicField(this, "upsert", (values, options) => new CollectionUpsertBuilder(
+      this.chainRequest,
+      Array.isArray(values) ? values : [values],
+      options ?? {}
+    ));
     __publicField(this, "requestFind", (body) => asPostgrestResponse(
       () => this.database._requestCollection(
         "POST",
@@ -3348,14 +4324,20 @@ var BrowserCollectionApi = class {
     __publicField(this, "findUnique", async (args) => {
       return this.findFirst({ where: args.where });
     });
-    __publicField(this, "insert", (data) => asPostgrestResponse(
-      () => this.database._requestCollection(
-        "POST",
-        `/${encodeURIComponent(this.name)}/records`,
-        { data },
-        this.databaseInstanceId
-      )
-    ));
+    /**
+     * Insert one row or an array of rows. Chain `.select()` for the inserted
+     * rows in flat shape, or await directly for the record envelope(s)
+     * (back-compat extension; Supabase resolves to null without `.select()`).
+     */
+    __publicField(this, "insert", ((data) => {
+      const isArray = Array.isArray(data);
+      const rows = isArray ? data : [data];
+      return new CollectionInsertChain(
+        this.chainRequest,
+        rows,
+        !isArray
+      );
+    }));
     /**
      * Insert multiple rows in one request (server multi-value `INSERT`, single transaction).
      * Empty **`items`** resolves to an empty array. Max batch size is enforced on the server (500).
@@ -3369,16 +4351,28 @@ var BrowserCollectionApi = class {
       )
     ));
     /**
-     * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
+     * Two forms:
+     * - `update(patch)` — Supabase-style chain: add filters, then await.
+     *   `update({ done: true }).eq("id", id)` (optionally `.select()`).
+     * - `update(where, patch)` — legacy direct call, returns updated records.
      */
-    __publicField(this, "update", (where, patch, options) => asPostgrestResponse(
-      () => this.database._requestCollection(
-        "PATCH",
-        `/${encodeURIComponent(this.name)}/records`,
-        { where, patch, ...options?.limit ? { limit: options.limit } : {} },
-        this.databaseInstanceId
-      )
-    ));
+    __publicField(this, "update", ((...args) => {
+      if (args.length >= 2) {
+        const [where, patch, options] = args;
+        return asPostgrestResponse(
+          () => this.database._requestCollection(
+            "PATCH",
+            `/${encodeURIComponent(this.name)}/records`,
+            { where, patch, ...options?.limit ? { limit: options.limit } : {} },
+            this.databaseInstanceId
+          )
+        );
+      }
+      return new CollectionUpdateBuilder(
+        this.chainRequest,
+        args[0]
+      );
+    }));
     /**
      * Like {@link BrowserCollectionApi.update} but the success payload includes
      * `meta.count` (number of rows returned from the update, bounded by `limit`).
@@ -3388,14 +4382,26 @@ var BrowserCollectionApi = class {
       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",
-        `/${encodeURIComponent(this.name)}/records`,
-        { where, ...options?.limit ? { limit: options.limit } : {} },
-        this.databaseInstanceId
-      )
-    ));
+    /**
+     * Two forms:
+     * - `delete()` — Supabase-style chain: add filters, then await.
+     *   `delete().eq("id", id)` (optionally `.select()`).
+     * - `delete(where)` — legacy direct call, returns `{ deleted, records }`.
+     */
+    __publicField(this, "delete", ((...args) => {
+      if (args.length === 0) {
+        return new CollectionDeleteBuilder(this.chainRequest);
+      }
+      const [where, options] = args;
+      return asPostgrestResponse(
+        () => this.database._requestCollection(
+          "DELETE",
+          `/${encodeURIComponent(this.name)}/records`,
+          { where, ...options?.limit ? { limit: options.limit } : {} },
+          this.databaseInstanceId
+        )
+      );
+    }));
     /**
      * Like {@link BrowserCollectionApi.delete} but the success payload includes **`meta.count`**
      * (number of deleted rows), matching {@link BrowserCollectionApi.updateMany}.
@@ -3597,7 +4603,7 @@ var RagableBrowserDatabaseClient = class {
   toUrl(path) {
     return `${normalizeBrowserApiBase()}${path.startsWith("/") ? path : `/${path}`}`;
   }
-  async _requestCollection(method, path, body, databaseInstanceId) {
+  async _requestCollection(method, path, body, databaseInstanceId, signal) {
     const gid = requireAuthGroupId(this.options);
     const token = await resolveDatabaseAuthBearer(this.options, this.ragableAuth);
     const id = databaseInstanceId?.trim() || this.options.databaseInstanceId?.trim();
@@ -3617,7 +4623,8 @@ var RagableBrowserDatabaseClient = class {
       {
         method,
         headers,
-        body: body !== void 0 ? JSON.stringify(body) : void 0
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        ...signal ? { signal } : {}
       }
     );
     const payload = await parseMaybeJsonBody(response);
@@ -4556,6 +5563,91 @@ function createBrowserClient(options) {
 }
 var createRagableBrowserClient = createBrowserClient;
 
+// src/server.ts
+function optionsForPrivilege(config, privilege) {
+  const base = {
+    organizationId: config.organizationId,
+    ...config.websiteId !== void 0 ? { websiteId: config.websiteId } : {},
+    ...config.authGroupId !== void 0 ? { authGroupId: config.authGroupId } : {},
+    ...config.databaseInstanceId !== void 0 ? { databaseInstanceId: config.databaseInstanceId } : {},
+    ...config.fetch !== void 0 ? { fetch: config.fetch } : {},
+    ...config.headers !== void 0 ? { headers: config.headers } : {}
+  };
+  if (privilege === "admin") {
+    const key = config.adminKey?.trim();
+    if (!key) {
+      throw new RagableError(
+        "Admin privilege requires `adminKey` (the auth group's data-admin key). It is not available \u2014 admin functions may be disabled for this project.",
+        403,
+        { code: "SDK_ADMIN_KEY_REQUIRED" }
+      );
+    }
+    return { ...base, dataAuth: "admin", dataStaticKey: key };
+  }
+  return {
+    ...base,
+    dataAuth: "auto",
+    getAccessToken: () => config.callerToken ?? null,
+    ...config.publicAnonKey !== void 0 ? { dataStaticKey: config.publicAnonKey } : {}
+  };
+}
+var RagableServerClient = class _RagableServerClient {
+  constructor(config, privilege) {
+    this.config = config;
+    __publicField(this, "database");
+    __publicField(this, "db");
+    __publicField(this, "storage");
+    __publicField(this, "mail");
+    __publicField(this, "functions");
+    __publicField(this, "ai");
+    __publicField(this, "agents");
+    /** Which credential this client is using. */
+    __publicField(this, "privilege");
+    this.privilege = privilege;
+    const options = optionsForPrivilege(config, privilege);
+    const transport = new Transport({
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      ...options.transport
+    });
+    this.database = new RagableBrowserDatabaseClient(options, null);
+    this.database._setTransport(transport);
+    this.db = this.database;
+    this.storage = new RagableBrowserStorageClient(options, bindFetch(options.fetch), null);
+    this.mail = new RagableBrowserMailClient(options, null);
+    this.functions = new RagableBrowserFunctionsClient(options, null).asInvoker();
+    this.ai = new RagableBrowserAiClient({
+      organizationId: options.organizationId,
+      ...options.websiteId !== void 0 ? { websiteId: options.websiteId } : {},
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      apiBase: normalizeBrowserApiBase()
+    });
+    this.agents = new RagableBrowserAgentsClient(options);
+  }
+  /**
+   * A client authenticated with the **data-admin key** — bypasses collection
+   * security (owner/group/claim grants do not apply) and can write protected
+   * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+   */
+  asAdmin() {
+    return new _RagableServerClient(this.config, "admin");
+  }
+  /**
+   * A client scoped to the invoking end user's identity (respects collection
+   * security). This is already the default; use it to drop back from `asAdmin()`.
+   */
+  asCaller() {
+    return new _RagableServerClient(this.config, "caller");
+  }
+};
+function createServerClient(config) {
+  return new RagableServerClient(
+    config,
+    config.defaultPrivilege ?? "caller"
+  );
+}
+
 // src/index.ts
 function createClient(options) {
   return createBrowserClient(options);
@@ -4563,6 +5655,12 @@ function createClient(options) {
 export {
   AuthBroadcastChannel,
   BrowserStorageBucketClient,
+  CollectionDeleteBuilder,
+  CollectionInsertChain,
+  CollectionMutationReturning,
+  CollectionSelectBuilder,
+  CollectionUpdateBuilder,
+  CollectionUpsertBuilder,
   CookieStorageAdapter,
   DEFAULT_RAGABLE_API_BASE,
   LocalStorageAdapter,
@@ -4592,6 +5690,7 @@ export {
   RagableError,
   RagableNetworkError,
   RagableSdkError,
+  RagableServerClient,
   RagableTimeoutError,
   SessionStorageAdapter,
   Transport,
@@ -4606,6 +5705,7 @@ export {
   createBrowserClient,
   createClient,
   createRagableBrowserClient,
+  createServerClient,
   createStreamResultFromParts,
   detectStorage,
   effectiveDataAuth,
@@ -4621,6 +5721,8 @@ export {
   normalizeBrowserApiBase,
   parseAgentStreamAgentInfo,
   parseAgentStreamDone,
+  parseOrString,
+  parseSelectExpression,
   parseSseDataLine,
   parseTransportResponse,
   readSseStream,
@@ -4633,4 +5735,3 @@ export {
   unwrapPostgrest,
   wrapStreamTextAsObject
 };
-//# sourceMappingURL=index.mjs.map