@coffre/client 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,255 @@
+//#region src/sync-fields.ts
+function initialValues(provider) {
+	return Object.fromEntries(provider.fields.map((field) => [field.name, field.type === "text" ? "" : field.initial]));
+}
+/** Whether the rest of the form makes the field meaningful. */
+function isAsked(field, values) {
+	if (field.type === "options" || field.when === void 0) return true;
+	const picked = values[field.when.field];
+	const list = Array.isArray(picked) ? picked : [];
+	return list.length === field.when.is.length && field.when.is.every((value) => list.includes(value));
+}
+/** The label of the first required field left empty, or null when the form can be sent. */
+function firstMissing(provider, values) {
+	for (const field of provider.fields) {
+		if (!isAsked(field, values)) continue;
+		const value = values[field.name];
+		if ((typeof value === "string" ? value.trim() === "" : (value ?? []).length === 0) && (field.type === "options" || field.optional !== true)) return field.label;
+	}
+	return null;
+}
+/**
+* The provider's config. Text is trimmed, and an optional field left empty
+* is left out rather than sent as "", which the server rightly refuses.
+*/
+function configFromForm(provider, values) {
+	const config = {};
+	for (const field of provider.fields) {
+		if (!isAsked(field, values)) continue;
+		const value = values[field.name];
+		if (field.type === "options") {
+			const picked = Array.isArray(value) ? value : [];
+			config[field.name] = field.multiple ? picked : picked[0];
+		} else {
+			const text = typeof value === "string" ? value.trim() : "";
+			if (text !== "") config[field.name] = text;
+		}
+	}
+	return config;
+}
+/**
+* The config from `name=value` arguments, as the CLI takes them. A field with
+* several options takes them comma-separated, and one left out gets what the
+* form preselects. Text goes as typed, for the server to check.
+*/
+function configFromArguments(provider, assignments) {
+	const config = {};
+	for (const assignment of assignments) {
+		const equals = assignment.indexOf("=");
+		const name = equals === -1 ? assignment : assignment.slice(0, equals);
+		const field = provider.fields.find((candidate) => candidate.name === name);
+		if (equals === -1 || field === void 0) {
+			const names = provider.fields.map((candidate) => candidate.name).join(", ");
+			throw new Error(`${provider.label} takes ${names} as name=value; got ${JSON.stringify(assignment)}`);
+		}
+		if (Object.hasOwn(config, name)) throw new Error(`${name} is given twice`);
+		const value = assignment.slice(equals + 1);
+		if (field.type === "text") config[name] = value;
+		else if (field.multiple) config[name] = value.split(",").map((item) => item.trim()).filter((item) => item !== "");
+		else config[name] = value;
+	}
+	for (const field of provider.fields) if (field.type === "options" && !Object.hasOwn(config, field.name)) config[field.name] = field.multiple ? field.initial : field.initial[0];
+	return config;
+}
+//#endregion
+//#region src/index.ts
+/** The API's error shape, `{ error, message }`, with the HTTP status. */
+const COFFRE_ERROR = Symbol.for("@coffre/client:CoffreError");
+var CoffreError = class extends Error {
+	/**
+	* `@coffre/ui`'s prebuilt pages bundle a copy of this class, and a page is
+	* handed a client the server made with this package's. So `instanceof`
+	* asks for the mark every copy leaves, rather than for this copy's prototype.
+	*/
+	static [Symbol.hasInstance](value) {
+		return typeof value === "object" && value !== null && COFFRE_ERROR in value;
+	}
+	[COFFRE_ERROR] = true;
+	status;
+	code;
+	/** The vault's own code when it refused: `no_grant`, `removed`, `bulk_limit`, ... */
+	reason;
+	constructor(status, code, message, reason) {
+		super(message);
+		this.name = "CoffreError";
+		this.status = status;
+		this.code = code;
+		this.reason = reason;
+	}
+};
+/** `market/prod/KEY` as route parameters. */
+function place(path) {
+	const [project = "", environment = "", key = ""] = path.replace(/^\/+|\/+$/g, "").split("/");
+	return {
+		project,
+		environment,
+		key
+	};
+}
+function createClient(options) {
+	const origin = options.url.replace(/\/+$/, "");
+	const transport = options.transport ?? ((request) => fetch(request));
+	async function send(method, path, input) {
+		const url = new URL(`${origin}/api${path}`);
+		const headers = new Headers(await options.headers?.());
+		let body;
+		if (method === "GET") {
+			for (const [name, value] of Object.entries(input ?? {})) if (value !== void 0 && value !== null) url.searchParams.set(name, String(value));
+		} else if (input !== void 0) {
+			headers.set("content-type", "application/json");
+			body = JSON.stringify(input);
+		}
+		const response = await transport(new Request(url, {
+			method,
+			headers,
+			body
+		}));
+		const payload = await response.json().catch(() => null);
+		if (!response.ok) {
+			const error = payload;
+			throw new CoffreError(response.status, typeof error?.error === "string" ? error.error : "http_error", typeof error?.message === "string" ? error.message : `request failed with status ${response.status}`, typeof error?.reason === "string" ? error.reason : void 0);
+		}
+		return payload;
+	}
+	/** A route key and its parameters as a method and a path. */
+	function address(key, params) {
+		const [method, pattern] = key.split(" ");
+		return [method, pattern.replace(/:(\w+)/g, (_, name) => encodeURIComponent(params[name]))];
+	}
+	/** Any route by its key: `call('GET /secrets/:project/:environment', { project, environment })`. */
+	async function call(key, ...[params, input]) {
+		const [method, path] = address(key, params);
+		return await send(method, path, input);
+	}
+	return {
+		call,
+		/** How this instance signs people in. Answers anyone, signed in or not. */
+		auth: () => send("GET", "/auth", void 0),
+		/** Who I am, and every place I can reach. */
+		me: () => call("GET /me", {}),
+		projects: {
+			/** With their environments. */
+			list: () => call("GET /projects", {}),
+			create: (project, input) => call("PUT /projects/:project", { project }, input),
+			update: (project, patch) => call("PATCH /projects/:project", { project }, patch)
+		},
+		environments: {
+			create: (path, input) => call("PUT /projects/:project/:environment", place(path), input),
+			update: (path, patch) => call("PATCH /projects/:project/:environment", place(path), patch)
+		},
+		secrets: {
+			/** Keys, versions and who changed what; never values. */
+			list: (path) => call("GET /secrets/:project/:environment", place(path)),
+			/** Decrypts one secret, or every secret in an environment. Logged in your name. */
+			reveal: (path) => call("POST /reveals", {}, { path }),
+			/** One transaction, a version and an audit entry per key; `null` archives. */
+			set: (path, values) => call("PATCH /secrets/:project/:environment", place(path), values),
+			/**
+			* What `set` would do to each key, `added`, `changed`, `unchanged` or
+			* `archived`, and nothing else: no value comes back and nothing is
+			* written. Comparing opens the current values, logged as reads.
+			*/
+			dryRun: (path, values) => {
+				const [method, route] = address("PATCH /secrets/:project/:environment", place(path));
+				return send(method, `${route}?dryRun=1`, values);
+			},
+			history: (path) => call("GET /secrets/:project/:environment/:key/versions", place(path)),
+			/** A new version holding the old one's value. */
+			restore: (path, version) => call("POST /secrets/:project/:environment/:key/restore", place(path), { version }),
+			rename: (path, key) => call("PATCH /secrets/:project/:environment/:key", place(path), { key }),
+			update: (path, patch) => call("PATCH /secrets/:project/:environment/:key", place(path), patch)
+		},
+		members: {
+			/** People and tokens, their role and their access; at a place, those who reach it. */
+			list: (path) => call("GET /members", {}, { path }),
+			/** What they hold, and what to rotate if they leave. */
+			get: (member) => call("GET /members/:member", { member }),
+			add: (member, input = {}) => call("PUT /members/:member", { member }, input),
+			/** Offboards; returns what to rotate. */
+			remove: (member) => call("DELETE /members/:member", { member })
+		},
+		tokens: {
+			list: (member) => call("GET /members/:member/tokens", { member }),
+			/** The value is in the answer, and only there. */
+			issue: (member, input) => call("POST /members/:member/tokens", { member }, input),
+			revoke: (member, id) => call("DELETE /members/:member/tokens/:id", {
+				member,
+				id
+			})
+		},
+		access: { 
+		/** What they should hold at each place; the server applies the difference. `null` revokes. */
+set: (member, access) => call("PATCH /access/:member", { member }, access) },
+		/** Where I am signed in. Only where coffre runs its own sign-in. */
+		sessions: {
+			list: () => call("GET /sessions", {}),
+			revoke: (id) => call("DELETE /sessions/:id", { id })
+		},
+		/** The accounts I sign in with. */
+		identities: {
+			list: () => call("GET /identities", {}),
+			unlink: (id) => call("DELETE /identities/:id", { id })
+		},
+		/** A `coffre login` waiting for someone to approve it, by the code it shows. */
+		deviceLogins: {
+			get: (code) => call("GET /device-logins/:code", { code }),
+			decide: (code, approve) => call("POST /device-logins/:code", { code }, { approve })
+		},
+		syncs: {
+			/** Where a sync can push on this instance, and what each asks for. */
+			providers: () => call("GET /syncs/providers", {}),
+			list: (path) => call("GET /syncs/:project/:environment", place(path)),
+			add: (path, input) => call("POST /syncs/:project/:environment", place(path), input),
+			update: (id, patch) => call("PATCH /syncs/by-id/:id", { id }, patch),
+			remove: (id) => call("DELETE /syncs/by-id/:id", { id }),
+			run: (id) => call("POST /syncs/by-id/:id/runs", { id })
+		},
+		audit: {
+			list: (query = {}) => call("GET /audit", {}, query),
+			verify: () => call("GET /audit/verification", {})
+		}
+	};
+}
+/**
+* What writing these entries (a parsed `.env` file) would do, from a dry run
+* of the write: the server compares, so no value leaves it, and the values it
+* opens to compare are logged as reads. `changes` is what to pass to
+* `secrets.set`: the keys that differ, so an unchanged value does not become
+* a new version.
+*/
+async function planImport(coffre, path, entries) {
+	const values = Object.create(null);
+	for (const { key, value } of entries) values[key] = value;
+	const [listed, compared] = await Promise.allSettled([coffre.secrets.list(path), coffre.secrets.dryRun(path, { ...values })]);
+	if (listed.status === "rejected") throw listed.reason;
+	if (compared.status === "rejected") throw compared.reason;
+	const [{ keys }, dryRun] = [listed.value, compared.value];
+	const versions = new Map(keys.map((entry) => [entry.key, entry.version]));
+	const plan = [];
+	const changes = Object.create(null);
+	for (const [key, value] of Object.entries(values)) {
+		const action = dryRun.keys[key];
+		plan.push({
+			key,
+			action,
+			version: versions.get(key) ?? null
+		});
+		if (action !== "unchanged") changes[key] = value;
+	}
+	return {
+		plan,
+		changes: { ...changes }
+	};
+}
+//#endregion
+export { CoffreError, configFromArguments, configFromForm, createClient, firstMissing, initialValues, isAsked, planImport };

package/package.json

@@ -1,8 +1,38 @@
 {
   "name": "@coffre/client",
-  "version": "0.0.0",
-  "description": "Reserved for coffre, a self-hosted secrets manager. The first release replaces this placeholder.",
+  "version": "0.1.0",
+  "description": "The coffre API as typed function calls.",
   "license": "MIT",
-  "homepage": "https://github.com/erwinkn/coffre",
-  "repository": { "type": "git", "url": "git+https://github.com/erwinkn/coffre.git", "directory": "packages/client" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erwinkn/coffre.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "coffre:source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "tsdown": "0.23.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "generate": "node scripts/generate-api.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --conditions=coffre:source --test"
+  }
+}