@kividb/client 0.1.1 → 0.1.4

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",
 });
 ```
 
@@ -168,3 +167,44 @@ 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);
+// signed *render* URL — a private-bucket thumbnail usable in an <img> tag:
+const { data: thumb } = await kdb.storage
+  .from("private-docs")
+  .createSignedUrl("photo.png", 3600, { transform: { width: 128, format: "webp" } });
+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

@@ -725,9 +725,14 @@ var BucketApi = class {
       { token: this.token() }
     );
   }
-  /** Mint a time-boxed signed URL for a private object (default 1 hour). */
-  createSignedUrl(path, expiresIn = 3600) {
-    return request(
+  /**
+   * Mint a time-boxed signed URL for a private object (default 1 hour). Pass
+   * `transform` to get a signed RENDER URL instead — a private-bucket
+   * thumbnail that works in an `<img>` tag. The signature covers the object
+   * (not the transform), so one token serves any rendition of it.
+   */
+  async createSignedUrl(path, expiresIn = 3600, options = {}) {
+    const res = await request(
       `${this.ctx.storage}/${this.ctx.project}/sign/${encodeURIComponent(this.bucket)}/${encodePath(path)}`,
       {
         method: "POST",
@@ -735,6 +740,11 @@ var BucketApi = class {
         body: JSON.stringify({ expiresIn })
       }
     );
+    if (!res.data || !options.transform) return res;
+    const rendered = new URL(this.getRenderUrl(path, options.transform));
+    rendered.searchParams.set("exp", String(res.data.exp));
+    rendered.searchParams.set("token", res.data.token);
+    return { data: { ...res.data, url: rendered.toString() }, error: null };
   }
   /** The token-less public URL for an object in a public bucket. */
   getPublicUrl(path) {
@@ -761,6 +771,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

package/dist/index.d.cts

@@ -451,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;
@@ -473,8 +491,15 @@ declare class BucketApi {
     }>>;
     /** 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>>;
+    /**
+     * Mint a time-boxed signed URL for a private object (default 1 hour). Pass
+     * `transform` to get a signed RENDER URL instead — a private-bucket
+     * thumbnail that works in an `<img>` tag. The signature covers the object
+     * (not the transform), so one token serves any rendition of it.
+     */
+    createSignedUrl(path: string, expiresIn?: number, options?: {
+        transform?: TransformOptions;
+    }): 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. */
@@ -485,6 +510,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>>;
 }
 
 /**
@@ -544,4 +585,4 @@ declare function createServerClient(url: string, anonKey: string, options: Omit<
     cookies: CookieMethods;
 }): KividbClient;
 
-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 };
+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

@@ -451,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;
@@ -473,8 +491,15 @@ declare class BucketApi {
     }>>;
     /** 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>>;
+    /**
+     * Mint a time-boxed signed URL for a private object (default 1 hour). Pass
+     * `transform` to get a signed RENDER URL instead — a private-bucket
+     * thumbnail that works in an `<img>` tag. The signature covers the object
+     * (not the transform), so one token serves any rendition of it.
+     */
+    createSignedUrl(path: string, expiresIn?: number, options?: {
+        transform?: TransformOptions;
+    }): 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. */
@@ -485,6 +510,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>>;
 }
 
 /**
@@ -544,4 +585,4 @@ declare function createServerClient(url: string, anonKey: string, options: Omit<
     cookies: CookieMethods;
 }): KividbClient;
 
-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 };
+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

@@ -687,9 +687,14 @@ var BucketApi = class {
       { token: this.token() }
     );
   }
-  /** Mint a time-boxed signed URL for a private object (default 1 hour). */
-  createSignedUrl(path, expiresIn = 3600) {
-    return request(
+  /**
+   * Mint a time-boxed signed URL for a private object (default 1 hour). Pass
+   * `transform` to get a signed RENDER URL instead — a private-bucket
+   * thumbnail that works in an `<img>` tag. The signature covers the object
+   * (not the transform), so one token serves any rendition of it.
+   */
+  async createSignedUrl(path, expiresIn = 3600, options = {}) {
+    const res = await request(
       `${this.ctx.storage}/${this.ctx.project}/sign/${encodeURIComponent(this.bucket)}/${encodePath(path)}`,
       {
         method: "POST",
@@ -697,6 +702,11 @@ var BucketApi = class {
         body: JSON.stringify({ expiresIn })
       }
     );
+    if (!res.data || !options.transform) return res;
+    const rendered = new URL(this.getRenderUrl(path, options.transform));
+    rendered.searchParams.set("exp", String(res.data.exp));
+    rendered.searchParams.set("token", res.data.token);
+    return { data: { ...res.data, url: rendered.toString() }, error: null };
   }
   /** The token-less public URL for an object in a public bucket. */
   getPublicUrl(path) {
@@ -723,6 +733,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

package/package.json

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