kvdb-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 n0bisuke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,147 @@
+# kvdb-client
+
+KVdb.io 用のシンプルな Node.js クライアントです。サードパーティーによる非公式 SDK です。
+
+## インストール
+
+```bash
+npm install kvdb-client
+```
+
+## クイックスタート
+
+```js
+import { KVdbClient } from "kvdb-client";
+
+const kv = new KVdbClient({ bucket: "YOUR_BUCKET" });
+
+await kv.set("myName", "n0bisuke");
+const name = await kv.get("myName");
+console.log(name);
+```
+
+## 認証
+
+```js
+// Basic 認証（デフォルト）
+const basic = new KVdbClient({ bucket: "YOUR_BUCKET", token: "supersecret" });
+
+// Bearer トークン
+const bearer = new KVdbClient({
+  bucket: "YOUR_BUCKET",
+  token: "ACCESS_TOKEN",
+  authType: "bearer"
+});
+
+// クエリ文字列でトークン指定
+const query = new KVdbClient({
+  bucket: "YOUR_BUCKET",
+  token: "ACCESS_TOKEN",
+  authType: "query"
+});
+```
+
+## サンプル
+
+実行可能なスクリプトは GitHub の `examples/` フォルダを参照してください。
+
+## 使い方
+
+### バケット作成
+
+```js
+const bucket = await KVdbClient.createBucket("you@example.com");
+```
+
+### 値の保存・取得
+
+```js
+await kv.set("myName", "n0bisuke");
+const name = await kv.get("myName");
+```
+
+### JSON の保存・取得
+
+```js
+await kv.set("myData", { name: "test", value: 123 }, { json: true });
+const data = await kv.get("myData", { parseJson: true });
+```
+
+### キー一覧
+
+```js
+const keys = await kv.list();
+const items = await kv.list({ values: true, format: "json" });
+```
+
+### 更新（PATCH）
+
+```js
+await kv.update("myName", "Sugawara");
+```
+
+### カウンター操作
+
+```js
+await kv.increment("visits");
+await kv.decrement("visits", 2);
+```
+
+### トランザクション
+
+```js
+await kv.transaction([
+  { set: "users:email:new@example.com", value: "user 1" },
+  { delete: "users:email:old@example.com" }
+]);
+```
+
+### アクセストークン作成
+
+```js
+const token = await kv.createAccessToken({
+  prefix: "user:123:",
+  permissions: "read,write",
+  ttl: 3600
+});
+```
+
+### キー削除
+
+```js
+await kv.delete("myName");
+```
+
+### バケット削除
+
+```js
+await kv.deleteBucket();
+```
+
+## API
+
+- `new KVdbClient({ bucket, token?, authType?, baseUrl? })`
+- `KVdbClient.createBucket(email, { baseUrl?, secretKey?, writeKey?, readKey?, signingKey?, defaultTtl? })`
+- `get(key, { parseJson? })`
+- `set(key, value, { json?, contentType?, ttl? })`
+- `update(key, value, { json?, contentType?, ttl? })`
+- `increment(key, amount?, { ttl? })`
+- `decrement(key, amount?, { ttl? })`
+- `delete(key)`
+- `list({ values?, format?, limit?, skip?, prefix?, reverse? })`
+- `transaction(operations)`
+- `createAccessToken({ prefix?, permissions?, ttl? })`
+- `updateBucketPolicy({ secretKey?, writeKey?, readKey?, signingKey?, defaultTtl? })`
+- `deleteBucket()`
+
+## 注意
+
+- KVdb は公開される可能性があるため、重要な情報は保存しないでください。
+- `token` は `curl -u 'token:'` と同じ形式で送信されます。
+- KVdb に保存した情報がどのように扱われるかについて、SDK 開発者（n0bisuke）は一切把握していません。利用は自己責任とし、トラブル等について開発者は責任を負いません。
+
+## Language
+
+- English: `README.md`
+- Japanese (this file)
+- English (GitHub): `https://github.com/n0bisuke/kvdb-client/blob/main/README.md`

package/README.md

