@dropby/server 0.4.0 → 0.5.0

package/README.md

@@ -94,6 +94,28 @@ workflows. Ids are plain strings: one in a URL path is checked before anything i
 sent (`invalid_input`), and one in a request body is checked by the API (a 400
 naming the field).
 
+## Asks, chat and ideas
+
+Ask a user a question, reply to their conversation, or tell them an idea is planned:
+
+<!-- snippet: import type { DropByServer } from "@dropby/server"; declare const dropby: DropByServer; declare const threadId: string; declare const ideaId: string; -->
+
+```ts
+await dropby.asks.create({
+  title: "how's the new inbox?",
+  fields: [{ type: "long_text", label: "what would make it better?", required: true }],
+  targets: [{ type: "user", id: "user_123" }],
+});
+
+await dropby.chat.reply(threadId, { text: "fixed in today's release" });
+
+await dropby.ideas.update(ideaId, { status: "planned", teamResponse: { text: "on the roadmap" } });
+```
+
+The ask shows in that user's widget, or wherever your own UI lists pending asks.
+Creating one needs a secret key with `ask:create`, replying `chat:write`, and
+updating an idea `ideas:write`.
+
 ## Feature flags
 
 `config.evaluate` resolves every flag for a user and account, as the browser
@@ -123,7 +145,9 @@ Every call retries by itself after a network error, a timeout, a 408, a 429 or
 a 5xx: twice by default, waiting up to half a second, then up to a second (set
 `maxRetries`, 0 to 10). A `Retry-After` of up to 10 seconds is waited out; a
 longer one ends the call at once, and the error's `retryAfter` says how long the
