@linabase/js 0.5.1 → 0.5.3

package/dist/index.js

@@ -18,7 +18,23 @@ var DatabaseClient = class {
     this.params = new URLSearchParams();
   }
   // ─── Query Methods ──────────────────────────────────────
-  /** Select columns. Supports nested joins: "*, comments(*)" and aliases: "full_name:name" */
+  /**
+   * Pick which columns to return. Supports nested joins (`"*, comments(*)"`)
+   * and column aliases (`"full_name:name"`). When chained after a mutation
+   * (`insert` / `update` / `upsert` / `delete`), it switches the request to
+   * `Prefer: return=representation` so the modified rows come back.
+   *
+   * @param columns - Postgres-style column list. Defaults to `"*"`.
+   * @param options - `count` returns a row count alongside the data; `head`
+   *   omits the rows entirely (useful for count-only queries).
+   *
+   * @example
+   * ```ts
+   * await linabase.from("posts").select("id, title");
+   * await linabase.from("posts").select("*, author:profiles(name)");
+   * await linabase.from("posts").select("*", { count: "exact", head: true });
+   * ```
+   */
   select(columns, options) {
     const isMutation = this.method === "POST" || this.method === "PATCH" || this.method === "DELETE";
     if (!isMutation) {
@@ -30,6 +46,15 @@ var DatabaseClient = class {
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
     return this;
   }
+  /**
+   * Insert one row or many. Returns the inserted rows by default.
+   *
+   * @example
+   * ```ts
+   * await linabase.from("posts").insert({ title: "Hi" });
+   * await linabase.from("posts").insert([{ title: "A" }, { title: "B" }]);
+   * ```
+   */
   insert(data, options) {
     this.method = "POST";
     this.body = data;
@@ -51,12 +76,36 @@ var DatabaseClient = class {
     if (options?.defaultToNull === false) this.preferHeaders.push("missing=default");
     return this;
   }
+  /**
+   * Update rows that match the active filters.
+   *
+   * @example
+   * ```ts
+   * await linabase
+   *   .from("posts")
+   *   .update({ published: true })
+   *   .eq("id", 42);
+   * ```
+   */
   update(data) {
     this.method = "PATCH";
     this.body = data;
     this.preferHeaders.push("return=representation");
     return this;
   }
+  /**
+   * Delete rows that match the active filters. **Always** combine with at
+   * least one filter (e.g. `.eq("id", x)`) — calling `.delete()` on a bare
+   * builder removes every row in the table.
+   *
+   * @example
+   * ```ts
+   * await linabase
+   *   .from("posts")
+   *   .delete()
+   *   .eq("id", 42);
+   * ```
+   */
   delete(options) {
     this.method = "DELETE";
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
@@ -83,36 +132,36 @@ var DatabaseClient = class {
   }
   // ─── Comparison Filters ─────────────────────────────────
   eq(column, value) {
-    this.params.set(column, `eq.${value}`);
+    this.params.append(column, `eq.${value}`);
     return this;
   }
   neq(column, value) {
-    this.params.set(column, `neq.${value}`);
+    this.params.append(column, `neq.${value}`);
     return this;
   }
   gt(column, value) {
-    this.params.set(column, `gt.${value}`);
+    this.params.append(column, `gt.${value}`);
     return this;
   }
   gte(column, value) {
-    this.params.set(column, `gte.${value}`);
+    this.params.append(column, `gte.${value}`);
     return this;
   }
   lt(column, value) {
-    this.params.set(column, `lt.${value}`);
+    this.params.append(column, `lt.${value}`);
     return this;
   }
   lte(column, value) {
-    this.params.set(column, `lte.${value}`);
+    this.params.append(column, `lte.${value}`);
     return this;
   }
   // ─── Pattern Matching ───────────────────────────────────
   like(column, pattern) {
-    this.params.set(column, `like.${pattern}`);
+    this.params.append(column, `like.${pattern}`);
     return this;
   }
   ilike(column, pattern) {
-    this.params.set(column, `ilike.${pattern}`);
+    this.params.append(column, `ilike.${pattern}`);
     return this;
   }
   /** Regex match (~) when called with (column, pattern). Object-based multi-column filter when called with ({ col: val }). */
@@ -122,76 +171,76 @@ var DatabaseClient = class {
         this.eq(key, value);
       }
     } else if (pattern !== void 0) {
-      this.params.set(columnOrFilter, `match.${pattern}`);
+      this.params.append(columnOrFilter, `match.${pattern}`);
     }
     return this;
   }
   /** Case-insensitive regex match (~*) */
   imatch(column, pattern) {
-    this.params.set(column, `imatch.${pattern}`);
+    this.params.append(column, `imatch.${pattern}`);
     return this;
   }
   // ─── Array/Set Filters ──────────────────────────────────
   in(column, values) {
-    this.params.set(column, `in.(${values.join(",")})`);
+    this.params.append(column, `in.(${values.join(",")})`);
     return this;
   }
   /** Contains (@>) - array or JSONB containment */
   contains(column, value) {
-    this.params.set(column, `cs.${JSON.stringify(value)}`);
+    this.params.append(column, `cs.${JSON.stringify(value)}`);
     return this;
   }
   /** Contained by (<@) */
   containedBy(column, value) {
-    this.params.set(column, `cd.${JSON.stringify(value)}`);
+    this.params.append(column, `cd.${JSON.stringify(value)}`);
     return this;
   }
   /** Overlap (&&) - ranges or arrays */
   overlaps(column, value) {
-    this.params.set(column, `ov.${JSON.stringify(value)}`);
+    this.params.append(column, `ov.${JSON.stringify(value)}`);
     return this;
   }
   // ─── Null/Boolean ───────────────────────────────────────
   is(column, value) {
     const v = value === null ? "null" : String(value);
-    this.params.set(column, `is.${v}`);
+    this.params.append(column, `is.${v}`);
     return this;
   }
   /** IS DISTINCT FROM */
   isDistinct(column, value) {
-    this.params.set(column, `isdistinct.${value}`);
+    this.params.append(column, `isdistinct.${value}`);
     return this;
   }
   // ─── Range Type Filters ──────────────────────────────────
   /** Strictly left of: [a,b] << [c,d] */
   rangeLt(column, range) {
-    this.params.set(column, `sl.${range}`);
+    this.params.append(column, `sl.${range}`);
     return this;
   }
   /** Strictly right of: [a,b] >> [c,d] */
   rangeGt(column, range) {
-    this.params.set(column, `sr.${range}`);
+    this.params.append(column, `sr.${range}`);
     return this;
   }
   /** Does not extend to the left of */
   rangeGte(column, range) {
-    this.params.set(column, `nxl.${range}`);
+    this.params.append(column, `nxl.${range}`);
     return this;
   }
   /** Does not extend to the right of */
   rangeLte(column, range) {
-    this.params.set(column, `nxr.${range}`);
+    this.params.append(column, `nxr.${range}`);
     return this;
   }
   /** Range is adjacent to */
   rangeAdjacent(column, range) {
-    this.params.set(column, `adj.${range}`);
+    this.params.append(column, `adj.${range}`);
     return this;
   }
   // ─── Negation ───────────────────────────────────────────
   /** Negate a filter: not.eq, not.in, not.is, etc. */
   not(column, operator, value) {
-    this.params.set(column, `not.${operator}.${value}`);
+    this.params.append(column, `not.${operator}.${value}`);
     return this;
   }
   // ─── Logical ────────────────────────────────────────────
@@ -209,7 +258,7 @@ var DatabaseClient = class {
   }
   /** Generic filter: filter("column", "operator", "value") */
   filter(column, operator, value) {
-    this.params.set(column, `${operator}.${value}`);
+    this.params.append(column, `${operator}.${value}`);
     return this;
   }
   // ─── Full-Text Search ───────────────────────────────────
@@ -217,7 +266,7 @@ var DatabaseClient = class {
   textSearch(column, query, options) {
     const op = options?.type === "plain" ? "plfts" : options?.type === "phrase" ? "phfts" : options?.type === "websearch" ? "wfts" : "fts";
     const config = options?.config ? `(${options.config})` : "";
-    this.params.set(column, `${op}${config}.${query}`);
+    this.params.append(column, `${op}${config}.${query}`);
     return this;
   }
   // ─── Ordering & Pagination ──────────────────────────────
@@ -498,6 +547,24 @@ var BucketClient = class {
     this.bucket = bucket;
     this.baseUrl = baseUrl || "";
   }
+  /**
+   * Upload a file to the bucket at the given path.
+   *
+   * @param path - Object key inside the bucket (e.g. `userId/avatar.png`).
+   * @param file - File contents as `Blob`, `File`, or `ArrayBuffer`.
+   * @param options.contentType - Override the content type. Inferred from
+   *   `File`/`Blob` when not set.
+   * @param options.upsert - If true, replaces an existing object at the same
+   *   path. Defaults to false (returns an error if the path is taken).
+   *
+   * @example
+   * ```ts
+   * const file = e.target.files![0];
+   * await linabase.storage
+   *   .from("avatars")
+   *   .upload(`${userId}/avatar.png`, file, { upsert: true });
+   * ```
+   */
   async upload(path, file, options) {
     try {
       const formData = new FormData();
@@ -519,6 +586,18 @@ var BucketClient = class {
       return { data: null, error: { message: err.message } };
     }
   }
+  /**
+   * Download an object as a `Blob`.
+   *
+   * @example
+   * ```ts
+   * const { data } = await linabase.storage.from("docs").download("file.pdf");
+   * if (data) {
+   *   const url = URL.createObjectURL(data);
+   *   window.open(url);
+   * }
+   * ```
+   */
   async download(path) {
     try {
       const res = await this.request(
@@ -567,6 +646,19 @@ var BucketClient = class {
       return { data: null, error: { message: err.message } };
     }
   }
+  /**
+   * Build a public URL for an object in a public bucket. No request is made;
+   * this just constructs the URL synchronously.
+   *
+   * For private buckets, use {@link createSignedUrl} instead.
+   *
+   * @example
+   * ```ts
+   * const { data: { publicUrl } } = linabase.storage
+   *   .from("avatars")
+   *   .getPublicUrl(`${userId}/avatar.png`, { transform: { width: 64, height: 64 } });
+   * ```
+   */
   getPublicUrl(path, options) {
     let url;
     if (options?.transform) {
@@ -585,6 +677,18 @@ var BucketClient = class {
     }
     return { data: { publicUrl: url } };
   }
+  /**
+   * Generate a time-limited signed URL for a private object. Valid for
+   * `expiresIn` seconds.
+   *
+   * @example
+   * ```ts
+   * const { data } = await linabase.storage
+   *   .from("docs")
+   *   .createSignedUrl(`${userId}/report.pdf`, 3600);
+   * if (data) window.open(data.signedUrl);
+   * ```
+   */
   async createSignedUrl(path, expiresIn) {
     try {
       const res = await this.request(
@@ -755,6 +859,22 @@ var AuthClient = class {
     }
   }
   // ─── Email/Password ────────────────────────────────────────
+  /**
+   * Create a new user account with email + password.
+   *
+   * On success, the user is signed in and the session is persisted. Pass
+   * extra metadata via `data`; it is stored on the user record and
+   * available later as `user.user_metadata`.
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await linabase.auth.signUp({
+   *   email: "alice@example.com",
+   *   password: "correct horse battery staple",
+   *   data: { full_name: "Alice" },
+   * });
+   * ```
+   */
   async signUp(params) {
     try {
       const res = await this.request("/auth/v1/signup", {
@@ -771,6 +891,21 @@ var AuthClient = class {
       return { data: null, error: { message: err.message } };
     }
   }
+  /**
+   * Sign in an existing user with email + password.
+   *
+   * Alias of {@link signInWithPassword}. On success, the session is persisted
+   * and subsequent SDK calls use the returned access token automatically.
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await linabase.auth.signIn({
+   *   email: "alice@example.com",
+   *   password: "correct horse battery staple",
+   * });
+   * if (error) console.error(error.message);
+   * ```
+   */
   async signIn(params) {
     try {
       const res = await this.request("/auth/v1/token?grant_type=password", {
@@ -812,6 +947,105 @@ var AuthClient = class {
       return { data: null, error: { message: err.message } };
     }
   }
+  // ─── Device-bound (Mobile) ──────────────────────────────────
+  /**
+   * Sign in with a device-bound secret. Intended for mobile clients that
+   * generate a random secret on first launch and persist it in the device
+   * keychain. No email or password is involved.
+   *
+   * Pass `create: true` on first launch to register a new anonymous user.
+   * Subsequent launches should call without `create` (or with `create: false`)
+   * to refuse silent account creation if the keychain entry was lost.
+   *
+   * Requires "Device-bound sign-ins" to be enabled in the project's Auth
+   * Settings.
+   *
+   * @example
+   * ```ts
+   * const secret = getOrCreateDeviceSecret();
+   * const { data, error } = await linabase.auth.signInWithDevice({
+   *   deviceSecret: secret,
+   *   create: true,
+   * });
+   * ```
+   */
+  async signInWithDevice(params) {
+    try {
+      const res = await this.request("/auth/v1/token?grant_type=device", {
+        method: "POST",
+        body: JSON.stringify({
+          device_secret: params.deviceSecret,
+          create: params.create,
+          data: params.data
+        })
+      });
+      const data = await res.json();
+      if (!res.ok) return { data: null, error: data };
+      const session = this.parseAuthResponse(data);
+      this.setSession(session, true);
+      this.emit("SIGNED_IN", session);
+      return { data: session, error: null };
+    } catch (err) {
+      return { data: null, error: { message: err.message } };
+    }
+  }
+  // ─── Game Center (iOS) ──────────────────────────────────────
+  /**
+   * Sign in with an Apple Game Center identity assertion. The mobile client
+   * obtains the assertion fields via
+   * `GKLocalPlayer.local.fetchItems(forIdentityVerificationSignature:)` (iOS
+   * 13.5+) and forwards them here. The project must have the app's bundle ID
+   * configured in the Game Center allowlist.
+   */
+  async signInWithGameCenter(params) {
+    try {
+      const res = await this.request("/auth/v1/token?grant_type=game_center", {
+        method: "POST",
+        body: JSON.stringify({
+          player_id: params.playerId,
+          bundle_id: params.bundleId,
+          public_key_url: params.publicKeyURL,
+          signature: params.signature,
+          salt: params.salt,
+          timestamp: params.timestamp,
+          display_name: params.displayName
+        })
+      });
+      const data = await res.json();
+      if (!res.ok) return { data: null, error: data };
+      const session = this.parseAuthResponse(data);
+      this.setSession(session, true);
+      this.emit("SIGNED_IN", session);
+      return { data: session, error: null };
+    } catch (err) {
+      return { data: null, error: { message: err.message } };
+    }
+  }
+  // ─── Google Play Games (Android) ────────────────────────────
+  /**
+   * Sign in with a Google Play Games server auth code obtained via
+   * `PlayGamesSignInClient.requestServerSideAccess(serverClientId)`. The
+   * project must have the matching OAuth client configured in Auth Settings.
+   */
+  async signInWithPlayGames(params) {
+    try {
+      const res = await this.request("/auth/v1/token?grant_type=play_games", {
+        method: "POST",
+        body: JSON.stringify({
+          server_auth_code: params.serverAuthCode,
+          redirect_uri: params.redirectUri
+        })
+      });
+      const data = await res.json();
+      if (!res.ok) return { data: null, error: data };
+      const session = this.parseAuthResponse(data);
+      this.setSession(session, true);
+      this.emit("SIGNED_IN", session);
+      return { data: session, error: null };
+    } catch (err) {
+      return { data: null, error: { message: err.message } };
+    }
+  }
   // ─── OAuth ─────────────────────────────────────────────────
   signInWithOAuth(params) {
     const queryParams = new URLSearchParams({ provider: params.provider });
@@ -825,6 +1059,16 @@ var AuthClient = class {
     return { url };
   }
   // ─── Session Management ────────────────────────────────────
+  /**
+   * Sign the current user out, clear the persisted session, and revoke the
+   * refresh token on the server. Fires a `SIGNED_OUT` event to listeners
+   * registered with `onAuthStateChange`.
+   *
+   * @example
+   * ```ts
+   * await linabase.auth.signOut();
+   * ```
+   */
   async signOut() {
     try {
       await this.request("/auth/v1/logout", { method: "POST" });
@@ -835,6 +1079,17 @@ var AuthClient = class {
       return { error: { message: err.message } };
     }
   }
+  /**
+   * Return the current persisted session. Auto-refreshes if the access
+   * token is expired and a refresh token is available. Returns
+   * `{ session: null }` when the user isn't signed in.
+   *
+   * @example
+   * ```ts
+   * const { data: { session } } = await linabase.auth.getSession();
+   * if (session) console.log("Signed in as", session.user.email);
+   * ```
+   */
   async getSession() {
     if (this.currentSession) {
       const now = Math.floor(Date.now() / 1e3);
@@ -1035,6 +1290,41 @@ var AuthClient = class {
         } catch (err) {
           return { error: { message: err.message } };
         }
+      },
+      async listSessions(userId) {
+        try {
+          const res = await request(`/auth/v1/admin/users/${userId}/sessions`);
+          const data = await res.json();
+          if (!res.ok) return { data: null, error: data };
+          return { data: data.sessions, error: null };
+        } catch (err) {
+          return { data: null, error: { message: err.message } };
+        }
+      },
+      async deleteSession(userId, sessionId) {
+        try {
+          const res = await request(`/auth/v1/admin/users/${userId}/sessions/${sessionId}`, {
+            method: "DELETE"
+          });
+          const data = await res.json().catch(() => ({}));
+          if (!res.ok) return { data: null, error: data };
+          return { data, error: null };
+        } catch (err) {
+          return { data: null, error: { message: err.message } };
+        }
+      },
+      async deleteOtherSessions(userId, exceptSessionId) {
+        try {
+          const qs = exceptSessionId ? `?except=${encodeURIComponent(exceptSessionId)}` : "";
+          const res = await request(`/auth/v1/admin/users/${userId}/sessions${qs}`, {
+            method: "DELETE"
+          });
+          const data = await res.json().catch(() => ({}));
+          if (!res.ok) return { data: null, error: data };
+          return { data, error: null };
+        } catch (err) {
+          return { data: null, error: { message: err.message } };
+        }
       }
     };
   }
@@ -1148,6 +1438,19 @@ var FunctionsClient = class {
   constructor(request) {
     this.request = request;
   }
+  /**
+   * Call a function by name.
+   *
+   * @param name - Function slug as registered on the project.
+   * @param options - Body, method, and optional extra headers.
+   * @returns `{ data, error }` — `data` is the parsed JSON response, `error`
+   *   is an object with `message` if the call failed (HTTP non-2xx or thrown).
+   *
+   * @example
+   * ```ts
+   * await linabase.functions.invoke("ping");
+   * ```
+   */
   async invoke(name, options) {
     try {
       const method = options?.method || "POST";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linabase/js",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "JavaScript/TypeScript client SDK for Linabase (database, storage, auth)",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,9 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "docs:json": "typedoc --json dist/typedoc.json",
+    "docs:reference": "pnpm docs:json && node scripts/build-reference.mjs"
   },
   "devDependencies": {
     "@linabase/db": "workspace:*",
@@ -52,6 +54,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "pg": "^8.13.0",
     "tsup": "^8.3.0",
+    "typedoc": "^0.28.19",
     "typescript": "^5.7.0",
     "vitest": "^3.2.1"
   }