@@ -0,0 +1,147 @@
+# kvdb-client
+
+A simple Node.js client for KVdb.io. This is a third-party, unofficial SDK.
+
+## Install
+
+```bash
+npm install kvdb-client
+```
+
+## Quick Start
+
+```js
+import { KVdbClient } from "kvdb-client";
+
+const kv = new KVdbClient({ bucket: "YOUR_BUCKET" });
+
+await kv.set("myName", "n0bisuke");
+const name = await kv.get("myName");
+console.log(name);
+```
+
+## Authentication
+
+```js
+// Basic auth (default)
+const basic = new KVdbClient({ bucket: "YOUR_BUCKET", token: "supersecret" });
+
+// Bearer token
+const bearer = new KVdbClient({
+  bucket: "YOUR_BUCKET",
+  token: "ACCESS_TOKEN",
+  authType: "bearer"
+});
+
+// Query string token
+const query = new KVdbClient({
+  bucket: "YOUR_BUCKET",
+  token: "ACCESS_TOKEN",
+  authType: "query"
+});
+```
+
+## Examples
+
+See the `examples/` folder on GitHub for runnable scripts.
+
+## Usage
+
+### Create a bucket
+
+```js
+const bucket = await KVdbClient.createBucket("you@example.com");
+```
+
+### Set / Get values
+
+```js
+await kv.set("myName", "n0bisuke");
+const name = await kv.get("myName");
+```
+
+### JSON values
+
+```js
+await kv.set("myData", { name: "test", value: 123 }, { json: true });
+const data = await kv.get("myData", { parseJson: true });
+```
+
+### List keys
+
+```js
+const keys = await kv.list();
+const items = await kv.list({ values: true, format: "json" });
+```
+
+### Update (PATCH)
+
+```js
+await kv.update("myName", "Sugawara");
+```
+
+### Counters
+
+```js
+await kv.increment("visits");
+await kv.decrement("visits", 2);
+```
+
+### Transactions
+
+```js
+await kv.transaction([
+  { set: "users:email:new@example.com", value: "user 1" },
+  { delete: "users:email:old@example.com" }
+]);
+```
+
+### Create access token
+
+```js
+const token = await kv.createAccessToken({
+  prefix: "user:123:",
+  permissions: "read,write",
+  ttl: 3600
+});
+```
+
+### Delete a key
+
+```js
+await kv.delete("myName");
+```
+
+### Delete a bucket
+
+```js
+await kv.deleteBucket();
+```
+
+## API
+
+- `new KVdbClient({ bucket, token?, authType?, baseUrl? })`
+- `KVdbClient.createBucket(email, { baseUrl?, secretKey?, writeKey?, readKey?, signingKey?, defaultTtl? })`
+- `get(key, { parseJson? })`
+- `set(key, value, { json?, contentType?, ttl? })`
+- `update(key, value, { json?, contentType?, ttl? })`
+- `increment(key, amount?, { ttl? })`
+- `decrement(key, amount?, { ttl? })`
+- `delete(key)`
+- `list({ values?, format?, limit?, skip?, prefix?, reverse? })`
+- `transaction(operations)`
+- `createAccessToken({ prefix?, permissions?, ttl? })`
+- `updateBucketPolicy({ secretKey?, writeKey?, readKey?, signingKey?, defaultTtl? })`
+- `deleteBucket()`
+
+## Notes
+
+- KVdb buckets can be public; avoid storing sensitive data.
+- `token` for Basic auth is sent as `curl -u 'token:'`.
+- The SDK author (n0bisuke) has no knowledge of how data stored in KVdb is handled; use at your own risk. The author is not responsible for any issues or damages.
+
+## Language
+
+- English (this file)
+- Japanese: `README.ja.md`
+- Japanese (GitHub): `https://github.com/n0bisuke/kvdb-client/blob/main/README.ja.md`

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "kvdb-client",
+  "version": "0.1.0",
+  "description": "Simple Node.js client for kvdb.io",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "kvdb",
+    "kvdb.io",
+    "key-value",
+    "sdk",
+    "node"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,70 @@
+export type KVdbClientOptions = {
+  bucket: string;
+  token?: string;
+  authType?: "basic" | "bearer" | "query";
+  baseUrl?: string;
+};
+
+export type CreateBucketOptions = {
+  baseUrl?: string;
+  secretKey?: string;
+  writeKey?: string;
+  readKey?: string;
+  signingKey?: string;
+  defaultTtl?: number;
+};
+
+export type GetOptions = {
+  parseJson?: boolean;
+};
+
+export type SetOptions = {
+  json?: boolean;
+  contentType?: string;
+  ttl?: number;
+};
+
+export type ListOptions = {
+  values?: boolean;
+  format?: string;
+  limit?: number;
+  skip?: number;
+  prefix?: string;
+  reverse?: boolean;
+};
+
+export type TransactionOperation =
+  | { set: string; value: unknown; ttl?: number }
+  | { delete: string };
+
+export type AccessTokenOptions = {
+  prefix?: string;
+  permissions?: string;
+  ttl?: number;
+};
+
+export type UpdateBucketPolicyOptions = {
+  secretKey?: string;
+  writeKey?: string;
+  readKey?: string;
+  signingKey?: string;
+  defaultTtl?: number;
+};
+
+export declare class KVdbClient {
+  constructor(options: KVdbClientOptions);
+  static createBucket(email: string, options?: CreateBucketOptions): Promise<string>;
+  get(key: string, options?: GetOptions): Promise<unknown>;
+  set(key: string, value: unknown, options?: SetOptions): Promise<unknown>;
+  update(key: string, value: unknown, options?: SetOptions): Promise<unknown>;
+  increment(key: string, amount?: number, options?: { ttl?: number }): Promise<unknown>;
+  decrement(key: string, amount?: number, options?: { ttl?: number }): Promise<unknown>;
+  delete(key: string): Promise<unknown>;
+  list(options?: ListOptions): Promise<unknown>;
+  transaction(operations: TransactionOperation[]): Promise<unknown>;
+  createAccessToken(options?: AccessTokenOptions): Promise<unknown>;
+  updateBucketPolicy(options?: UpdateBucketPolicyOptions): Promise<unknown>;
+  deleteBucket(): Promise<unknown>;
+}
+
+export default KVdbClient;