-API asked for. `timeoutMs` (30 seconds by default) bounds each attempt.
+API asked for. `timeoutMs` (30 seconds by default) bounds each attempt. When a
+call still fails, the error's `retryable` says whether the same call is worth
+trying again later, such as from a job queue.
 
 Retrying is safe for every call. Updates and merges change nothing when
 repeated (though an update retried after a lost answer can overwrite a change
@@ -168,8 +192,8 @@ import { DropByError } from "@dropby/server";
 try {
   await dropby.chat.reply(threadId, { text });
 } catch (error) {
-  if (error instanceof DropByError && error.code === "rate_limited") {
-    // error.retryAfter says how long the API asked to wait
+  if (error instanceof DropByError && error.retryable) {
+    // worth another try later; error.retryAfter says how long the API asked to wait
   }
   throw error;
 }
@@ -180,12 +204,15 @@ API codes are `bad_request`, `unauthorized`, `forbidden`, `not_found`,
 `rate_limited`, `unavailable` and `internal_error`; the API may add more. The
 client adds `invalid_input` (a bad argument or option, raised before anything
 is sent), `network_error`, `timeout` (30 seconds per attempt by default;
-set `timeoutMs`), `invalid_response` and `request_failed` (an error response without
-a DropBy error body). No message includes your keys.
-
-Responses are returned as the API sends them. New fields and values can appear
-as the API grows, so treat enums such as a status as open and keep a default
-branch when you switch over one.
+set `timeoutMs`), `invalid_response` (a success that is not JSON, or lacks what
+the method returns: usually an `apiBaseUrl` that is not DropBy's) and
+`request_failed` (an error response without a DropBy error body). `retryable` is
+true for `network_error`, `timeout`, and a 408, 429 or 5xx. No message includes
+your keys.
+
+Responses are returned as the API sends them, once they carry what the method
+returns. New fields and values can appear as the API grows, so treat enums such
+as a status as open and keep a default branch when you switch over one.
 
 ## Identity proofs
 

package/dist/index.d.ts

@@ -48,7 +48,15 @@ type Attributes = Record<string, AttributeValue>;
  */
 interface SessionUser {
   id: string;
+  /**
+   * Shown to your team in the dropby dashboard. Empty or blank means no email, and
+   * then the one DropBy already has is kept; any other value must be an email address.
+   */
   email?: string | undefined;
+  /**
+   * Shown to your team in the dropby dashboard. Trimmed and cut at 500 characters;
+   * empty or blank means no name, and then the name DropBy already has is kept.
+   */
   name?: string | undefined;
   attributes?: Attributes | undefined;
   [key: string]: AttributeValue | Attributes | undefined;
@@ -61,6 +69,10 @@ interface SessionUser {
 interface SessionAccount {
   id: string;
   domain?: string | undefined;
+  /**
+   * Shown to your team in the dropby dashboard. Trimmed and cut at 500 characters;
+   * empty or blank means no name, and then the name DropBy already has is kept.
+   */
   name?: string | undefined;
   attributes?: Attributes | undefined;
   [key: string]: AttributeValue | Attributes | undefined;
@@ -765,7 +777,9 @@ interface DropByConfigClient {
 /**
  * A client for DropBy's server API, from `createDropByServer`. Calls retry network
  * errors, timeouts, 408, 429 and 5xx up to `maxRetries` times, and reject with a
- * `DropByError`; a `Retry-After` over 10 seconds rejects at once.
+ * `DropByError`; a `Retry-After` over 10 seconds rejects at once. A success that
+ * lacks what its method returns rejects as `invalid_response`, usually an
+ * `apiBaseUrl` that is not DropBy's.
  */
 interface DropByServer {
   /** Asks: questions and surveys, and their answers. */
@@ -809,6 +823,13 @@ export declare class DropByError extends Error {
   readonly status: number | undefined;
   /** The seconds the API asked to wait before retrying, when it said. */
   readonly retryAfter: number | undefined;
+  /**
+   * Whether this kind of failure is worth trying again: no response arrived, or the
+   * status was 408, 429 or 5xx. By the time it reaches you the client has done any
+   * retrying it will do, so true means try later, such as from a queue, and not
+   * before `retryAfter` when it is set.
+   */
+  get retryable(): boolean;
   constructor(code: DropByErrorCode, message: string, options?: DropByErrorOptions);
 }
 /**
@@ -818,9 +839,15 @@ export declare class DropByError extends Error {
 interface IdentityProofUser {
   /** Your own id for the user, 1 to 256 characters. */
   id: string;
-  /** Shown to your team. */
+  /**
+   * Shown to your team in the dropby dashboard. Trimmed and cut at 500 characters;
+   * empty or blank means no name, and then the name DropBy already has is kept.
+   */
   name?: string | undefined;
-  /** Shown to your team. */
+  /**
+   * Shown to your team in the dropby dashboard. Empty or blank means no email, and
+   * then the one DropBy already has is kept; any other value must be an email address.
+   */
   email?: string | undefined;
   /** Saved on the user, for audiences. */
   attributes?: Attributes | undefined;
@@ -832,7 +859,10 @@ interface IdentityProofUser {
 interface IdentityProofAccount {
   /** Your own id for the account, 1 to 256 characters. */
   id: string;
-  /** Shown to your team. */
+  /**
+   * Shown to your team in the dropby dashboard. Trimmed and cut at 500 characters;
+   * empty or blank means no name, and then the name DropBy already has is kept.
+   */
   name?: string | undefined;
   /** The account's web domain. */
   domain?: string | undefined;

package/dist/index.js

@@ -3,6 +3,9 @@ var DropByError = class extends Error {
 	code;
 	status;
 	retryAfter;
+	get retryable() {
+		return retryable(this);
+	}
 	constructor(code, message, options = {}) {
 		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
 		this.code = code;
@@ -10,6 +13,10 @@ var DropByError = class extends Error {
 		this.retryAfter = options.retryAfter;
 	}
 };
+function retryable(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 invalidInput(message) {
 	return new DropByError("invalid_input", message);
 }
@@ -30,6 +37,58 @@ function retryAfter(response) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
+const replies = {
+	"asks.create": { ask: "object" },
+	"asks.list": { items: "list" },
+	"asks.get": { ask: "object" },
+	"asks.listResponses": { items: "list" },
+	"browserSessions.create": { session: "object" },
+	"chat.list": { items: "list" },
+	"chat.get": { thread: "object" },
+	"chat.listMessages": { items: "list" },
+	"chat.create": {
+		thread: "object",
+		message: "object"
+	},
+	"chat.reply": {
+		thread: "object",
+		message: "object"
+	},
+	"chat.update": { thread: "object" },
+	"chat.getAttachmentDownload": { download: "object" },
+	"config.evaluate": { config: "object" },
+	"ideas.list": { items: "list" },
+	"ideas.get": { idea: "object" },
+	"ideas.listVoters": { items: "list" },
+	"ideas.listDuplicates": { items: "list" },
+	"ideas.create": { idea: "object" },
+	"ideas.update": { idea: "object" },
+	"ideas.merge": {
+		idea: "object",
+		canonicalIdea: "object"
+	}
+};
+const isoDateTime = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+function checkedReply(name, body, status) {
+	if (!isObject(body)) throw refused(name, "is not a JSON object", status);
+	for (const [field, kind] of Object.entries(replies[name])) {
+		const value = body[field];
+		if (kind === "list" ? !Array.isArray(value) : !isObject(value)) throw refused(name, `has no ${field} ${kind}`, status);
+	}
+	if (name === "browserSessions.create") checkSession(body.session, status);
+	return body;
+}
+function checkSession(session, status) {
+	const { sessionToken, expiresAt } = isObject(session) ? session : {};
+	if (typeof sessionToken !== "string" || !sessionToken.startsWith("dbs_")) throw refused("browserSessions.create", "has no session.sessionToken", status);
+	if (typeof expiresAt !== "string" || !isoDateTime.test(expiresAt) || Number.isNaN(Date.parse(expiresAt))) throw refused("browserSessions.create", "has no session.expiresAt date-time", status);
+}
+function refused(name, problem, status) {
+	return new DropByError("invalid_response", `${name}: DropBy's reply ${problem}`, { status });
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 const defaultApiBaseUrl = "https://api.dropby.chat";
 const defaultTimeoutMs = 3e4;
 const defaultMaxRetries = 2;
@@ -59,89 +118,89 @@ var Server = class {
 		this.#maxRetries = retries(options.maxRetries ?? defaultMaxRetries);
 		this.#cache = acceptsCacheOption();
 		this.asks = {
-			create: async (input, options = {}) => this.#send("POST", "/v1/asks", {
+			create: async (input, options = {}) => this.#send("asks.create", "POST", "/v1/asks", {
 				body: input,
 				key: options.idempotencyKey,
 				keyed: true
 			}),
-			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("GET", "/v1/asks", { query: {
+			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("asks.list", "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: {
+			get: async (askId) => this.#send("asks.get", "GET", `/v1/asks/${pathId(askId, "ask_")}`),
+			listResponses: async (askId, { limit, cursor } = {}) => this.#send("asks.listResponses", "GET", `/v1/asks/${pathId(askId, "ask_")}/responses`, { query: {
 				limit,
 				cursor
 			} })
 		};
-		this.browserSessions = { create: async (input) => this.#send("POST", "/v1/browser-sessions", { body: input }) };
+		this.browserSessions = { create: async (input) => this.#send("browserSessions.create", "POST", "/v1/browser-sessions", { body: input }) };
 		this.chat = {
-			list: async ({ filter, limit, cursor } = {}) => this.#send("GET", "/v1/chat/threads", { query: {
+			list: async ({ filter, limit, cursor } = {}) => this.#send("chat.list", "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: {
+			get: async (threadId) => this.#send("chat.get", "GET", `/v1/chat/threads/${pathId(threadId, "thr_")}`),
+			listMessages: async (threadId, { limit, cursor } = {}) => this.#send("chat.listMessages", "GET", `/v1/chat/threads/${pathId(threadId, "thr_")}/messages`, { query: {
 				limit,
 				cursor
 			} }),
-			create: async (input, options = {}) => this.#send("POST", "/v1/chat/threads", {
+			create: async (input, options = {}) => this.#send("chat.create", "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`, {
+			reply: async (threadId, input, options = {}) => this.#send("chat.reply", "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`)
+			update: async (threadId, changes) => this.#send("chat.update", "PATCH", `/v1/chat/threads/${pathId(threadId, "thr_")}`, { body: changes }),
+			getAttachmentDownload: async (attachmentId) => this.#send("chat.getAttachmentDownload", "GET", `/v1/chat/attachments/${pathId(attachmentId, "att_")}/download`)
 		};
-		this.config = { evaluate: async (input) => this.#send("POST", "/v1/config/evaluate", { body: input }) };
+		this.config = { evaluate: async (input) => this.#send("config.evaluate", "POST", "/v1/config/evaluate", { body: input }) };
 		this.ideas = {
-			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("GET", "/v1/ideas", { query: {
+			list: async ({ filter, sort, limit, cursor } = {}) => this.#send("ideas.list", "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: {
+			get: async (ideaId) => this.#send("ideas.get", "GET", `/v1/ideas/${pathId(ideaId, "idea_")}`),
+			listVoters: async (ideaId, { limit, cursor } = {}) => this.#send("ideas.listVoters", "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: {
+			listDuplicates: async (ideaId, { limit, cursor } = {}) => this.#send("ideas.listDuplicates", "GET", `/v1/ideas/${pathId(ideaId, "idea_")}/duplicates`, { query: {
 				limit,
 				cursor
 			} }),
-			create: async (input, options = {}) => this.#send("POST", "/v1/ideas", {
+			create: async (input, options = {}) => this.#send("ideas.create", "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 })
+			update: async (ideaId, changes) => this.#send("ideas.update", "PATCH", `/v1/ideas/${pathId(ideaId, "idea_")}`, { body: changes }),
+			merge: async (ideaId, input) => this.#send("ideas.merge", "POST", `/v1/ideas/${pathId(ideaId, "idea_")}/merge`, { body: input })
 		};
 	}
-	async #send(method, path, options = {}) {
+	async #send(name, 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);
+			return await this.#attempt(name, method, url, payload, sentKey);
 		} catch (error) {
-			if (!(error instanceof DropByError) || !transient(error) || attempt >= this.#maxRetries) throw error;
+			if (!(error instanceof DropByError) || !retryable(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) {
+	async #attempt(name, method, url, payload, key) {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
 		try {
@@ -159,11 +218,13 @@ var Server = class {
 			});
 			if (!response.ok) throw await apiError(response);
 			const text = await response.text();
+			let body;
 			try {
-				return JSON.parse(text);
+				body = JSON.parse(text);
 			} catch {
-				throw new DropByError("invalid_response", `DropBy answered ${response.status} with a body that is not JSON`, { status: response.status });
+				throw new DropByError("invalid_response", `${name}: DropBy answered ${response.status} with a body that is not JSON`, { status: response.status });
 			}
+			return checkedReply(name, body, 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;
@@ -176,10 +237,6 @@ var Server = class {
 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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dropby/server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "DropBy for your backend: browser sessions, identity proofs and the server API for chat, ideas and asks.",
   "keywords": [
@@ -34,7 +34,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "714b80e34a96081832e3c6e66ede69b925c9b851",
+  "gitHead": "e08819c87c99727dbd8f8e6c3c697985c69c4d12",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js"
 }