@osm-editor-kit/key-value-db-client 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Jordans
+
+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.md

@@ -0,0 +1,25 @@
+# @osm-editor-kit/key-value-db-client
+
+Typed, dependency-free `fetch` client for [key-value-db](https://github.com/FixMyBerlin/key-value-db), a shared key-value API for OpenStreetMap-authenticated apps.
+
+```ts
+import { createKvClient } from '@osm-editor-kit/key-value-db-client'
+
+const kv = createKvClient<MyData>({
+  baseUrl: 'https://key-value-store.fixmycity.workers.dev',
+  project: 'my-project',
+  apiKey: 'kv_…', // public project key
+  getOsmToken: () => osmAccessToken ?? null,
+})
+
+await kv.put('way/1', { note: 'hi' }, ['tag-a'])
+const { items } = await kv.list({ tags: ['tag-a'] })
+```
+
+Methods: `list`, `get`, `put` (with `ifMatch`), `remove`, `batch`, `tags`, `me`, `removeMine` ("delete my data" in this project), and `forget` (drops the server-side token cache). Errors are thrown as `KvError` with `status` and `code`. Response envelopes are checked; your `data` is not.
+
+API reference: [docs/API.md](https://github.com/FixMyBerlin/key-value-db/blob/main/docs/API.md).
+
+## License
+
+This package is [MIT](LICENSE). The key-value-db server in the same repo is AGPL-3.0.

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+import type { KvErrorCode } from './types.js';
+export declare class KvError extends Error {
+    readonly status: number;
+    readonly code: KvErrorCode;
+    readonly details?: unknown;
+    constructor(status: number, code: KvErrorCode, message: string, details?: unknown);
+}
+export declare function kvErrorFromResponse(response: Response): Promise<KvError>;

package/dist/errors.js

@@ -0,0 +1,53 @@
+const KV_ERROR_CODES = new Set([
+    'invalid_project_key',
+    'origin_not_allowed',
+    'unauthenticated',
+    'forbidden_user',
+    'not_found',
+    'validation_failed',
+    'payload_too_large',
+    'version_conflict',
+    'rate_limited',
+    'osm_unavailable',
+    'internal',
+]);
+export class KvError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'KvError';
+    }
+}
+function asKvErrorCode(code) {
+    if (typeof code === 'string' && KV_ERROR_CODES.has(code)) {
+        return code;
+    }
+    return 'internal';
+}
+export async function kvErrorFromResponse(response) {
+    let code = 'internal';
+    let message = response.statusText || 'Request failed';
+    let details;
+    try {
+        const body = await response.json();
+        if (body !== null && typeof body === 'object' && 'error' in body) {
+            const err = body.error;
+            if (err !== null && typeof err === 'object') {
+                const envelope = err;
+                code = asKvErrorCode(envelope.code);
+                if (typeof envelope.message === 'string')
+                    message = envelope.message;
+                details = envelope.details;
+            }
+        }
+    }
+    catch {
+        // Non-JSON error bodies still become a KvError with status.
+    }
+    return new KvError(response.status, code, message, details);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { KvError } from './errors.js';
+import type { KvClient, KvClientOptions } from './types.js';
+export type { KvBatchResult, KvClient, KvClientOptions, KvEntry, KvErrorCode, KvListResult, KvUser, } from './types.js';
+export { KvError };
+export declare function createKvClient<T = unknown>(options: KvClientOptions): KvClient<T>;

package/dist/index.js

@@ -0,0 +1,138 @@
+import { kvErrorFromResponse, KvError } from './errors.js';
+import { assertBatch, assertDeleted, assertEntry, assertList, assertMe, assertTags, } from './validate.js';
+export { KvError };
+function trimTrailingSlashes(baseUrl) {
+    return baseUrl.replace(/\/+$/, '');
+}
+function projectUrl(baseUrl, project, ...segments) {
+    const parts = [
+        trimTrailingSlashes(baseUrl),
+        'v1',
+        'projects',
+        encodeURIComponent(project),
+        ...segments,
+    ];
+    return parts.join('/');
+}
+async function requestHeaders(apiKey, getOsmToken, extra) {
+    const headers = new Headers(extra);
+    headers.set('X-Api-Key', apiKey);
+    const token = await getOsmToken();
+    if (token != null) {
+        headers.set('Authorization', `Bearer ${token}`);
+    }
+    return headers;
+}
+async function parseJson(response, check) {
+    if (!response.ok) {
+        throw await kvErrorFromResponse(response);
+    }
+    const body = await response.json();
+    check(body);
+    return body;
+}
+async function parseEmpty(response) {
+    if (!response.ok) {
+        throw await kvErrorFromResponse(response);
+    }
+}
+export function createKvClient(options) {
+    const { apiKey, getOsmToken, project } = options;
+    const baseUrl = options.baseUrl;
+    const entriesCollection = () => projectUrl(baseUrl, project, 'entries');
+    const entryUrl = (id) => projectUrl(baseUrl, project, 'entries', encodeURIComponent(id));
+    const tagsUrl = () => projectUrl(baseUrl, project, 'tags');
+    const meUrl = () => projectUrl(baseUrl, project, 'me');
+    const batchUrl = () => projectUrl(baseUrl, project, 'batch');
+    return {
+        async list(params) {
+            const query = new URLSearchParams();
+            for (const tag of params?.tags ?? []) {
+                query.append('tag', tag);
+            }
+            if (params?.match !== undefined) {
+                query.set('match', params.match);
+            }
+            if (params?.updatedSince !== undefined) {
+                query.set('updated_since', params.updatedSince);
+            }
+            if (params?.limit !== undefined) {
+                query.set('limit', String(params.limit));
+            }
+            if (params?.cursor !== undefined) {
+                query.set('cursor', params.cursor);
+            }
+            const qs = query.toString();
+            const url = qs ? `${entriesCollection()}?${qs}` : entriesCollection();
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            return parseJson(response, assertList);
+        },
+        async get(id) {
+            const response = await fetch(entryUrl(id), {
+                method: 'GET',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            return parseJson(response, assertEntry);
+        },
+        async put(id, data, tags = [], opts) {
+            const headers = await requestHeaders(apiKey, getOsmToken, {
+                'Content-Type': 'application/json',
+            });
+            if (opts?.ifMatch !== undefined) {
+                headers.set('If-Match', opts.ifMatch);
+            }
+            const response = await fetch(entryUrl(id), {
+                method: 'PUT',
+                headers,
+                body: JSON.stringify({ data, tags }),
+            });
+            return parseJson(response, assertEntry);
+        },
+        async remove(id) {
+            const response = await fetch(entryUrl(id), {
+                method: 'DELETE',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            await parseEmpty(response);
+        },
+        async tags() {
+            const response = await fetch(tagsUrl(), {
+                method: 'GET',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            return parseJson(response, assertTags);
+        },
+        async batch(ops) {
+            const response = await fetch(batchUrl(), {
+                method: 'POST',
+                headers: await requestHeaders(apiKey, getOsmToken, { 'Content-Type': 'application/json' }),
+                body: JSON.stringify({ put: ops.put ?? [], delete: ops.delete ?? [] }),
+            });
+            return parseJson(response, assertBatch);
+        },
+        async removeMine() {
+            const response = await fetch(`${meUrl()}/entries`, {
+                method: 'DELETE',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            return parseJson(response, assertDeleted);
+        },
+        async me() {
+            const response = await fetch(meUrl(), {
+                method: 'GET',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            return parseJson(response, assertMe);
+        },
+        async forget() {
+            const response = await fetch(meUrl(), {
+                method: 'DELETE',
+                headers: await requestHeaders(apiKey, getOsmToken),
+            });
+            await parseEmpty(response);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+export type KvErrorCode = 'invalid_project_key' | 'origin_not_allowed' | 'unauthenticated' | 'forbidden_user' | 'not_found' | 'validation_failed' | 'payload_too_large' | 'version_conflict' | 'rate_limited' | 'osm_unavailable' | 'internal';
+export type KvUser = {
+    osm_uid: number;
+    display_name: string;
+};
+export type KvEntry<T> = {
+    id: string;
+    data: T;
+    tags: string[];
+    version: number;
+    created_at: string;
+    updated_at: string;
+    created_by: KvUser;
+    updated_by: KvUser;
+    /** ISO time the entry expires (projects with entry_ttl_s); null or absent = never. */
+    expires_at?: string | null;
+};
+export type KvListResult<T> = {
+    items: Array<KvEntry<T>>;
+    next_cursor: string | null;
+};
+export type KvClientOptions = {
+    baseUrl: string;
+    project: string;
+    apiKey: string;
+    getOsmToken: () => string | null | Promise<string | null>;
+};
+export type KvClient<T> = {
+    list(params?: {
+        tags?: string[];
+        match?: 'all' | 'any';
+        updatedSince?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<KvListResult<T>>;
+    get(id: string): Promise<KvEntry<T>>;
+    put(id: string, data: T, tags?: string[], opts?: {
+        ifMatch?: string;
+    }): Promise<KvEntry<T>>;
+    remove(id: string): Promise<void>;
+    tags(): Promise<{
+        tags: Array<{
+            tag: string;
+            count: number;
+        }>;
+    }>;
+    /** Up to 25 puts and 50 deletes in one atomic call. Deleting an absent id is not an error. */
+    batch(ops: {
+        put?: Array<{
+            id: string;
+            data: T;
+            tags?: string[];
+        }>;
+        delete?: string[];
+    }): Promise<KvBatchResult<T>>;
+    me(): Promise<{
+        user: KvUser;
+        can_write: boolean;
+    }>;
+    /** "Delete my data" for this project: removes every entry the user created here. */
+    removeMine(): Promise<{
+        deleted: number;
+    }>;
+    forget(): Promise<void>;
+};
+export type KvBatchResult<T> = {
+    put: Array<KvEntry<T>>;
+    deleted: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import type { KvBatchResult, KvEntry, KvListResult, KvUser } from './types.js';
+export declare function assertEntry<T>(v: unknown): asserts v is KvEntry<T>;
+export declare function assertList<T>(v: unknown): asserts v is KvListResult<T>;
+export declare function assertBatch<T>(v: unknown): asserts v is KvBatchResult<T>;
+export declare function assertTags(v: unknown): asserts v is {
+    tags: Array<{
+        tag: string;
+        count: number;
+    }>;
+};
+export declare function assertMe(v: unknown): asserts v is {
+    user: KvUser;
+    can_write: boolean;
+};
+export declare function assertDeleted(v: unknown): asserts v is {
+    deleted: number;
+};

package/dist/validate.js

@@ -0,0 +1,57 @@
+import { KvError } from './errors.js';
+// Small hand-written checks for the response envelopes, so the client stays
+// dependency-free. `data` is not checked: each app validates its own payload.
+const isObject = (v) => typeof v === 'object' && v !== null;
+function invalid(what) {
+    return new KvError(200, 'internal', `Unexpected response from the KV API: ${what}`);
+}
+function assertUser(v, what) {
+    if (!isObject(v) || typeof v.osm_uid !== 'number' || typeof v.display_name !== 'string') {
+        throw invalid(what);
+    }
+}
+export function assertEntry(v) {
+    if (!isObject(v) ||
+        typeof v.id !== 'string' ||
+        !('data' in v) ||
+        !Array.isArray(v.tags) ||
+        !v.tags.every((t) => typeof t === 'string') ||
+        typeof v.version !== 'number' ||
+        typeof v.created_at !== 'string' ||
+        typeof v.updated_at !== 'string' ||
+        (v.expires_at !== undefined && v.expires_at !== null && typeof v.expires_at !== 'string')) {
+        throw invalid('entry');
+    }
+    assertUser(v.created_by, 'entry.created_by');
+    assertUser(v.updated_by, 'entry.updated_by');
+}
+export function assertList(v) {
+    if (!isObject(v) || !Array.isArray(v.items))
+        throw invalid('list');
+    if (v.next_cursor !== null && typeof v.next_cursor !== 'string')
+        throw invalid('list.next_cursor');
+    for (const item of v.items)
+        assertEntry(item);
+}
+export function assertBatch(v) {
+    if (!isObject(v) || !Array.isArray(v.put) || typeof v.deleted !== 'number')
+        throw invalid('batch');
+    for (const item of v.put)
+        assertEntry(item);
+}
+export function assertTags(v) {
+    if (!isObject(v) ||
+        !Array.isArray(v.tags) ||
+        !v.tags.every((t) => isObject(t) && typeof t.tag === 'string' && typeof t.count === 'number')) {
+        throw invalid('tags');
+    }
+}
+export function assertMe(v) {
+    if (!isObject(v) || typeof v.can_write !== 'boolean')
+        throw invalid('me');
+    assertUser(v.user, 'me.user');
+}
+export function assertDeleted(v) {
+    if (!isObject(v) || typeof v.deleted !== 'number')
+        throw invalid('deleted');
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@osm-editor-kit/key-value-db-client",
+  "version": "0.0.0",
+  "description": "Typed, dependency-free fetch client for key-value-db: a shared key-value API for OpenStreetMap-authenticated apps (Cloudflare Workers + D1).",
+  "keywords": [
+    "client",
+    "cloudflare",
+    "d1",
+    "key-value",
+    "openstreetmap",
+    "osm"
+  ],
+  "homepage": "https://github.com/FixMyBerlin/key-value-db/tree/main/packages/kv-client#readme",
+  "bugs": {
+    "url": "https://github.com/FixMyBerlin/key-value-db/issues"
+  },
+  "license": "MIT",
+  "author": "Tobias Jordans",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FixMyBerlin/key-value-db.git",
+    "directory": "packages/kv-client"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check-exports": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution --profile node16",
+    "prepublishOnly": "bun run build",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "test-run": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}