@chatwarden/player-react 0.0.0-stage → 0.1.2

package/src/RulesPage.tsx

@@ -0,0 +1,49 @@
+import { useId } from 'react';
+import type { PlayerClient } from './client.js';
+import { usePlayerData } from './hooks.js';
+import { ErrorBlock, Root, useUi } from './ui.js';
+import type { PlayerUiProps } from './ui.js';
+
+export interface RulesPageProps extends PlayerUiProps {
+  client: PlayerClient;
+  /** Change it to load the rules again. */
+  refreshKey?: number | string;
+}
+
+/** The community rules: the profile's summary and the numbered rules from `GET /rules`. Text only, never HTML. */
+export function RulesPage(props: RulesPageProps) {
+  const { client, refreshKey, theme, className } = props;
+  const ui = useUi(props);
+  const { t } = ui;
+  const state = usePlayerData(() => client.rules(), refreshKey);
+  const titleId = useId();
+  const data = state.data;
+
+  return (
+    <Root theme={theme} className={className}>
+      <section className="cw-section" aria-labelledby={titleId}>
+        <h2 id={titleId} className="cw-title">
+          {t('player.rules.title')}
+        </h2>
+        {state.error !== null && <ErrorBlock ui={ui} what={t('player.rules.loadFailed')} error={state.error} onRetry={state.reload} />}
+        {data === undefined && state.error === null && (
+          <p className="cw-state" role="status">
+            {t('player.rules.loading')}
+          </p>
+        )}
+        {data !== undefined && data.summary !== '' && <p className="cw-summary">{data.summary}</p>}
+        {data !== undefined && data.rules.length === 0 && <p className="cw-state">{t('player.rules.empty')}</p>}
+        {data !== undefined && data.rules.length > 0 && (
+          // The kit's own numbers, so a retired rule leaves a gap instead of renumbering the ones after it.
+          <ol className="cw-rules" aria-labelledby={titleId}>
+            {data.rules.map((rule) => (
+              <li key={rule.number} value={rule.number}>
+                <strong className="cw-rule-title">{rule.title}</strong> <span className="cw-rule-text">{rule.text}</span>
+              </li>
+            ))}
+          </ol>
+        )}
+      </section>
+    </Root>
+  );
+}

package/src/client.ts

