/**
 * blip v2: the plugin an app copies in to use Blip. One file, no dependencies (node:crypto and fetch); runs on your
 * server (Node 18+, Next.js route handlers and server actions, Express, Remix, SvelteKit, Bun, Deno with node:crypto).
 * Get the latest:   curl -o src/lib/blip.ts https://sendablip.com/plugin/v1/blip.ts
 * Install guide:    https://sendablip.com/plugin/v1/INSTALL.md   API reference: https://sendablip.com/docs
 *
 *   whoami         is the key set up right, and what's left to do (GET /api/v1/me) (2.12)
 *   testWebhook    send a signed webhook.test to your app's webhook address now and see what it answered (2.12)
 *   recorderUrl    a link that opens Blip's recorder for your workspace, tagged with your ref ("ps:project:<uuid>")
 *   listVideos     your workspace's Blips, all or just one ref's;  getVideo  one of them
 *   createLink     a personal link for one person (only its hash is kept: this is the one time you see it)
 *   requests       createRequest, listRequests, newRequestLink, revokeRequest: a link anyone records on (2.1)
 *   tickets        listTickets, getTicket, getTicketTeam, replyToTicket, addTicketNote, updateTicket, setTicketStatus:
 *                  your Support inbox by API (2.22; tickets:read, tickets:write, and tickets:reply to answer a visitor)
 *                  Replies by email (2.23): every ticket event carries reply_token; postTicketReply (no key) or
 *                  addVisitorReply (a key) brings a visitor's emailed reply onto the ticket.
 *   listAssignments  the Blips someone was asked to watch (2.1)
 *   listCosts      what the Blips cost, per ref (2.1, costs:read)
 *   prepareClip, clipTarget  for the renderer of Reply clips (2.2, clips:render)
 *   watchUrl, embedUrl   the share page and the player for a share code
 *   Replies        sendEvent, createInvite, cancelInvites, erasePerson, listInvites (Blip Reply, as in v1)
 *   webhooks       verify and read what Blip sends: video.ready, reply.invite_ready, reply.reminder,
 *                  reply.completed, reply.cancelled, reply.test, and the step events an app asks for:
 *                  reply.opened, reply.started, reply.expired, reply.tagged, reply.clip_published, reply.clip_taken_down,
 *                  and for an app that keeps Blip's alerts, CRM notes and clip renders on its side (2.11): video.alert,
 *                  video.gate_entry, video.link_milestone, clip.render_requested, clip.file_retired, and for an
 *                  app that files support tickets: ticket.created, ticket.transcript_ready, and (2.13) the rest of a
 *                  ticket's life, for an app or email tool that sends the visitor's emails itself: ticket.replied,
 *                  ticket.status_changed, ticket.solved_check. Blip sends a visitor no email: these events are how
 *                  your own tool does. (2.18) ticket.replied carries `video` when the team answered with a video:
 *                  its link, a picture of it and its length. (2.19) What your team does to a ticket, for an app
 *                  that keeps its own copy: ticket.assigned, ticket.note_added, ticket.tagged; and every ticket
 *                  event carries ticket.assignee and ticket.tags.
 *   signSupportUser  (2.24) sign who's signed in to your app, so the support button's tickets are verified: Blip checks
 *                  the signature, files the ticket under that name and email, and events say visitor.verified: true.
 *                  Needs the support button's identity secret (BLIP_SUPPORT_IDENTITY_SECRET), not your API key.
 *                  (2.25) listTickets and getTicket say the same: visitor.verified and visitor.external_id.
 *
 * Env: BLIP_API_KEY (blip_sk_..., from Blip, Settings, Developers; scopes videos:read, videos:write, replies:read,
 * replies:write as needed), BLIP_WEBHOOK_SECRET (bsk_..., the app's signing secret; only for webhooks),
 * BLIP_SUPPORT_IDENTITY_SECRET (bsi_..., a support button's; only for signSupportUser), and BLIP_URL
 * only to point somewhere other than https://sendablip.com. Server only: never import this into browser code.
 */
import { createHmac, timingSafeEqual } from "node:crypto";

export const BLIP_PLUGIN_VERSION = "2.27.0";
const TOLERANCE_SECONDS = 300;
const SHARE_BASE = "https://sendablip.com"; // brand-files: origin (scripts/brand-files.mts writes it from src/lib/brand.ts)
const NAME = "Blip"; // brand-files: name (scripts/brand-files.mts writes it from src/lib/brand.ts)

export interface BlipConfig {
  url: string;
  apiKey: string;
  /** The app's signing secret, for webhooks. */
  secret: string | null;
}

/**
 * The config from env, or null when the key is missing or BLIP_URL isn't https (the app then does nothing; ask
 * blipConfigProblem why). BLIP_URL is https://sendablip.com unless set.
 */
export function blipConfig(env: Record<string, string | undefined> = process.env): BlipConfig | null {
  const url = (env.BLIP_URL?.trim() || SHARE_BASE).replace(/\/+$/, "");
  const apiKey = env.BLIP_API_KEY?.trim();
  if (!/^https:\/\/|^http:\/\/localhost/.test(url) || !apiKey || !apiKey.startsWith("blip_sk_")) return null;
  return { url, apiKey, secret: env.BLIP_WEBHOOK_SECRET?.trim() || null };
}

/** Why blipConfig is null, in a sentence to log or show the developer; null when it's fine (2.12). */
export function blipConfigProblem(env: Record<string, string | undefined> = process.env): string | null {
  const key = env.BLIP_API_KEY?.trim();
  if (!key) return `BLIP_API_KEY isn't set. Make a key in ${NAME} under Settings, Developers and put it in your server's env (not a NEXT_PUBLIC_ one).`;
  if (!key.startsWith("blip_sk_")) return `BLIP_API_KEY should start with blip_sk_. Copy the whole key from ${NAME}, Settings, Developers.`;
  const url = env.BLIP_URL?.trim();
  if (url && !/^https:\/\/|^http:\/\/localhost/.test(url)) return `BLIP_URL has to start with https://. Leave it out to use ${SHARE_BASE}.`;
  return null;
}

export type BlipCallResult<T> = { ok: true; status: number; data: T } | { ok: false; status: number | null; error: string };