package/src/index.js

@@ -0,0 +1,271 @@
+const DEFAULT_BASE_URL = "https://kvdb.io";
+
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/$/, "");
+}
+
+function normalizeKey(key) {
+  if (typeof key !== "string" || key.trim() === "") {
+    throw new TypeError("key must be a non-empty string");
+  }
+  return key.replace(/^\/+/, "");
+}
+
+function buildAuthHeaders(authType, token) {
+  if (!token) return {};
+  if (authType === "bearer") {
+    return { Authorization: `Bearer ${token}` };
+  }
+  if (authType === "basic") {
+    const encoded = Buffer.from(`${token}:`, "utf8").toString("base64");
+    return { Authorization: `Basic ${encoded}` };
+  }
+  return {};
+}
+
+function appendAccessToken(url, authType, token) {
+  if (!token || authType !== "query") return url;
+  const hasQuery = url.includes("?");
+  const separator = hasQuery ? "&" : "?";
+  return `${url}${separator}access_token=${encodeURIComponent(token)}`;
+}
+
+async function readResponseBody(response) {
+  const contentType = response.headers.get("content-type") || "";
+  const text = await response.text();
+  if (contentType.includes("application/json")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+async function throwIfNotOk(response) {
+  if (response.ok) return response;
+  const body = await response.text();
+  const error = new Error(`KVdb request failed: ${response.status} ${response.statusText}`);
+  error.status = response.status;
+  error.body = body;
+  throw error;
+}
+
+export class KVdbClient {
+  constructor({ bucket, token, authType = "basic", baseUrl = DEFAULT_BASE_URL } = {}) {
+    if (!bucket) throw new TypeError("bucket is required");
+    this.bucket = bucket;
+    this.token = token;
+    this.authType = authType;
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+  }
+
+  static async createBucket(email, {
+    baseUrl = DEFAULT_BASE_URL,
+    secretKey,
+    writeKey,
+    readKey,
+    signingKey,
+    defaultTtl
+  } = {}) {
+    if (!email) throw new TypeError("email is required");
+    const body = new URLSearchParams({ email });
+    if (secretKey) body.set("secret_key", secretKey);
+    if (writeKey) body.set("write_key", writeKey);
+    if (readKey) body.set("read_key", readKey);
+    if (signingKey) body.set("signing_key", signingKey);
+    if (typeof defaultTtl === "number") body.set("default_ttl", String(defaultTtl));
+    const response = await fetch(normalizeBaseUrl(baseUrl), {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body
+    });
+    await throwIfNotOk(response);
+    return response.text();
+  }
+
+  _urlForKey(key, query = "") {
+    const safeKey = normalizeKey(key);
+    const suffix = query ? `?${query}` : "";
+    return `${this.baseUrl}/${this.bucket}/${safeKey}${suffix}`;
+  }
+
+  _urlForBucket(query = "") {
+    const suffix = query ? `?${query}` : "";
+    return `${this.baseUrl}/${this.bucket}${suffix}`;
+  }
+
+  _urlForBucketList(query = "") {
+    const suffix = query ? `/?${query}` : "/";
+    return `${this.baseUrl}/${this.bucket}${suffix}`;
+  }
+
+  _buildUrl(url) {
+    return appendAccessToken(url, this.authType, this.token);
+  }
+
+  _authHeaders() {
+    return buildAuthHeaders(this.authType, this.token);
+  }
+
+  async _request({ method, url, headers, body }) {
+    const response = await fetch(this._buildUrl(url), {
+      method,
+      headers: {
+        ...headers,
+        ...this._authHeaders()
+      },
+      body
+    });
+    await throwIfNotOk(response);
+    return readResponseBody(response);
+  }
+
+  async get(key, { parseJson } = {}) {
+    const body = await this._request({
+      method: "GET",
+      url: this._urlForKey(key)
+    });
+    if (parseJson && typeof body === "string") {
+      try {
+        return JSON.parse(body);
+      } catch {
+        return body;
+      }
+    }
+    return body;
+  }
+
+  async set(key, value, { json, contentType, ttl } = {}) {
+    const { body, headers } = this._serializeValue(value, { json, contentType });
+    const query = typeof ttl === "number" ? `ttl=${ttl}` : "";
+    return this._request({
+      method: "POST",
+      url: this._urlForKey(key, query),
+      headers,
+      body
+    });
+  }
+
+  async update(key, value, { json, contentType, ttl } = {}) {
+    const { body, headers } = this._serializeValue(value, { json, contentType });
+    const query = typeof ttl === "number" ? `ttl=${ttl}` : "";
+    return this._request({
+      method: "PATCH",
+      url: this._urlForKey(key, query),
+      headers,
+      body
+    });
+  }
+
+  async increment(key, amount = 1, { ttl } = {}) {
+    if (typeof amount !== "number") throw new TypeError("amount must be a number");
+    const sign = amount >= 0 ? "+" : "";
+    const query = typeof ttl === "number" ? `ttl=${ttl}` : "";
+    return this._request({
+      method: "PATCH",
+      url: this._urlForKey(key, query),
+      headers: { "content-type": "text/plain" },
+      body: `${sign}${amount}`
+    });
+  }
+
+  async decrement(key, amount = 1, { ttl } = {}) {
+    return this.increment(key, -Math.abs(amount), { ttl });
+  }
+
+  async delete(key) {
+    return this._request({
+      method: "DELETE",
+      url: this._urlForKey(key)
+    });
+  }
+
+  async list({
+    values = false,
+    format = "json",
+    limit,
+    skip,
+    prefix,
+    reverse
+  } = {}) {
+    const query = new URLSearchParams();
+    if (values) query.set("values", "true");
+    if (format) query.set("format", format);
+    if (typeof limit === "number") query.set("limit", String(limit));
+    if (typeof skip === "number") query.set("skip", String(skip));
+    if (prefix) query.set("prefix", prefix);
+    if (reverse) query.set("reverse", "true");
+    const body = await this._request({
+      method: "GET",
+      url: this._urlForBucketList(query.toString())
+    });
+    if (format === "json" && typeof body === "string") {
+      try {
+        return JSON.parse(body);
+      } catch {
+        return body;
+      }
+    }
+    return body;
+  }
+
+  async transaction(operations) {
+    if (!Array.isArray(operations)) throw new TypeError("operations must be an array");
+    const body = JSON.stringify({ txn: operations });
+    return this._request({
+      method: "POST",
+      url: this._urlForBucket(),
+      headers: { "content-type": "application/json" },
+      body
+    });
+  }
+
+  async createAccessToken({ prefix, permissions, ttl } = {}) {
+    const body = new URLSearchParams();
+    if (prefix) body.set("prefix", prefix);
+    if (permissions) body.set("permissions", permissions);
+    if (typeof ttl === "number") body.set("ttl", String(ttl));
+    return this._request({
+      method: "POST",
+      url: `${this.baseUrl}/${this.bucket}/tokens/`,
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body
+    });
+  }
+
+  async updateBucketPolicy({ secretKey, writeKey, readKey, signingKey, defaultTtl } = {}) {
+    const body = new URLSearchParams();
+    if (secretKey) body.set("secret_key", secretKey);
+    if (writeKey) body.set("write_key", writeKey);
+    if (readKey) body.set("read_key", readKey);
+    if (signingKey) body.set("signing_key", signingKey);
+    if (typeof defaultTtl === "number") body.set("default_ttl", String(defaultTtl));
+    return this._request({
+      method: "PATCH",
+      url: this._urlForBucket(),
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body
+    });
+  }
+
+  async deleteBucket() {
+    return this._request({
+      method: "DELETE",
+      url: `${this.baseUrl}/${this.bucket}/`
+    });
+  }
+
+  _serializeValue(value, { json, contentType } = {}) {
+    const headers = {};
+    if (contentType) headers["content-type"] = contentType;
+    if (json || value instanceof Object && !(value instanceof Buffer) && !(value instanceof ArrayBuffer) && !(value instanceof Uint8Array)) {
+      headers["content-type"] = headers["content-type"] || "application/json";
+      return { body: JSON.stringify(value), headers };
+    }
+    return { body: typeof value === "string" ? value : String(value), headers };
+  }
+}
+
+export default KVdbClient;