feat(sdk): add TypeScript client for Node.js

Adds sdk/javascript — a zero-dependency TypeScript SDK mirroring the
Python client's API: create, destroy, list, status, and withCopy. Uses
the global fetch available in Node 18+ with an injectable implementation
for testing. Ships a CI job and a tag-triggered npm publish workflow
with provenance.

Also modernises the Python pyproject.toml (correct build backend,
SPDX licence string, project URLs) and adds sdk/python/README.md.

Author: attaradev

.github/workflows/ci.yml

@@ -30,6 +30,37 @@ jobs:
           globs: |
             **/*.md
 
+  javascript-sdk:
+    name: JavaScript SDK
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/javascript
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: sdk/javascript/package-lock.json
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+
+  python-sdk:
+    name: Python SDK
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/python
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+
   test:
     name: Test
     runs-on: ubuntu-latest

.github/workflows/release-javascript-sdk.yml

@@ -0,0 +1,38 @@
+name: Release JavaScript SDK
+
+on:
+  push:
+    tags:
+      - "sdk-js-v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/javascript
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: sdk/javascript/package-lock.json
+      - run: npm install -g npm@11
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#sdk-js-v}"
+          PACKAGE_VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "tag version $TAG_VERSION does not match package.json version $PACKAGE_VERSION" >&2
+            exit 1
+          fi
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+      - run: npm publish --provenance

.github/workflows/release-python-sdk.yml

@@ -0,0 +1,44 @@
+name: Release Python SDK
+
+on:
+  push:
+    tags:
+      - "sdk-python-v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import tomllib
+
+          tag_version = os.environ["GITHUB_REF_NAME"].removeprefix("sdk-python-v")
+          pyproject = tomllib.loads(Path("sdk/python/pyproject.toml").read_text())
+          package_version = pyproject["project"]["version"]
+
+          if tag_version != package_version:
+              raise SystemExit(
+                  f"tag version {tag_version} does not match pyproject version {package_version}"
+              )
+          PY
+      - name: Build distributions
+        working-directory: sdk/python
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdk/python/dist

.gitignore

@@ -33,6 +33,11 @@ __pycache__/
 dist/
 .venv/
 
+# TypeScript / JavaScript
+node_modules/
+*.tsbuildinfo
+sdk/javascript/.tmp/
+
 # OS
 .DS_Store
 Thumbs.db

CONTRIBUTING.md

@@ -117,6 +117,7 @@ aligned before you invest implementation time.
 | `internal/server/` | HTTP API server for remote copy operations |
 | `internal/store/` | SQLite metadata for copy state and lifecycle events |
 | `pkg/ditto/` | Go SDK for tests and programmatic copy lifecycle |
+| `sdk/javascript/` | TypeScript SDK for Node.js clients |
 | `sdk/python/` | Python SDK and pytest fixture |
 | `actions/` | Composite GitHub Actions bundled in the repository |
 | `docs/` | Diataxis documentation set |

docs/how-to/use-ditto-in-ci.md

@@ -171,3 +171,31 @@ with client.with_copy() as dsn:
 
 The Python SDK reads `DITTO_SERVER_URL`, `DITTO_TOKEN`, and `DITTO_TTL` from the environment when
 they are present.
+
+## Use the JavaScript / TypeScript SDK
+
+Install from the package directory during local development, or from npm once you have published the
+package for your environment:
+
+```bash
+npm install ./sdk/javascript
+```
+
+Example:
+
+```ts
+import { DittoClient } from "@attaradev/ditto-sdk";
+
+const client = new DittoClient({
+  serverUrl: "http://ditto.internal:8080",
+  token: process.env.DITTO_TOKEN,
+  ttlSeconds: 600,
+});
+
+await client.withCopy(async (dsn) => {
+  await runMigrations(dsn);
+});
+```
+
+The JavaScript SDK reads `DITTO_SERVER_URL`, `DITTO_TOKEN`, and `DITTO_TTL` from the environment
+when they are present.

sdk/javascript/README.md

@@ -0,0 +1,44 @@
+# ditto JavaScript SDK
+
+TypeScript client for provisioning ephemeral database copies from a running ditto server.
+
+## Install
+
+```bash
+npm install @attaradev/ditto-sdk
+```
+
+## Usage
+
+```ts
+import { DittoClient } from "@attaradev/ditto-sdk";
+
+const client = new DittoClient({
+  serverUrl: "http://ditto.internal:8080",
+  token: process.env.DITTO_TOKEN
+});
+
+const copy = await client.create({ ttlSeconds: 600 });
+console.log(copy.connection_string);
+await client.destroy(copy.id);
+```
+
+Use `withCopy` when you want automatic cleanup:
+
+```ts
+import { DittoClient } from "@attaradev/ditto-sdk";
+
+const client = new DittoClient({ serverUrl: "http://ditto.internal:8080" });
+
+await client.withCopy(async (dsn) => {
+  console.log(dsn);
+});
+```
+
+## Environment variables
+
+`DittoClient` reads these variables by default:
+
+- `DITTO_SERVER_URL`
+- `DITTO_TOKEN`
+- `DITTO_TTL`

sdk/javascript/package-lock.json

@@ -0,0 +1,53 @@
+{
+  "name": "@attaradev/ditto-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript client for the ditto ephemeral database copy service",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .tmp",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build:test": "rm -rf .tmp && tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test .tmp/test/client.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ditto",
+    "database",
+    "testing",
+    "typescript",
+    "sdk"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/attaradev/ditto.git",
+    "directory": "sdk/javascript"
+  },
+  "bugs": {
+    "url": "https://github.com/attaradev/ditto/issues"
+  },
+  "homepage": "https://github.com/attaradev/ditto/tree/main/sdk/javascript",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
+  }
+}