async function call<T>(cfg: BlipConfig, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown, timeoutMs = 10_000, headers: Record<string, string> = {}): Promise<BlipCallResult<T>> {
  try {
    const res = await fetch(`${cfg.url}/api/v1/${path}`, {
      method,
      headers: { authorization: `Bearer ${cfg.apiKey}`, "content-type": "application/json", "user-agent": `blip/${BLIP_PLUGIN_VERSION}`, ...headers },
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
    const data = (await res.json().catch(() => ({}))) as T & { error?: string };
    if (!res.ok) return { ok: false, status: res.status, error: data?.error ?? `HTTP ${res.status}` };
    return { ok: true, status: res.status, data };
  } catch (e) {
    return { ok: false, status: null, error: e instanceof Error ? e.message : "network error" };
  }
}

const query = (q: Record<string, string | number | undefined | null>) => {
  const p = new URLSearchParams();
  for (const [k, v] of Object.entries(q)) if (v !== undefined && v !== null && v !== "") p.set(k, String(v));
  const s = p.toString();
  return s ? `?${s}` : "";
};

/** The config, or an error that says what's missing (2.12). For routes that can't do anything without Blip. */
export function requireBlip(env: Record<string, string | undefined> = process.env): BlipConfig {
  const cfg = blipConfig(env);
  if (!cfg) throw new Error(`${NAME} isn't set up: ${blipConfigProblem(env) ?? "check BLIP_API_KEY."}`);
  return cfg;
}

// ---- Setup checks (2.12) -----------------------------------------------------------------------------------------------

export interface BlipWhoami {
  /** windows: may Blip open windows on your sites (off by default: it stays inside your pages). */
  workspace: { id: string; name: string | null; windows: boolean };
  key: { name: string; prefix: string; scopes: string[] };
  /** sites: where the app's Record button opens Blip inside the page. */
  app: { slug: string; name: string; active: boolean; webhook_url: string | null; events: string[]; sites: string[] } | null;
  /** ok false: the workspace's plan doesn't include the API, and problem says what to do. */
  api: { ok: true } | { ok: false; problem: string };
  /** snippet is the script tag to paste for that button. */
  support_buttons: { name: string; active: boolean; files_with_this_app: boolean; sites: string[]; snippet: string }[];
  plugin: { version: string; files: Record<string, string> };
  /** What still has to happen, in plain sentences. Empty when everything's set. */
  next_steps: string[];
}

/** Is this key set up right, and what's left to do. Any key, any scope. */
export const whoami = (cfg: BlipConfig) => call<BlipWhoami>(cfg, "GET", "me");

/** Send {type: "webhook.test"} to the app's webhook address now, signed, and see what it answered. Needs an app key. */
export const testWebhook = (cfg: BlipConfig) =>
  call<{ ok: boolean; status: number | null; answer: string; error: string | null; url: string; ms: number }>(cfg, "POST", "deliveries/test", {}, 15_000);

// ---- Videos -----------------------------------------------------------------------------------------------------------

export interface BlipVideo {
  id: string;
  title: string;
  status: "uploading" | "processing" | "ready" | "failed";
  duration_seconds: number;
  external_ref: string | null;
  created_at: string;
  owner: { name: string | null } | null;
  /** The name a guest gave, when it wasn't a member who recorded it (2.1). */
  guest_name: string | null;
  source: string;
  views: number;
  /** Made through a request (2.1). */
  request_id: string | null;
  /** What it is, set where it was made: a Blip, a support report, or a Blip Reply answer or clip. */
  purpose?: "blip" | "support" | "reply" | "thread";
  share: { code: string; enabled: boolean; url: string; embed_url: string; thumbnail_url: string };
  /** With player: true, a signed player address for your own team (works with the share link off; expires). */
  player_url?: string | null;
}

/** A link to Blip's recorder. Whoever opens it signs in to Blip and must be in your workspace. Lasts 2 hours unless asked. */
export const recorderUrl = (cfg: BlipConfig, o: { ref?: string; title?: string; expires_in?: number } = {}) =>
  call<{ url: string; expires_at: string }>(cfg, "POST", "recorder-links", o);

export const listVideos = (cfg: BlipConfig, q: { ref?: string; ref_prefix?: string; purpose?: "blip" | "support" | "reply" | "thread"; limit?: number; before?: string; player?: boolean } = {}) =>
  call<{ videos: BlipVideo[]; next_before: string | null }>(cfg, "GET", `videos${query({ ...q, player: q.player ? 1 : undefined })}`);

export const getVideo = (cfg: BlipConfig, id: string, o: { player?: boolean } = {}) => call<{ video: BlipVideo }>(cfg, "GET", `videos/${encodeURIComponent(id)}${o.player ? "?player=1" : ""}`);

/** Rename a Blip, set or clear its ref, or turn its share link on or off (2.8). */
export const updateVideo = (cfg: BlipConfig, id: string, p: { title?: string; ref?: string | null; share_enabled?: boolean }) =>
  call<{ video: BlipVideo }>(cfg, "PATCH", `videos/${encodeURIComponent(id)}`, p);

/** Delete a Blip: its link stops and its files go (2.8). */
export const deleteVideo = (cfg: BlipConfig, id: string) => call<{ deleted: true }>(cfg, "DELETE", `videos/${encodeURIComponent(id)}`);

export interface BlipTranscript {
  /** queued and running: coming. done: has words. no_speech, failed, none: won't. */
  state: "queued" | "running" | "done" | "no_speech" | "failed" | "none";
  language: string | null;
  text: string;
  segments: { start: number; end: number; text: string }[];
  summary: string | null;
  chapters: { start: number; title: string }[];
  action_items: { title: string; description: string; quote: string | null }[];
}

/** A Blip's transcript, summary, chapters and action items (2.8). */
export const getTranscript = (cfg: BlipConfig, id: string) => call<{ transcript: BlipTranscript }>(cfg, "GET", `videos/${encodeURIComponent(id)}/transcript`);

export interface BlipComment {
  id: string;
  body: string;
  at_seconds: number | null;
  created_at: string;
  /** guest: typed by a visitor, so not a confirmed name. */
  author: { name: string | null; guest: boolean };
  task: { label: string; url: string } | null;
}

/** A Blip's comments, oldest first (2.8). */
export const listComments = (cfg: BlipConfig, id: string) => call<{ comments: BlipComment[] }>(cfg, "GET", `videos/${encodeURIComponent(id)}/comments`);

/** Views, viewers, minutes watched, finishes, button clicks and reactions. The owner's own watching doesn't count (2.8). */
export const getVideoStats = (cfg: BlipConfig, id: string) =>
  call<{ stats: { views: number; viewers: number; minutes_watched: number; completed: number; button_clicks: number; reactions: Record<string, number> } }>(cfg, "GET", `videos/${encodeURIComponent(id)}/stats`);

export const createLink = (cfg: BlipConfig, l: { video_id: string; name: string; email?: string; ref?: string; expires_at?: string }) =>
  call<{ id: string; url: string }>(cfg, "POST", "links", l);

export interface BlipRequest {
  id: string;
  ref: string | null;
  label: string | null;
  recipient_name: string | null;
  note: string | null;
  due_at: string | null;
  expires_at: string;
  single_use: boolean;
  max_seconds: number;
  received_count: number;
  received_at: string | null;
  created_at: string;
  requested_by: { id: string; name: string | null } | null;
  state: "open" | "received" | "expired" | "revoked";
  latest_video_id: string | null;
}

/**
 * A link anyone can record on, no account. `label` is what they see it's for. The url comes back this once. Made with an
 * app key, it opens inside your page from recorder.js (open: "page") on the app's sites; "window" only where your
 * workspace allows windows and the app lists no sites. Emailed or pasted, it's a page of its own either way.
 */
export const createRequest = (
  cfg: BlipConfig,
  r: { ref: string; label?: string; note?: string; recipient_name?: string; due_at?: string | null; expires_in_days?: number; multi_use?: boolean; max_minutes?: number; requested_by?: string },
) => call<{ id: string; url: string; open: "page" | "window" }>(cfg, "POST", "requests", r);

export const listRequests = (cfg: BlipConfig, q: { ref?: string; ref_prefix?: string } = {}) => call<{ requests: BlipRequest[] }>(cfg, "GET", `requests${query(q)}`);

/** A new link for a request; the old one stops. */
export const newRequestLink = (cfg: BlipConfig, id: string) => call<{ url: string; open: "page" | "window" }>(cfg, "POST", `requests/${encodeURIComponent(id)}/new-link`);

export const revokeRequest = (cfg: BlipConfig, id: string) => call<{ ok: true }>(cfg, "POST", `requests/${encodeURIComponent(id)}/revoke`);

// ---- Threads -----------------------------------------------------------------------------------------------------------
// A DM between a student and your team, kept in order: video, voice or text both ways, a coach or assistant (or the
// AI) answering. People are yours, by your own ids. Needs an app key with threads:read and threads:write, and Threads
// switched on for the app. And groups (2.21): one place where several students and your team talk together.

export type BlipThreadRole = "student" | "coach" | "assistant";
export interface BlipThreadPerson {
  id: string;
  name: string;
  email: string | null;
  role: BlipThreadRole;
  active: boolean;
}
export interface BlipThread {
  id: string;
  /** "group" (2.21): several students and your team in one place. It has no student, is never waiting and is nobody's. */
  kind: "dm" | "topic" | "group";
  /** Whose it is. Null for a group. */
  student: BlipThreadPerson | null;
  /** A topic's title, or a group's name. */
  title: string | null;
  ref: string | null;
  /** A topic: the DM or group it was split out of, and the message it started from. */
  parent_id: string | null;
  from_message_id: string | null;
  assigned_to: BlipThreadPerson | null;
  /** Since when the student has been waiting on your team, or null. */
  waiting_since: string | null;
  answered_at: string | null;
  answered_by: BlipThreadPerson | null;
  messages: number;
  last_message_at: string | null;
  last_preview: string | null;
  created_at: string;
  /**
   * Where Blip's AI stands on the thread's latest question (2.20), or null: "answered", "unknown" (it said your
   * material doesn't have it), "draft" (one waits for your team: `getThreadDraft`), "nothing" (draft mode, and the
   * material had nothing), "no_material", "allowance" (this month's AI answers are used up) or "failed".
   */
  ai: { state: "answered" | "unknown" | "draft" | "nothing" | "no_material" | "allowance" | "failed"; at: string | null } | null;
  /** When the student asked for a person instead of the AI (2.20); null once your team has written. */
  person_asked_at: string | null;
  /** A group (2.21): how many students are in it (your team is in every group), and when it was archived. Null otherwise. */
  member_count: number | null;
  archived_at: string | null;
  /** With `for` on `listThreads` or `getThread` (2.21): how many messages from others that person hasn't read, counted to 100. */
  unread?: number;
}
/** A document Blip's AI answered from (2.20). */
export interface BlipThreadSource {
  id: string;
  title: string;
  kind: "text" | "video";
  /** kind "video": the Blip whose transcript it is. */
  video_id: string | null;
}
/** A voice note: sound only, kept as it was recorded. No video is made, and it doesn't use video minutes. */
export interface BlipThreadVoice {
  /** Its length. What the sender said until it has been heard, then what was measured. */
  seconds: number;
  /** What was said, once `transcript_state` is "done". */
  transcript: string | null;
  /** "pending" for a few seconds after it's sent; then "done", "none" (nobody spoke) or "failed". */
  transcript_state: "pending" | "done" | "none" | "failed";
  /** Where it plays from (an <audio> src). Good for three hours: read the message again for a fresh one. */
  audio_url: string | null;
}
export interface BlipThreadMessage {
  id: string;
  thread_id: string;
  /** Who wrote it; null for the AI and for notes Blip adds. */
  from: BlipThreadPerson | null;
  role: BlipThreadRole | "ai" | "system";
  kind: "text" | "video" | "voice" | "event";
  text: string | null;
  /** kind "video": the Blip. */
  video_id: string | null;
  /** kind "voice": the voice note. Null for anything else. */
  voice: BlipThreadVoice | null;
  /**
   * Blip's AI's part in it (2.20), or null. On its own message (role "ai"): the documents the answer rests on, and
   * `unknown` when it's the note that your material doesn't have it. On a coach's message that began as the AI's
   * draft: `from_draft` true, with the draft's documents. Always label a role "ai" message as written by AI.
   */
  ai: { sources: BlipThreadSource[]; unknown: boolean; needs_person: boolean; from_draft: boolean } | null;
  reply_to: string | null;
  /** kind "event": split_out, assigned, answered or asked_person (the student asked for a person, 2.20). */
  event: "split_out" | "assigned" | "answered" | "asked_person" | null;
  created_at: string;
}

/** Add your people or bring them up to date, up to 500 at a time. `active: false` switches a person off. */
export const syncThreadPeople = (cfg: BlipConfig, people: { id: string; name: string; email?: string | null; role: BlipThreadRole; active?: boolean }[]) =>
  call<{ saved: number }>(cfg, "PUT", "threads/people", { people });

export const listThreadPeople = (cfg: BlipConfig, q: { role?: BlipThreadRole; limit?: number; after?: string } = {}) =>
  call<{ people: BlipThreadPerson[]; next_after: string | null }>(cfg, "GET", `threads/people${query(q)}`);

/** A student's DM for a ref (a course, a cohort): the one there is, or a new one. */
export const openThread = (cfg: BlipConfig, t: { student: string; ref?: string | null; title?: string | null }) => call<{ thread: BlipThread }>(cfg, "POST", "threads", t);

/**
 * Threads. Pass `for` (a person's id) for anything a person sees: a student gets only their own and the groups
 * they're in, each with `unread`. `state: "waiting"` is the coach's inbox, the longest-waiting first (a group is never
 * in it). `kind: "group"` with `for` lists a person's groups. Archived groups are left out unless `archived: true`.
 */
export const listThreads = (
  cfg: BlipConfig,
  q: { for?: string; state?: "waiting" | "answered" | "all"; assigned?: string; student?: string; kind?: "dm" | "topic" | "group"; parent?: string; ref?: string; archived?: boolean; limit?: number; before?: string } = {},
) => call<{ threads: BlipThread[]; next_before: string | null }>(cfg, "GET", `threads${query({ ...q, archived: q.archived ? "true" : undefined })}`);

export const getThread = (cfg: BlipConfig, id: string, q: { for?: string } = {}) => call<{ thread: BlipThread }>(cfg, "GET", `threads/${encodeURIComponent(id)}${query(q)}`);

/** A coach or assistant (`by`) gives a thread to someone (null: nobody), marks it answered or not, or names it. */
export const updateThread = (cfg: BlipConfig, id: string, c: { by: string; assigned_to?: string | null; answered?: boolean; title?: string }) =>
  call<{ thread: BlipThread }>(cfg, "PATCH", `threads/${encodeURIComponent(id)}`, c);

/** A thread's messages, newest first. */
export const listThreadMessages = (cfg: BlipConfig, id: string, q: { for?: string; limit?: number; before?: string } = {}) =>
  call<{ messages: BlipThreadMessage[]; next_before: string | null }>(cfg, "GET", `threads/${encodeURIComponent(id)}/messages${query(q)}`);

/**
 * Post a message: `from` is your id for who's posting, or `as: "ai"` for an answer from your own AI. A video message
 * carries the id of a Blip in your workspace. A voice note goes with `postThreadVoice`.
 */
export const postThreadMessage = (
  cfg: BlipConfig,
  id: string,
  m: { from: string; kind?: "text" | "video"; text?: string; video_id?: string; reply_to?: string } | { as: "ai"; text: string; reply_to?: string },
) => call<{ message: BlipThreadMessage; thread: BlipThread }>(cfg, "POST", `threads/${encodeURIComponent(id)}/messages`, m);

/**
 * Post a voice note: the sound file itself, as a browser's or a phone's recorder made it (`type` is "audio/webm",
 * "audio/mp4" or "audio/m4a"; 4 MB and 5 minutes at most), with its length in seconds. Blip keeps the file as it is
 * and writes its words out a few seconds later (`message.voice.transcript`). A student's voice notes count against
 * their voice minutes a month (`setThreadSettings`, `student_voice_minutes`), not your video minutes.
 * Your people can also record one straight into the Threads screens, with nothing for you to build.
 */
export async function postThreadVoice(
  cfg: BlipConfig,
  id: string,
  v: { from: string; audio: Blob | ArrayBuffer | Uint8Array; type: "audio/webm" | "audio/mp4" | "audio/m4a"; seconds: number; reply_to?: string },
): Promise<BlipCallResult<{ message: BlipThreadMessage; thread: BlipThread }>> {
  try {
    const res = await fetch(`${cfg.url}/api/v1/threads/${encodeURIComponent(id)}/messages${query({ from: v.from, seconds: Math.round(v.seconds), reply_to: v.reply_to })}`, {
      method: "POST",
      headers: { authorization: `Bearer ${cfg.apiKey}`, "content-type": v.type, "user-agent": `blip/${BLIP_PLUGIN_VERSION}` },
      body: v.audio as BodyInit,
      signal: AbortSignal.timeout(30_000),
    });
    const data = (await res.json().catch(() => ({}))) as { message: BlipThreadMessage; thread: BlipThread; error?: string };
    if (!res.ok) return { ok: false, status: res.status, error: data?.error ?? `HTTP ${res.status}` };
    return { ok: true, status: res.status, data };
  } catch (e) {
    return { ok: false, status: null, error: e instanceof Error ? e.message : "network error" };
  }
}

/**
 * A question out of a DM into a thread of its own. Out of a group (2.21): a student's message, by a coach, an assistant
 * or the student who wrote it, into a private topic between that student and your team, which waits like any topic.
 */
export const splitThread = (cfg: BlipConfig, id: string, s: { by: string; message_id: string; title?: string | null }) =>
  call<{ thread: BlipThread }>(cfg, "POST", `threads/${encodeURIComponent(id)}/split`, s);

// ---- Group threads (2.21) ----------------------------------------------------------------------------------------------
// A group is a thread of kind "group": read it, post in it (`postThreadMessage`, `postThreadVoice`) and list it like any
// thread. Its members are students, by your ids; every coach and assistant of your app is in every group already. A
// student reads and posts in a group only while they're a member. Nobody waits in a group and Blip's AI stays out of it.

/** A student in a group, and when they were put in. */
export interface BlipThreadMember extends BlipThreadPerson {
  added_at: string;
}
/** What changing a group's members gives back: the group, how many went in and came out, and how many are in it now. */
export interface BlipThreadMembersResult {
  thread: BlipThread;
  added: number;
  removed: number;
  count: number;
}

/**
 * A group, e.g. a cohort. With a `ref` (your name for it) the same call again gives the group there is, so it's safe
 * every time you sync. `members` (students, by your ids; sync them first with `syncThreadPeople`) are added to whoever
 * is in it; 500 in a group at most. `by` is the coach doing it, if a person is.
 */
export const createThreadGroup = (cfg: BlipConfig, g: { name: string; ref?: string | null; members?: string[]; by?: string | null }) =>
  call<{ thread: BlipThread }>(cfg, "POST", "threads/groups", g);

/** A group's name, its ref (null takes it off) or `archived`: true closes it (still read, nothing new said), false opens it again. */
export const updateThreadGroup = (cfg: BlipConfig, id: string, c: { name?: string; ref?: string | null; archived?: boolean; by?: string | null }) =>
  call<{ thread: BlipThread }>(cfg, "PATCH", `threads/groups/${encodeURIComponent(id)}`, c);

/** Everyone in a group (students only; your team is in every group), by name. */
export const listThreadGroupMembers = (cfg: BlipConfig, id: string) =>
  call<{ members: BlipThreadMember[]; count: number }>(cfg, "GET", `threads/groups/${encodeURIComponent(id)}/members`);

/** The group's members become exactly these students. Anyone left out loses the group at once; what they wrote stays. */
export const setThreadGroupMembers = (cfg: BlipConfig, id: string, members: string[], by?: string | null) =>
  call<BlipThreadMembersResult>(cfg, "PUT", `threads/groups/${encodeURIComponent(id)}/members`, { members, ...(by ? { by } : {}) });

/** Put students in a group and take students out. A student can't join or leave by themselves: your app decides. */
export const changeThreadGroupMembers = (cfg: BlipConfig, id: string, c: { add?: string[]; remove?: string[]; by?: string | null }) =>
  call<BlipThreadMembersResult>(cfg, "POST", `threads/groups/${encodeURIComponent(id)}/members`, c);

/** What `createThreadSession` gives back: put `thread_url` or `inbox_url` in BlipThread, BlipThreadInbox or threads.js. */
export interface BlipThreadSession {
  token: string;
  /** The person's own conversation: for a student. */
  thread_url: string;
  /** The team's inbox: for a coach or an assistant; null for a student. */
  inbox_url: string | null;
  expires_at: string;
  user: { id: string; name: string; email: string | null; role: BlipThreadRole };
}

/**
 * The drop-in screens: a session for whoever is signed in to your app, good for two hours on one of your sites' pages.
 * Call it on your server when the page loads (it needs your key), and hand the url to the browser. The person is added
 * or brought up to date, so there's nothing to sync first. `origin` is the site the screen will be on, like
 * "https://yourapp.com": it must be on your app's list of sites, and only it can frame the screen.
 */
export const createThreadSession = (cfg: BlipConfig, s: { user: { id: string; name: string; email?: string | null; role: BlipThreadRole }; origin: string }) =>
  call<BlipThreadSession>(cfg, "POST", "threads/sessions", s);

/**
 * Threads settings for your app. `student_minutes`: the video one student may record in a calendar month (60 unless
 * set). `student_voice_minutes`: the voice notes one student may send in a calendar month (120 unless set).
 *
 * The AI (2.20). `ai_mode`: "off" (unless set), "draft" (it writes an answer for your team to send, change or throw
 * away) or "answer" (it answers on its own, labelled as AI). It answers only from the material you give it
 * (`putThreadKnowledge`) and says when that has nothing. A coach can change the mode from the inbox screen too.
 * `ai_monthly_answers`: AI answers and drafts a calendar month, yours to lower, never above `ai_monthly_answers_max`;
 * when they're used up the AI stays quiet until next month. `ai_answers_used`: this month's count.
 */
export interface BlipThreadSettings {
  student_minutes: number;
  student_voice_minutes: number;
  ai_mode: "off" | "draft" | "answer";
  ai_monthly_answers: number;
  /** Read-only: the most your app may have a month. */
  ai_monthly_answers_max: number;
  /** Read-only. */
  ai_answers_used: number;
}
export const getThreadSettings = (cfg: BlipConfig) => call<BlipThreadSettings>(cfg, "GET", "threads/settings");

export const setThreadSettings = (cfg: BlipConfig, s: Partial<Pick<BlipThreadSettings, "student_minutes" | "student_voice_minutes" | "ai_mode" | "ai_monthly_answers">>) =>
  call<BlipThreadSettings>(cfg, "PUT", "threads/settings", s);

// The AI's material (2.20): what Blip's AI may answer a student from, and nothing else.

export interface BlipThreadDocument {
  id: string;
  kind: "text" | "video";
  /** Your own name for it, if you gave one. */
  ref: string | null;
  title: string;
  video_id: string | null;
  /** "waiting": a Blip whose transcript isn't written yet (Blip reads it when it is). "empty": nothing was said in it. */
  state: "ready" | "waiting" | "empty";
  characters: number;
  created_at: string;
  updated_at: string;
}

export const listThreadKnowledge = (cfg: BlipConfig) =>
  call<{ documents: BlipThreadDocument[]; limits: { documents: number; characters_per_document: number } }>(cfg, "GET", "threads/knowledge");

/**
 * A document for the AI to answer from: pasted text with a title (100,000 characters at most), or one of your
 * workspace's Blips for its transcript (`video_id`, or `video_ref`: your own ref for it). Send the same `ref` again and
 * the document is replaced, so each lesson can be kept in step under its own ref. 100 documents an app.
 */
export const putThreadKnowledge = (
  cfg: BlipConfig,
  d: { title: string; text: string; ref?: string | null } | { video_id: string; title?: string | null; ref?: string | null } | { video_ref: string; title?: string | null; ref?: string | null },
) => call<{ document: BlipThreadDocument }>(cfg, "PUT", "threads/knowledge", d);

/** One document with `text`: what the AI reads. */
export const getThreadKnowledge = (cfg: BlipConfig, id: string) => call<{ document: BlipThreadDocument & { text: string } }>(cfg, "GET", `threads/knowledge/${encodeURIComponent(id)}`);

/** The AI stops answering from it at once. */
export const deleteThreadKnowledge = (cfg: BlipConfig, id: string) => call<{ deleted: true }>(cfg, "DELETE", `threads/knowledge/${encodeURIComponent(id)}`);

/**
 * "Ask a person" (2.20): the thread's own student (`by`) says the AI isn't enough. The thread is flagged
 * (`person_asked_at`) and waiting, and the AI stays out of it until your team has written. The Threads screens have
 * this as a button, so this is for screens of your own. Sends thread.person_asked, once.
 */
export const askThreadPerson = (cfg: BlipConfig, id: string, by: string) => call<{ thread: BlipThread; asked: boolean }>(cfg, "POST", `threads/${encodeURIComponent(id)}/person`, { by });

/** The AI's draft waiting on a thread (ai_mode "draft"), for your team only. Never show it to the student. */
export interface BlipThreadDraft {
  text: string;
  sources: BlipThreadSource[];
  for_message_id: string | null;
  needs_person: boolean;
  /** Your material covers only part of the question, and the draft says which. */
  partial: boolean;
  created_at: string | null;
}
export const getThreadDraft = (cfg: BlipConfig, id: string) => call<{ draft: BlipThreadDraft | null }>(cfg, "GET", `threads/${encodeURIComponent(id)}/draft`);

/** A coach or an assistant (`by`) sends the draft, as written or with their changes in `text`. It is their message. */
export const sendThreadDraft = (cfg: BlipConfig, id: string, d: { by: string; text?: string | null }) =>
  call<{ message: BlipThreadMessage; thread: BlipThread }>(cfg, "POST", `threads/${encodeURIComponent(id)}/draft`, d);

/** Throws the draft away. The student is still waiting. */
export const discardThreadDraft = (cfg: BlipConfig, id: string, by: string) => call<{ thread: BlipThread }>(cfg, "DELETE", `threads/${encodeURIComponent(id)}/draft${query({ by })}`);

// ---- Support tickets (2.22): tickets:read, tickets:write, tickets:reply ---------------------------------------------------

/** Someone on your own team: who a ticket can be assigned to. */
export interface BlipTicketPerson {
  id: string;
  name: string | null;
  email: string | null;
}

/** A support ticket, as listTickets gives it. The names match the ticket events' (BlipTicketEvent), so one parser reads both. */
export interface BlipTicket {
  id: string;
  number: number;
  /** What the visitor was shown: your own number if you answered ticket.created with one, else "#12". */
  ref: string;
  title: string;
  body: string | null;
  kind: "text" | "screenshot" | "video";
  severity: "minor" | "major";
  status: "open" | "waiting" | "done";
  /** The status as the visitor reads it: "We answered, over to you". */
  status_words: string;
  /** Who closed it, when it's done: visitor, team, or no_reply (closed after silence; not solved). */
  solved_by: "visitor" | "team" | "no_reply" | null;
  reopened_count: number;
  /** The visitor wrote after your team's last answer: it's waiting on your team again. */
  awaiting_team: boolean;
  origin: "support_button" | "report_a_problem" | "team_report";
  page: string | null;
  site: string | null;
  /**
   * Who filed it, the same as on every ticket event (2.25): verified when your own server signed them with
   * signSupportUser and Blip checked it, or they were signed in to Blip. external_id: the id you signed, or null.
   * It says nothing about a later reply: a message's `via` does ("email" is one your tool posted back; Blip didn't
   * check who sent that email).
   */
  visitor: { name: string | null; first_name: string; email: string | null; verified: boolean; external_id: string | null };
  assignee: BlipTicketPerson | null;
  tags: string[];
  button: { id: string; name: string; ref: string | null } | null;
  app_ref: string | null;
  app_url: string | null;
  /** The visitor's own page for this ticket: no login, every answer, a reply box. */
  status_url: string | null;
  created_at: string;
  updated_at: string;
  first_answer_at: string | null;
  last_team_at: string | null;
  last_visitor_at: string | null;
  solved_at: string | null;
}

export interface BlipTicketMessage {
  id: string;
  /** answer: your team's, shown to the visitor. visitor: theirs. note: your team's own, never shown to the visitor. event: something that happened. */
  kind: "answer" | "visitor" | "note" | "event";
  from: "team" | "visitor" | "system";
  /** Where it was written: inbox, status_page, email, api, mcp, system. */
  via: string;
  /** For an event: solved_by_visitor, closed_by_team, closed_no_reply, reopened, moved, solved_check, assigned, tagged, email_attachments. */
  event: string | null;
  /** May the visitor see it on their ticket page. Never true for a note. */
  visible_to_visitor: boolean;
  author: { id: string | null; name: string | null };
  /** The API key it was sent with, when it came through this API. */
  key: { id: string; name: string | null } | null;
  body: string;
  created_at: string;
  /** A video answer: state is ready, preparing, held or removed; url is the visitor's ticket page at that answer. */
  video: { id: string | null; state: "ready" | "preparing" | "held" | "removed"; title: string | null; url: string | null; thumbnail_url: string | null; duration_seconds: number | null } | null;
  /** How telling your email tool went, when it was told. */
  notice: { state: "queued" | "sent" | "failed" | "skipped"; attempts: number; last_error: string | null } | null;
  held: boolean;
}

/** One ticket, whole: getTicket. */
export interface BlipTicketDetail extends BlipTicket {
  browser: string | null;
  viewport: string | null;
  /** The page's last errors, as the support button caught them. */
  errors: string[];
  /** The screenshots. Each link works for 7 days; read the ticket again for fresh ones. */
  files: { id: string; url: string; content_type: string; width: number; height: number }[];
  /** The visitor's recording, when the report is one. transcript.state: waiting, done, no_speech, failed or none. */
  video: {
    id: string;
    title: string;
    status: string;
    duration_seconds: number | null;
    url: string;
    player_url: string | null;
    transcript: { state: "waiting" | "done" | "no_speech" | "failed" | "none"; language: string | null; summary: string | null; chapters: { start: number; title: string }[]; action_items: { title: string; description: string; quote: string | null }[]; text: string | null; truncated: boolean };
  } | null;
  /** The thread, oldest first. */
  messages: BlipTicketMessage[];
  /** How this workspace's visitors get emailed, and whether anything will hear ticket.replied. Blip sends them no email. */
  email: { mode: "none" | "sender" | "app"; told: boolean };
}

/** Your workspace's support tickets, newest first. Needs tickets:read. before: the next_before of the page before. */
export const listTickets = (
  cfg: BlipConfig,
  q: { status?: "open" | "waiting" | "done"; q?: string; assignee?: string; button?: string; tag?: string; kind?: "text" | "screenshot" | "video"; severity?: "minor" | "major"; since?: string; updated_since?: string; limit?: number; before?: number } = {},
) => call<{ tickets: BlipTicket[]; next_before: number | null }>(cfg, "GET", `tickets${query(q)}`);

/** One ticket by its number: the thread, notes, screenshots, recording and transcript. view "visitor": the thread as its visitor sees it (no notes). Needs tickets:read. */
export const getTicket = (cfg: BlipConfig, number: number, o: { view?: "team" | "visitor" } = {}) => call<{ ticket: BlipTicketDetail }>(cfg, "GET", `tickets/${encodeURIComponent(String(number))}${query({ view: o.view })}`);

/** Who a ticket can be assigned to, and the tags it can carry. Needs tickets:read. */
export const getTicketTeam = (cfg: BlipConfig) => call<{ people: (BlipTicketPerson & { role: string })[]; tags: string[] }>(cfg, "GET", "tickets/team");

export interface BlipTicketMessageResult {
  message: BlipTicketMessage;
  ticket: BlipTicket;
  /** How telling your email webhook went, or null when the workspace has none. */
  notice: { state: "queued" | "sent" | "failed" | "skipped"; error: string | null } | null;
  apps: number;
  /** This idempotency key had already made this message: nothing was added or sent again. */
  replayed: boolean;
}

const idem = (key: string | undefined): Record<string, string> => (key ? { "idempotency-key": key } : {});

/**
 * Answer the visitor. It goes on their ticket page, and ticket.replied goes to your email webhook and connected apps,
 * so your own tool emails it from your domain. Blip sends them no email. Needs tickets:write and tickets:reply.
 * then: where the ticket goes (waiting unless said). author_name: who the visitor reads it's from (your business's
 * name without one). idempotency_key: the same key again on the same ticket adds nothing, so a retry is safe.
 */
export const replyToTicket = (cfg: BlipConfig, number: number, m: { body: string; then?: "open" | "waiting" | "done"; author_name?: string; idempotency_key?: string }) =>
  call<BlipTicketMessageResult>(cfg, "POST", `tickets/${encodeURIComponent(String(number))}/messages`, { as: "team", body: m.body, then: m.then, author_name: m.author_name }, 30_000, idem(m.idempotency_key));

/** Add a note for your team. The visitor never sees it and no email tool is told. Needs tickets:write. */
export const addTicketNote = (cfg: BlipConfig, number: number, m: { body: string; idempotency_key?: string }) =>
  call<BlipTicketMessageResult>(cfg, "POST", `tickets/${encodeURIComponent(String(number))}/messages`, { as: "note", body: m.body }, 15_000, idem(m.idempotency_key));

/**
 * The visitor's own reply, which reached you by email (2.23). body is the email's plain text as it came: Blip keeps the
 * reply and drops the message it quotes and the signature mark. It moves the ticket back to To do (a reopen from Done)
 * and tells your team. message_id (the email's Message-ID) makes the same email posted twice one message. Needs
 * tickets:write.
 */
export const addVisitorReply = (cfg: BlipConfig, number: number, m: { body: string; message_id?: string; attachments?: number }) =>
  call<BlipTicketMessageResult>(cfg, "POST", `tickets/${encodeURIComponent(String(number))}/messages`, { as: "visitor", body: m.body, message_id: m.message_id, attachments: m.attachments }, 15_000);

/**
 * The same, with no key (2.23): the ticket's reply_token (from any ticket event) is the key, for that one ticket.
 * Send reply_token, or `to` (the address the reply was sent to, with the token in it), or neither when the token is in
 * the words. duplicate: this email was already on the ticket. reopened: it reopened a closed one. base: only to point
 * somewhere other than https://sendablip.com.
 */
export async function postTicketReply(
  r: { reply_token?: string; to?: string; subject?: string; text?: string; html?: string; message_id?: string; attachments?: number },
  base: string = SHARE_BASE,
): Promise<BlipCallResult<{ ok: true; reopened: boolean; duplicate: boolean; test?: boolean; kept?: string }>> {
  try {
    const res = await fetch(`${base.replace(/\/+$/, "")}/api/support/tickets/reply`, {
      method: "POST",
      headers: { "content-type": "application/json", "user-agent": `blip/${BLIP_PLUGIN_VERSION}` },
      body: JSON.stringify(r),
      signal: AbortSignal.timeout(15_000),
    });
    const data = (await res.json().catch(() => ({}))) as { ok: true; reopened: boolean; duplicate: boolean; error?: string };
    if (!res.ok) return { ok: false, status: res.status, error: data?.error ?? `HTTP ${res.status}` };
    return { ok: true, status: res.status, data };
  } catch (e) {
    return { ok: false, status: null, error: e instanceof Error ? e.message : "network error" };
  }
}

/** Change any of a ticket's status, assignee (a person's id or email address, or null) and tags (all of them). Needs tickets:write. */
export const updateTicket = (cfg: BlipConfig, number: number, p: { status?: "open" | "waiting" | "done"; assignee?: string | null; tags?: string[] }) =>
  call<{ ticket: BlipTicket; changed: ("status" | "assignee" | "tags")[] }>(cfg, "PATCH", `tickets/${encodeURIComponent(String(number))}`, p);

/** To do (open), Waiting or Done. Needs tickets:write. */
export const setTicketStatus = (cfg: BlipConfig, number: number, status: "open" | "waiting" | "done") => updateTicket(cfg, number, { status });

export interface BlipAssignment {
  video_id: string;
  title: string;
  external_ref: string | null;
  due_at: string | null;
  best_percent: number;
  completed_at: string | null;
  assigned_at: string;
}

/** What this person was asked to watch and hasn't finished (done: true for all). */
export const listAssignments = (cfg: BlipConfig, user: string, o: { done?: boolean } = {}) =>
  call<{ assignments: BlipAssignment[] }>(cfg, "GET", `assignments${query({ user, done: o.done ? 1 : undefined })}`);

export interface BlipCostRow {
  ref: string | null;
  video_id: string | null;
  kind: "encoding" | "storage" | "delivery" | "transcript" | string;
  cents: number;
}

/** What your Blips cost in a date range (YYYY-MM-DD), per ref, Blip and kind. Needs costs:read (2.1). */
export const listCosts = (cfg: BlipConfig, q: { from: string; to: string; ref_prefix?: string }) => call<{ rows: BlipCostRow[] }>(cfg, "GET", `costs${query(q)}`);

// ---- Clip rendering (clips:render, 2.2): for the renderer that makes Blip Reply's clips ---------------------------------

/** A clip's recipe: its parts (signed sources and in/out points), captions and intro, in seconds. */
export interface BlipClipSpec {
  width: number;
  height: number;
  parts: { source: unknown; in: number; out: number }[];
  captions: unknown[];
  intro: { name: string; disclosure: string | null; seconds: number };
  seconds: number;
}

export const prepareClip = (cfg: BlipConfig, testimonialId: string) => call<{ clip: BlipClipSpec }>(cfg, "POST", `clips/${encodeURIComponent(testimonialId)}/prepare`, {});

/** Where the finished clip uploads: a new Blip video and its upload endpoint. */
export const clipTarget = (cfg: BlipConfig, testimonialId: string) =>
  call<{ target: { video_id: string; title: string; endpoint: string; headers: Record<string, string> } }>(cfg, "POST", `clips/${encodeURIComponent(testimonialId)}/target`, {});

/** The renderer reports a clip done (2.8): the video it uploaded, its length and size, the disclosure it burned in. */
export const finishClip = (cfg: BlipConfig, testimonialId: string, r: { video_id: string; seconds: number; bytes: number; disclosure: string | null; file_key?: string | null }) =>
  call<{ ok: true }>(cfg, "POST", `clips/${encodeURIComponent(testimonialId)}/finish`, r);

/** The renderer reports a clip failed (2.8): it goes back to a draft, with why, so it can be made again. */
export const failClip = (cfg: BlipConfig, testimonialId: string, error: string) => call<{ ok: true }>(cfg, "POST", `clips/${encodeURIComponent(testimonialId)}/fail`, { error });

/** Apps Blip lets sign people in only (2.3; Project System today): a one-use link, good for a minute, that signs this team member in to Blip and opens `next`. */
export const createSession = (cfg: BlipConfig, s: { user_id: string; email: string; next?: string }) => call<{ url: string; expires_at: string }>(cfg, "POST", "sessions", s);

/**
 * Apps Blip lets sign people in only (2.4; Project System today): the recorder inside your own page, with no new window and no
 * second sign-in. On your server, then in the browser pass the url to BlipRecorder.open() from
 * https://sendablip.com/plugin/v1/recorder.js. The recorder only loads on `origin`, one of your app's sites.
 */
export const recorderSession = (cfg: BlipConfig, s: { user_id: string; email: string; origin: string }) => call<{ url: string; expires_at: string }>(cfg, "POST", "recorder-sessions", s);

/**
 * Who can see what, by your own rules (2.5). Blip never learns them: run your own query as this person, so your own row
 * security decides, and send every ref they can see. It replaces their list for your app. Call it when they open Blip and
 * when their access changes. An empty list removes everything.
 */
export const syncAccess = (cfg: BlipConfig, s: { email: string; refs: string[] }) => call<{ synced: number }>(cfg, "PUT", "access", s);

/**
 * Everyone your app lets into Blip in your workspace, by your own rules (2.9). It replaces your last list: people on it
 * become members (now, or when they first have a Blip account); members your list made who aren't on it stop being
 * members. People your workspace's owners add in Blip aren't touched. Send it on a schedule and when someone joins or
 * leaves.
 */
export const syncMembers = (cfg: BlipConfig, s: { people: { email: string; name?: string | null }[] }) => call<{ listed: number }>(cfg, "PUT", "members", s);

/**
 * Your places and their names (2.10): "ps:project:42" is "Acme website". Blip shows the names and offers the places a
 * person can see (syncAccess) when they file a Blip. It replaces your last list; archived places stay named but aren't
 * offered.
 */
export const syncRefs = (cfg: BlipConfig, s: { refs: { ref: string; label: string; archived?: boolean }[] }) => call<{ listed: number }>(cfg, "PUT", "refs", s);

/** A Blip's page in Blip's own app (for its owner and workspace). */
export const appVideoUrl = (cfg: BlipConfig, id: string) => `${cfg.url}/videos/${encodeURIComponent(id)}`;

const CODE = /^[0-9a-f]{24}$/;
/** The share page for a share code (sendablip.com/<code>). */
export const watchUrl = (code: string) => (CODE.test(code) ? `${SHARE_BASE}/${code}` : null);
/** The player for an iframe. */
export const embedUrl = (code: string) => (CODE.test(code) ? `${SHARE_BASE}/embed/${code}` : null);

// ---- Replies ----------------------------------------------------------------------------------------------------------

export interface BlipEvent {
  /** Your own id for this event, so a retry is never counted twice (e.g. the order id plus the type). */
  event_id: string;
  /** Lowercase, like purchase.completed. */
  type: string;
  /** What it's about (an order id): one invite per Reply per external_id, and what cancel finds. */
  external_id?: string | null;
  person?: { email?: string | null; name?: string | null } | null;
  /** Fields the automations match on ({"product": "ai-playbook"}). No payment details; 8 KB at most. */
  data?: Record<string, unknown>;
}

export const sendEvent = (cfg: BlipConfig, e: BlipEvent) =>
  call<{ duplicate: boolean; invites: { reply_id: string; invite_id: string; send_at: string }[] }>(cfg, "POST", "blip/events", e);

export const createInvite = (
  cfg: BlipConfig,
  i: { reply_id: string; external_id?: string; person?: { name?: string; email?: string }; meta?: Record<string, unknown>; delivery?: "app" | "email" | "link"; send_at?: string },
) => call<{ invite_id: string; url: string | null; duplicate: boolean }>(cfg, "POST", "blip/invites", i);

export const cancelInvites = (cfg: BlipConfig, by: { external_id: string } | { invite_id: string }) => call<{ cancelled: number; taken_down: number }>(cfg, "POST", "blip/cancel", by);

export const erasePerson = (cfg: BlipConfig, email: string) => call<{ erased: number; clips: number }>(cfg, "POST", "blip/erase", { email });

export const listInvites = (cfg: BlipConfig, q: { external_id?: string; email?: string; limit?: number } = {}) =>
  call<{ invites: { id: string; reply_id: string; external_id: string | null; status: string }[] }>(cfg, "GET", `blip/invites${query(q)}`);

// ---- Webhooks ---------------------------------------------------------------------------------------------------------

export interface BlipDelivery {
  id: string;
  type: string;
  state: "queued" | "sent" | "failed";
  attempts: number;
  last_status: number | null;
  last_error: string | null;
  created_at: string;
  sent_at: string | null;
  next_attempt_at: string;
  invite_id: string | null;
}

/** The webhooks Blip sent your app, or is still trying to send (2.8). */
export const listDeliveries = (cfg: BlipConfig, q: { state?: "queued" | "sent" | "failed"; type?: string; limit?: number } = {}) =>
  call<{ deliveries: BlipDelivery[] }>(cfg, "GET", `deliveries${query(q)}`);

/** Send one again, with the same delivery_id and a fresh signature (2.8). */
export const redeliver = (cfg: BlipConfig, id: string) => call<{ queued: true }>(cfg, "POST", `deliveries/${encodeURIComponent(id)}/redeliver`);

export interface BlipPerson {
  name: string | null;
  email: string | null;
}

/** The team's tag on someone's answers. */
export type BlipReview = "new" | "use" | "maybe" | "no";

/** What every step event says about the person and their invite. */
export interface BlipReplyStep {
  delivery_id: string;
  invite_id: string;
  reply_id: string;
  reply_name: string;
  external_id: string | null;
  person: BlipPerson;
  status: "scheduled" | "sent" | "opened" | "started" | "finished" | "expired" | "cancelled";
  review: BlipReview;
  meta: Record<string, unknown>;
}

/** A published clip. Its page is path (and embed_path) on sendablip.com or the brand's own domain. */
export interface BlipClip {
  id: string;
  code: string;
  path: string;
  embed_path: string;
  kind: string;
  aspect: string;
  display_name: string | null;
  wall: string | null;
  published_at: string | null;
  taken_down_at: string | null;
  taken_down_reason: string | null;
}

export type BlipWebhook =
  | { type: "video.ready"; delivery_id: string; video: Omit<BlipVideo, "owner" | "share"> & { share: Omit<BlipVideo["share"], "thumbnail_url"> } }
  | {
      type: "reply.invite_ready" | "reply.reminder";
      delivery_id: string;
      invite_id: string;
      reply_id: string;
      external_id: string | null;
      person: BlipPerson;
      /** The link to send. A reminder carries a new one; the old one has stopped. */
      url: string;
      expires_at: string;
      reward_label: string | null;
      reward_image_url?: string | null;
      questions?: string[];
      meta: Record<string, unknown>;
    }
  | {
      type: "reply.completed";
      delivery_id: string;
      invite_id: string;
      reply_id: string;
      external_id: string | null;
      person: BlipPerson;
      /** Same for everyone who finishes this Reply. Says nothing about what they said. */
      reward_code: string | null;
      finished_at: string;
      answers: { videos: number; texts: number };
      meta: Record<string, unknown>;
    }
  | { type: "reply.cancelled"; delivery_id: string; invite_id: string; reply_id: string; external_id: string | null }
  /** From testWebhook (2.12): answer 2xx. reply.test is the old name. */
  | { type: "webhook.test" | "reply.test"; delivery_id: string; sent_at?: string }
  /**
   * Action items, or a comment, for your app to make into tasks (if ticked). Answer {tasks: [{key, id, ref, url}]} and
   * Blip links each back to the moment in the video.
   */
  | {
      type: "video.tasks";
      delivery_id: string;
      event_key: string;
      video: { id: string; title: string; url: string };
      project_ref: string | null;
      actor_id: string | null;
      kind: "action_items" | "comment";
      items: { key: string; title: string; description: string; assignee_id: string | null }[];
    }
  /**
   * A bug report or support ticket, from your team or a customer's Report a problem button. Answer
   * {task: {id, ref, url}} and the reporter sees ref ("Filed as SUP-214"). finding.description is HTML: page, browser,
   * steps, what they expected and what happened. A customer's words are marked unverified (finding.meta.untrusted).
   */
  | {
      type: "video.reported";
      delivery_id: string;
      event_key: string;
      video: { id: string; title: string; owner_id: string | null; url: string };
      project_ref: string;
      reporter: { id: string | null; name: string | null; guest: boolean };
      finding: { title: string; severity: "blocker" | "major" | "minor" | "polish" | null; description: string; meta: Record<string, unknown> };
    }
  /** Only to apps that ask for them in Settings, Developers. One each per invite, except tagged, which comes per change. */
  | (BlipReplyStep & { type: "reply.opened"; opened_at: string })
  | (BlipReplyStep & { type: "reply.started"; started_at: string })
  | (BlipReplyStep & { type: "reply.expired"; expired_at: string })
  | (BlipReplyStep & { type: "reply.tagged"; previous_review: BlipReview; tagged_at: string })
  | (BlipReplyStep & { type: "reply.clip_published" | "reply.clip_taken_down"; clip: BlipClip })
  /**
   * Something a person on your team should hear about (2.11): a first view, a comment, a Blip to watch, a finished watch,
   * a recording someone sent, an old guest video hidden. Show it in your own alerts; path is on Blip (BLIP_URL + path).
   */
  | {
      type: "video.alert";
      delivery_id: string;
      alert_id: string;
      kind: string;
      title: string;
      body: string | null;
      path: string | null;
      entity: { type: string | null; id: string | null };
      recipient: { user_id: string; email: string | null };
      actor_user_id: string | null;
    }
  /** Someone gave their name and email to watch a Blip behind an email gate (2.11). Not verified. */
  | { type: "video.gate_entry"; delivery_id: string; video: BlipEventVideo; entry: { id: string; name: string; email: string } }
  /** Someone started or finished a Blip through their personal link (2.11). */
  | {
      type: "video.link_milestone";
      delivery_id: string;
      video: BlipEventVideo;
      link: { id: string; person_name: string; person_email: string | null; created_by: string | null };
      milestone: "link_view" | "link_finished";
      body: string;
    }
  /**
   * A Reply clip to render, for an app with clips:render (2.11). Render it with prepareClip and clipTarget, then call
   * finishClip or failClip with job_id.
   */
  | { type: "clip.render_requested"; delivery_id: string; testimonial_id: string; reply_id: string; job_id: string; prefix: string; requested_by: string | null }
  /** A rendered clip file nobody uses any more (2.11): delete it from your storage. */
  | { type: "clip.file_retired"; delivery_id: string; key: string }
  /**
   * A support ticket (text, screenshots or a video), from a support button or Blip's own Report a problem, to apps that
   * ask for it in Settings, Developers. files[].url are signed for 7 days: copy them if you keep them. Answer
   * {ticket: {ref, url}} and the person sees ref. A video ticket also comes as video.reported, as before.
   * video.transcript_state: the recording's words aren't here (the transcript is written after the ticket is filed).
   * queued or running: ticket.transcript_ready follows if anyone speaks. done: it follows right away. none: none is coming.
   * Since 2.13 it also carries what every ticket event does (BlipTicketEvent): visitor, status_url, button.
   */
  | (BlipTicketEvent & {
      type: "ticket.created";
      ticket: BlipTicketEvent["ticket"] & { browser: string | null; viewport: string | null; errors: string[] };
      /** The same person as visitor, kept for apps built before 2.13. */
      reporter: { name: string | null; email: string | null; guest: boolean };
      files: { url: string; content_type: string; width: number; height: number }[];
      video: { id: string; url: string; transcript_state: "queued" | "running" | "done" | "none" } | null;
      project_ref: string | null;
    })
  /**
   * A message was added to a ticket (2.13): message.from says "team" (an answer: email it to visitor.email, from your
   * own domain, with status_url so they can reply) or "visitor" (they wrote back on their ticket page: tell your team).
   * video (2.18) is there when the team answered with a video: see BlipAnswerVideo. message.body is still the words
   * that go with it.
   */
  | (BlipTicketEvent & { type: "ticket.replied"; message: { id: string; from: "team" | "visitor"; author_name: string | null; body: string; via: string }; video?: BlipAnswerVideo })
  /**
   * A ticket was marked done, moved or reopened (2.13). ticket.status is where it is now, ticket.previous_status where
   * it was, ticket.solved_by who closed it (visitor, team, or no_reply: closed after silence, not solved). Not sent for
   * the move an answer or a reply makes by itself: ticket.replied already said that.
   */
  | (BlipTicketEvent & { type: "ticket.status_changed"; ticket: BlipTicketEvent["ticket"] & { previous_status: "open" | "waiting" | "done" } })
  /**
   * An answer has had no reply for the days the workspace set (2.13): ask "did that fix it?" with solved_url and
   * not_solved_url. Opening either changes nothing; the visitor presses the button on their ticket page.
   */
  | (BlipTicketEvent & { type: "ticket.solved_check" })
  /**
   * A ticket was assigned to someone on your team, or to nobody (2.19). assignee is who has it now, previous_assignee
   * who had it (each {id, name, email}, or null for nobody), by who did it. To apps that ask for it in Settings,
   * Developers; never to an email webhook.
   */
  | (BlipTicketEvent & { type: "ticket.assigned"; assignee: BlipTeamMember | null; previous_assignee: BlipTeamMember | null; by: string | null })
  /**
   * Your team added a note to a ticket (2.19). A note is your team's own: the visitor never sees it on their ticket
   * page, and it's never sent to an email webhook. Don't put it in anything they read.
   */
  | (BlipTicketEvent & { type: "ticket.note_added"; note: { id: string; author_name: string | null; body: string }; by: string | null })
  /** A ticket's tags changed (2.19): tags is all of them now, added and removed what changed, by who did it. */
  | (BlipTicketEvent & { type: "ticket.tagged"; tags: string[]; added: string[]; removed: string[]; by: string | null })
  /**
   * A message was added to a Thread, by a student, your team or the AI: notify whoever should know (a student's
   * message: the assigned coach, or everyone; a team message: the student). To apps that ask for it. Answer 2xx.
   * In a group (thread.kind "group", 2.21) it also carries `members`: the ids of the students who can read the group,
   * so you can notify them (all but message.from) and your team. `ids` stops at 200: when `complete` is false,
   * `listThreadGroupMembers` has everyone.
   */
  | { type: "thread.message"; delivery_id: string; event_key: string; thread: BlipThread; message: BlipThreadMessage; members?: { count: number; ids: string[]; complete: boolean } }
  /** A Thread was given to a coach or an assistant (thread.assigned_to), by a reply or by hand. */
  | { type: "thread.assigned"; delivery_id: string; event_key: string; thread: BlipThread; by: BlipThreadPerson | null }
  /** A waiting Thread was answered: by a reply (message_id) or marked answered by hand (message_id null). */
  | { type: "thread.answered"; delivery_id: string; event_key: string; thread: BlipThread; by: BlipThreadPerson | null; message_id: string | null }
  /** A student asked for a person instead of the AI (2.20): tell your team. Once per time they ask. */
  | { type: "thread.person_asked"; delivery_id: string; event_key: string; thread: BlipThread; by: BlipThreadPerson | null }
  /** The AI left a draft answer for your team to send, change or throw away (2.20, ai_mode "draft"). Never for the student. */
  | { type: "thread.draft"; delivery_id: string; event_key: string; thread: BlipThread; draft: BlipThreadDraft | null }
  /**
   * What Blip heard in a ticket's recording, once per video ticket, when its transcript is written (usually a few
   * minutes after ticket.created; a recording nobody speaks in never sends it). To apps that ask for it in Settings,
   * Developers. ticket.id and ticket.number are ticket.created's; ticket.ref is your own number if you answered
   * ticket.created with one. transcript.text is the words, cut at 100,000 characters (truncated says so); the timed
   * lines are at GET /videos/:id/transcript. chapters[].start is seconds into the recording. Answer 2xx.
   */
  | {
      type: "ticket.transcript_ready";
      delivery_id: string;
      event_key: string;
      ticket: { id: string; number: number; title: string; ref: string | null };
      video: { id: string; url: string };
      transcript: {
        language: string | null;
        summary: string | null;
        chapters: { start: number; title: string }[];
        action_items: { title: string; description: string; quote: string | null }[];
        text: string;
        truncated: boolean;
      };
      workspace: { id: string; name: string };
    };

/**
 * What every ticket event carries (2.13). Data only: Blip writes no email. Your tool decides what email, if any, each
 * becomes, and sends it from your own domain. event_key is the same on every retry: send once per key.
 */
export interface BlipTicketEvent {
  delivery_id: string;
  event_key: string;
  /**
   * The person who reported it. verified: Blip knows who they are: signed in to Blip, or (2.24) your own server signed
   * them with signSupportUser and Blip checked it. A name and email typed into the form aren't checked. external_id:
   * the id you signed for them, or null.
   */
  visitor: { name: string | null; first_name: string; email: string | null; verified: boolean; external_id: string | null };
  ticket: {
    id: string;
    number: number;
    /** What the visitor was shown: your own number if you answered ticket.created with one, else "#12". */
    ref: string;
    kind: "text" | "screenshot" | "video";
    /** What happened, first line. */
    title: string;
    body: string | null;
    severity: "minor" | "major";
    status: "open" | "waiting" | "done";
    /** The status as the visitor reads it: "We answered, over to you". */
    status_words: string;
    solved_by: "visitor" | "team" | "no_reply" | null;
    reopened_count: number;
    origin: "support_button" | "report_a_problem" | "team_report";
    page: string | null;
    created_at: string;
    /** Who on your team has it (2.19): by name, or null for nobody. */
    assignee: { id: string; name: string | null } | null;
    /** Its tags, from your workspace's list (2.19). */
    tags: string[];
    /**
     * ticket.created only (2.24): the requests the page made that failed before the report, where your site's script
     * tag has data-network="true". Never what was sent or received, never a header or a cookie.
     */
    network?: BlipFailedRequest[];
  };
  /** The visitor's own page for this ticket: no login, every answer, a reply box. Put it in every email. */
  status_url: string | null;
  /** The status page opened on "Did this solve it?". */
  solved_url: string | null;
  not_solved_url: string | null;
  /**
   * How a reply by email comes back (2.23). Put it in your email (a last line like "Ref: rt_...", or the reply-to
   * address support+rt_...@your-domain); when the visitor's reply reaches your mailbox, postTicketReply sends its words
   * to this ticket. It adds a reply and can read nothing.
   */
  reply_token: string | null;
  /** The support button it came through: its name, your ref for it (a product or queue), the site it was on. */
  button: { name: string; ref: string | null; site: string | null } | null;
  workspace: { id: string; name: string };
  /** Only on a "Send a test" from Settings, Email: nobody real is in it. */
  test?: boolean;
}

/** One request a page made that failed (2.24): the address has no query string; status 0 means there was no answer. */
export interface BlipFailedRequest {
  method: string;
  url: string;
  status: number;
  ms: number;
}

/** Someone on your own team, in the events about what your team did (2.19). */
export interface BlipTeamMember {
  id: string;
  name: string | null;
  email: string | null;
}

/**
 * A video answer on a ticket (2.18), in ticket.replied when the team answered with one. Data for your own email, for a
 * line like "Watch the answer (1:42)" over a picture: Blip writes no email. The event is sent once the video is ready
 * to watch, so the link and the picture work when your email arrives.
 */
export interface BlipAnswerVideo {
  id: string;
  title: string | null;
  /** The visitor's ticket page, at this answer. The video plays there; link your picture and your words to it. */
  url: string;
  /** A still of the video, served by Blip for as long as the ticket's link works. Use it as an image's address. */
  thumbnail_url: string;
  /** Its length in seconds as it plays, or null when Blip doesn't know it. */
  duration_seconds: number | null;
  /** The same as "1:42". */
  duration: string | null;
}

/** The Blip an event is about. url opens it on Blip. */
export interface BlipEventVideo {
  id: string;
  title: string;
  owner_id: string | null;
  url: string;
}

// ---- Verified visitors (2.24) ----------------------------------------------------------------------------------------

/** What signSupportUser returns: hand it to BlipSupport.identify() or <BlipSupportButton user={...} /> as it is. */
export interface BlipSignedUser {
  email: string;
  name: string;
  /** Your own id for them, when you gave one. It comes back on every ticket event as visitor.external_id. */
  id?: string;
  /** When the signature stops counting, in unix seconds. */
  expires: number;
  signature: string;
}

/**
 * Sign who's signed in to your app, on your server, so Blip can trust it (2.24). `secret` is the support button's
 * identity secret (bsi_..., from Blip, Settings, Developers, Verified visitors): keep it on your server, never in the
 * page. Give the result to the page: BlipSupport.identify(signed), or <BlipSupportButton user={signed} />.
 *
 * Blip checks it. Good: the ticket is filed under this name and email, your team sees Verified, and events carry
 * visitor.verified: true. Wrong (a changed name or email, another button's secret): ignored, as if you'd named nobody.
 * Run out: it only fills the form in. expiresIn is in seconds: an hour unless you say, 30 days at most. Sign at each
 * page load rather than once.
 *
 * What's signed, with HMAC-SHA256, hex: "v1\n<email, trimmed, lower case>\n<name, trimmed>\n<id or empty>\n<expires>".
 */
export function signSupportUser(secret: string, user: { email: string; name?: string | null; id?: string | number | null }, o: { expiresIn?: number; nowMs?: number } = {}): BlipSignedUser {
  const email = String(user.email ?? "").trim().toLowerCase();
  const name = String(user.name ?? "").trim();
  const id = user.id === null || user.id === undefined ? "" : String(user.id).trim();
  if (!secret) throw new Error(`signSupportUser needs the support button's identity secret (${NAME}, Settings, Developers, Verified visitors).`);
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || email.length > 254) throw new Error("signSupportUser needs the person's email.");
  if (name.length > 120 || id.length > 200 || /[\r\n]/.test(name + id)) throw new Error("signSupportUser: the name is 120 characters at most and the id 200, each on one line.");
  const expires = Math.floor((o.nowMs ?? Date.now()) / 1000) + Math.min(Math.max(1, Math.floor(o.expiresIn ?? 3600)), 30 * 86_400);
  const signature = createHmac("sha256", secret).update(["v1", email, name, id, String(expires)].join("\n")).digest("hex");
  return { email, name, ...(id ? { id } : {}), expires, signature };
}

/** hex HMAC-SHA256 of `${x-blip-timestamp}.${rawBody}`, within five minutes. Read the raw body before parsing it. */
export function verifyWebhook(secret: string, rawBody: string, timestamp: string | null, signature: string | null, nowMs = Date.now()): boolean {
  if (!secret || !timestamp || !signature || !/^\d{9,11}$/.test(timestamp) || !/^[0-9a-f]{64}$/.test(signature)) return false;
  if (Math.abs(nowMs / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const want = Buffer.from(createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"), "hex");
  const got = Buffer.from(signature, "hex");
  return want.length === got.length && timingSafeEqual(want, got);
}

/** Fetch's Headers (Next.js, Remix, Hono, Bun) or Node's req.headers object (Express, Fastify). */
export type BlipHeaders = { get(name: string): string | null } | Record<string, string | string[] | undefined>;

function header(h: BlipHeaders, name: string): string | null {
  if (typeof (h as { get?: unknown }).get === "function") return (h as { get(n: string): string | null }).get(name);
  const v = (h as Record<string, string | string[] | undefined>)[name] ?? (h as Record<string, string | string[] | undefined>)[name.toLowerCase()];
  return Array.isArray(v) ? (v[0] ?? null) : (v ?? null);
}

/**
 * The webhook, verified and parsed, or null (answer 401). The same delivery can come twice: dedupe on delivery_id.
 * rawBody is the body exactly as it came, before any JSON parsing (Next.js: await req.text(); Express:
 * express.raw({ type: "application/json" }) on this route, then req.body.toString("utf8")).
 */
export function readWebhook(secret: string, rawBody: string, headers: BlipHeaders, nowMs = Date.now()): BlipWebhook | null {
  if (!verifyWebhook(secret, rawBody, header(headers, "x-blip-timestamp"), header(headers, "x-blip-signature"), nowMs)) return null;
  try {
    const w = JSON.parse(rawBody) as BlipWebhook;
    return w && typeof w.type === "string" && typeof w.delivery_id === "string" ? w : null;
  } catch {
    return null;
  }
}