@@ -0,0 +1,132 @@
+import type { PlayerNotice, PlayerReporting } from '@chatwarden/core';
+import { readReporting } from './reporting.js';
+import type { Transport, TransportRequest, TransportResponse } from './transport.js';
+
+/**
+ * Why a call to the player routes failed. `status` is the HTTP status, or 0 when no answer arrived. `code` is the kit's error
+ * code (`not_found`, `rate_limited`, ...), `network` for a dropped connection, `bad_response` for an answer that is not the
+ * shape the components expect, `unexpected` for anything else, and `http_<status>` when the body is not a kit error.
+ * `retryAfter` is the seconds from a `retry-after` header (a 429).
+ */
+export class PlayerError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly retryAfter: number | undefined;
+
+  constructor(init: { status: number; code: string; message: string; retryAfter?: number }) {
+    super(init.message);
+    this.name = 'PlayerError';
+    this.status = init.status;
+    this.code = init.code;
+    this.retryAfter = init.retryAfter;
+  }
+}
+
+/** A `PlayerError` as is; anything else (a bug in the caller's code, say) becomes status 0, code `unexpected`. */
+export function toPlayerError(e: unknown): PlayerError {
+  if (e instanceof PlayerError) return e;
+  return new PlayerError({ status: 0, code: 'unexpected', message: e instanceof Error ? e.message : 'Something went wrong.' });
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v: unknown): v is string => typeof v === 'string';
+
+function errorOf(res: TransportResponse): PlayerError {
+  const b = res.body;
+  const raw = res.headers['retry-after'];
+  const rest = raw !== undefined && /^\d{1,9}$/.test(raw) ? { retryAfter: Number(raw) } : {};
+  if (isObject(b) && text(b.error) && text(b.message)) return new PlayerError({ status: res.status, code: b.error, message: b.message, ...rest });
+  // A proxy's HTML page, or an empty body: say the status, never echo the body.
+  return new PlayerError({ status: res.status, code: `http_${res.status}`, message: `The server answered with status ${res.status}.`, ...rest });
+}
+
+async function send(transport: Transport, req: TransportRequest): Promise<unknown> {
+  let res: TransportResponse;
+  try {
+    res = await transport(req);
+  } catch (e) {
+    throw new PlayerError({ status: 0, code: 'network', message: e instanceof Error && e.name === 'AbortError' ? 'The request was cancelled.' : 'Could not reach the server.' });
+  }
+  if (res.status < 200 || res.status > 299) throw errorOf(res);
+  return res.body;
+}
+
+const bad = (): PlayerError => new PlayerError({ status: 200, code: 'bad_response', message: 'The server sent an answer these components do not understand.' });
+
+/** One notice, keeping only the fields the kit documents for a player. Anything else the server sent never reaches the page. */
+function noticeOf(raw: unknown): PlayerNotice | null {
+  if (!isObject(raw) || !text(raw.id) || !text(raw.kind)) return null;
+  const excerpt = Array.isArray(raw.excerpt)
+    ? raw.excerpt.filter(isObject).filter((l) => text(l.text) && text(l.day)).map((l) => ({ text: l.text as string, day: l.day as string }))
+    : [];
+  return {
+    id: raw.id,
+    kind: raw.kind as PlayerNotice['kind'],
+    rule: typeof raw.rule === 'number' || raw.rule === 'uncovered' ? raw.rule : null,
+    ruleLabel: text(raw.ruleLabel) ? raw.ruleLabel : null,
+    until: typeof raw.until === 'number' && Number.isFinite(raw.until) ? raw.until : null,
+    refCode: text(raw.refCode) ? raw.refCode : null,
+    excerpt,
+    createdAt: typeof raw.createdAt === 'number' && Number.isFinite(raw.createdAt) ? raw.createdAt : 0,
+    mustAcknowledge: raw.mustAcknowledge === true,
+  };
+}
+
+function noticesOf(body: unknown, key: 'notices' | 'record'): PlayerNotice[] {
+  if (!isObject(body) || !Array.isArray(body[key])) throw bad();
+  return (body[key] as unknown[]).map(noticeOf).filter((n): n is PlayerNotice => n !== null);
+}
+
+/** One rule as `GET /rules` gives it. */
+export interface PlayerRule {
+  number: number;
+  title: string;
+  text: string;
+}
+
+/** `GET /rules`: the profile's one-line summary, the active rules and how reporting works here (`undefined` from an older server). */
+export interface PlayerRules {
+  summary: string;
+  rules: PlayerRule[];
+  /** The flow, the reasons a player may give and the thank-you: pass it to `ReportDialog` as `reporting`. */
+  reporting?: PlayerReporting;
+}
+
+export interface PlayerClient {
+  /** `GET /notices`: notices not yet acknowledged, as the kit sends them (oldest first). */
+  notices(): Promise<PlayerNotice[]>;
+  /** `POST /notices/:id/ack`: `true` when it was this player's live notice, `false` (still a 200) when it was not, or it is gone. */
+  ack(id: string): Promise<boolean>;
+  /** `GET /record`: the player's sanctions that still apply (seen or not). */
+  record(): Promise<PlayerNotice[]>;
+  /** `GET /rules`: the summary, the numbered rules and the reporting settings. */
+  rules(): Promise<PlayerRules>;
+}
+
+export interface PlayerClientOptions {
+  /** How to reach the player routes: `fetchTransport({ baseUrl: '/player' })`, or any function with the same shape. */
+  transport: Transport;
+}
+
+/** A client over the kit's player routes. It resolves with typed values and rejects with a `PlayerError`. */
+export function createPlayerClient({ transport }: PlayerClientOptions): PlayerClient {
+  return {
+    notices: async () => noticesOf(await send(transport, { method: 'GET', path: '/notices' }), 'notices'),
+    record: async () => noticesOf(await send(transport, { method: 'GET', path: '/record' }), 'record'),
+    ack: async (id) => {
+      const body = await send(transport, { method: 'POST', path: `/notices/${encodeURIComponent(id)}/ack` });
+      if (!isObject(body) || typeof body.ok !== 'boolean') throw bad();
+      return body.ok;
+    },
+    rules: async () => {
+      const body = await send(transport, { method: 'GET', path: '/rules' });
+      if (!isObject(body) || !text(body.summary) || !Array.isArray(body.rules)) throw bad();
+      const rules = body.rules
+        .filter(isObject)
+        .filter((r) => typeof r.number === 'number' && text(r.title) && text(r.text))
+        .map((r) => ({ number: r.number as number, title: r.title as string, text: r.text as string }));
+      const reporting = readReporting(body.reporting);
+      return { summary: body.summary, rules, ...(reporting === undefined ? {} : { reporting }) };
+    },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+/** The longest note the kit keeps (a test keeps this the same as core's `REPORT_NOTE_MAX`). */
+export const NOTE_MAX = 500;
+
+/** How many days a warning stays on a record (a test keeps this the same as core's notice record window). */
+export const WARNING_DAYS = 90;

package/src/format.ts

@@ -0,0 +1,53 @@
+// Small pure helpers for showing days, times and waits. Times use Intl with the component's `locale`; none holds English.
+
+const MIN = 60_000;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+function safeLocale(locale: string): string {
+  try {
+    return Intl.getCanonicalLocales(locale)[0] ?? 'en';
+  } catch {
+    return 'en';
+  }
+}
+
+/** Some runtimes put a narrow no-break space before "PM". A plain space reads the same and survives a copy. */
+const plain = (text: string): string => text.replace(/[\u202f\u00a0]/g, ' ');
+
+/**
+ * A UTC day from the kit (`2027-01-15`) as the locale writes a date (`Jan 15, 2027`), in UTC whatever the viewer's zone: the kit
+ * names the day in UTC, so a notice never shows a different day than the moderator's tools. A value that is not a day comes back
+ * as it was; it is never shown as "Invalid Date".
+ */
+export function dayText(day: string, locale: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+  if (m === null) return day;
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const date = new Date(Date.UTC(y, mo - 1, d));
+  if (date.getUTCFullYear() !== y || date.getUTCMonth() !== mo - 1 || date.getUTCDate() !== d) return day;
+  return new Intl.DateTimeFormat(safeLocale(locale), { dateStyle: 'medium', timeZone: 'UTC' }).format(date);
+}
+
+/** A date and time: `Jan 15, 2027, 8:30 PM`. Pass a time zone for a fixed one; the default is the viewer's. An unknown zone is ignored. */
+export function untilText(at: number, locale: string, timeZone?: string): string {
+  const options: Intl.DateTimeFormatOptions = { dateStyle: 'medium', timeStyle: 'short' };
+  try {
+    return plain(new Intl.DateTimeFormat(safeLocale(locale), { ...options, ...(timeZone === undefined ? {} : { timeZone }) }).format(at));
+  } catch {
+    return plain(new Intl.DateTimeFormat(safeLocale(locale), options).format(at));
+  }
+}
+
+/**
+ * How long is left until `at`, as the locale says it ("in 3 hours"): minutes under an hour (a part of a minute counts as a whole
+ * one, so a live restriction never reads "in 0 minutes"), hours under two days, then days. Null when `at` is now or has passed.
+ */
+export function timeLeft(at: number, now: number, locale: string): string | null {
+  const left = at - now;
+  if (!(left > 0)) return null;
+  const rtf = new Intl.RelativeTimeFormat(safeLocale(locale), { numeric: 'always' });
+  if (left < HOUR) return rtf.format(Math.max(1, Math.ceil(left / MIN)), 'minute');
+  if (left < 2 * DAY) return rtf.format(Math.round(left / HOUR), 'hour');
+  return rtf.format(Math.round(left / DAY), 'day');
+}

package/src/hooks.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { PlayerError, toPlayerError } from './client.js';
+
+export interface PlayerData<T> {
+  /** The last answer, kept when a later load fails. */
+  data: T | undefined;
+  /** The last failure, or null. Cleared when a load starts. */
+  error: PlayerError | null;
+  /** Starts the same load again. */
+  reload: () => void;
+}
+
+/**
+ * Runs `load` on mount, again when `refreshKey` changes, and again on `reload()`. An answer from a load that has been replaced
+ * (or from a component that is gone) is dropped, so a slow old request never overwrites a newer one.
+ */
+export function usePlayerData<T>(load: () => Promise<T>, refreshKey: unknown): PlayerData<T> {
+  const [state, setState] = useState<{ data: T | undefined; error: PlayerError | null }>({ data: undefined, error: null });
+  const [again, setAgain] = useState(0);
+  const loader = useRef(load);
+  loader.current = load;
+
+  useEffect(() => {
+    let live = true;
+    setState((s) => (s.error === null ? s : { ...s, error: null }));
+    loader.current().then(
+      (data) => {
+        if (live) setState({ data, error: null });
+      },
+      (e: unknown) => {
+        if (live) setState((s) => ({ data: s.data, error: toPlayerError(e) }));
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [refreshKey, again]);
+
+  const reload = useCallback(() => setAgain((n) => n + 1), []);
+  return { data: state.data, error: state.error, reload };
+}

package/src/i18n.ts

@@ -0,0 +1,187 @@
+// Every word the player components show is a key in this catalog; components never hold English.
+//
+// Key naming: `player.<area>.<thing>[.<detail>]`, lower camel case segments, for example `player.notice.title.warning`.
+// Areas: error, state, notice, notices, record, rules, restricted, report.
+// Plural forms add the CLDR category as the last segment: `player.report.remaining.one`, `.other`. A caller asks for the base
+// key with a numeric `count` (`t('player.report.remaining', { count: 3 })`); `.zero` is used for 0 when it exists.
+// `{name}` marks a value to fill in. To translate, spread this catalog over yours so a missing key falls back to English:
+// `createT({ ...en, ...de }, 'de')`.
+//
+// The copy is written for a player in the middle of a game: second person, sentence case, plain words, and never shaming. It says
+// what happened, until when, and what the player can do.
+
+export const en = {
+  'player.error.network': 'Could not reach the server. Check your connection and try again.',
+  'player.error.unauthorized': 'You are signed out. Sign in again, then try again.',
+  'player.error.forbidden': 'This account cannot do that.',
+  'player.error.notFound': 'That could not be found.',
+  'player.error.rateLimited': 'Too many requests. Try again in a moment.',
+  'player.error.rateLimited.after.one': 'Too many requests. Try again in {count} second.',
+  'player.error.rateLimited.after.other': 'Too many requests. Try again in {count} seconds.',
+  'player.error.server': 'The server had a problem. Try again in a moment.',
+  'player.error.generic': 'Something went wrong.',
+
+  'player.state.retry': 'Try again',
+
+  'player.notices.loadFailed': 'We could not check for notices.',
+
+  'player.notice.title.warning': 'You have a warning',
+  'player.notice.title.chat': 'Your chat is turned off',
+  'player.notice.title.area': 'You cannot join public rooms',
+  'player.notice.title.ban': 'You are banned',
+  'player.notice.title.report_outcome': 'Thanks for your report',
+  'player.notice.title.fallback': 'A message from the moderators',
+  'player.notice.body.warning': 'A moderator gave you a warning for something you wrote. You can keep playing.',
+  'player.notice.body.chat': 'A moderator turned off your chat. You can still play.',
+  'player.notice.body.area': 'A moderator stopped you joining public rooms and matchmaking. You can still play in private rooms.',
+  'player.notice.body.ban': 'A moderator banned you from playing.',
+  'player.notice.body.report_outcome': 'A moderator looked at your report and took action. We do not share what was done.',
+  'player.notice.body.fallback': 'There is a new message about your account.',
+  'player.notice.position': 'Notice {n} of {total}',
+  'player.notice.rule': 'Rule',
+  'player.notice.given': 'Given',
+  'player.notice.until': 'Until',
+  'player.notice.ended': 'Ended',
+  'player.notice.noEnd': 'No end date',
+  'player.notice.onRecordUntil': 'On your record until',
+  'player.notice.untilLeft': '{when} ({left})',
+  'player.notice.ref': 'Reference',
+  'player.notice.refHint': 'Quote this code if you contact us.',
+  'player.notice.lines': 'Your messages that led to this',
+  'player.notice.todo.warning': 'Press Acknowledge to confirm you saw this.',
+  'player.notice.acknowledge': 'Acknowledge',
+  'player.notice.gotIt': 'Got it',
+  'player.notice.appeal': 'Think this is a mistake?',
+  'player.notice.ackFailed': 'Your notice is still here.',
+  'player.notice.closeForNow': 'Close for now',
+
+  'player.record.title': 'Your record',
+  'player.record.loading': 'Loading your record',
+  'player.record.loadFailed': 'We could not load your record.',
+  'player.record.intro': 'This is what is on your record now. A warning stays for {days} days.',
+  'player.record.empty': 'Your record is clear. Nothing is on it right now.',
+  'player.record.kind.warning': 'Warning',
+  'player.record.kind.chat': 'Chat restriction',
+  'player.record.kind.area': 'Public rooms restriction',
+  'player.record.kind.ban': 'Ban',
+  'player.record.kind.fallback': 'Notice',
+
+  'player.rules.title': 'Community rules',
+  'player.rules.loading': 'Loading the rules',
+  'player.rules.loadFailed': 'We could not load the rules.',
+  'player.rules.empty': 'No rules are published yet.',
+
+  'player.restricted.moderator.until': 'A moderator turned off your chat until {when} ({left}).',
+  'player.restricted.moderator.noEnd': 'A moderator turned off your chat. It does not end on its own.',
+  'player.restricted.filter.until': 'Your chat is off until {when} ({left}). The automatic filter caught a message.',
+  'player.restricted.filter.noEnd': 'Your chat is off. It does not end on its own. The automatic filter caught a message.',
+  'player.restricted.ended': 'Your chat is back on. The restriction ended {when}.',
+  'player.restricted.ref': 'Reference {code}',
+
+  'player.report.title': 'Report a player',
+  'player.report.titleNamed': 'Report {name}',
+  'player.report.intro': 'Tell us what happened and a moderator will look at it.',
+  'player.report.legend': 'What happened?',
+  'player.report.titleOneTap': 'Report this message?',
+  'player.report.titleOneTapNamed': 'Report {name}?',
+  'player.report.titleOneTapPlayer': 'Report this player?',
+  'player.report.titleSent': 'Report sent',
+  'player.report.titleRefused': "Couldn't send the report",
+  'player.report.oneTap.intro': 'We will pass it to the moderators. You do not need to say why.',
+  'player.report.oneTap.send': 'Report',
+  'player.report.quote': '“{line}”',
+  'player.report.skip': 'Skip and report',
+  'player.report.needReason': 'Choose a reason.',
+  'player.report.needReasonOrSkip': 'Choose what happened, or skip.',
+  'player.report.addReason': 'Add a reason',
+  'player.report.addReasonHint': 'This helps, but the moderators decide what it really is. You can add this for a few minutes after you report.',
+  'player.report.detail.legend': 'What was it about?',
+  'player.report.detail.send': 'Add to my report',
+  'player.report.detail.need': 'Choose a reason or write a note.',
+  'player.report.detail.added': 'Added. Thanks.',
+  'player.report.detail.failed': 'We could not add that.',
+  'player.report.detail.refused.off': 'Adding to a report is not available right now.',
+  'player.report.detail.refused.not_found': 'We cannot find that report any more.',
+  'player.report.detail.refused.not_reporter': 'Only the player who sent a report can add to it.',
+  'player.report.detail.refused.too_late': 'It is too late to add to this report. We still have the report.',
+  'player.report.detail.refused.already_added': 'You already added to this report.',
+  'player.report.detail.refused.reason_unknown': 'That reason is not available any more. Your report is still with us.',
+  'player.report.note': 'Add a note (optional)',
+  'player.report.noteHint': 'A moderator will read this. Up to {max} characters. Do not include passwords or personal details.',
+  'player.report.send': 'Send report',
+  'player.report.cancel': 'Cancel',
+  'player.report.close': 'Close',
+  'player.report.failed': 'Your report was not sent.',
+  'player.report.thanks': 'Thanks. We got your report.',
+  'player.report.remaining.zero': 'You have no more reports left today.',
+  'player.report.remaining.one': 'You can send {count} more report today.',
+  'player.report.remaining.other': 'You can send {count} more reports today.',
+  'player.report.refused.duplicate': 'You already reported this player here. We have your report.',
+  'player.report.refused.rate': 'You have sent as many reports as you can today. You can send more tomorrow.',
+  'player.report.refused.self': 'You cannot report yourself.',
+  'player.report.refused.not_player': 'We cannot find that player any more. They may have left.',
+  'player.report.refused.off': 'Reports are not available right now. Try again later.',
+  'player.report.refused.suspended': 'You cannot send reports from this account for now.',
+  'player.report.refused.reason_required': 'This report needs a reason. Close this and report again to choose one.',
+  'player.report.refused.reason_unknown': 'That reason is not available any more. Close this and report again.',
+  'player.report.refused.unknown': 'We could not take that report.',
+} as const;
+
+/** A catalog: keys to English (or translated) text. Any object of strings will do. */
+export type PlayerCatalog = Readonly<Record<string, string>>;
+
+type PluralForm = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type BaseKey<K extends string> = K extends `${infer B}.${PluralForm}` ? B : K;
+
+/** Every key a component may ask for: the English catalog's keys with the plural suffix taken off. */
+export type PlayerText = BaseKey<keyof typeof en>;
+
+export type PlayerParams = Readonly<Record<string, string | number>>;
+
+/** The `t` the components take: a key and optional values, always a string back. */
+export type PlayerT = (key: PlayerText, params?: PlayerParams) => string;
+
+const isCount = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * Builds the `t` function for a catalog and a locale.
+ * - `{name}` is replaced by `params.name`; a name with no value stays as written; a value is never expanded again.
+ * - Numbers are formatted for the locale (`1,234`).
+ * - With a numeric `count`, the plural form for the locale is used (`key.one`, `key.other`, ...), `key.zero` for 0 if it
+ *   exists, and `key.other` when the locale's form is missing.
+ * - A key with no text comes back as the key itself, so a gap in a translation is visible instead of blank.
+ */
+export function createT(catalog: PlayerCatalog, locale = 'en'): PlayerT {
+  let numbers: Intl.NumberFormat;
+  let plurals: Intl.PluralRules;
+  try {
+    numbers = new Intl.NumberFormat(locale);
+    plurals = new Intl.PluralRules(locale);
+  } catch {
+    numbers = new Intl.NumberFormat('en');
+    plurals = new Intl.PluralRules('en');
+  }
+  const has = (key: string): boolean => Object.hasOwn(catalog, key);
+
+  return (key, params) => {
+    let template: string | undefined;
+    const count = params?.count;
+    if (isCount(count)) {
+      const form = count === 0 && has(`${key}.zero`) ? 'zero' : plurals.select(count);
+      for (const candidate of [`${key}.${form}`, `${key}.other`]) {
+        if (has(candidate)) {
+          template = catalog[candidate];
+          break;
+        }
+      }
+    }
+    template ??= has(key) ? catalog[key] : undefined;
+    if (template === undefined) return key;
+    if (params === undefined) return template;
+    return template.replace(/\{([a-zA-Z]+)\}/g, (whole, name: string) => {
+      if (!Object.hasOwn(params, name)) return whole;
+      const value = params[name];
+      return typeof value === 'number' ? numbers.format(value) : String(value);
+    });
+  };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export const VERSION = '0.1.2';
+
+export { NoticeQueue } from './NoticeQueue.js';
+export type { NoticeQueueProps } from './NoticeQueue.js';
+export { MyRecord } from './MyRecord.js';
+export type { MyRecordProps } from './MyRecord.js';
+export { RulesPage } from './RulesPage.js';
+export type { RulesPageProps } from './RulesPage.js';
+export { ReportDialog } from './ReportDialog.js';
+export type { ReportFollowUp, ReportDialogProps, ReportDraft } from './ReportDialog.js';
+export { RestrictedChatLine } from './RestrictedChatLine.js';
+export type { RestrictedChatLineProps } from './RestrictedChatLine.js';
+
+export { createPlayerClient, PlayerError, toPlayerError } from './client.js';
+export type { PlayerClient, PlayerClientOptions, PlayerRule, PlayerRules } from './client.js';
+export { fetchTransport, routerTransport } from './transport.js';
+export type {
+  FetchTransportOptions,
+  RouterRequest,
+  RouterResponse,
+  RouterTransportOptions,
+  Transport,
+  TransportRequest,
+  TransportResponse,
+} from './transport.js';
+
+export { createT, en } from './i18n.js';
+export type { PlayerCatalog, PlayerParams, PlayerT, PlayerText } from './i18n.js';
+export type { PlayerUiProps } from './ui.js';
+export { dayText, timeLeft, untilText } from './format.js';
+
+export type { NoticeKind, PlayerNotice, PlayerReporting, ReportDetailResult, ReportFlow, ReportRefusal, ReportResult } from '@chatwarden/core';

package/src/reporting.ts

@@ -0,0 +1,51 @@
+import type { PlayerReporting, ReportFlow } from '@chatwarden/core';
+
+const FLOWS: readonly ReportFlow[] = ['one_tap', 'reason_first', 'reason_required'];
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v: unknown): v is string => typeof v === 'string';
+
+/**
+ * The reporting payload of `GET /rules` as the dialog may rely on it. Anything that is not the documented shape is dropped: a
+ * reason needs a text id and label; the hint and group default to `''` and `asksNote` to false; an unknown flow is `one_tap` (the
+ * default); a field the server should not send (a rule mapping, an enabled flag) is never copied. `undefined` when there is no
+ * list of reasons at all (an older server, or something that is not the payload).
+ */
+export function readReporting(raw: unknown): PlayerReporting | undefined {
+  if (!isObject(raw) || !Array.isArray(raw.reasons)) return undefined;
+  const reasons = raw.reasons
+    .filter(isObject)
+    .filter((r) => text(r.id) && r.id !== '' && text(r.label) && r.label !== '')
+    .map((r) => ({ id: r.id as string, label: r.label as string, hint: text(r.hint) ? r.hint : '', group: text(r.group) ? r.group : '', asksNote: r.asksNote === true }));
+  const flow = FLOWS.find((f) => f === raw.flow) ?? 'one_tap';
+  return { flow, reasons, thanks: text(raw.thanks) ? raw.thanks : '' };
+}
+
+export type ReasonItem = PlayerReporting['reasons'][number];
+
+/** A heading (`''` for none) and the reasons under it. */
+export interface ReasonGroup {
+  name: string;
+  items: ReasonItem[];
+}
+
+/**
+ * The reasons grouped for the screen: a group is where its first reason is in the list, "Something else" (`other`) is always
+ * last, and a group with no name has no heading.
+ */
+export function groupReasons(reasons: readonly ReasonItem[]): ReasonGroup[] {
+  const groups: ReasonGroup[] = [];
+  for (const r of reasons) {
+    if (r.id === 'other') continue;
+    const into = groups.find((g) => g.name === r.group);
+    if (into === undefined) groups.push({ name: r.group, items: [r] });
+    else into.items.push(r);
+  }
+  const other = reasons.find((r) => r.id === 'other');
+  if (other !== undefined) {
+    const last = groups.at(-1);
+    if (last !== undefined && last.name === '') last.items.push(other);
+    else groups.push({ name: '', items: [other] });
+  }
+  return groups;
+}

package/src/safeHref.ts

@@ -0,0 +1,36 @@
+// The rule for a link address, copied from `@chatwarden/hub-react` (its `isSafeHref`, which guards links in policy documents).
+// The two packages never import each other, so this is a copy; test/safe-href.test.ts runs both on one table.
+
+function hasControlOrSpace(text: string): boolean {
+  for (const ch of text) {
+    const c = ch.codePointAt(0) as number;
+    if (c <= 0x20 || (c >= 0x7f && c <= 0x9f)) return true;
+  }
+  return false;
+}
+
+/** Whether an address may become a link: `https:` (with a host), or a relative address on this site. */
+export function isSafeHref(href: string): boolean {
+  // A control character or space inside an address is how `java\tscript:` slips past a scheme check: refuse them all.
+  const s = href.trim();
+  if (s === '' || hasControlOrSpace(s) || /\s/u.test(s)) return false;
+  // A browser reads `\` as `/`, so `/\evil.example` is `//evil.example`, a different site: refuse a backslash anywhere, and a
+  // slash that is followed by another slash or by anything that could be read as one.
+  if (s.includes('\\') || /^\/[\s/]/u.test(s)) return false;
+  // An address that carries an entity is not one an adopter wrote: refuse.
+  if (/&#?\w+;/.test(s)) return false;
+  const scheme = /^([^/?#]*):/.exec(s);
+  if (scheme === null) return true;
+  try {
+    const url = new URL(s);
+    return url.protocol === 'https:' && url.hostname !== '';
+  } catch {
+    return false;
+  }
+}
+
+/** The address for an appeal link (trimmed), or null when it is not safe to link to. `http:` is refused: https only. */
+export function safeHref(url: string | undefined): string | null {
+  if (typeof url !== 'string') return null;
+  return isSafeHref(url) ? url.trim() : null;
+}