@kividb/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,493 @@
+/**
+ * Wire shapes shared across the client. These mirror what the kividb services
+ * actually return — see apps/auth, apps/data-api, apps/realtime. Keep them in
+ * sync with the server protocol, not with what we wish it were.
+ */
+/** A signed-in session as returned by the auth service token endpoints. */
+interface Session {
+    access_token: string;
+    token_type: "bearer";
+    /** Lifetime of the access token in seconds (currently 3600). */
+    expires_in: number;
+    /** Opaque, rotates on every refresh. No expiry until revoked. */
+    refresh_token: string;
+    user: User;
+}
+/** The public projection of a user the auth service is willing to expose. */
+interface User {
+    id: string;
+    email: string | null;
+    email_confirmed_at: string | null;
+    last_sign_in_at: string | null;
+    user_metadata: Record<string, unknown>;
+    created_at: string;
+}
+type OAuthProvider = "github" | "google";
+type Row = Record<string, unknown>;
+/**
+ * Every public method resolves to this instead of throwing, so callers can
+ * destructure `{ data, error }` the way they would with supabase-js. Network
+ * faults and non-2xx responses both land in `error`.
+ */
+interface KividbResponse<T> {
+    data: T | null;
+    error: KividbError | null;
+}
+/** Normalized error. `status` is 0 for transport failures (never reached the service). */
+interface KividbError {
+    message: string;
+    status: number;
+    /** Extra fields the service attached, e.g. the OAuth `reason` code. */
+    details?: Record<string, unknown>;
+}
+/** Persistence hook so a session survives reloads. Defaults to in-memory only. */
+interface SessionStore {
+    get(): Session | null | Promise<Session | null>;
+    set(session: Session | null): void | Promise<void>;
+}
+interface ClientOptions {
+    /**
+     * Override the project slug. By default it is read from the anon key's `ref`
+     * claim, which is correct for normal keys — only set this for unusual setups.
+     */
+    project?: string;
+    /**
+     * Per-service base URL overrides. Normally you don't set these: the three
+     * are derived from the single `url` passed to createClient (gateway model,
+     * `{url}/auth`, `{url}/rest`, `{url}/realtime`). Override one when hitting a
+     * service directly — e.g. local dev with no gateway: `rest: "http://localhost:4001"`.
+     */
+    rest?: string;
+    auth?: string;
+    realtime?: string;
+    storage?: string;
+    /** Where to persist the session. In-memory if omitted. */
+    store?: SessionStore;
+    /** Automatically refresh the access token shortly before it expires. Default true. */
+    autoRefresh?: boolean;
+}
+
+type AuthEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+type AuthListener = (event: AuthEvent, session: Session | null) => void;
+/**
+ * Single source of truth for "who is signed in right now". The auth client
+ * writes to it; the REST and realtime clients read from it to pick the bearer
+ * token. Keeping it separate avoids a circular dependency between those three.
+ */
+declare class SessionManager {
+    private readonly store?;
+    private current;
+    private readonly listeners;
+    constructor(store?: SessionStore | undefined);
+    /** Load any persisted session on startup. Safe to call more than once. */
+    hydrate(): Promise<Session | null>;
+    /**
+     * Synchronous hydrate for stores that read synchronously (cookies,
+     * localStorage). SSR needs the session in memory before the first request in
+     * the same tick — an awaited hydrate would be too late. No-ops for async stores.
+     */
+    hydrateSync(): void;
+    get(): Session | null;
+    /** The token data requests should send: the user's, or null to fall back to the anon key. */
+    accessToken(): string | null;
+    set(session: Session | null, event: AuthEvent): Promise<void>;
+    onChange(listener: AuthListener): () => void;
+}
+
+/**
+ * Wraps the auth service (apps/auth). Every route is scoped by project slug:
+ * `{auth}/{project}/...`. Methods that mint a session also store it via the
+ * SessionManager, so a successful sign-in immediately upgrades subsequent data
+ * requests from the anon key to the user's token.
+ */
+declare class AuthClient {
+    private readonly base;
+    private readonly project;
+    private readonly session;
+    private readonly autoRefresh;
+    constructor(base: string, project: string, session: SessionManager, autoRefresh?: boolean);
+    private url;
+    /** Register an email/password user. Returns a session only if autoconfirm is on server-side. */
+    signUp(params: {
+        email: string;
+        password: string;
+        data?: Record<string, unknown>;
+    }): Promise<KividbResponse<Session | {
+        user: User;
+        confirmation_sent: true;
+    }>>;
+    signInWithPassword(params: {
+        email: string;
+        password: string;
+    }): Promise<KividbResponse<Session>>;
+    /** Passwordless — triggers a magic-link email. The link resolves via `verifyOtp`. */
+    signInWithOtp(params: {
+        email: string;
+    }): Promise<KividbResponse<{
+        message: string;
+    }>>;
+    /**
+     * Build the URL the browser should navigate to in order to start an OAuth
+     * flow. We return the URL rather than redirecting so the caller controls
+     * navigation (and so this works outside a browser). `redirectTo` is where the
+     * provider bounces back with a one-time `?code=` to feed to `exchangeCodeForSession`.
+     */
+    getOAuthUrl(params: {
+        provider: OAuthProvider;
+        redirectTo: string;
+        /** Pass a signed-in user's access token to LINK this provider instead of logging in. */
+        linkToken?: string;
+    }): string;
+    /** Trade the one-time `?code=` from an OAuth redirect for a real session. */
+    exchangeCodeForSession(code: string): Promise<KividbResponse<Session>>;
+    /** Rotate the refresh token for a fresh access token. Defaults to the stored session's. */
+    refreshSession(refreshToken?: string): Promise<KividbResponse<Session>>;
+    signOut(): Promise<KividbResponse<null>>;
+    /** The currently stored session (in-memory / from the store). No network call. */
+    getSession(): Session | null;
+    /**
+     * Fetch the live user record for the signed-in session. This is also the
+     * canonical server-side "is this token still valid?" check (there is no local
+     * JWKS verification yet — see README). On a 401 it transparently rotates the
+     * refresh token once and retries, which is what middleware leans on to keep a
+     * session alive across requests.
+     */
+    getUser(): Promise<KividbResponse<User>>;
+    updateUser(params: {
+        password?: string;
+        data?: Record<string, unknown>;
+    }): Promise<KividbResponse<User>>;
+    resetPasswordForEmail(email: string): Promise<KividbResponse<{
+        message: string;
+    }>>;
+    /** Consume an emailed one-time token (confirmation / recovery / magiclink) for a session. */
+    verifyOtp(params: {
+        type: "confirmation" | "recovery" | "magiclink";
+        token: string;
+    }): Promise<KividbResponse<Session>>;
+    /** Subscribe to sign-in / sign-out / refresh transitions. Returns an unsubscribe fn. */
+    onAuthStateChange(listener: AuthListener): () => void;
+    private token;
+}
+
+/**
+ * Cookie plumbing for SSR. The auth service returns tokens in the response
+ * body (it never sets cookies itself), so the SDK is responsible for putting
+ * the session somewhere both the server and the browser can read it. A cookie
+ * is that shared place: the browser client writes it, the server client reads
+ * it on the next request.
+ *
+ * The adapter shape mirrors @supabase/ssr so the same Next.js wiring (middleware
+ * request/response cookies, next/headers in RSC, route handlers) drops in.
+ */
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+}
+interface CookieMethods {
+    getAll(): {
+        name: string;
+        value: string;
+    }[];
+    setAll(cookies: {
+        name: string;
+        value: string;
+        options?: CookieOptions;
+    }[]): void;
+}
+/** Cookie name carrying the JSON session for a given project. */
+declare function sessionCookieName(project: string): string;
+
+interface Context {
+    rest: string;
+    project: string;
+    anonKey: string;
+    session: SessionManager;
+}
+/** Entry point returned by `client.from(table)`. Picks the HTTP verb. */
+declare class FromBuilder {
+    private readonly ctx;
+    private readonly table;
+    constructor(ctx: Context, table: string);
+    select(columns?: string): FilterBuilder;
+    insert(values: Row | Row[]): FilterBuilder;
+    update(values: Row): FilterBuilder;
+    delete(): FilterBuilder;
+}
+/**
+ * Chainable filters that resolve to `{ data, error }` when awaited (it's a
+ * thenable, like supabase-js). The data-api always RETURNs the affected rows,
+ * so insert/update/delete come back with their rows too — no extra `.select()`
+ * needed. Filters apply to GET/PATCH/DELETE; they are ignored by the server on
+ * POST.
+ */
+declare class FilterBuilder implements PromiseLike<KividbResponse<Row[]>> {
+    private readonly ctx;
+    private readonly table;
+    private readonly method;
+    private readonly reserved;
+    private readonly body?;
+    private readonly filters;
+    private readonly orders;
+    private limitValue?;
+    private offsetValue?;
+    constructor(ctx: Context, table: string, method: string, reserved: Record<string, string>, body?: (Row | Row[]) | undefined);
+    eq(column: string, value: unknown): this;
+    neq(column: string, value: unknown): this;
+    gt(column: string, value: unknown): this;
+    gte(column: string, value: unknown): this;
+    lt(column: string, value: unknown): this;
+    lte(column: string, value: unknown): this;
+    like(column: string, pattern: string): this;
+    ilike(column: string, pattern: string): this;
+    /** Only `null`, `true`, `false` are accepted by the server for `is`. */
+    is(column: string, value: null | boolean): this;
+    order(column: string, opts?: {
+        ascending?: boolean;
+    }): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    /** Inclusive range helper, like supabase-js. `range(0, 9)` → first 10 rows. */
+    range(from: number, to: number): this;
+    private filter;
+    private buildUrl;
+    private execute;
+    then<TResult1 = KividbResponse<Row[]>, TResult2 = never>(onfulfilled?: ((value: KividbResponse<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+
+/**
+ * Realtime client for apps/realtime. One WebSocket per project carries many
+ * topics (channels) multiplexed over it — matching the server, which keys all
+ * routing off the per-message `topic`. Auth rides on the connection URL as
+ * `?token=`, so a channel cannot outlive a token change without reconnecting.
+ */
+interface PostgresChange {
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    schema: string;
+    table: string;
+    new?: Record<string, unknown>;
+    old?: Record<string, unknown>;
+}
+type PostgresEvent = "INSERT" | "UPDATE" | "DELETE" | "*";
+type BroadcastHandler = (msg: {
+    event: string;
+    payload: unknown;
+}) => void;
+type PresenceHandler = (state: Record<string, unknown>) => void;
+type PostgresHandler = (change: PostgresChange) => void;
+interface BroadcastBinding {
+    kind: "broadcast";
+    event: string;
+    cb: BroadcastHandler;
+}
+interface PresenceBinding {
+    kind: "presence";
+    cb: PresenceHandler;
+}
+interface PostgresBinding {
+    kind: "postgres_changes";
+    table: string;
+    event: PostgresEvent;
+    cb: PostgresHandler;
+}
+type Binding = BroadcastBinding | PresenceBinding | PostgresBinding;
+declare class RealtimeChannel {
+    readonly topic: string;
+    private readonly client;
+    /** @internal */ readonly bindings: Binding[];
+    private subscribed;
+    constructor(topic: string, client: RealtimeClient);
+    /** Listen for a custom broadcast event. Pass `event: "*"` for every event. */
+    on(type: "broadcast", filter: {
+        event: string;
+    }, cb: BroadcastHandler): this;
+    /** Listen for presence sync (the full tracked-state map). */
+    on(type: "presence", filter: {
+        event: "sync";
+    }, cb: PresenceHandler): this;
+    /** Listen for row changes on a table. RLS is enforced server-side per row. */
+    on(type: "postgres_changes", filter: {
+        table: string;
+        event?: PostgresEvent;
+    }, cb: PostgresHandler): this;
+    /** Open the connection (if needed) and register this channel's topic. */
+    subscribe(): this;
+    /** Send a broadcast to every other subscriber on this topic (no self-echo). */
+    send(message: {
+        event: string;
+        payload: unknown;
+    }): void;
+    /** Advertise presence state for this client on the topic. */
+    track(payload?: Record<string, unknown>): void;
+    untrack(): void;
+    unsubscribe(): void;
+    /** @internal The subscribe frame the server expects for this channel. */
+    _subscribeFrame(): {
+        type: "subscribe";
+        topic: string;
+        presence: boolean;
+        postgres_changes: {
+            table: string;
+            event: PostgresEvent;
+        }[];
+    };
+    /** @internal */ get isSubscribed(): boolean;
+}
+declare class RealtimeClient {
+    private readonly base;
+    private readonly project;
+    private readonly anonKey;
+    private readonly session;
+    private socket;
+    private readonly channels;
+    private readonly outbox;
+    private reconnectAttempts;
+    private closedByUser;
+    constructor(base: string, project: string, anonKey: string, session: SessionManager);
+    channel(topic: string): RealtimeChannel;
+    /** Tear everything down. Call on app unmount / sign-out. */
+    disconnect(): void;
+    /** @internal */
+    _attach(channel: RealtimeChannel): void;
+    /** @internal */
+    _detach(channel: RealtimeChannel): void;
+    /** @internal Queues until the socket is open, then flushes in order. */
+    _send(frame: unknown): void;
+    private connect;
+    private scheduleReconnect;
+    private dispatch;
+}
+
+/**
+ * Object storage client — `kdb.storage.from(bucket)`. Mirrors supabase-js's
+ * storage surface. Requests carry the signed-in user's token when there is one,
+ * falling back to the anon key, so bucket RLS applies exactly as it does to data
+ * requests. Public and render URLs are built locally (no round-trip) for use in
+ * `<img>`/`<a>` tags.
+ */
+interface StorageObjectInfo {
+    id: string;
+    name: string;
+    size: number | null;
+    mimeType: string | null;
+    checksum: string | null;
+    metadata: Record<string, unknown>;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
+interface UploadOptions {
+    /** Overrides the content type (defaults to a Blob's own type, else octet-stream). */
+    contentType?: string;
+}
+interface TransformOptions {
+    width?: number;
+    height?: number;
+    resize?: "cover" | "contain" | "fill" | "inside" | "outside";
+    format?: "webp" | "jpeg" | "png" | "avif";
+    quality?: number;
+}
+interface SignedUrl {
+    url: string;
+    token: string;
+    exp: number;
+    expiresAt: string;
+}
+interface Ctx {
+    storage: string;
+    project: string;
+    anonKey: string;
+    session: SessionManager;
+}
+declare class BucketApi {
+    private readonly ctx;
+    private readonly bucket;
+    constructor(ctx: Ctx, bucket: string);
+    private token;
+    private objectUrl;
+    /** Upload (or overwrite) an object. */
+    upload(path: string, body: UploadBody, options?: UploadOptions): Promise<KividbResponse<StorageObjectInfo>>;
+    /** Download an object's bytes. */
+    download(path: string): Promise<KividbResponse<Blob>>;
+    /** Delete one or more objects. */
+    remove(paths: string[]): Promise<KividbResponse<{
+        removed: number;
+    }>>;
+    /** List objects in the bucket, optionally under a path prefix. */
+    list(prefix?: string): Promise<KividbResponse<StorageObjectInfo[]>>;
+    /** Mint a time-boxed signed URL for a private object (default 1 hour). */
+    createSignedUrl(path: string, expiresIn?: number): Promise<KividbResponse<SignedUrl>>;
+    /** The token-less public URL for an object in a public bucket. */
+    getPublicUrl(path: string): string;
+    /** A transform (render) URL — resize/reformat an image on the fly. */
+    getRenderUrl(path: string, transform?: TransformOptions): string;
+}
+declare class StorageClient {
+    private readonly ctx;
+    constructor(ctx: Ctx);
+    /** Operate on a bucket. */
+    from(bucket: string): BucketApi;
+}
+
+/**
+ * Read the project slug out of an anon key. The key is a kividb JWT whose `ref`
+ * claim is the project it's scoped to, so the SDK can recover the slug without a
+ * separate config value. This is an UNVERIFIED decode — we only read a public
+ * claim to know which project paths to build; the server still verifies the
+ * signature on every request.
+ */
+declare function projectFromAnonKey(anonKey: string): string;
+
+/**
+ * The kividb client. One per (url, anon key) pair.
+ *
+ *   const kdb = createClient("https://database.akivi.se", anonKey);
+ *   const { data } = await kdb.from("posts").select("*").eq("published", true);
+ *   await kdb.auth.signInWithPassword({ email, password });
+ *   kdb.channel("room:1").on("broadcast", { event: "msg" }, console.log).subscribe();
+ *
+ * `url` is the gateway origin fronting all services. The project slug is read
+ * from the anon key's `ref` claim (override with `options.project`). `anonKey`
+ * is the project's long-lived anon JWT — data requests use it until a user signs
+ * in, after which they automatically switch to that user's access token.
+ */
+declare class KividbClient {
+    readonly url: string;
+    private readonly anonKey;
+    readonly auth: AuthClient;
+    readonly realtime: RealtimeClient;
+    readonly storage: StorageClient;
+    readonly project: string;
+    private readonly endpoints;
+    private readonly session;
+    constructor(url: string, anonKey: string, options?: ClientOptions);
+    /** Start a query against a table. */
+    from(table: string): FromBuilder;
+    /** Open (or reuse) a realtime channel for a topic. */
+    channel(topic: string): RealtimeChannel;
+}
+declare function createClient(url: string, anonKey: string, options?: ClientOptions): KividbClient;
+/**
+ * Browser client for SSR setups: persists the session to `document.cookie` so
+ * the server can read it on the next request. Use this in client components.
+ */
+declare function createBrowserClient(url: string, anonKey: string, options?: Omit<ClientOptions, "store">): KividbClient;
+/**
+ * Server client for SSR setups: reads (and writes) the session through a cookie
+ * adapter you supply — Next.js `cookies()` in RSC, or the request/response
+ * cookies in middleware and route handlers. Mirrors @supabase/ssr's wiring.
+ *
+ * There is no local token verification yet, so `auth.getUser()` is a network
+ * call to the auth service — that is the canonical server-side auth check.
+ */
+declare function createServerClient(url: string, anonKey: string, options: Omit<ClientOptions, "store"> & {
+    cookies: CookieMethods;
+}): KividbClient;
+
+export { AuthClient, type AuthEvent, type AuthListener, type ClientOptions, type CookieMethods, type CookieOptions, FilterBuilder, FromBuilder, KividbClient, type KividbError, type KividbResponse, type OAuthProvider, type PostgresChange, RealtimeChannel, RealtimeClient, type Row, type Session, type SessionStore, type SignedUrl, StorageClient, type StorageObjectInfo, type TransformOptions, type UploadBody, type UploadOptions, type User, createBrowserClient, createClient, createServerClient, projectFromAnonKey, sessionCookieName };