@linabase/js 0.5.2 → 0.5.3

package/dist/index.d.cts

@@ -20,6 +20,43 @@ interface CsvQueryResult {
     error: PostgrestError | null;
     count: number | null;
 }
+/**
+ * Chainable query builder for a Postgres table.
+ *
+ * Created by `linabase.from(table)`. Every chained method returns the same
+ * client so you can keep adding filters, modifiers, and projections. Awaiting
+ * the chain (or calling a terminal method like `.single()` or `.csv()`)
+ * sends the request.
+ *
+ * Queries respect row-level security: signed-in users see only the rows
+ * their RLS policies allow.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await linabase
+ *   .from("posts")
+ *   .select("id, title, author:profiles(name)")
+ *   .eq("published", true)
+ *   .order("created_at", { ascending: false })
+ *   .limit(20);
+ * ```
+ *
+ * @example Insert
+ * ```ts
+ * await linabase
+ *   .from("posts")
+ *   .insert({ title: "Hello", body: "World" });
+ * ```
+ *
+ * @example Update + return updated rows
+ * ```ts
+ * const { data } = await linabase
+ *   .from("posts")
+ *   .update({ title: "Edited" })
+ *   .eq("id", 42)
+ *   .select();
+ * ```
+ */
 declare class DatabaseClient {
     private request;
     private table;
@@ -34,11 +71,36 @@ declare class DatabaseClient {
     private _abortSignal;
     private _schema;
     constructor(request: RequestFn$3, table: string);
-    /** 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?: string, options?: {
         count?: "exact" | "estimated" | "planned";
         head?: boolean;
     }): 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: Record<string, any> | Record<string, any>[], options?: {
         defaultToNull?: boolean;
     }): this;
@@ -48,7 +110,31 @@ declare class DatabaseClient {
         onConflict?: string;
         defaultToNull?: boolean;
     }): this;
+    /**
+     * Update rows that match the active filters.
+     *
+     * @example
+     * ```ts
+     * await linabase
+     *   .from("posts")
+     *   .update({ published: true })
+     *   .eq("id", 42);
+     * ```
+     */
     update(data: Record<string, any>): 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?: {
         count?: "exact" | "estimated" | "planned";
     }): this;
@@ -159,6 +245,23 @@ declare class RpcClient {
 }
 
 type RequestFn$2 = (path: string, options?: RequestInit) => Promise<Response>;
+/**
+ * S3-compatible storage API for a project.
+ *
+ * Exposed via `linabase.storage`. Provides bucket management at the top
+ * level; per-bucket file operations live on {@link BucketClient}, accessed
+ * via `linabase.storage.from("bucket-name")`.
+ *
+ * @example
+ * ```ts
+ * // Top-level bucket management
+ * await linabase.storage.createBucket("avatars", { public: true });
+ * const { data: buckets } = await linabase.storage.listBuckets();
+ *
+ * // File operations on a bucket
+ * await linabase.storage.from("avatars").upload("alice.png", file);
+ * ```
+ */
 declare class StorageClient {
     private request;
     private baseUrl;
@@ -175,11 +278,50 @@ declare class StorageClient {
         error: any;
     }>;
 }
+/**
+ * Operations against a single storage bucket: upload, download, list,
+ * delete, signed URLs, public URLs, move, and copy.
+ *
+ * Created by `linabase.storage.from(bucketName)`. Most file paths inside
+ * a bucket are arbitrary keys; common conventions are
+ * `userId/filename.ext` or `category/asset.ext`.
+ *
+ * @example
+ * ```ts
+ * const bucket = linabase.storage.from("avatars");
+ *
+ * await bucket.upload(`${user.id}/avatar.png`, file, { upsert: true });
+ *
+ * // Public bucket: anyone can fetch the URL.
+ * const { data: { publicUrl } } = bucket.getPublicUrl(`${user.id}/avatar.png`);
+ *
+ * // Private bucket: time-limited URL.
+ * const { data } = await bucket.createSignedUrl(`${user.id}/report.pdf`, 3600);
+ * ```
+ */
 declare class BucketClient {
     private request;
     private bucket;
     private baseUrl;
     constructor(request: RequestFn$2, bucket: string, baseUrl?: string);
+    /**
+     * 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 });
+     * ```
+     */
     upload(path: string, file: Blob | File | ArrayBuffer, options?: {
         contentType?: string;
         upsert?: boolean;
@@ -188,6 +330,18 @@ declare class BucketClient {
         data: any;
         error: any;
     }>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
     download(path: string): Promise<{
         data: Blob | null;
         error: any;
@@ -200,6 +354,19 @@ declare class BucketClient {
         data: any;
         error: any;
     }>;
+    /**
+     * 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: string, options?: {
         transform?: {
             width?: number;
@@ -212,6 +379,18 @@ declare class BucketClient {
             publicUrl: string;
         };
     };
+    /**
+     * 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);
+     * ```
+     */
     createSignedUrl(path: string, expiresIn: number): Promise<{
         data: {
             signedUrl: string;
@@ -277,6 +456,30 @@ interface AuthUser {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Authentication API for a Linabase project.
+ *
+ * Exposed via `linabase.auth` on the client returned by `createClient`. Handles
+ * sign-up, sign-in (password / magic-link / OAuth), session management, and
+ * — when called with a service-role key — server-side admin operations under
+ * `auth.admin`.
+ *
+ * Sessions are persisted in the configured storage (defaults to localStorage
+ * in the browser, in-memory in Node). The current access token is automatically
+ * attached to every database, storage, and function request.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await linabase.auth.signInWithPassword({
+ *   email: "alice@example.com",
+ *   password: "correct horse battery staple",
+ * });
+ *
+ * linabase.auth.onAuthStateChange((event, session) => {
+ *   console.log(event, session?.user.email);
+ * });
+ * ```
+ */
 declare class AuthClient {
     private request;
     private listeners;
@@ -319,6 +522,22 @@ declare class AuthClient {
         data: AuthSession | null;
         error: any;
     }>;
+    /**
+     * 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" },
+     * });
+     * ```
+     */
     signUp(params: {
         email: string;
         password: string;
@@ -327,6 +546,21 @@ declare class AuthClient {
         data: AuthSession | null;
         error: any;
     }>;
+    /**
+     * 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);
+     * ```
+     */
     signIn(params: {
         email: string;
         password: string;
@@ -350,15 +584,96 @@ declare class AuthClient {
         data: AuthSession | null;
         error: any;
     }>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    signInWithDevice(params: {
+        deviceSecret: string;
+        create?: boolean;
+        data?: Record<string, unknown>;
+    }): Promise<{
+        data: AuthSession | null;
+        error: any;
+    }>;
+    /**
+     * 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.
+     */
+    signInWithGameCenter(params: {
+        playerId: string;
+        bundleId: string;
+        publicKeyURL: string;
+        signature: string;
+        salt: string;
+        timestamp: number;
+        displayName?: string;
+    }): Promise<{
+        data: AuthSession | null;
+        error: any;
+    }>;
+    /**
+     * 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.
+     */
+    signInWithPlayGames(params: {
+        serverAuthCode: string;
+        redirectUri?: string;
+    }): Promise<{
+        data: AuthSession | null;
+        error: any;
+    }>;
     signInWithOAuth(params: {
         provider: OAuthProvider;
         redirectTo?: string;
     }): {
         url: string;
     };
+    /**
+     * 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();
+     * ```
+     */
     signOut(): Promise<{
         error: any;
     }>;
+    /**
+     * 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);
+     * ```
+     */
     getSession(): Promise<{
         data: {
             session: AuthSession | null;
@@ -504,14 +819,44 @@ declare class AuthClient {
 }
 
 type RequestFn = (path: string, options?: RequestInit) => Promise<Response>;
+/** Options for {@link FunctionsClient.invoke}. */
 interface FunctionInvokeOptions {
+    /** JSON body for POST, or query parameters for GET. */
     body?: Record<string, any>;
+    /** HTTP method. Defaults to `POST`. */
     method?: "GET" | "POST";
+    /** Extra request headers (merged with auth headers). */
     headers?: Record<string, string>;
 }
+/**
+ * Invoke server-side functions registered with the project.
+ *
+ * Exposed via `linabase.functions`. The auth token, when set, is forwarded
+ * automatically so the function can identify the calling user.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await linabase.functions.invoke("send-welcome", {
+ *   body: { userId: user.id },
+ * });
+ * ```
+ */
 declare class FunctionsClient {
     private request;
     constructor(request: RequestFn);
+    /**
+     * 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");
+     * ```
+     */
     invoke<T = any>(name: string, options?: FunctionInvokeOptions): Promise<{
         data: T | null;
         error: any;
@@ -557,23 +902,64 @@ interface LinabaseConfig {
         detectSessionInUrl?: boolean;
     };
 }
+/**
+ * The Linabase client. Returned by {@link createClient}.
+ *
+ * Combines query, auth, storage, and function-invocation APIs behind a
+ * single object. Most apps create one client per project at startup and
+ * reuse it everywhere.
+ */
 interface LinabaseClient {
+    /** Start a query against a table in the project's `public` schema. */
     from: (table: string) => DatabaseClient;
+    /** Target a non-default schema (`auth`, `storage`, etc.) for the next query. */
     schema: (schemaName: string) => {
         from: (table: string) => DatabaseClient;
     };
+    /** Call a Postgres function (RPC). */
     rpc: (fn: string, args?: Record<string, any>) => ReturnType<RpcClient["call"]>;
+    /** S3-compatible object storage for the project. */
     storage: StorageClient;
+    /** User auth: sign in, sign up, sessions, OAuth, admin operations. */
     auth: AuthClient;
+    /** Invoke server-side functions. */
     functions: FunctionsClient;
     /** Realtime channel (stub; not yet supported). Returns a chainable no-op. */
     channel: (name: string) => any;
     /** Remove a realtime channel (stub; not yet supported). */
     removeChannel: (channel: any) => void;
+    /** Generate TypeScript types for the project's database schema. */
     generateTypes: () => Promise<string>;
     /** Returns a new client that targets the given branch via X-Branch header. */
     branch: (slug: string) => LinabaseClient;
 }
+/**
+ * Create a Linabase client for a project.
+ *
+ * The client is the single entry point to the SDK. Every query, auth call,
+ * and storage operation goes through it. The same instance can be reused
+ * across the app; it tracks the user's session internally.
+ *
+ * @param config - Connection details. `url` is the project's Linabase API
+ *   URL, and `anonKey` is the public API key (safe to ship in frontend
+ *   bundles). Use `serviceRoleKey` only on a trusted server.
+ * @returns A {@link LinabaseClient} instance.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@linabase/js";
+ *
+ * const linabase = createClient({
+ *   url: "https://linabase.com",
+ *   anonKey: "lb_anon_...",
+ * });
+ *
+ * const { data, error } = await linabase
+ *   .from("posts")
+ *   .select("*, author:profiles(name)")
+ *   .eq("published", true);
+ * ```
+ */
 declare function createClient(config: LinabaseConfig): LinabaseClient;
 
 export { AuthClient, type AuthSession, type AuthUser, BucketClient, type CsvQueryResult, DatabaseClient, type FunctionInvokeOptions, FunctionsClient, type LinabaseClient, type LinabaseConfig, type OAuthProvider, type PostgrestError, type QueryResult, RpcClient, type SessionStorage, type SingleQueryResult, StorageClient, createClient };