lazypock 0.12.0 → 0.14.0

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   CollectionService: () => CollectionService,
   CollectionsService: () => CollectionsService,
   FilesService: () => FilesService,
+  FilterBuilder: () => FilterBuilder,
+  FilterExpr: () => FilterExpr,
   HttpClient: () => HttpClient,
   LazypockClient: () => LazypockClient,
   RealtimeService: () => RealtimeService,
@@ -44,12 +46,13 @@ module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
 var ApiError = class extends Error {
-  constructor(message, data, status, isAbort = false) {
+  constructor(message, data, status, isAbort = false, code) {
     super(message);
     this.name = "ApiError";
     this.data = data;
     this.status = status;
     this.isAbort = isAbort;
+    this.code = code;
   }
 };
 
@@ -80,11 +83,15 @@ var HttpClient = class {
     this.inflight = {};
     /** Global toggle for the auto-cancellation behaviour (default: on). */
     this.enableAutoCancellation = true;
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this._baseUrl = baseUrl.replace(/\/+$/, "");
     this.authStore = authStore;
     this.connectionId = connectionId;
     this.defaultFetch = globalThis.fetch.bind(globalThis);
   }
+  /** The API base URL (trailing slash stripped). Used for OAuth2 origin checks. */
+  get baseUrl() {
+    return this._baseUrl;
+  }
   async refreshAuth() {
     const collection = this.authStore.collectionName;
     if (!collection) return null;
@@ -470,6 +477,340 @@ var memoryStorage = {
   }
 };
 
+// src/filter.ts
+function literal(value) {
+  if (value === null) return "null";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `[lazypock] filter: ${String(value)} is not a valid numeric value`
+      );
+    }
+    return String(value);
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  const escaped = String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `'${escaped}'`;
+}
+var FilterExpr = class _FilterExpr {
+  /** @internal Build from a raw string — use {@link FilterBuilder} instead. */
+  constructor(raw) {
+    this.raw = raw;
+  }
+  /** Combine with `&&` (both must match). */
+  and(other) {
+    return new _FilterExpr(`(${this.raw} && ${other.raw})`);
+  }
+  /** Combine with `||` (either may match). */
+  or(other) {
+    return new _FilterExpr(`(${this.raw} || ${other.raw})`);
+  }
+  /** Negate the expression (`!(…)`). */
+  not() {
+    return new _FilterExpr(`!(${this.raw})`);
+  }
+  /** The raw filter string (used when serializing the request). */
+  toString() {
+    return this.raw;
+  }
+};
+var FilterBuilder = class {
+  /** @internal Use {@link CollectionService.where}. */
+  constructor(field) {
+    this.field = field;
+  }
+  /** `field = value` (equal). */
+  eq(value) {
+    return this.cmp("=", value);
+  }
+  /** `field != value` (not equal). */
+  neq(value) {
+    return this.cmp("!=", value);
+  }
+  /** `field ~ value` (contains / LIKE). */
+  contains(value) {
+    return this.cmp("~", value);
+  }
+  /** `field !~ value` (does not contain / NOT LIKE). */
+  notContains(value) {
+    return this.cmp("!~", value);
+  }
+  /** `field > value` (greater than). */
+  gt(value) {
+    return this.cmp(">", value);
+  }
+  /** `field >= value` (greater than or equal). */
+  gte(value) {
+    return this.cmp(">=", value);
+  }
+  /** `field < value` (less than). */
+  lt(value) {
+    return this.cmp("<", value);
+  }
+  /** `field <= value` (less than or equal). */
+  lte(value) {
+    return this.cmp("<=", value);
+  }
+  /**
+   * `field = v1 || field = v2 || …` (value is in the list).
+   *
+   * ```ts
+   * svc.where("id").in(["a", "b", "c"]);
+   * // → (id = 'a' || id = 'b' || id = 'c')
+   * ```
+   */
+  in(values) {
+    return new FilterExpr(this.chain("=", " || ", values));
+  }
+  /**
+   * `field != v1 && field != v2 && …` (value is not in the list).
+   */
+  notIn(values) {
+    return new FilterExpr(this.chain("!=", " && ", values));
+  }
+  /** Build `(field <op> v <join> field <op> v …)`, wrapped for safe composing. */
+  chain(op, join, values) {
+    if (values.length === 0) {
+      throw new Error(
+        `[lazypock] filter: ${op === "=" ? "in" : "notIn"}() requires at least one value`
+      );
+    }
+    const clauses = values.map((v) => `${this.field} ${op} ${literal(v)}`);
+    return `(${clauses.join(join)})`;
+  }
+  /** `field ?= value` — at least one array element equals `value`. */
+  anyEq(value) {
+    return this.cmp("?=", value);
+  }
+  /** `field ?!= value` — at least one array element differs. */
+  anyNeq(value) {
+    return this.cmp("?!=", value);
+  }
+  /** `field ?~ value` — at least one array element contains `value`. */
+  anyContains(value) {
+    return this.cmp("?~", value);
+  }
+  /** `field ?!~ value` — at least one array element does not contain `value`. */
+  anyNotContains(value) {
+    return this.cmp("?!~", value);
+  }
+  /** `field ?> value` — at least one array element is greater. */
+  anyGt(value) {
+    return this.cmp("?>", value);
+  }
+  /** `field ?>= value` — at least one array element is greater or equal. */
+  anyGte(value) {
+    return this.cmp("?>=", value);
+  }
+  /** `field ?< value` — at least one array element is less. */
+  anyLt(value) {
+    return this.cmp("?<", value);
+  }
+  /** `field ?<= value` — at least one array element is less or equal. */
+  anyLte(value) {
+    return this.cmp("?<=", value);
+  }
+  cmp(op, value) {
+    return new FilterExpr(`${this.field} ${op} ${literal(value)}`);
+  }
+};
+
+// src/oauth2.ts
+var DEFAULT_POPUP_WIDTH = 500;
+var DEFAULT_POPUP_HEIGHT = 700;
+var DEFAULT_OAUTH2_TIMEOUT_MS = 12e4;
+var CLOSE_POLL_MS = 500;
+function oauth2RedirectOrigin(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    throw new ApiError(
+      `Invalid baseUrl for OAuth2 origin check: "${baseUrl}"`,
+      {},
+      0,
+      false,
+      "oauth2_invalid_base_url"
+    );
+  }
+}
+function isSafeBrowserUrl(url) {
+  try {
+    const protocol = new URL(url).protocol;
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function isRecordAuth(value) {
+  return !!value && typeof value === "object" && typeof value.token === "string" && !!value.record && typeof value.record === "object";
+}
+function authorizeWithOAuth2Popup(opts) {
+  return new Promise((resolve, reject) => {
+    if (typeof window === "undefined") {
+      reject(
+        new ApiError(
+          "OAuth2 popup flow requires a browser window. Use `authWithOAuth2Code()` in non-browser environments.",
+          {},
+          0,
+          false,
+          "oauth2_popup_unavailable"
+        )
+      );
+      return;
+    }
+    let settled = false;
+    let popup = null;
+    let closePoll = null;
+    let timeout = null;
+    const cleanup = () => {
+      if (timeout) {
+        clearTimeout(timeout);
+        timeout = null;
+      }
+      if (closePoll) {
+        clearInterval(closePoll);
+        closePoll = null;
+      }
+      window.removeEventListener("message", onMessage);
+    };
+    const finish = (err, result) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (err) reject(err);
+      else resolve(result);
+    };
+    const onMessage = (event) => {
+      if (event.origin !== opts.expectedOrigin) return;
+      if (popup && event.source && event.source !== popup) return;
+      const data = event.data;
+      if (!data || typeof data !== "object") return;
+      if (data.type === "lazypock:oauth2") {
+        if (isRecordAuth(data.result)) {
+          if (popup) {
+            try {
+              popup.close();
+            } catch {
+            }
+          }
+          finish(null, data.result);
+        } else {
+          finish(
+            new ApiError(
+              "OAuth2 callback returned an invalid result.",
+              data,
+              400,
+              false,
+              "oauth2_provider_error"
+            )
+          );
+        }
+        return;
+      }
+      if (data.type === "lazypock:oauth2:error") {
+        const result = data.result ?? {};
+        const message = typeof result.message === "string" && result.message ? result.message : "OAuth2 authorization failed.";
+        finish(
+          new ApiError(
+            message,
+            result,
+            typeof result.code === "number" ? result.code : 400,
+            false,
+            "oauth2_provider_error"
+          )
+        );
+      }
+    };
+    const openPopup = () => {
+      if (!isSafeBrowserUrl(opts.authURL)) {
+        finish(
+          new ApiError(
+            "OAuth2 authorization URL has an unsupported protocol.",
+            {},
+            0,
+            false,
+            "oauth2_provider_error"
+          )
+        );
+        return;
+      }
+      const width = opts.popup?.width ?? DEFAULT_POPUP_WIDTH;
+      const height = opts.popup?.height ?? DEFAULT_POPUP_HEIGHT;
+      const features = "width=" + width + ",height=" + height + ",scrollbars=yes,resizable=yes";
+      const win = window.open(opts.authURL, "_blank", features);
+      if (!win) {
+        finish(
+          new ApiError(
+            "OAuth2 popup was blocked by the browser. Please allow popups for this site and try again.",
+            {},
+            0,
+            false,
+            "oauth2_popup_blocked"
+          )
+        );
+        return;
+      }
+      popup = win;
+      closePoll = setInterval(() => {
+        if (popup && popup.closed) {
+          finish(
+            new ApiError(
+              "OAuth2 sign-in was cancelled.",
+              {},
+              0,
+              false,
+              "oauth2_cancelled"
+            )
+          );
+        }
+      }, CLOSE_POLL_MS);
+    };
+    window.addEventListener("message", onMessage);
+    timeout = setTimeout(() => {
+      if (popup) {
+        try {
+          popup.close();
+        } catch {
+        }
+      }
+      finish(
+        new ApiError(
+          "OAuth2 sign-in timed out.",
+          {},
+          0,
+          false,
+          "oauth2_timeout"
+        )
+      );
+    }, opts.timeoutMs);
+    if (opts.urlCallback) {
+      Promise.resolve(opts.urlCallback(opts.authURL)).catch((err) => {
+        finish(
+          err instanceof ApiError ? err : new ApiError(
+            `OAuth2 urlCallback failed: ${String(err)}`,
+            {},
+            0,
+            false,
+            "oauth2_provider_error"
+          )
+        );
+      });
+    } else if (typeof window.open === "function") {
+      openPopup();
+    } else {
+      finish(
+        new ApiError(
+          "OAuth2 popup flow requires a browser window. Use `authWithOAuth2Code()` in non-browser environments.",
+          {},
+          0,
+          false,
+          "oauth2_popup_unavailable"
+        )
+      );
+    }
+  });
+}
+
 // src/collection.ts
 function stableStringify(value) {
   const seen = /* @__PURE__ */ new Set();
@@ -507,14 +848,24 @@ function normalizeAction(event, rawAction) {
   if (event === "delete" || event === "record_delete") return "delete";
   return "update";
 }
+function pickFields(value, fields) {
+  if (!value || typeof value !== "object") return {};
+  const src = value;
+  const out = {};
+  for (const f of fields) {
+    if (f in src) out[f] = src[f];
+  }
+  return out;
+}
 var CollectionService = class _CollectionService {
   /** @internal */
-  constructor(http, collectionName, authStore, realtime, schema) {
+  constructor(http, collectionName, authStore, realtime, schema, schemaResolver) {
     this.http = http;
     this.collectionName = collectionName;
     this.authStore = authStore;
     this.realtime = realtime;
     this.schema = schema;
+    this.schemaResolver = schemaResolver;
   }
   encodeId(id) {
     return encodeURIComponent(id);
@@ -549,7 +900,8 @@ var CollectionService = class _CollectionService {
       this.collectionName,
       this.authStore,
       this.realtime,
-      this.schema
+      this.schema,
+      this.schemaResolver
     );
     derived.fieldsPreset = preset;
     if (this.schema && preset !== "*") {
@@ -612,20 +964,255 @@ var CollectionService = class _CollectionService {
       ])
     ].join(",");
   }
+  // ── Typed filter builder ──
+  /**
+   * Start a type-checked filter expression. The field name is suggested
+   * from the collection's key set and the value is checked against the
+   * field's type (when the service is typed). Values are escaped safely.
+   *
+   * ```ts
+   * const q = posts.where;
+   * await posts.getList(1, 20, {
+   *   filter: q("title").contains("x").and(q("published").eq(true)),
+   * });
+   * // → filter=(title ~ '%x%' && published = true)
+   *
+   * // PocketBase `?` array operators (multi-select / multi-relation):
+   * posts.getList(1, 20, { filter: q("tags").anyEq("news") });
+   * ```
+   *
+   * Chain `.and()` / `.or()` / `.not()` to compose. A `FilterExpr` can be
+   * passed anywhere a `filter` string is accepted. Relation dot-paths
+   * (`where("author.email")`) are supported by servers that compile
+   * relation dot-path filters, and `where("id").in(ids)` covers list
+   * membership without hand-written OR chains.
+   */
+  where(field) {
+    return new FilterBuilder(field);
+  }
+  /**
+   * Resolve the leading relation chain of an expand token against the
+   * (optionally schema-aware) collection graph.
+   *
+   * Walks `segments` from this collection: each segment that is a relation
+   * advances to its target collection. Stops at the first non-relation
+   * segment or when the target schema is unknown.
+   *
+   * @returns `depth` — how many leading segments are relations; and
+   * `canInspect` — whether the schema at `depth` is known (so the next
+   * segment can be classified as a field selection vs a nested relation).
+   */
+  resolveRelationChain(segments) {
+    let currentFields = this.schema?.fields;
+    if (!currentFields) return { depth: 0, canInspect: false };
+    for (let i = 0; i < segments.length; i++) {
+      const field = currentFields.find((f) => f.name === segments[i]);
+      if (!field || field.type !== "relation") {
+        return { depth: i, canInspect: true };
+      }
+      if (i === segments.length - 1) {
+        return { depth: segments.length, canInspect: true };
+      }
+      const target = this.resolveTargetCollection(field);
+      if (!target?.fields) {
+        return { depth: i + 1, canInspect: false };
+      }
+      currentFields = target.fields;
+    }
+    return { depth: segments.length, canInspect: true };
+  }
+  /** Follow a relation field to its target collection, if resolvable. */
+  resolveTargetCollection(field) {
+    const key = field.options?.collection ?? field.options?.collectionId ?? field.collectionId ?? void 0;
+    if (!key || !this.schemaResolver) return void 0;
+    return this.schemaResolver(String(key));
+  }
   /** Warn once when an expand field is not a relation (schema known). */
-  validateExpand(expand) {
-    if (!expand || !this.schema?.fields) return;
-    const relations = new Set(
-      this.schema.fields.filter((f) => f.type === "relation").map((f) => f.name)
+  warnNonRelation(name) {
+    console.warn(
+      `[lazypock] expand("${name}"): field is not a relation on collection "${this.collectionName}"`
     );
-    for (const f of expand.split(",")) {
-      const name = f.trim();
-      if (name && !relations.has(name)) {
-        console.warn(
-          `[lazypock] expand("${name}"): field is not a relation on collection "${this.collectionName}"`
-        );
+  }
+  /**
+   * Validate and normalise a caller's `expand` string.
+   *
+   * PocketBase only expands *relations*: a dotted token like `author.user`
+   * walks into the related record. Callers often use a dotted token to mean
+   * "only these fields of the expanded record" (`owner.name,owner.email`),
+   * which PocketBase silently drops. When the trailing segment is not a
+   * relation — resolved from the schema graph — the token is rewritten as a
+   * field selection:
+   *
+   * ```
+   * expand: 'owner.name,owner.email'
+   * → expand=owner&fields=<base>,expand.owner.name,expand.owner.email
+   * ```
+   *
+   * Tokens whose whole path is relations keep their existing nested-expand
+   * behaviour. Without a schema the two are indistinguishable, so a lone
+   * dotted token stays a nested expand (with a warning) while two or more
+   * dotted tokens sharing the same relation are treated as field selection.
+   */
+  normalizeExpand(expand) {
+    const narrow = /* @__PURE__ */ new Map();
+    if (!expand) return { fieldSelectors: [], narrow };
+    const tokens = expand.split(",").map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0) return { fieldSelectors: [], narrow };
+    const relations = this.schema?.fields ? new Set(
+      this.schema.fields.filter((f) => f.type === "relation").map((f) => f.name)
+    ) : void 0;
+    const parsed = [];
+    for (const token of tokens) {
+      const segments = token.split(".").filter(Boolean);
+      const base = segments[0] ?? token;
+      if (segments.length <= 1) {
+        if (relations && !relations.has(base)) {
+          this.warnNonRelation(base);
+        }
+        parsed.push({ token, base, segments, kind: "plain", depth: 0 });
+        continue;
+      }
+      if (!relations) {
+        parsed.push({ token, base, segments, kind: "unknown", depth: 1 });
+        continue;
+      }
+      const { depth, canInspect } = this.resolveRelationChain(segments);
+      if (depth === 0) {
+        this.warnNonRelation(base);
+        parsed.push({ token, base, segments, kind: "plain", depth: 0 });
+      } else if (depth === segments.length) {
+        parsed.push({ token, base, segments, kind: "nested", depth });
+      } else if (canInspect) {
+        parsed.push({ token, base, segments, kind: "narrow", depth });
+      } else {
+        parsed.push({ token, base, segments, kind: "unknown", depth });
       }
     }
+    const byBase = /* @__PURE__ */ new Map();
+    for (const t of parsed) {
+      const arr = byBase.get(t.base);
+      if (arr) arr.push(t);
+      else byBase.set(t.base, [t]);
+    }
+    for (const [base, group] of byBase) {
+      const unknowns = group.filter((t) => t.kind === "unknown");
+      if (unknowns.length === 0) continue;
+      const distinct = new Set(unknowns.map((t) => t.token));
+      const hasNarrow = group.some((t) => t.kind === "narrow");
+      if (!hasNarrow && distinct.size < 2) {
+        for (const t of unknowns) {
+          t.kind = "nested";
+          console.warn(
+            `[lazypock] expand("${t.token}"): treated as a nested relation. Pass types.schemas (or use fields=) to select fields of "${base}".`
+          );
+        }
+      } else {
+        for (const t of unknowns) t.kind = "narrow";
+      }
+    }
+    const expandParams = [];
+    const expandSeen = /* @__PURE__ */ new Set();
+    const fieldSelectors = [];
+    const selectorSeen = /* @__PURE__ */ new Set();
+    const pushParam = (p) => {
+      if (!expandSeen.has(p)) {
+        expandSeen.add(p);
+        expandParams.push(p);
+      }
+    };
+    const pushSelector = (s) => {
+      if (!selectorSeen.has(s)) {
+        selectorSeen.add(s);
+        fieldSelectors.push(s);
+      }
+    };
+    for (const t of parsed) {
+      if (t.kind === "plain") {
+        pushParam(t.token);
+        pushSelector(`expand.${t.token}`);
+      } else if (t.kind === "nested") {
+        for (let i = 1; i <= t.segments.length; i++) {
+          pushParam(t.segments.slice(0, i).join("."));
+        }
+        pushSelector(`expand.${t.segments[0]}`);
+      } else {
+        const depth = Math.max(1, t.depth);
+        const relationPath = t.segments.slice(0, depth).join(".");
+        pushParam(relationPath);
+        pushSelector(`expand.${t.segments.slice(0, depth + 1).join(".")}`);
+        if (t.segments.length === depth + 1) {
+          const base = t.segments[0];
+          const leaf = t.segments[depth];
+          const leaves = narrow.get(base) ?? [];
+          if (!leaves.includes(leaf)) leaves.push(leaf);
+          narrow.set(base, leaves);
+        }
+      }
+    }
+    return {
+      expand: expandParams.length > 0 ? expandParams.join(",") : void 0,
+      fieldSelectors,
+      narrow
+    };
+  }
+  /**
+   * Keep only the requested leaf fields on `record.expand.<relation>`.
+   *
+   * Mirrors PocketBase's server-side `fields=expand.<rel>.<field>` projection
+   * for servers that don't support it (the LazyPock server), so field
+   * selection behaves the same against both. A no-op when the server already
+   * narrowed the record. Multi-relations are narrowed element-wise.
+   */
+  applyExpandNarrowing(record, narrow) {
+    if (narrow.size === 0) return record;
+    const rec = record;
+    const expand = rec.expand;
+    if (!expand || typeof expand !== "object") return record;
+    const next = { ...expand };
+    for (const [relation, leaves] of narrow) {
+      const value = next[relation];
+      if (value === void 0 || value === null) continue;
+      next[relation] = Array.isArray(value) ? value.map((el) => pickFields(el, leaves)) : pickFields(value, leaves);
+    }
+    return { ...rec, expand: next };
+  }
+  /**
+   * Merge the expand-preserving selectors into the base field projection.
+   *
+   * Both servers are kept happy at once:
+   * - PocketBase drops the whole `expand` payload unless an `expand.<key>`
+   *   entry is present in `fields`;
+   * - the LazyPock server projects first (strict, top-level only) and then
+   *   expands, so the relation *field* itself must be present in `fields`.
+   *
+   * We therefore add both the relation field (`cate`) and the
+   * `expand.<key>` entry. When no projection is active, no `fields` param is
+   * sent at all — a value like `*` plus other tokens is not a wildcard on
+   * the LazyPock server (it is a strict take, yielding empty records) and
+   * the server keeps `expand` by default when `fields` is absent.
+   */
+  mergeExpandFields(base, info) {
+    if (info.fieldSelectors.length === 0) return base;
+    if (base === void 0) return void 0;
+    const parts = base.split(",").map((f) => f.trim()).filter(Boolean);
+    const seen = new Set(parts);
+    const push = (value) => {
+      if (seen.has(value)) return;
+      seen.add(value);
+      parts.push(value);
+    };
+    const fullKeys = /* @__PURE__ */ new Set();
+    for (const selector of info.fieldSelectors) {
+      const seg = selector.split(".");
+      if (seg.length === 2) fullKeys.add(seg[1]);
+    }
+    for (const selector of info.fieldSelectors) {
+      const seg = selector.split(".");
+      if (seg.length > 2 && fullKeys.has(seg[1])) continue;
+      if (seg.length >= 2) push(seg[1]);
+      push(selector);
+    }
+    return parts.join(",");
   }
   /**
    * Fetch a paginated list of records (PocketBase `getList`).
@@ -634,7 +1221,7 @@ var CollectionService = class _CollectionService {
    * @param perPage Records per page (default 30).
    * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
    */
-  getList(page = 1, perPage = 30, options) {
+  async getList(page = 1, perPage = 30, options) {
     const {
       requestKey,
       autoCancel,
@@ -646,12 +1233,24 @@ var CollectionService = class _CollectionService {
       params,
       ...queryParams
     } = options ?? {};
-    const fields = this.effectiveFields(queryParams.fields);
-    if (fields !== void 0 && queryParams.fields === void 0) {
-      queryParams.fields = fields;
+    if (Array.isArray(queryParams.sort)) {
+      queryParams.sort = queryParams.sort.join(",");
+    }
+    if (Array.isArray(queryParams.expand)) {
+      queryParams.expand = queryParams.expand.join(",");
     }
-    if (typeof queryParams.expand === "string") {
-      this.validateExpand(queryParams.expand);
+    const expandInfo = this.normalizeExpand(
+      typeof queryParams.expand === "string" ? queryParams.expand : void 0
+    );
+    if (expandInfo.expand !== void 0) {
+      queryParams.expand = expandInfo.expand;
+    }
+    const fields = this.mergeExpandFields(
+      this.effectiveFields(queryParams.fields),
+      expandInfo
+    );
+    if (fields !== void 0) {
+      queryParams.fields = fields;
     }
     const qs = new URLSearchParams(
       Object.fromEntries(
@@ -662,19 +1261,22 @@ var CollectionService = class _CollectionService {
         }).map(([k, v]) => [k, String(v)])
       )
     ).toString();
-    return this.http.get(
-      "/" + this.encodeId(this.collectionName) + "?" + qs,
-      {
-        requestKey,
-        autoCancel,
-        cancelKey,
-        fetch,
-        headers,
-        signal,
-        singleFlight,
-        params
-      }
-    );
+    const result = await this.http.get("/" + this.encodeId(this.collectionName) + "?" + qs, {
+      requestKey,
+      autoCancel,
+      cancelKey,
+      fetch,
+      headers,
+      signal,
+      singleFlight,
+      params
+    });
+    if (result && expandInfo.narrow.size > 0) {
+      result.items = result.items.map(
+        (item) => this.applyExpandNarrowing(item, expandInfo.narrow)
+      );
+    }
+    return result;
   }
   /**
    * Fetch all records at once (auto-paginates). Mirrors PocketBase's
@@ -722,19 +1324,32 @@ var CollectionService = class _CollectionService {
    * @param id Record ID.
    * @param options Optional request options.
    */
-  getOne(id, options) {
-    const fields = this.effectiveFields(options?.fields);
-    if (typeof options?.expand === "string") {
-      this.validateExpand(options.expand);
-    }
+  async getOne(id, options) {
+    let rawExpand;
+    if (Array.isArray(options?.expand)) {
+      rawExpand = options.expand.join(",");
+    } else if (typeof options?.expand === "string") {
+      rawExpand = options.expand;
+    }
+    const expandInfo = this.normalizeExpand(rawExpand);
+    const fields = this.mergeExpandFields(
+      this.effectiveFields(options?.fields),
+      expandInfo
+    );
     const qs = new URLSearchParams();
     if (fields !== void 0) qs.set("fields", fields);
-    if (typeof options?.expand === "string") qs.set("expand", options.expand);
+    if (rawExpand !== void 0) {
+      qs.set("expand", expandInfo.expand ?? rawExpand);
+    }
     const qsStr = qs.toString();
-    return this.http.get(
+    const record = await this.http.get(
       "/" + this.encodeId(this.collectionName) + "/" + this.encodeId(id) + (qsStr ? "?" + qsStr : ""),
       options
     );
+    if (record && expandInfo.narrow.size > 0) {
+      return this.applyExpandNarrowing(record, expandInfo.narrow);
+    }
+    return record;
   }
   /**
    * Create a new record.
@@ -818,7 +1433,8 @@ var CollectionService = class _CollectionService {
       this.collectionName,
       this.authStore,
       this.realtime,
-      schema
+      schema,
+      this.schemaResolver
     );
     derived.fieldsPreset = this.fieldsPreset;
     return derived;
@@ -904,15 +1520,108 @@ var CollectionService = class _CollectionService {
     return data;
   }
   /**
-   * Get available auth methods for this collection.
+   * Get available auth methods for this collection (PocketBase `listAuthMethods`).
+   * Returns `password`, `oauth2.providers` (each with `name`, `authURL`,
+   * `state`, `codeVerifier`), and `mfa`.
    */
-  // ── end Realtime ──
-  async authMethods(options) {
+  async listAuthMethods(options) {
     return this.http.get(
       "/" + this.encodeId(this.collectionName) + "/auth-methods",
       options
     );
   }
+  /**
+   * Get available auth methods for this collection.
+   * @deprecated Use {@link listAuthMethods} (typed).
+   */
+  authMethods(options) {
+    return this.listAuthMethods(options);
+  }
+  /**
+   * Sign in with an OAuth2 provider (PocketBase `authWithOAuth2` parity).
+   *
+   * One call handles the whole web flow: fetch the provider's `authURL`,
+   * open a popup (or call `options.urlCallback`), wait for the backend's
+   * `postMessage` result, populate the auth store, and resolve with
+   * `{ token, record, meta }`.
+   *
+   * `options.createData` is accepted for PocketBase signature parity but is
+   * **not** forwarded by the backend's popup redirect flow — use
+   * {@link authWithOAuth2Code} when you need extra fields on first sign-up.
+   *
+   * React Native / non-browser: the popup flow depends on
+   * `window.postMessage`. Use {@link listAuthMethods} + {@link authWithOAuth2Code}
+   * instead.
+   */
+  async authWithOAuth2(options) {
+    const {
+      provider,
+      urlCallback,
+      popup,
+      timeoutMs = DEFAULT_OAUTH2_TIMEOUT_MS
+    } = options;
+    const methods = await this.listAuthMethods();
+    const providerInfo = methods?.oauth2?.providers?.find(
+      (p) => p.name === provider
+    );
+    if (!providerInfo) {
+      throw new ApiError(
+        `OAuth2 provider "${provider}" is not enabled for this collection.`,
+        methods ?? {},
+        400,
+        false,
+        "oauth2_unknown_provider"
+      );
+    }
+    const result = await authorizeWithOAuth2Popup({
+      authURL: providerInfo.authURL,
+      expectedOrigin: oauth2RedirectOrigin(this.http.baseUrl),
+      urlCallback,
+      popup,
+      timeoutMs
+    });
+    if (this.authStore) {
+      this.authStore.setCollectionName(this.collectionName);
+      this.authStore.set(result.token, result.record);
+    }
+    return result;
+  }
+  /**
+   * Exchange an OAuth2 authorization code directly (PocketBase
+   * `authWithOAuth2Code` parity).
+   *
+   * Used by mobile / non-browser flows: fetch {@link listAuthMethods} to get
+   * the provider `authURL` + `codeVerifier`, present the URL yourself,
+   * capture the `code` from your redirect/deep link, then call this to
+   * finish and populate the auth store.
+   */
+  async authWithOAuth2Code(options) {
+    const { provider, code, codeVerifier, redirectUrl, createData } = options;
+    const data = await this.http.post(
+      "/" + this.encodeId(this.collectionName) + "/auth-with-oauth2",
+      {
+        provider,
+        code,
+        codeVerifier,
+        redirectUrl: redirectUrl ?? this.http.baseUrl + "/oauth2-redirect",
+        createData: createData ?? {}
+      }
+    );
+    if (!data) {
+      throw new ApiError(
+        "OAuth2 code exchange returned no data.",
+        {},
+        0,
+        false,
+        "oauth2_exchange_failed"
+      );
+    }
+    if (this.authStore) {
+      this.authStore.setCollectionName(this.collectionName);
+      this.authStore.set(data.token, data.record);
+    }
+    return data;
+  }
 };
 
 // src/realtime.ts
@@ -1803,6 +2512,10 @@ var LazypockClient = class {
       this.schemaByName = new Map(
         options.types.schemas.map((s) => [s.name, s])
       );
+      this.schemaById = /* @__PURE__ */ new Map();
+      for (const s of options.types.schemas) {
+        if (s.id) this.schemaById.set(String(s.id), s);
+      }
     }
   }
   /**
@@ -1825,7 +2538,10 @@ var LazypockClient = class {
         this.authStore,
         this.realtime,
         // Prefer the explicit schema, then the client-level `types.schemas`.
-        schema ?? this.schemaByName?.get(name)
+        schema ?? this.schemaByName?.get(name),
+        // Let the service follow relation fields into other collections
+        // (expand field selection vs nested-relation expansion).
+        (key) => this.schemaByName?.get(key) ?? this.schemaById?.get(key)
       );
       this.collectionCache.set(name, svc);
     }
@@ -2021,6 +2737,8 @@ function createClient(options) {
   CollectionService,
   CollectionsService,
   FilesService,
+  FilterBuilder,
+  FilterExpr,
   HttpClient,
   LazypockClient,
   RealtimeService,