@dropby/server 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,882 @@
+/** DropBy's id for one of your products, `prj_…`. */
+type ProductId = `prj_${string}`;
+/**
+ * DropBy's id for one of your end users, `act_…`. Your own id for them is their
+ * `externalId`.
+ */
+type UserId = `act_${string}`;
+/**
+ * DropBy's id for one of your customer accounts, `acc_…`. Your own id for it is
+ * its `externalId`.
+ */
+type AccountId = `acc_${string}`;
+/** The id of someone on your team in DropBy, `adm_…`. */
+type TeamMemberId = `adm_${string}`;
+/** The id of an ask, `ask_…`. */
+type AskId = `ask_${string}`;
+/** The id of one user's response to an ask, `asr_…`. */
+type AskResponseId = `asr_${string}`;
+/** The id of a chat attachment, `att_…`. */
+type AttachmentId = `att_${string}`;
+/** The id of an idea, `idea_…`. */
+type IdeaId = `idea_${string}`;
+/** The id of a chat message, `msg_…`. */
+type MessageId = `msg_${string}`;
+/** DropBy's id for a browser key, `pkey_…`. It names the key; it is not the key. */
+type PublicKeyId = `pkey_${string}`;
+/** A browser session token, `dbs_…`, as `browserSessions.create` returns it. */
+type SessionToken = `dbs_${string}`;
+/** The id of a chat thread, `thr_…`. */
+type ThreadId = `thr_${string}`;
+/**
+ * Which of a product's two environments: `live` for your real users, `test` for
+ * trying things.
+ */
+type Environment = "live" | "test";
+/**
+ * A flat attribute or context value. Strings are at most 500 characters, lists at
+ * most 20 items.
+ */
+type AttributeValue = string | number | boolean | null | (string | number | boolean)[];
+/** Flat facts about a user or account, key to value. */
+type Attributes = Record<string, AttributeValue>;
+/**
+ * An end user of your product, as your backend knows them. Keys besides the
+ * named ones are facts about this session that ask and feature flag rules can
+ * target as `user.<key>`. `attributes` are saved on the user instead, for
+ * audiences.
+ */
+interface SessionUser {
+  id: string;
+  email?: string | undefined;
+  name?: string | undefined;
+  attributes?: Attributes | undefined;
+  [key: string]: AttributeValue | Attributes | undefined;
+}
+/**
+ * The customer account an end user belongs to. Keys besides the named ones are
+ * facts about this session that ask and feature flag rules can target as
+ * `account.<key>`. `attributes` are saved on the account instead, for audiences.
+ */
+interface SessionAccount {
+  id: string;
+  domain?: string | undefined;
+  name?: string | undefined;
+  attributes?: Attributes | undefined;
+  [key: string]: AttributeValue | Attributes | undefined;
+}
+/** A user in a response: `id` is DropBy's, `externalId` is the id you gave them. */
+interface UserReference {
+  id: UserId;
+  externalId: string;
+  name: string | null;
+  email: string | null;
+}
+/** An account in a response: `id` is DropBy's, `externalId` is the id you gave it. */
+interface AccountReference {
+  id: AccountId;
+  externalId: string;
+  name: string | null;
+  domain: string | null;
+}
+/** A page of a list. Pass `nextCursor` back as `cursor` for the next page; null on the last. */
+interface Page<Item> {
+  items: Item[];
+  nextCursor: string | null;
+}
+/** The context an end user had when they wrote, by namespace. */
+interface ContextSnapshot {
+  user: Attributes;
+  account: Attributes;
+  device: Attributes;
+  context: Attributes;
+}
+/** Who a browser session is for, as your backend knows them. */
+interface BrowserSessionInput {
+  /** The signed-in user, by your own id. */
+  user: SessionUser;
+  /** Omit for a user-only product: the session then has no account. */
+  account?: SessionAccount | undefined;
+}
+/** Return this to the browser: it is what `@dropby/browser`'s `auth` expects. */
+interface BrowserSession {
+  sessionToken: SessionToken;
+  expiresAt: string;
+}
+/**
+ * Where an ask is: `draft` while you write it, `active` once published (users can
+ * answer it between its `startsAt` and `expiresAt`), `closed` after you close it.
+ */
+type AskStatus = "draft" | "active" | "closed";
+/** Which asks a list returns: every one not archived, those in one status, or the archived. */
+type AskFilter = "all" | AskStatus | "archived";
+/** How a list of asks is ordered: last changed, newest first, or most responses. */
+type AskSort = "updated" | "newest" | "responses";
+/** How many asks each filter holds, for tabs or badges. */
+type AskCounts = Record<AskFilter, number>;
+/** A choice in a choice question. `optionId` defaults to `option_1`, `option_2`, … in order. */
+interface AskOptionInput {
+  /** Its id in the answers; lowercase snake case. */
+  optionId?: string | undefined;
+  /** The choice as the user reads it. */
+  label: string;
+}
+/**
+ * A question in an ask. `fieldId` and `optionId` are lowercase snake case and
+ * default to `field_1`, `field_2`, … and `option_1`, `option_2`, … in order.
+ */
+type AskFieldInput = {
+  /** The kind of question. */
+  type: "single_choice";
+  /** Its id in the answers; defaults to `field_1`, `field_2`, … in order. */
+  fieldId?: string | undefined;
+  /** The question as the user reads it. */
+  label: string;
+  /** Whether it must be answered to submit. */
+  required: boolean;
+  /** The choices, 2 to 10. */
+  options: AskOptionInput[];
+} | {
+  /** The kind of question. */
+  type: "multi_choice";
+  /** Its id in the answers; defaults to `field_1`, `field_2`, … in order. */
+  fieldId?: string | undefined;
+  /** The question as the user reads it. */
+  label: string;
+  /** Whether it must be answered to submit. */
+  required: boolean;
+  /** The choices, 2 to 10. */
+  options: AskOptionInput[];
+  /** How many choices can be picked, 1 to 10; all of them by default. */
+  maxSelections?: number | undefined;
+} | {
+  /** The kind of question. */
+  type: "short_text";
+  /** Its id in the answers; defaults to `field_1`, `field_2`, … in order. */
+  fieldId?: string | undefined;
+  /** The question as the user reads it. */
+  label: string;
+  /** Whether it must be answered to submit. */
+  required: boolean;
+  /** Hint text shown in the empty box. */
+  placeholder?: string | undefined;
+  /**
+   * The longest answer: up to 240 characters for short text, 2000 for long;
+   * the most allowed by default.
+   */
+  maxLength?: number | undefined;
+} | {
+  /** The kind of question. */
+  type: "long_text";
+  /** Its id in the answers; defaults to `field_1`, `field_2`, … in order. */
+  fieldId?: string | undefined;
+  /** The question as the user reads it. */
+  label: string;
+  /** Whether it must be answered to submit. */
+  required: boolean;
+  /** Hint text shown in the empty box. */
+  placeholder?: string | undefined;
+  /**
+   * The longest answer: up to 240 characters for short text, 2000 for long;
+   * the most allowed by default.
+   */
+  maxLength?: number | undefined;
+} | {
+  /** The kind of question. */
+  type: "rating";
+  /** Its id in the answers; defaults to `field_1`, `field_2`, … in order. */
+  fieldId?: string | undefined;
+  /** The question as the user reads it. */
+  label: string;
+  /** Whether it must be answered to submit. */
+  required: boolean;
+  /** The lowest rating, 0 or 1. */
+  min: 0 | 1;
+  /** The highest rating; always 10. */
+  max: 10;
+  /** What the lowest rating means, such as `not likely`. */
+  minLabel?: string | undefined;
+  /** What the highest rating means, such as `very likely`. */
+  maxLabel?: string | undefined;
+};
+/**
+ * Who an ask goes to, by your own ids. A user target without `accountId` matches
+ * the user in any account.
+ */
+type AskTarget = {
+  type: "user";
+  id: string;
+  accountId?: string | undefined;
+} | {
+  type: "account";
+  id: string;
+};
+/** How a targeting rule compares a field with its value. */
+type TargetingOperator = "eq" | "neq" | "in" | "exists" | "contains" | "gt" | "gte" | "lt" | "lte";
+/** `field` is `<user|account|device|context>.<key>`. */
+type TargetingRule = {
+  all: TargetingRule[];
+} | {
+  any: TargetingRule[];
+} | {
+  not: TargetingRule;
+} | {
+  field: string;
+  op: TargetingOperator;
+  value?: AttributeValue | AttributeValue[] | undefined;
+};
+/** An ask needs `targets`, a `targetingRule`, or both. */
+interface AskInput {
+  /** The ask's title, up to 180 characters. */
+  title: string;
+  /** The questions, 1 to 8. */
+  fields: AskFieldInput[];
+  /** Up to 50 users or accounts it goes to. */
+  targets?: AskTarget[] | undefined;
+  /** A rule on user, account, device and context facts; users it matches get the ask. */
+  targetingRule?: TargetingRule | undefined;
+  /** Whether the user can dismiss it without answering; true by default. */
+  dismissible?: boolean | undefined;
+  /** When it starts showing, as an ISO 8601 time; now when omitted or null. */
+  startsAt?: string | null | undefined;
+  /** When it stops showing, as an ISO 8601 time; never when omitted or null. */
+  expiresAt?: string | null | undefined;
+}
+/** A choice in a choice question, with its id filled in. */
+interface AskOption {
+  optionId: string;
+  label: string;
+}
+/** A question as the ask holds it: ids filled in, unset optional properties null. */
+type AskField = {
+  type: "single_choice";
+  fieldId: string;
+  label: string;
+  required: boolean;
+  options: AskOption[];
+} | {
+  type: "multi_choice";
+  fieldId: string;
+  label: string;
+  required: boolean;
+  options: AskOption[];
+  maxSelections: number;
+} | {
+  type: "short_text";
+  fieldId: string;
+  label: string;
+  required: boolean;
+  placeholder: string | null;
+  maxLength: number;
+} | {
+  type: "long_text";
+  fieldId: string;
+  label: string;
+  required: boolean;
+  placeholder: string | null;
+  maxLength: number;
+} | {
+  type: "rating";
+  fieldId: string;
+  label: string;
+  required: boolean;
+  min: 0 | 1;
+  max: 10;
+  minLabel: string | null;
+  maxLabel: string | null;
+};
+/** A question or survey you put to some of your users, with its counts. */
+interface Ask {
+  askId: AskId;
+  productId: ProductId;
+  env: Environment;
+  title: string;
+  status: AskStatus;
+  dismissible: boolean;
+  /** The questions; empty on a draft, whose questions are unfinished. */
+  fields: AskField[];
+  targetCount: number;
+  responseCount: number;
+  dismissedCount: number;
+  createdAt: string;
+  startsAt: string | null;
+  expiresAt: string | null;
+  updatedAt: string;
+  closedAt: string | null;
+  archivedAt: string | null;
+}
+/** A page of asks, with how many each filter holds. */
+interface AskPage extends Page<Ask> {
+  counts: AskCounts;
+}
+/** One answer in a response: the field it answers and its value. */
+interface AskAnswer {
+  fieldId: string;
+  /** Text, the chosen option ids, or a rating. */
+  value: string | string[] | number;
+}
+/** One user's answers to an ask, or their dismissal. */
+interface AskResponse {
+  responseId: AskResponseId;
+  askId: AskId;
+  productId: ProductId;
+  env: Environment;
+  kind: "answered" | "dismissed";
+  user: UserReference;
+  account: AccountReference | null;
+  answers: AskAnswer[];
+  /** The page context the user had when they answered. */
+  context: Attributes;
+  createdAt: string;
+}
+/** How many answers chose one option. */
+interface AskOptionCount {
+  optionId: string;
+  label: string;
+  count: number;
+}
+/** One user's written answer, from a text field's summary. */
+interface AskTextSample {
+  responseId: AskResponseId;
+  user: UserReference;
+  account: AccountReference | null;
+  value: string;
+  createdAt: string;
+}
+/** Every response to one field, summarised. */
+type AskFieldSummary = {
+  type: "single_choice";
+  fieldId: string;
+  label: string;
+  answerCount: number;
+  skippedCount: number;
+  options: AskOptionCount[];
+} | {
+  type: "multi_choice";
+  fieldId: string;
+  label: string;
+  answerCount: number;
+  skippedCount: number;
+  selectionCount: number;
+  options: AskOptionCount[];
+} | {
+  type: "rating";
+  fieldId: string;
+  label: string;
+  answerCount: number;
+  skippedCount: number;
+  average: number | null;
+  counts: {
+    value: number;
+    count: number;
+  }[];
+} | {
+  type: "short_text";
+  fieldId: string;
+  label: string;
+  answerCount: number;
+  skippedCount: number;
+  samples: AskTextSample[];
+} | {
+  type: "long_text";
+  fieldId: string;
+  label: string;
+  answerCount: number;
+  skippedCount: number;
+  samples: AskTextSample[];
+};
+/** An ask with every question's answers summarised. */
+interface AskDetail {
+  ask: Ask;
+  /** Every question's answers, summarised, in question order. */
+  fieldSummaries: AskFieldSummary[];
+}
+/**
+ * Where an idea is on your board. Only `open`, `planned`, `building` and `done`
+ * can be public; `duplicate` ones were merged into another.
+ */
+type IdeaStatus = "under_review" | "open" | "planned" | "building" | "done" | "not_planned" | "duplicate";
+/** Whether other users can see an idea on the public board. */
+type IdeaVisibility = "private" | "public";
+/** Which ideas a list returns: every one not archived, those in one status, or the archived. */
+type IdeaFilter = "all" | IdeaStatus | "archived";
+/** How a list of ideas is ordered: most votes, or newest first. */
+type IdeaSort = "votes" | "newest";
+/** How many ideas each filter holds, for tabs or badges. */
+type IdeaCounts = Record<IdeaFilter, number>;
+/** An idea a user posted, or your team created, with its vote count. */
+interface Idea {
+  ideaId: IdeaId;
+  productId: ProductId;
+  env: Environment;
+  status: IdeaStatus;
+  visibility: IdeaVisibility;
+  votingEnabled: boolean;
+  title: string;
+  description: string | null;
+  /** Your team's public reply, shown with the idea. */
+  teamResponse: {
+    text: string;
+    updatedAt: string;
+  } | null;
+  /** Set when the idea is a duplicate: the idea it was merged into. */
+  canonicalIdeaId: IdeaId | null;
+  voteCount: number;
+  /** How many ideas were merged directly into this one. */
+  duplicateCount: number;
+  /** Who posted it; null when your team created it. */
+  user: UserReference | null;
+  account: AccountReference | null;
+  createdAt: string;
+  updatedAt: string;
+  archivedAt: string | null;
+}
+/** A page of ideas, with how many each filter holds. */
+interface IdeaPage extends Page<Idea> {
+  counts: IdeaCounts;
+}
+/** A user who voted for an idea, and when. */
+interface IdeaVoter {
+  user: UserReference;
+  account: AccountReference | null;
+  votedAt: string;
+}
+/**
+ * An idea with what was first written, where it came from, its first voters and
+ * the ideas merged into it.
+ */
+interface IdeaDetail {
+  idea: Idea;
+  /** The chat thread the idea was created from. */
+  sourceThreadId: ThreadId | null;
+  /** The context the user had when they posted it. */
+  contextSnapshot: ContextSnapshot | null;
+  /** What was first written, kept through later edits. */
+  original: {
+    title: string;
+    description: string | null;
+  };
+  canonicalIdea: Idea | null;
+  /** Newest vote first; more through `listVoters`. */
+  voters: Page<IdeaVoter>;
+  /** The ideas merged into this one, oldest first; more through `listDuplicates`. */
+  duplicates: Page<Idea>;
+}
+/** A new idea created by your team. */
+interface IdeaInput {
+  /** Up to 180 characters. */
+  title: string;
+  /** Up to 5000 characters. */
+  description?: string | undefined;
+  /**
+   * `under_review` by default. A new idea starts private with voting off; `update`
+   * changes that.
+   */
+  status?: Exclude<IdeaStatus, "duplicate"> | undefined;
+  /** The chat thread the idea came from. */
+  sourceThreadId?: string | undefined;
+}
+/**
+ * Any of an idea's settings, applied together in a fixed order. An omitted field
+ * is unchanged; null clears `description` and `teamResponse`.
+ */
+interface IdeaUpdate {
+  /** Up to 180 characters. */
+  title?: string | undefined;
+  /** Up to 5000 characters; null removes it. */
+  description?: string | null | undefined;
+  /**
+   * Moves the idea. A status other than `open`, `planned`, `building` or `done`
+   * also makes it private and turns voting off.
+   */
+  status?: Exclude<IdeaStatus, "duplicate"> | undefined;
+  /** Whether other users can see it on the public board; `public` needs one of those statuses. */
+  visibility?: IdeaVisibility | undefined;
+  /** Whether users can vote on it; only a public idea can take votes. */
+  votingEnabled?: boolean | undefined;
+  /** Your team's public reply; null removes it. */
+  teamResponse?: {
+    text: string;
+  } | null | undefined;
+  /** Archives it, or brings it back; archived ideas leave the `all` list. */
+  archived?: boolean | undefined;
+}
+/**
+ * Where a conversation is: `open` waiting on your team, `replied` waiting on the
+ * user, `closed` done until a new message reopens it.
+ */
+type ChatThreadStatus = "open" | "replied" | "closed";
+/**
+ * Which conversations a list returns: every one, those in one status, or those
+ * with messages your team has not read.
+ */
+type ChatThreadFilter = "all" | "open" | "replied" | "closed" | "unread";
+/** How many conversations each filter holds, for tabs or badges. */
+type ChatThreadCounts = Record<ChatThreadFilter, number>;
+/** The file types a chat message can carry. */
+type ChatAttachmentContentType = "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "application/pdf" | "text/plain" | "text/csv";
+/** A file attached to a chat message. Download it with `chat.getAttachmentDownload`. */
+interface ChatAttachment {
+  attachmentId: AttachmentId;
+  fileName: string;
+  contentType: ChatAttachmentContentType;
+  byteSize: number;
+  kind: "image" | "file";
+}
+/** One message in a conversation, from the user, your team or DropBy itself. */
+interface ChatMessage {
+  messageId: MessageId;
+  threadId: ThreadId;
+  /** The message's position in its thread, from 1. */
+  sequence: number;
+  authorType: "user" | "team" | "system";
+  text: string;
+  /** The key the user's message was sent with; null on team and system messages. */
+  clientMessageId: string | null;
+  /** Who on your team wrote it; `id` is null for replies sent through the API. */
+  teamMember: {
+    id: TeamMemberId | null;
+    name: string | null;
+  } | null;
+  attachments: ChatAttachment[];
+  createdAt: string;
+}
+/** How far the user has read your team's replies. */
+interface ChatUserSeen {
+  lastSeenAt: string | null;
+  lastSeenTeamMessageId: MessageId | null;
+  unreadTeamMessageCount: number;
+}
+/** How far your team has read the user's messages. */
+interface ChatTeamSeen {
+  lastSeenAt: string | null;
+  lastSeenUserMessageId: MessageId | null;
+  unreadUserMessageCount: number;
+}
+/** A conversation. The same shape from every method; its messages page separately. */
+interface ChatThread {
+  threadId: ThreadId;
+  productId: ProductId;
+  env: Environment;
+  user: UserReference;
+  account: AccountReference | null;
+  status: ChatThreadStatus;
+  userSeen: ChatUserSeen;
+  teamSeen: ChatTeamSeen;
+  messageCount: number;
+  lastMessagePreview: string;
+  lastAuthorType: ChatMessage["authorType"];
+  createdAt: string;
+  updatedAt: string;
+}
+/** A page of conversations, with how many each filter holds. */
+interface ChatThreadPage extends Page<ChatThread> {
+  counts: ChatThreadCounts;
+}
+/** A conversation with its newest messages. */
+interface ChatThreadDetail {
+  thread: ChatThread;
+  /** The newest messages; pages run back from them, each oldest first. */
+  messages: Page<ChatMessage>;
+  /** The context the user had when they started the thread. */
+  contextSnapshot: ContextSnapshot | null;
+}
+/** A conversation your backend starts on a user's behalf, with its first message. */
+interface ChatThreadInput {
+  /** The user the conversation is with, by your own id. */
+  user: SessionUser;
+  /** The account the conversation belongs to. */
+  account?: SessionAccount | undefined;
+  /** The first message, as the user's, 1 to 5000 characters. */
+  message: {
+    text: string;
+  };
+}
+/** A reply from your team. */
+interface ChatReplyInput {
+  /** The reply, 1 to 5000 characters. */
+  text: string;
+  /** The name shown as the reply's author. */
+  authorName?: string | undefined;
+}
+/** `replied` is set by a reply; `open` reopens a replied or closed thread. */
+interface ChatThreadUpdate {
+  /** `closed` closes the conversation; `open` reopens it. */
+  status?: "open" | "closed" | undefined;
+}
+/**
+ * Who to resolve feature flags for. Flag rules on `context` or `device` see
+ * those fields as missing here.
+ */
+interface ConfigEvaluationInput {
+  /** Omit to evaluate without per-user overrides. */
+  user?: SessionUser | undefined;
+  /** Omit to evaluate without per-account overrides. */
+  account?: SessionAccount | undefined;
+}
+/**
+ * Every feature flag resolved for one user and account, and the configuration
+ * version it came from.
+ */
+interface EvaluatedConfig {
+  configVersion: number;
+  config: Record<string, string | number | boolean>;
+}
+/** Options for `createDropByServer`. */
+interface DropByServerOptions {
+  /** Your product's secret key, `sk_live_…` or `sk_test_…`. Never send it to a browser. */
+  secretKey: string;
+  /** The API origin. Defaults to `https://api.dropby.chat`. */
+  apiBaseUrl?: string | undefined;
+  /** A `fetch` to use instead of the global one. */
+  fetch?: typeof fetch | undefined;
+  /** How long one attempt may take, body included. Defaults to 30000. */
+  timeoutMs?: number | undefined;
+  /**
+   * How many times a failed call is tried again (0 to 10, default 2): after a
+   * network error, a timeout, a 408, a 429 or a 5xx. Every call is safe to repeat.
+   */
+  maxRetries?: number | undefined;
+}
+/**
+ * Pages take the `nextCursor` of the page before; a cursor is valid only with the
+ * same filter and sort. `limit` is 1 to 100, 50 by default.
+ */
+interface PageOptions {
+  /** How many items a page holds, 1 to 100; 50 by default. */
+  limit?: number | undefined;
+  /** The `nextCursor` of the page before; omit for the first page. */
+  cursor?: string | undefined;
+}
+/** Which page of asks to list, filtered and sorted. */
+interface ListAsksOptions extends PageOptions {
+  /** Which asks: `all` by default. */
+  filter?: AskFilter | undefined;
+  /** Their order: `updated` by default. */
+  sort?: AskSort | undefined;
+}
+/** Which page of ideas to list, filtered and sorted. */
+interface ListIdeasOptions extends PageOptions {
+  /** Which ideas: `all` by default. */
+  filter?: IdeaFilter | undefined;
+  /** Their order: `votes` by default. */
+  sort?: IdeaSort | undefined;
+}
+/** Which page of conversations to list, filtered. */
+interface ListChatThreadsOptions extends PageOptions {
+  /** Which conversations: `all` by default. */
+  filter?: ChatThreadFilter | undefined;
+}
+/**
+ * For a create or reply: a repeat with the same key returns the original instead
+ * of posting again.
+ */
+interface WriteOptions {
+  /**
+   * 1 to 128 visible ASCII characters, such as a UUID. One is generated for each
+   * call when none is given; pass your own when you retry a whole call yourself.
+   */
+  idempotencyKey?: string | undefined;
+}
+/** Browser sessions, minted by your backend for the users it has signed in. */
+interface DropByBrowserSessionsClient {
+  /** Mints a short-lived browser session for a user your backend has authenticated. */
+  create(input: BrowserSessionInput): Promise<{
+    session: BrowserSession;
+  }>;
+}
+/** Asks: questions and surveys you put to your users, and their answers. */
+interface DropByAsksClient {
+  /** Creates an ask for the users it targets. */
+  create(input: AskInput, options?: WriteOptions): Promise<{
+    ask: Ask;
+  }>;
+  /** A page of asks, with how many each filter holds. */
+  list(options?: ListAsksOptions): Promise<AskPage>;
+  /** The ask with every question's answers summarised. */
+  get(askId: string): Promise<AskDetail>;
+  /** Newest first. */
+  listResponses(askId: string, options?: PageOptions): Promise<Page<AskResponse>>;
+}
+/** Ideas: your users' feature requests, their votes, and your team's replies. */
+interface DropByIdeasClient {
+  /** A page of ideas, with how many each filter holds. */
+  list(options?: ListIdeasOptions): Promise<IdeaPage>;
+  /** The idea with its first page of voters and of duplicates. */
+  get(ideaId: string): Promise<IdeaDetail>;
+  /** Newest vote first. */
+  listVoters(ideaId: string, options?: PageOptions): Promise<Page<IdeaVoter>>;
+  /** The ideas merged into this one, oldest first. */
+  listDuplicates(ideaId: string, options?: PageOptions): Promise<Page<Idea>>;
+  /** Creates an idea as your team. */
+  create(input: IdeaInput, options?: WriteOptions): Promise<{
+    idea: Idea;
+  }>;
+  /** Changes any of the idea's settings in one step; repeating it changes nothing. */
+  update(ideaId: string, changes: IdeaUpdate): Promise<{
+    idea: Idea;
+  }>;
+  /**
+   * Marks `ideaId` a duplicate of `canonicalIdeaId`; returns both. Repeating it
+   * changes nothing.
+   */
+  merge(ideaId: string, input: {
+    canonicalIdeaId: string;
+  }): Promise<{
+    idea: Idea;
+    canonicalIdea: Idea;
+  }>;
+}
+/** Support chat: conversations with your users, and your team's replies. */
+interface DropByChatClient {
+  /** A page of conversations, with how many each filter holds. */
+  list(options?: ListChatThreadsOptions): Promise<ChatThreadPage>;
+  /** The thread with its newest messages. */
+  get(threadId: string): Promise<ChatThreadDetail>;
+  /** Pages run from the newest messages back; each page reads oldest first. */
+  listMessages(threadId: string, options?: PageOptions): Promise<Page<ChatMessage>>;
+  /** Starts a conversation on behalf of a user. */
+  create(input: ChatThreadInput, options?: WriteOptions): Promise<{
+    thread: ChatThread;
+    message: ChatMessage;
+  }>;
+  /** Replies as your team. */
+  reply(threadId: string, input: ChatReplyInput, options?: WriteOptions): Promise<{
+    thread: ChatThread;
+    message: ChatMessage;
+  }>;
+  /** Closes a conversation, or opens it again. */
+  update(threadId: string, changes: ChatThreadUpdate): Promise<{
+    thread: ChatThread;
+  }>;
+  /** A short-lived download link for a message attachment. */
+  getAttachmentDownload(attachmentId: string): Promise<{
+    download: {
+      url: string;
+      expiresAt: string;
+    };
+  }>;
+}
+/** Feature flags, resolved on your server. */
+interface DropByConfigClient {
+  /** Resolves every feature flag for a user and account. */
+  evaluate(input: ConfigEvaluationInput): Promise<EvaluatedConfig>;
+}
+/**
+ * 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.
+ */
+interface DropByServer {
+  /** Asks: questions and surveys, and their answers. */
+  readonly asks: DropByAsksClient;
+  /** Browser sessions for the users your backend has signed in. */
+  readonly browserSessions: DropByBrowserSessionsClient;
+  /** Support chat: conversations and your team's replies. */
+  readonly chat: DropByChatClient;
+  /** Feature flags, resolved on your server. */
+  readonly config: DropByConfigClient;
+  /** Ideas: feature requests, votes and your team's replies. */
+  readonly ideas: DropByIdeasClient;
+}
+/** A client for your backend, holding your secret key. Never send it to a browser. */
+export declare function createDropByServer(options: DropByServerOptions): DropByServer;
+/**
+ * What went wrong, to branch on: the API's codes, and those the client raises
+ * itself (`invalid_input`, `network_error`, `timeout`, `invalid_response`,
+ * `request_failed`). Open to codes the API adds.
+ */
+type DropByErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "idea_archived" | "idea_merged" | "idempotency_key_reused" | "rate_limited" | "unavailable" | "internal_error" | "request_failed" | "invalid_input" | "network_error" | "timeout" | "invalid_response" | (string & {});
+/** What a `DropByError` carries besides its code and message. */
+interface DropByErrorOptions {
+  /** The HTTP status; undefined when no response arrived. */
+  status?: number | undefined;
+  /** The seconds the API asked to wait before retrying, when it said. */
+  retryAfter?: number | undefined;
+  /** The error underneath, such as the failed `fetch`. */
+  cause?: unknown;
+}
+/**
+ * Every error the client throws. Branch on `code`; `status` is the HTTP status
+ * when a response arrived, and `retryAfter` the wait the API asked for.
+ */
+export declare class DropByError extends Error {
+  /** Always `"DropByError"`. */
+  readonly name = "DropByError";
+  /** What went wrong, to branch on. */
+  readonly code: DropByErrorCode;
+  /** The HTTP status; undefined when no response arrived. */
+  readonly status: number | undefined;
+  /** The seconds the API asked to wait before retrying, when it said. */
+  readonly retryAfter: number | undefined;
+  constructor(code: DropByErrorCode, message: string, options?: DropByErrorOptions);
+}
+/**
+ * The user an identity proof vouches for. Only these fields go into the proof,
+ * which the browser can read.
+ */
+interface IdentityProofUser {
+  /** Your own id for the user, 1 to 256 characters. */
+  id: string;
+  /** Shown to your team. */
+  name?: string | undefined;
+  /** Shown to your team. */
+  email?: string | undefined;
+  /** Saved on the user, for audiences. */
+  attributes?: Attributes | undefined;
+}
+/**
+ * The account an identity proof vouches for. Only these fields go into the
+ * proof, which the browser can read.
+ */
+interface IdentityProofAccount {
+  /** Your own id for the account, 1 to 256 characters. */
+  id: string;
+  /** Shown to your team. */
+  name?: string | undefined;
+  /** The account's web domain. */
+  domain?: string | undefined;
+  /** Saved on the account, for audiences. */
+  attributes?: Attributes | undefined;
+}
+/**
+ * What `createIdentityProof` signs: the browser key it is for, the environment,
+ * and who the user is. `secret` is the browser key's identity secret; keep it on
+ * your server.
+ */
+interface CreateIdentityProofOptions {
+  /** The browser key's identity secret, 64 lowercase hex characters, from the dashboard. */
+  secret: string;
+  /** `prj_…`, as the dashboard lists it. */
+  productId: string;
+  /** `pkey_…`, the browser key the proof is for. */
+  publicKeyId: string;
+  /** The environment the browser key belongs to. */
+  env: Environment;
+  /** Who the proof vouches for. */
+  user: IdentityProofUser;
+  /** Omit for a user-only product: the session then has no account. */
+  account?: IdentityProofAccount | undefined;
+  /** 1 to 900 seconds; defaults to 900. */
+  ttlSeconds?: number | undefined;
+}
+/**
+ * Signs the identity of an end user your backend has authenticated, for your
+ * session endpoint to return to the browser. Never expose the secret.
+ */
+export declare function createIdentityProof(options: CreateIdentityProofOptions): Promise<string>;
+/** The environment variables `identityProofOptionsFromEnv` reads. */
+type IdentityProofEnvVariable = "DROPBY_PRODUCT_ID" | "DROPBY_PUBLIC_KEY_ID" | "DROPBY_ENV" | "DROPBY_IDENTITY_SECRET";
+/**
+ * The identity proof settings read from the environment, ready to spread into
+ * `createIdentityProof`.
+ */
+type IdentityProofEnvOptions = Pick<CreateIdentityProofOptions, "secret" | "productId" | "publicKeyId" | "env">;
+/**
+ * Reads the identity proof settings the dashboard lists: `DROPBY_PRODUCT_ID`,
+ * `DROPBY_PUBLIC_KEY_ID`, `DROPBY_ENV` and `DROPBY_IDENTITY_SECRET`. Pass
+ * `process.env`, or a Workers `env`. Throws naming the first missing or invalid
+ * variable; the message never includes a value, since one is the secret.
+ */
+export declare function identityProofOptionsFromEnv(vars: Readonly<Partial<Record<IdentityProofEnvVariable, unknown>>>): IdentityProofEnvOptions;
+export type { AccountId, AccountReference, Ask, AskAnswer, AskCounts, AskDetail, AskField, AskFieldInput, AskFieldSummary, AskFilter, AskId, AskInput, AskOption, AskOptionCount, AskOptionInput, AskPage, AskResponse, AskResponseId, AskSort, AskStatus, AskTarget, AskTextSample, AttachmentId, AttributeValue, Attributes, BrowserSession, BrowserSessionInput, ChatAttachment, ChatAttachmentContentType, ChatMessage, ChatReplyInput, ChatTeamSeen, ChatThread, ChatThreadCounts, ChatThreadDetail, ChatThreadFilter, ChatThreadInput, ChatThreadPage, ChatThreadStatus, ChatThreadUpdate, ChatUserSeen, ConfigEvaluationInput, ContextSnapshot, CreateIdentityProofOptions, DropByErrorCode, DropByErrorOptions, DropByServer, DropByServerOptions, Environment, EvaluatedConfig, Idea, IdeaCounts, IdeaDetail, IdeaFilter, IdeaId, IdeaInput, IdeaPage, IdeaSort, IdeaStatus, IdeaUpdate, IdeaVisibility, IdeaVoter, IdentityProofAccount, IdentityProofEnvOptions, IdentityProofEnvVariable, IdentityProofUser, ListAsksOptions, ListChatThreadsOptions, ListIdeasOptions, MessageId, Page, PageOptions, ProductId, PublicKeyId, SessionAccount, SessionToken, SessionUser, TargetingOperator, TargetingRule, TeamMemberId, ThreadId, UserId, UserReference, WriteOptions };