@kividb/client 0.1.0 → 0.1.1

package/README.md

@@ -134,3 +134,37 @@ 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.

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) {
@@ -770,6 +799,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 +812,8 @@ var KividbClient = class {
   auth;
   realtime;
   storage;
+  /** Schema migrations — requires the client to hold the service key. */
+  migrations;
   project;
   endpoints;
   session;
@@ -819,6 +855,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;
@@ -463,6 +515,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 +544,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 ClientOptions, type CookieMethods, type CookieOptions, 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;
@@ -463,6 +515,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 +544,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 ClientOptions, type CookieMethods, type CookieOptions, 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) {
@@ -733,6 +761,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 +774,8 @@ var KividbClient = class {
   auth;
   realtime;
   storage;
+  /** Schema migrations — requires the client to hold the service key. */
+  migrations;
   project;
   endpoints;
   session;
@@ -781,6 +816,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.1",
   "description": "JavaScript/TypeScript client SDK for kividb — typed database queries, auth, realtime, and storage",
   "license": "MIT",
   "repository": {