@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/api.ts

@@ -0,0 +1,531 @@
+/**
+ * The comment service's HTTP API: wire types and request functions. DOM-free, so native clients
+ * (`@devaccel-labs/app-comments-native`) share it; `./client.ts` re-exports it with the browser-only sign-in
+ * relay and storage helpers.
+ */
+import type { Anchor } from "../core/index.js";
+import { APP_ORIGIN_HEADER } from "../native-wire.js";
+import type { ClarityDraft, ClarityMode } from "./clarity-model.js";
+import type { ReportKind } from "./kind-model.js";
+import { readJwt, type Session } from "./session-source.js";
+import type { TicketDraft, TicketForm } from "./ticket-form-model.js";
+export type Mentioned = { id: string; name: string };
+
+/** Where a page screenshot was taken. */
+export type Capture = {
+  url: string;
+  viewport?: { width: number; height: number };
+  browser?: string;
+};
+export type Attachment = {
+  id: string;
+  name: string;
+  contentType: string;
+  size: number;
+  url: string;
+  capture?: Capture;
+};
+
+/** An earlier version of a message. `createdAt` is when that version was written. */
+export type Revision = { body: string; mentions?: Mentioned[]; createdAt: string };
+
+export type CommentMessage = {
+  id: string;
+  body: string;
+  author: string;
+  /** Missing on messages written before author ids were stored. */
+  authorId?: string | null;
+  createdAt: string;
+  editedAt?: string | null;
+  mentions?: Mentioned[];
+  attachments?: Attachment[];
+  /** Earlier versions, oldest first. The current body is the version after the last one. */
+  revisions?: Revision[];
+};
+
+export type Member = { id: string; name: string; email: string };
+
+export type Delivery = {
+  emailed: Mentioned[];
+  skipped: Array<Mentioned & { reason: "rate_limited" | "muted" | "disabled" | string }>;
+};
+
+export type Profile = { name: string; email: string | null; mentionEmails: boolean };
+
+export type PostExtras = {
+  mentions?: string[];
+  screenshot?: string | null;
+  attachments?: string[];
+};
+
+export type FieldDef = { id: string; label: string };
+export type FieldValue = FieldDef & { value: string };
+export type Settings = {
+  roles: { enabled: boolean; options: string[] };
+  fields: { enabled: boolean; items: FieldDef[] };
+};
+/** Role and custom field values for a new or edited comment, keyed by field id. */
+export type Details = { role: string | null; fields: Record<string, string> };
+
+export type Thread = {
+  id: string;
+  /** The environment the comment was left in. Differs from the session's for comments from a linked environment. */
+  environment?: string;
+  route: string;
+  /** The page the comment was left on, including query and hash. */
+  url: string;
+  role: string | null;
+  fields: FieldValue[];
+  anchor: Anchor;
+  status: "open" | "resolved";
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  messages: CommentMessage[];
+  /** Set when the team turned this comment into a ticket in their tracker. */
+  ticket?: TicketBadge;
+};
+
+/** A comment's support ticket, as the commenter sees it: number and status only. */
+export type TicketBadge = { number: string; status: string; label: string };
+
+type ErrorBody = { error?: { code?: string; message?: string } };
+
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function storageKey(session: Pick<Session, "apiUrl" | "project" | "environment">) {
+  return `devaccel.comment.${session.apiUrl}.${session.project}.${session.environment}`;
+}
+
+/**
+ * Where a client keeps its member token, keyed by `storageKey(session)`. The web toolbar keeps it in the page's
+ * `localStorage` itself; native clients pass the device keychain.
+ */
+export type MemberTokenStore = {
+  read(key: string): Promise<string | null>;
+  write(key: string, token: string): Promise<void>;
+  remove(key: string): Promise<void>;
+};
+
+/** The stored member token for `session`, or null when there is none or it has expired. */
+export async function readMemberToken(
+  session: Pick<Session, "apiUrl" | "project" | "environment">,
+  store: MemberTokenStore,
+) {
+  const token = await store.read(storageKey(session));
+  return token && memberIsCurrent(token) ? token : null;
+}
+
+export function memberIsCurrent(token: string) {
+  const claims = readJwt(token);
+  if (!claims || claims.typ !== "member" || !claims.name || !claims.email) return false;
+  return (claims.exp ?? 0) * 1000 > Date.now() + 5_000;
+}
+
+/** A native client's app origin header (`x-comment-service-origin`). Empty for web, where the browser sends `Origin`. */
+function originHeaders(session: Pick<Session, "clientOrigin">): Record<string, string> {
+  return session.clientOrigin ? { [APP_ORIGIN_HEADER]: session.clientOrigin } : {};
+}
+
+async function request<T>(
+  session: Session,
+  url: string,
+  token: string,
+  init?: RequestInit,
+): Promise<T> {
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${token}`,
+      ...originHeaders(session),
+      ...(init?.body ? { "content-type": "application/json" } : {}),
+      ...(init?.headers ?? {}),
+    },
+  });
+  const payload = (await response.json().catch(() => null)) as (T & ErrorBody) | null;
+  if (!response.ok) {
+    throw new ApiError(
+      response.status,
+      payload?.error?.code ?? "request_failed",
+      payload?.error?.message ?? "Request failed.",
+    );
+  }
+  return payload as T;
+}
+
+/**
+ * How people can sign in here: through the service's identity connection, or not at all. Passphrase sign-in is
+ * gone. The wire keeps the connection under `msf`, its name from before.
+ */
+export type SignInOptions = {
+  passphrase: false;
+  /** `label` names the account to sign in with; "your account" when the service names none. */
+  msf: { authorizeUrl: string; label: string } | null;
+  /** The options request failed. */
+  unavailable?: boolean;
+  /** The status it failed with, when the service answered. */
+  status?: number;
+};
+
+export async function signInOptions(session: Session): Promise<SignInOptions> {
+  try {
+    const response = await fetch(`${session.apiUrl}/v1/auth/options`, {
+      headers: { authorization: `Bearer ${session.hostToken}`, ...originHeaders(session) },
+    });
+    if (!response.ok)
+      return { passphrase: false, msf: null, unavailable: true, status: response.status };
+    const payload = (await response.json()) as Partial<SignInOptions>;
+    const msf = payload.msf && typeof payload.msf.authorizeUrl === "string" ? payload.msf : null;
+    return {
+      passphrase: false,
+      msf: msf ? { authorizeUrl: msf.authorizeUrl, label: msf.label || "your account" } : null,
+    };
+  } catch {
+    return { passphrase: false, msf: null, unavailable: true };
+  }
+}
+
+/** Base64url without padding, as OAuth PKCE wants for the state, verifier and challenge. */
+export function base64Url(bytes: Uint8Array) {
+  return btoa(String.fromCharCode(...bytes))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+/**
+ * The identity connection's authorize URL for an OAuth 2.0 request with PKCE (S256). The sign-in callback sends the code
+ * back to `returnTo` (a page of this app, without a hash, or a native app's `<scheme>://app/app-comments/auth`).
+ */
+export function msfAuthorizeUrl(
+  authorizeUrl: string,
+  returnTo: string,
+  state: string,
+  challenge: string,
+) {
+  const url = new URL(authorizeUrl);
+  const redirect = url.searchParams.get("redirect_uri");
+  if (redirect) {
+    const back = new URL(redirect);
+    back.searchParams.set("return", returnTo);
+    url.searchParams.set("redirect_uri", back.toString());
+  }
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+/** Trades the authorization code for a member token. */
+export async function finishMsfSignIn(
+  session: Session,
+  input: { state: string; verifier: string; code: string },
+) {
+  const response = await fetch(`${session.apiUrl}/v1/auth/msf`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${session.hostToken}`,
+      "content-type": "application/json",
+      ...originHeaders(session),
+    },
+    body: JSON.stringify({
+      hostToken: session.hostToken,
+      state: input.state,
+      codeVerifier: input.verifier,
+      code: input.code,
+    }),
+  });
+  const payload = (await response.json().catch(() => null)) as
+    | ({ token?: string } & ErrorBody)
+    | null;
+  if (!response.ok || !payload?.token) {
+    throw new ApiError(
+      response.status,
+      payload?.error?.code ?? "request_failed",
+      payload?.error?.message ?? "Sign-in failed.",
+    );
+  }
+  return payload.token;
+}
+
+/** What the sign-in window hands back to the app (a code, or an error such as access_denied). */
+export type MsfHandoff = { state: string; code?: string; error?: string; at: number };
+
+/** The sign-in result the callback puts in the return address's hash (`cs-msf-state`, `cs-msf-code`, `cs-msf-error`). */
+export function msfHandoffFrom(hash: string, at = Date.now()): MsfHandoff | null {
+  const params = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+  const state = params.get("cs-msf-state");
+  if (!state) return null;
+  const code = params.get("cs-msf-code");
+  const error = params.get("cs-msf-error");
+  return { state, ...(code ? { code } : {}), ...(error ? { error } : {}), at };
+}
+
+export async function createInvite(session: Session, memberToken: string) {
+  return request<{ invite: string; invitedBy: string; expiresAt: string }>(
+    session,
+    `${session.apiUrl}/v1/invites`,
+    memberToken,
+    {
+      method: "POST",
+    },
+  );
+}
+
+export async function getProfile(session: Session, memberToken: string) {
+  return request<Profile>(session, `${session.apiUrl}/v1/me`, memberToken);
+}
+
+export async function updateProfile(
+  session: Session,
+  memberToken: string,
+  patch: { displayName?: string; email?: string; mentionEmails?: boolean },
+) {
+  return request<Profile & { token: string }>(session, `${session.apiUrl}/v1/me`, memberToken, {
+    method: "POST",
+    body: JSON.stringify(patch),
+  });
+}
+
+/** `environment` targets a linked environment, for files on a reply to one of its comments. */
+function inEnvironment(url: string, environment?: string) {
+  return environment ? `${url}?environment=${encodeURIComponent(environment)}` : url;
+}
+
+export async function uploadAttachment(
+  session: Session,
+  memberToken: string,
+  file: Blob,
+  name: string,
+  environment?: string,
+  capture?: Capture,
+  /** The image was drawn on in the markup editor; the comment service shows it to the title model first. */
+  markedUp = false,
+) {
+  const response = await fetch(inEnvironment(`${session.apiUrl}/v1/attachments`, environment), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${memberToken}`,
+      ...originHeaders(session),
+      "content-type": file.type || "application/octet-stream",
+      "x-file-name": encodeURIComponent(name),
+      ...(capture ? { "x-capture": encodeURIComponent(JSON.stringify(capture)) } : {}),
+      ...(markedUp ? { "x-markup": "1" } : {}),
+    },
+    body: file,
+  });
+  const payload = (await response.json().catch(() => null)) as
+    | ({ attachment: Attachment } & ErrorBody)
+    | null;
+  if (!response.ok || !payload?.attachment) {
+    throw new ApiError(
+      response.status,
+      payload?.error?.code ?? "upload_failed",
+      payload?.error?.message ?? "Upload failed.",
+    );
+  }
+  return payload.attachment;
+}
+
+/** Audio `/v1/transcribe` takes: 16 kHz mono WAV from the web toolbar, m4a (AAC) takes from native clients. */
+const TRANSCRIBE_TYPES: readonly string[] = ["audio/wav", "audio/mp4", "audio/x-m4a"];
+
+/**
+ * One dictated piece to text, sent as its blob's type (`audio/wav`, `audio/mp4`, `audio/x-m4a`; WAV when the
+ * blob is untyped). `prompt` is the writing just before it, for continuity.
+ */
+export async function transcribeAudio(
+  session: Session,
+  memberToken: string,
+  audio: Blob,
+  prompt: string,
+  signal: AbortSignal,
+  environment?: string,
+) {
+  const response = await fetch(inEnvironment(`${session.apiUrl}/v1/transcribe`, environment), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${memberToken}`,
+      ...originHeaders(session),
+      "content-type": TRANSCRIBE_TYPES.includes(audio.type) ? audio.type : "audio/wav",
+      ...(prompt ? { "x-dictation-prompt": encodeURIComponent(prompt) } : {}),
+    },
+    body: audio,
+    signal,
+  });
+  const payload = (await response.json().catch(() => null)) as
+    | ({ text: string } & ErrorBody)
+    | null;
+  if (!response.ok || typeof payload?.text !== "string") {
+    throw new ApiError(
+      response.status,
+      payload?.error?.code ?? "transcribe_failed",
+      payload?.error?.message ?? "Couldn’t transcribe that.",
+    );
+  }
+  return payload.text;
+}
+
+export async function listMembers(session: Session, memberToken: string, environment?: string) {
+  const payload = await request<{ members: Member[] }>(
+    session,
+    inEnvironment(`${session.apiUrl}/v1/members`, environment),
+    memberToken,
+  );
+  return payload.members;
+}
+
+/** "view": this person may read but not comment. Older services don't send it, which means "edit". */
+export type Access = "edit" | "view";
+
+export async function listThreads(session: Session, memberToken: string) {
+  return request<{
+    threads: Thread[];
+    settings: Settings;
+    environment?: string | null;
+    linked?: string[];
+    access?: Access;
+    /** Set by the project's people settings. A tester comments with the ticket form. */
+    memberType?: "client" | "tester";
+    /**
+     * Whether this environment checks a new comment before it is posted (`./clarity-model.ts`). A service
+     * that predates the check doesn't send it, and is never asked to check.
+     */
+    clarity?: ClarityMode;
+  }>(session, `${session.apiUrl}/v1/threads`, memberToken);
+}
+
+/**
+ * Asks whether a comment that has not been posted yet says enough for a reader to act on. Resolves with the
+ * service's answer as it came (`readClarityResponse` reads it) and rejects on any other status; the caller
+ * posts the comment either way (`askClarity`).
+ */
+export async function checkClarity(
+  session: Session,
+  memberToken: string,
+  draft: ClarityDraft,
+  signal?: AbortSignal,
+) {
+  return request<unknown>(session, `${session.apiUrl}/v1/clarity`, memberToken, {
+    method: "POST",
+    body: JSON.stringify(draft),
+    ...(signal ? { signal } : {}),
+  });
+}
+
+/** The tracker's ticket form, for testers only. */
+export async function fetchTicketForm(session: Session, memberToken: string) {
+  const payload = await request<{ form: TicketForm }>(
+    session,
+    `${session.apiUrl}/v1/ticket-form`,
+    memberToken,
+  );
+  return payload.form;
+}
+
+const liveProtocol = "devaccel-comments";
+
+/** `WebSocket` as React Native types it: a third argument carries headers. Browsers ignore it. */
+type HeaderSocket = new (
+  url: string,
+  protocols: string[],
+  options?: { headers: Record<string, string> },
+) => WebSocket;
+
+/** A socket that says "changed" whenever comments change in this environment or one it links to. */
+export function openLive(session: Session, memberToken: string) {
+  const url = new URL("/v1/live", session.apiUrl).href.replace(/^http/, "ws");
+  const protocols = [liveProtocol, memberToken];
+  if (!session.clientOrigin) return new WebSocket(url, protocols);
+  return new (WebSocket as unknown as HeaderSocket)(url, protocols, {
+    headers: originHeaders(session),
+  });
+}
+
+export async function saveSettings(session: Session, memberToken: string, settings: Settings) {
+  const payload = await request<{ settings: Settings }>(
+    session,
+    `${session.apiUrl}/v1/settings`,
+    memberToken,
+    {
+      method: "PUT",
+      body: JSON.stringify({ settings }),
+    },
+  );
+  return payload.settings;
+}
+
+export async function createThread(
+  session: Session,
+  memberToken: string,
+  anchor: Anchor,
+  body: string,
+  extras: PostExtras &
+    Partial<Details> & { url?: string; ticket?: TicketDraft; kind?: ReportKind } = {},
+) {
+  return request<{ thread: Thread; delivery?: Delivery }>(
+    session,
+    `${session.apiUrl}/v1/threads`,
+    memberToken,
+    {
+      method: "POST",
+      body: JSON.stringify({ anchor, body, ...extras }),
+    },
+  );
+}
+
+export async function replyToThread(
+  session: Session,
+  memberToken: string,
+  threadId: string,
+  body: string,
+  extras: PostExtras = {},
+) {
+  return request<{ message: CommentMessage; delivery?: Delivery }>(
+    session,
+    `${session.apiUrl}/v1/threads/${threadId}/replies`,
+    memberToken,
+    {
+      method: "POST",
+      body: JSON.stringify({ body, ...extras }),
+    },
+  );
+}
+
+export async function updateThread(
+  session: Session,
+  memberToken: string,
+  threadId: string,
+  patch: { status?: "open" | "resolved"; anchor?: Anchor; url?: string } & Partial<Details>,
+) {
+  return request<{ id: string }>(session, `${session.apiUrl}/v1/threads/${threadId}`, memberToken, {
+    method: "PATCH",
+    body: JSON.stringify(patch),
+  });
+}
+
+export async function editMessage(
+  session: Session,
+  memberToken: string,
+  threadId: string,
+  messageId: string,
+  body: string,
+  mentions: string[],
+) {
+  return request<{
+    message: { id: string; body: string; editedAt: string | null };
+    delivery: Delivery | null;
+  }>(session, `${session.apiUrl}/v1/threads/${threadId}/messages/${messageId}`, memberToken, {
+    method: "PATCH",
+    body: JSON.stringify({ body, mentions }),
+  });
+}

package/src/runtime/attachment-model.ts

@@ -0,0 +1,42 @@
+/** How attachments are limited, named and described. DOM-free, so native clients share it. */
+
+/** Largest file one message may carry. */
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** Most files one message may carry. */
+export const ATTACHMENT_MAX_FILES = 5;
+/** The file types a message may carry (the file picker's `accept` list). */
+export const ATTACHMENT_TYPES: readonly string[] = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+  "text/plain",
+  "text/csv",
+  "application/json",
+  "application/zip",
+  "video/mp4",
+  "video/webm",
+  "video/quicktime",
+  "audio/webm",
+  "audio/mp4",
+  "audio/ogg",
+  "audio/mpeg",
+];
+
+/** `2026-10-31-13-56-37` (UTC): the stamp in `recording-…`, `replay-…` and other attachment names. */
+export function attachmentStamp(at: number | Date) {
+  return new Date(at).toISOString().slice(0, 19).replace(/[:T]/g, "-");
+}
+
+/** `512 B`, `40 KB`, `2.4 MB`. */
+export function formatSize(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/** A `replay-*.json` activity file (an instant replay or a clip's timeline). */
+export function isReplayFile(file: { name: string; contentType: string }) {
+  return file.contentType === "application/json" && file.name.startsWith("replay-");
+}