@dropby/server 0.4.0

package/dist/index.js

@@ -0,0 +1,343 @@
+var DropByError = class extends Error {
+	name = "DropByError";
+	code;
+	status;
+	retryAfter;
+	constructor(code, message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.code = code;
+		this.status = options.status;
+		this.retryAfter = options.retryAfter;
+	}
+};
+function invalidInput(message) {
+	return new DropByError("invalid_input", message);
+}
+async function apiError(response) {
+	const body = await response.json().catch(() => null);
+	const error = isRecord(body) && isRecord(body.error) ? body.error : null;
+	const options = {
+		status: response.status,
+		retryAfter: retryAfter(response)
+	};
+	if (error && typeof error.code === "string" && typeof error.message === "string") return new DropByError(error.code, error.message, options);
+	return new DropByError("request_failed", `DropBy request failed with status ${response.status}`, options);
+}
+function retryAfter(response) {
+	const value = response.headers.get("retry-after");
+	return value !== null && /^\d{1,6}$/.test(value) ? Number(value) : void 0;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+const defaultApiBaseUrl = "https://api.dropby.chat";
+const defaultTimeoutMs = 3e4;
+const defaultMaxRetries = 2;
+const maxMaxRetries = 10;
+const maxRetryAfterSeconds = 10;
+const maxTimeoutMs = 2147483647;
+const secretKeyPattern = /^sk_(?:live|test)_[0-9a-f]{64}$/;
+const idBodyPattern = /^[A-Za-z0-9_-]+$/;
+const idempotencyKeyPattern = /^[\x21-\x7e]{1,128}$/;
+var Server = class {
+	asks;
+	browserSessions;
+	chat;
+	config;
+	ideas;
+	#secretKey;
+	#origin;
+	#fetch;
+	#timeoutMs;
+	#maxRetries;
+	#cache;
+	constructor(options) {
+		this.#secretKey = requiredSecretKey(options.secretKey);
+		this.#origin = apiOrigin(options.apiBaseUrl ?? defaultApiBaseUrl);
+		this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+		this.#timeoutMs = requestTimeout(options.timeoutMs ?? defaultTimeoutMs);
+		this.#maxRetries = retries(options.maxRetries ?? defaultMaxRetries);
+		this.#cache = acceptsCacheOption();
+		this.asks = {
+			create: async (input, options = {}) => this.#send("POST", "/v1/asks", {
+				body: input,
+				key: options.idempotencyKey,
+				keyed: true
+			}),
+			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("GET", "/v1/asks", { query: {
+				filter,
+				sort,
+				limit,
+				cursor
+			} }),
+			get: async (askId) => this.#send("GET", `/v1/asks/${pathId(askId, "ask_")}`),
+			listResponses: async (askId, { limit, cursor } = {}) => this.#send("GET", `/v1/asks/${pathId(askId, "ask_")}/responses`, { query: {
+				limit,
+				cursor
+			} })
+		};
+		this.browserSessions = { create: async (input) => this.#send("POST", "/v1/browser-sessions", { body: input }) };
+		this.chat = {
+			list: async ({ filter, limit, cursor } = {}) => this.#send("GET", "/v1/chat/threads", { query: {
+				filter,
+				limit,
+				cursor
+			} }),
+			get: async (threadId) => this.#send("GET", `/v1/chat/threads/${pathId(threadId, "thr_")}`),
+			listMessages: async (threadId, { limit, cursor } = {}) => this.#send("GET", `/v1/chat/threads/${pathId(threadId, "thr_")}/messages`, { query: {
+				limit,
+				cursor
+			} }),
+			create: async (input, options = {}) => this.#send("POST", "/v1/chat/threads", {
+				body: input,
+				key: options.idempotencyKey,
+				keyed: true
+			}),
+			reply: async (threadId, input, options = {}) => this.#send("POST", `/v1/chat/threads/${pathId(threadId, "thr_")}/messages`, {
+				body: input,
+				key: options.idempotencyKey,
+				keyed: true
+			}),
+			update: async (threadId, changes) => this.#send("PATCH", `/v1/chat/threads/${pathId(threadId, "thr_")}`, { body: changes }),
+			getAttachmentDownload: async (attachmentId) => this.#send("GET", `/v1/chat/attachments/${pathId(attachmentId, "att_")}/download`)
+		};
+		this.config = { evaluate: async (input) => this.#send("POST", "/v1/config/evaluate", { body: input }) };
+		this.ideas = {
+			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("GET", "/v1/ideas", { query: {
+				filter,
+				sort,
+				limit,
+				cursor
+			} }),
+			get: async (ideaId) => this.#send("GET", `/v1/ideas/${pathId(ideaId, "idea_")}`),
+			listVoters: async (ideaId, { limit, cursor } = {}) => this.#send("GET", `/v1/ideas/${pathId(ideaId, "idea_")}/voters`, { query: {
+				limit,
+				cursor
+			} }),
+			listDuplicates: async (ideaId, { limit, cursor } = {}) => this.#send("GET", `/v1/ideas/${pathId(ideaId, "idea_")}/duplicates`, { query: {
+				limit,
+				cursor
+			} }),
+			create: async (input, options = {}) => this.#send("POST", "/v1/ideas", {
+				body: input,
+				key: options.idempotencyKey,
+				keyed: true
+			}),
+			update: async (ideaId, changes) => this.#send("PATCH", `/v1/ideas/${pathId(ideaId, "idea_")}`, { body: changes }),
+			merge: async (ideaId, input) => this.#send("POST", `/v1/ideas/${pathId(ideaId, "idea_")}/merge`, { body: input })
+		};
+	}
+	async #send(method, path, options = {}) {
+		const { key, keyed } = options;
+		if (key !== void 0 && (typeof key !== "string" || !idempotencyKeyPattern.test(key))) throw invalidInput("idempotencyKey must be 1 to 128 visible ASCII characters, such as a UUID");
+		const sentKey = key ?? (keyed ? crypto.randomUUID() : void 0);
+		const payload = options.body === void 0 ? void 0 : serialise(options.body);
+		const url = `${this.#origin}${path}${search(options.query)}`;
+		for (let attempt = 0;; attempt++) try {
+			return await this.#attempt(method, url, payload, sentKey);
+		} catch (error) {
+			if (!(error instanceof DropByError) || !transient(error) || attempt >= this.#maxRetries) throw error;
+			if (error.retryAfter !== void 0 && error.retryAfter > maxRetryAfterSeconds) throw error;
+			await sleep(Math.max(backoff(attempt + 1), (error.retryAfter ?? 0) * 1e3));
+		}
+	}
+	async #attempt(method, url, payload, key) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+		try {
+			const response = await this.#fetch(url, {
+				method,
+				...this.#cache ? { cache: "no-store" } : {},
+				signal: controller.signal,
+				headers: {
+					accept: "application/json",
+					authorization: `Bearer ${this.#secretKey}`,
+					...payload === void 0 ? {} : { "content-type": "application/json" },
+					...key === void 0 ? {} : { "idempotency-key": key }
+				},
+				...payload === void 0 ? {} : { body: payload }
+			});
+			if (!response.ok) throw await apiError(response);
+			const text = await response.text();
+			try {
+				return JSON.parse(text);
+			} catch {
+				throw new DropByError("invalid_response", `DropBy answered ${response.status} with a body that is not JSON`, { status: response.status });
+			}
+		} catch (error) {
+			if (controller.signal.aborted) throw new DropByError("timeout", `DropBy did not answer within ${this.#timeoutMs} ms`, { cause: error });
+			if (error instanceof DropByError) throw error;
+			throw new DropByError("network_error", "DropBy could not be reached", { cause: error });
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+};
+function createDropByServer(options) {
+	return new Server(options);
+}
+function transient(error) {
+	if (error.status === void 0) return error.code === "network_error" || error.code === "timeout";
+	return error.status === 408 || error.status === 429 || error.status >= 500;
+}
+function backoff(retry) {
+	return Math.min(8e3, 500 * 2 ** (retry - 1)) * (.5 + Math.random() / 2);
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function acceptsCacheOption() {
+	try {
+		new Request("https://api.dropby.chat", { cache: "no-store" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function retries(value) {
+	if (!Number.isInteger(value) || value < 0 || value > maxMaxRetries) throw invalidInput(`maxRetries must be a whole number from 0 to ${maxMaxRetries}`);
+	return value;
+}
+function requiredSecretKey(value) {
+	const key = typeof value === "string" ? value.trim() : "";
+	if (secretKeyPattern.test(key)) return key;
+	if (!key) throw invalidInput("secretKey is missing");
+	if (key.startsWith("pk_") || key.startsWith("pkey_")) throw invalidInput("secretKey is a browser key; the server API takes a secret key (sk_live_… or sk_test_…)");
+	throw invalidInput("secretKey is not a DropBy secret key (sk_live_… or sk_test_…)");
+}
+function apiOrigin(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw invalidInput("apiBaseUrl is not a URL");
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:" || url.pathname !== "/" || url.search || url.hash) throw invalidInput("apiBaseUrl must be an origin, like https://api.dropby.chat");
+	if (url.protocol === "http:" && !localHost(url.hostname)) throw invalidInput("apiBaseUrl must use https unless it is a local host");
+	return url.origin;
+}
+function localHost(hostname) {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function requestTimeout(value) {
+	if (!Number.isInteger(value) || value < 1 || value > maxTimeoutMs) throw invalidInput("timeoutMs must be a whole number of milliseconds above zero");
+	return value;
+}
+function pathId(value, prefix) {
+	if (typeof value !== "string" || !value.startsWith(prefix) || !idBodyPattern.test(value.slice(prefix.length))) throw invalidInput(`Expected a DropBy id starting with ${prefix}`);
+	return value;
+}
+function search(query) {
+	const params = new URLSearchParams();
+	for (const [name, value] of Object.entries(query ?? {})) if (value !== void 0 && value !== "") params.set(name, String(value));
+	const encoded = params.toString();
+	return encoded ? `?${encoded}` : "";
+}
+function serialise(body) {
+	try {
+		return JSON.stringify(body);
+	} catch (cause) {
+		throw new DropByError("invalid_input", "The request body cannot be serialised as JSON", { cause });
+	}
+}
+const identityProofAudience = "dropby:browser-session";
+const identityProofType = "dropby-identity+jwt";
+const identitySecretPattern$1 = /^[0-9a-f]{64}$/;
+async function createIdentityProof(options) {
+	const { secret, productId, publicKeyId, env } = options;
+	if (typeof secret !== "string" || !identitySecretPattern$1.test(secret)) throw invalidInput("The identity secret must be 64 lowercase hexadecimal characters");
+	if (!hasPrefix(productId, "prj_")) throw invalidInput("productId must start with prj_");
+	if (!hasPrefix(publicKeyId, "pkey_")) throw invalidInput("publicKeyId must start with pkey_");
+	if (env !== "live" && env !== "test") throw invalidInput("env must be \"live\" or \"test\"");
+	const ttlSeconds = options.ttlSeconds ?? 900;
+	if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > 900) throw invalidInput(`ttlSeconds must be a whole number from 1 to 900`);
+	const user = options.user;
+	checkIdentityId(user?.id, "user.id");
+	const account = options.account;
+	if (account) checkIdentityId(account.id, "account.id");
+	const iat = Math.floor(Date.now() / 1e3);
+	const claims = {
+		iss: productId,
+		aud: identityProofAudience,
+		env,
+		publicKeyId,
+		iat,
+		exp: iat + ttlSeconds,
+		user: known(user, [
+			"id",
+			"name",
+			"email",
+			"attributes"
+		]),
+		...account ? { account: known(account, [
+			"id",
+			"name",
+			"domain",
+			"attributes"
+		]) } : {}
+	};
+	const header = {
+		alg: "HS256",
+		typ: identityProofType
+	};
+	const encoder = new TextEncoder();
+	const signingInput = `${encodeJson(header)}.${encodeJson(claims)}`;
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(signingInput));
+	const proof = `${signingInput}.${base64url(new Uint8Array(signature))}`;
+	if (proof.length > 131072) throw invalidInput("The identity proof is too large; send fewer attributes");
+	return proof;
+}
+function hasPrefix(value, prefix) {
+	return typeof value === "string" && value.startsWith(prefix) && value.length > prefix.length;
+}
+function checkIdentityId(value, name) {
+	const id = typeof value === "string" ? value.trim() : "";
+	if (id.length < 1 || id.length > 256) throw invalidInput(`${name} must be 1 to 256 characters`);
+	for (const char of id) {
+		const code = char.charCodeAt(0);
+		if (code < 32 || code === 127) throw invalidInput(`${name} cannot contain control characters`);
+	}
+}
+function known(value, keys) {
+	const picked = {};
+	for (const key of keys) if (value[key] !== void 0) picked[key] = value[key];
+	return picked;
+}
+function encodeJson(value) {
+	let json;
+	try {
+		json = JSON.stringify(value);
+	} catch (cause) {
+		throw new DropByError("invalid_input", "The identity cannot be serialised as JSON", { cause });
+	}
+	return base64url(new TextEncoder().encode(json));
+}
+function base64url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+const uuid = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const productIdPattern = new RegExp(`^prj_${uuid}$`);
+const publicKeyIdPattern = new RegExp(`^pkey_${uuid}$`);
+const identitySecretPattern = /^[0-9a-f]{64}$/;
+function identityProofOptionsFromEnv(vars) {
+	return {
+		productId: read(vars, "DROPBY_PRODUCT_ID", (value) => productIdPattern.test(value) ? value : null),
+		publicKeyId: read(vars, "DROPBY_PUBLIC_KEY_ID", (value) => publicKeyIdPattern.test(value) ? value : null),
+		env: read(vars, "DROPBY_ENV", (value) => value === "live" || value === "test" ? value : null),
+		secret: read(vars, "DROPBY_IDENTITY_SECRET", (value) => identitySecretPattern.test(value) ? value : null)
+	};
+}
+function read(vars, name, parse) {
+	const value = vars[name];
+	if (value === void 0 || value === "") throw invalidInput(`${name} is missing`);
+	const result = typeof value === "string" ? parse(value) : null;
+	if (result === null) throw invalidInput(`${name} is invalid`);
+	return result;
+}
+export { DropByError, createDropByServer, createIdentityProof, identityProofOptionsFromEnv };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dropby/server",
+  "version": "0.4.0",
+  "private": false,
+  "description": "DropBy for your backend: browser sessions, identity proofs and the server API for chat, ideas and asks.",
+  "keywords": [
+    "dropby",
+    "customer-support",
+    "chat",
+    "feedback",
+    "feature-requests",
+    "surveys",
+    "server",
+    "sdk"
+  ],
+  "license": "MIT",
+  "author": "Simpllyf Software",
+  "homepage": "https://dropby.chat",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "714b80e34a96081832e3c6e66ede69b925c9b851",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js"
+}