@kividb/client 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,9 @@
 # @kividb/client
 
 The JavaScript/TypeScript client SDK for kividb — a thin, typed wrapper over the
-`data-api`, `auth`, and `realtime` services. Works in browsers, React Native,
-and Node 22+ (uses global `fetch` and `WebSocket`, no runtime dependencies).
-
-> Status: initial scaffold. Covers the full data, auth, and realtime surface the
-> services expose today. Storage and edge-function helpers are not built yet.
+`data-api`, `auth`, `realtime`, and `storage` services. Works in browsers,
+React Native, and Node 22+ (uses global `fetch` and `WebSocket`, no runtime
+dependencies).
 
 ## Install
 
@@ -32,6 +30,7 @@ const kdb = createClient("http://localhost", ANON_KEY, {
   auth: "http://localhost:4000",
   rest: "http://localhost:4001",
   realtime: "ws://localhost:4002",
+  storage: "http://localhost:4004",
 });
 ```
 
@@ -134,3 +133,74 @@ channel.unsubscribe();
 One WebSocket is shared per project across all channels. It reconnects with
 backoff and re-subscribes automatically; `DELETE` postgres events are delivered
 only to `service_role` tokens (a documented v1 server limitation).
+
+## Migrations
+
+Create and evolve your schema from code instead of the dashboard. Requires the
+**service key** (server-side only — never ship it to a browser):
+
+```ts
+const kdb = createClient(KIVIDB_URL, process.env.KIVIDB_SERVICE_KEY!);
+
+await kdb.migrations.apply([
+  {
+    name: "0001_messages",
+    sql: `
+      create table messages (
+        id         uuid primary key default gen_random_uuid(),
+        room       text not null,
+        body       text not null,
+        created_at timestamptz not null default now()
+      );
+      alter table messages enable row level security;
+    `,
+  },
+]);
+
+const { data } = await kdb.migrations.list(); // the applied-migrations ledger
+```
+
+`apply` is idempotent: each migration is recorded by name in a per-project
+ledger, so re-running the same list skips what's already applied — keep one
+array in your repo, append to it, and run it on every deploy. Applied
+migrations are immutable (changing an applied name's SQL is a 409; add a new
+one instead). Each migration runs in its own transaction as the project owner
+role, with your project schema as the `search_path` — remember to enable RLS
+on new tables, and don't put `begin`/`commit` inside the SQL.
+
+## Storage
+
+Objects live in buckets. Object requests carry the signed-in user's token (or
+the anon key), so storage RLS applies exactly like data requests:
+
+```ts
+await kdb.storage.from("avatars").upload("user-42/photo.png", file);
+const { data: blob } = await kdb.storage.from("avatars").download("user-42/photo.png");
+const { data: objects } = await kdb.storage.from("avatars").list("user-42/");
+await kdb.storage.from("avatars").remove(["user-42/photo.png"]);
+
+const { data: signed } = await kdb.storage.from("private-docs").createSignedUrl("report.pdf", 3600);
+kdb.storage.from("avatars").getPublicUrl("user-42/photo.png");           // public buckets
+kdb.storage.from("avatars").getRenderUrl("user-42/photo.png", { width: 128, format: "webp" });
+```
+
+### Buckets
+
+Creating and deleting buckets requires the **service key** (server-side only);
+listing and reading bucket metadata work with any key:
+
+```ts
+const kdb = createClient(KIVIDB_URL, process.env.KIVIDB_SERVICE_KEY!);
+
+await kdb.storage.createBucket("avatars", { public: true });
+await kdb.storage.createBucket("attachments", {
+  allowedMimeTypes: ["image/png", "image/jpeg", "application/pdf"],
+  maxObjectSize: 10_000_000, // bytes
+});
+
+const { data: buckets } = await kdb.storage.listBuckets();
+const { data: bucket } = await kdb.storage.getBucket("attachments");
+await kdb.storage.deleteBucket("attachments"); // 409 unless the bucket is empty
+```
+
+Bucket names are 2–63 chars: lowercase letters, digits, `.`, `_` or `-`.

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   FilterBuilder: () => FilterBuilder,
   FromBuilder: () => FromBuilder,
   KividbClient: () => KividbClient,
+  MigrationsClient: () => MigrationsClient,
   RealtimeChannel: () => RealtimeChannel,
   RealtimeClient: () => RealtimeClient,
   StorageClient: () => StorageClient,
@@ -302,6 +303,34 @@ function base64UrlDecode(segment) {
   return new TextDecoder().decode(bytes);
 }
 
+// src/migrations.ts
+var MigrationsClient = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  get endpoint() {
+    return `${this.cfg.rest}/${this.cfg.project}/-/migrations`;
+  }
+  /**
+   * Apply migrations in order, skipping ones already applied. On a failure the
+   * error's `details` carry `failed` (the migration that broke) plus the
+   * `applied`/`skipped` progress before it; already-applied migrations stay
+   * applied and skip on the next run.
+   */
+  apply(migrations) {
+    return request(this.endpoint, {
+      method: "POST",
+      body: JSON.stringify({ migrations }),
+      token: this.cfg.key
+    });
+  }
+  /** The applied-migrations ledger, oldest first. */
+  list() {
+    return request(this.endpoint, { token: this.cfg.key });
+  }
+};
+
 // src/postgrest.ts
 var FromBuilder = class {
   constructor(ctx, table) {
@@ -732,6 +761,42 @@ var StorageClient = class {
   from(bucket) {
     return new BucketApi(this.ctx, bucket);
   }
+  token() {
+    return this.ctx.session.accessToken() ?? this.ctx.anonKey;
+  }
+  bucketsUrl(name) {
+    const base = `${this.ctx.storage}/${this.ctx.project}/buckets`;
+    return name ? `${base}/${encodeURIComponent(name)}` : base;
+  }
+  /** All buckets in the project (any key; bucket metadata is readable). */
+  listBuckets() {
+    return request(this.bucketsUrl(), { token: this.token() });
+  }
+  /** One bucket's metadata, or a 404 error if it doesn't exist. */
+  getBucket(name) {
+    return request(this.bucketsUrl(name), { token: this.token() });
+  }
+  /**
+   * Create a bucket. Requires the service_role key. Names are 2–63 chars of
+   * lowercase letters, digits, ".", "_" or "-".
+   */
+  createBucket(name, options = {}) {
+    return request(this.bucketsUrl(), {
+      method: "POST",
+      token: this.token(),
+      body: JSON.stringify({ name, ...options })
+    });
+  }
+  /**
+   * Delete an empty bucket (a non-empty bucket is a 409 — remove its objects
+   * first). Requires the service_role key.
+   */
+  deleteBucket(name) {
+    return request(this.bucketsUrl(name), {
+      method: "DELETE",
+      token: this.token()
+    });
+  }
 };
 
 // src/index.ts
@@ -770,6 +835,11 @@ var KividbClient = class {
       anonKey,
       session: this.session
     });
+    this.migrations = new MigrationsClient({
+      rest: this.endpoints.rest,
+      project: this.project,
+      key: anonKey
+    });
     this.session.hydrateSync();
     void this.session.hydrate();
   }
@@ -778,6 +848,8 @@ var KividbClient = class {
   auth;
   realtime;
   storage;
+  /** Schema migrations — requires the client to hold the service key. */
+  migrations;
   project;
   endpoints;
   session;
@@ -819,6 +891,7 @@ function createServerClient(url, anonKey, options) {
   FilterBuilder,
   FromBuilder,
   KividbClient,
+  MigrationsClient,
   RealtimeChannel,
   RealtimeClient,
   StorageClient,

package/dist/index.d.cts

@@ -203,6 +203,58 @@ interface CookieMethods {
 /** Cookie name carrying the JSON session for a given project. */
 declare function sessionCookieName(project: string): string;
 
+/**
+ * Schema migrations, applied through the data API's service_role-only
+ * `/:project/-/migrations` endpoint. Create the client with the project's
+ * **service key** (never ship that key to a browser):
+ *
+ *   const kdb = createClient(url, serviceKey);
+ *   await kdb.migrations.apply([
+ *     { name: "0001_messages", sql: `create table messages (…); alter table messages enable row level security;` },
+ *   ]);
+ *
+ * Applying is idempotent: each migration is recorded in a per-project ledger
+ * by name, so re-running the same list skips what's already applied. Applied
+ * migrations are immutable — changing the SQL of an applied name is a 409;
+ * add a new migration instead.
+ */
+/** A named schema migration. Names must be unique and are applied in order. */
+interface Migration {
+    name: string;
+    sql: string;
+}
+interface ApplyMigrationsResult {
+    /** Names applied by this call, in order. */
+    applied: string[];
+    /** Names already in the ledger (identical SQL), skipped. */
+    skipped: string[];
+}
+/** A ledger entry for an applied migration. */
+interface AppliedMigration {
+    name: string;
+    /** sha256 of the SQL as applied. */
+    checksum: string;
+    applied_at: string;
+}
+declare class MigrationsClient {
+    private readonly cfg;
+    constructor(cfg: {
+        rest: string;
+        project: string;
+        key: string;
+    });
+    private get endpoint();
+    /**
+     * Apply migrations in order, skipping ones already applied. On a failure the
+     * error's `details` carry `failed` (the migration that broke) plus the
+     * `applied`/`skipped` progress before it; already-applied migrations stay
+     * applied and skip on the next run.
+     */
+    apply(migrations: Migration[]): Promise<KividbResponse<ApplyMigrationsResult>>;
+    /** The applied-migrations ledger, oldest first. */
+    list(): Promise<KividbResponse<AppliedMigration[]>>;
+}
+
 interface Context {
     rest: string;
     project: string;
@@ -399,6 +451,24 @@ interface SignedUrl {
     exp: number;
     expiresAt: string;
 }
+/** A bucket as the storage service returns it. */
+interface BucketInfo {
+    id: string;
+    name: string;
+    public: boolean;
+    allowedMimeTypes: string[] | null;
+    maxObjectSize: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateBucketOptions {
+    /** Public buckets serve objects at a token-less URL. Default false. */
+    public?: boolean;
+    /** Restrict uploads to these mime types (e.g. ["image/*"]). Null = any. */
+    allowedMimeTypes?: string[] | null;
+    /** Per-object size cap in bytes. Null = the service default. */
+    maxObjectSize?: number | null;
+}
 interface Ctx {
     storage: string;
     project: string;
@@ -433,6 +503,22 @@ declare class StorageClient {
     constructor(ctx: Ctx);
     /** Operate on a bucket. */
     from(bucket: string): BucketApi;
+    private token;
+    private bucketsUrl;
+    /** All buckets in the project (any key; bucket metadata is readable). */
+    listBuckets(): Promise<KividbResponse<BucketInfo[]>>;
+    /** One bucket's metadata, or a 404 error if it doesn't exist. */
+    getBucket(name: string): Promise<KividbResponse<BucketInfo>>;
+    /**
+     * Create a bucket. Requires the service_role key. Names are 2–63 chars of
+     * lowercase letters, digits, ".", "_" or "-".
+     */
+    createBucket(name: string, options?: CreateBucketOptions): Promise<KividbResponse<BucketInfo>>;
+    /**
+     * Delete an empty bucket (a non-empty bucket is a 409 — remove its objects
+     * first). Requires the service_role key.
+     */
+    deleteBucket(name: string): Promise<KividbResponse<null>>;
 }
 
 /**
@@ -463,6 +549,8 @@ declare class KividbClient {
     readonly auth: AuthClient;
     readonly realtime: RealtimeClient;
     readonly storage: StorageClient;
+    /** Schema migrations — requires the client to hold the service key. */
+    readonly migrations: MigrationsClient;
     readonly project: string;
     private readonly endpoints;
     private readonly session;
@@ -490,4 +578,4 @@ declare function createServerClient(url: string, anonKey: string, options: Omit<
     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 };
+export { type AppliedMigration, type ApplyMigrationsResult, AuthClient, type AuthEvent, type AuthListener, type BucketInfo, type ClientOptions, type CookieMethods, type CookieOptions, type CreateBucketOptions, FilterBuilder, FromBuilder, KividbClient, type KividbError, type KividbResponse, type Migration, MigrationsClient, 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 };

package/dist/index.d.ts

@@ -203,6 +203,58 @@ interface CookieMethods {
 /** Cookie name carrying the JSON session for a given project. */
 declare function sessionCookieName(project: string): string;
 
+/**
+ * Schema migrations, applied through the data API's service_role-only
+ * `/:project/-/migrations` endpoint. Create the client with the project's
+ * **service key** (never ship that key to a browser):
+ *
+ *   const kdb = createClient(url, serviceKey);
+ *   await kdb.migrations.apply([
+ *     { name: "0001_messages", sql: `create table messages (…); alter table messages enable row level security;` },
+ *   ]);
+ *
+ * Applying is idempotent: each migration is recorded in a per-project ledger
+ * by name, so re-running the same list skips what's already applied. Applied
+ * migrations are immutable — changing the SQL of an applied name is a 409;
+ * add a new migration instead.
+ */
+/** A named schema migration. Names must be unique and are applied in order. */
+interface Migration {
+    name: string;
+    sql: string;
+}
+interface ApplyMigrationsResult {
+    /** Names applied by this call, in order. */
+    applied: string[];
+    /** Names already in the ledger (identical SQL), skipped. */
+    skipped: string[];
+}
+/** A ledger entry for an applied migration. */
+interface AppliedMigration {
+    name: string;
+    /** sha256 of the SQL as applied. */
+    checksum: string;
+    applied_at: string;
+}
+declare class MigrationsClient {
+    private readonly cfg;
+    constructor(cfg: {
+        rest: string;
+        project: string;
+        key: string;
+    });
+    private get endpoint();
+    /**
+     * Apply migrations in order, skipping ones already applied. On a failure the
+     * error's `details` carry `failed` (the migration that broke) plus the
+     * `applied`/`skipped` progress before it; already-applied migrations stay
+     * applied and skip on the next run.
+     */
+    apply(migrations: Migration[]): Promise<KividbResponse<ApplyMigrationsResult>>;
+    /** The applied-migrations ledger, oldest first. */
+    list(): Promise<KividbResponse<AppliedMigration[]>>;
+}
+
 interface Context {
     rest: string;
     project: string;
@@ -399,6 +451,24 @@ interface SignedUrl {
     exp: number;
     expiresAt: string;
 }
+/** A bucket as the storage service returns it. */
+interface BucketInfo {
+    id: string;
+    name: string;
+    public: boolean;
+    allowedMimeTypes: string[] | null;
+    maxObjectSize: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateBucketOptions {
+    /** Public buckets serve objects at a token-less URL. Default false. */
+    public?: boolean;
+    /** Restrict uploads to these mime types (e.g. ["image/*"]). Null = any. */
+    allowedMimeTypes?: string[] | null;
+    /** Per-object size cap in bytes. Null = the service default. */
+    maxObjectSize?: number | null;
+}
 interface Ctx {
     storage: string;
     project: string;
@@ -433,6 +503,22 @@ declare class StorageClient {
     constructor(ctx: Ctx);
     /** Operate on a bucket. */
     from(bucket: string): BucketApi;
+    private token;
+    private bucketsUrl;
+    /** All buckets in the project (any key; bucket metadata is readable). */
+    listBuckets(): Promise<KividbResponse<BucketInfo[]>>;
+    /** One bucket's metadata, or a 404 error if it doesn't exist. */
+    getBucket(name: string): Promise<KividbResponse<BucketInfo>>;
+    /**
+     * Create a bucket. Requires the service_role key. Names are 2–63 chars of
+     * lowercase letters, digits, ".", "_" or "-".
+     */
+    createBucket(name: string, options?: CreateBucketOptions): Promise<KividbResponse<BucketInfo>>;
+    /**
+     * Delete an empty bucket (a non-empty bucket is a 409 — remove its objects
+     * first). Requires the service_role key.
+     */
+    deleteBucket(name: string): Promise<KividbResponse<null>>;
 }
 
 /**
@@ -463,6 +549,8 @@ declare class KividbClient {
     readonly auth: AuthClient;
     readonly realtime: RealtimeClient;
     readonly storage: StorageClient;
+    /** Schema migrations — requires the client to hold the service key. */
+    readonly migrations: MigrationsClient;
     readonly project: string;
     private readonly endpoints;
     private readonly session;
@@ -490,4 +578,4 @@ declare function createServerClient(url: string, anonKey: string, options: Omit<
     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 };
+export { type AppliedMigration, type ApplyMigrationsResult, AuthClient, type AuthEvent, type AuthListener, type BucketInfo, type ClientOptions, type CookieMethods, type CookieOptions, type CreateBucketOptions, FilterBuilder, FromBuilder, KividbClient, type KividbError, type KividbResponse, type Migration, MigrationsClient, 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 };

package/dist/index.js

@@ -265,6 +265,34 @@ function base64UrlDecode(segment) {
   return new TextDecoder().decode(bytes);
 }
 
+// src/migrations.ts
+var MigrationsClient = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  get endpoint() {
+    return `${this.cfg.rest}/${this.cfg.project}/-/migrations`;
+  }
+  /**
+   * Apply migrations in order, skipping ones already applied. On a failure the
+   * error's `details` carry `failed` (the migration that broke) plus the
+   * `applied`/`skipped` progress before it; already-applied migrations stay
+   * applied and skip on the next run.
+   */
+  apply(migrations) {
+    return request(this.endpoint, {
+      method: "POST",
+      body: JSON.stringify({ migrations }),
+      token: this.cfg.key
+    });
+  }
+  /** The applied-migrations ledger, oldest first. */
+  list() {
+    return request(this.endpoint, { token: this.cfg.key });
+  }
+};
+
 // src/postgrest.ts
 var FromBuilder = class {
   constructor(ctx, table) {
@@ -695,6 +723,42 @@ var StorageClient = class {
   from(bucket) {
     return new BucketApi(this.ctx, bucket);
   }
+  token() {
+    return this.ctx.session.accessToken() ?? this.ctx.anonKey;
+  }
+  bucketsUrl(name) {
+    const base = `${this.ctx.storage}/${this.ctx.project}/buckets`;
+    return name ? `${base}/${encodeURIComponent(name)}` : base;
+  }
+  /** All buckets in the project (any key; bucket metadata is readable). */
+  listBuckets() {
+    return request(this.bucketsUrl(), { token: this.token() });
+  }
+  /** One bucket's metadata, or a 404 error if it doesn't exist. */
+  getBucket(name) {
+    return request(this.bucketsUrl(name), { token: this.token() });
+  }
+  /**
+   * Create a bucket. Requires the service_role key. Names are 2–63 chars of
+   * lowercase letters, digits, ".", "_" or "-".
+   */
+  createBucket(name, options = {}) {
+    return request(this.bucketsUrl(), {
+      method: "POST",
+      token: this.token(),
+      body: JSON.stringify({ name, ...options })
+    });
+  }
+  /**
+   * Delete an empty bucket (a non-empty bucket is a 409 — remove its objects
+   * first). Requires the service_role key.
+   */
+  deleteBucket(name) {
+    return request(this.bucketsUrl(name), {
+      method: "DELETE",
+      token: this.token()
+    });
+  }
 };
 
 // src/index.ts
@@ -733,6 +797,11 @@ var KividbClient = class {
       anonKey,
       session: this.session
     });
+    this.migrations = new MigrationsClient({
+      rest: this.endpoints.rest,
+      project: this.project,
+      key: anonKey
+    });
     this.session.hydrateSync();
     void this.session.hydrate();
   }
@@ -741,6 +810,8 @@ var KividbClient = class {
   auth;
   realtime;
   storage;
+  /** Schema migrations — requires the client to hold the service key. */
+  migrations;
   project;
   endpoints;
   session;
@@ -781,6 +852,7 @@ export {
   FilterBuilder,
   FromBuilder,
   KividbClient,
+  MigrationsClient,
   RealtimeChannel,
   RealtimeClient,
   StorageClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kividb/client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "JavaScript/TypeScript client SDK for kividb — typed database queries, auth, realtime, and storage",
   "license": "MIT",
   "repository": {