@takosjp/yurucommu-core 3.0.0

package/packages/api/src/lib/api/fetch.ts

@@ -0,0 +1,111 @@
+/**
+ * Fetch wrapper with consistent configuration.
+ * All API calls should use this wrapper so frontend plugins can override
+ * transport behavior (URL resolution, auth headers, credentials mode).
+ */
+
+import {
+  fetchWithTimeout,
+  type FetchWithTimeoutInit,
+} from "../fetch-with-timeout.ts";
+import { getYurucommuApiTransport } from "../transport.ts";
+
+/**
+ * Custom error class for API responses that includes the HTTP status code.
+ */
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    // `message` is the human-facing server error (or a caller fallback); the
+    // HTTP status lives on `.status`. Keep `.message` clean — many UI surfaces
+    // render `err.message` verbatim in an error box, and a "<status>: " prefix
+    // reads as technical noise (e.g. "422: Add this account as an alias…").
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/**
+ * Read an error message from a failed API response. Attempts to parse JSON
+ * with an `error` field; falls back to `statusText`.
+ */
+export async function extractErrorMessage(
+  res: Response,
+  fallback: string,
+): Promise<string> {
+  try {
+    const data = (await res.json()) as {
+      error?: string | { message?: string };
+    };
+    // The server uses a flat `{ error: "message" }` envelope. Defensively also
+    // unwrap a nested `{ error: { message } }` so a stray non-flat error never
+    // renders as the "[object Object]" stringification.
+    const err = data.error;
+    const message = typeof err === "string" ? err : err?.message;
+    return message || fallback;
+  } catch {
+    return res.statusText || fallback;
+  }
+}
+
+/**
+ * Assert that a response is OK. Throws an `ApiError` with the status code
+ * and a message extracted from the response body when it is not.
+ */
+export async function assertOk(res: Response, fallback: string): Promise<void> {
+  if (!res.ok) {
+    const message = await extractErrorMessage(res, fallback);
+    throw new ApiError(res.status, message);
+  }
+}
+
+export interface ApiRequestInit extends FetchWithTimeoutInit {}
+
+export function apiFetch(
+  url: string,
+  options: ApiRequestInit = {},
+): Promise<Response> {
+  const transport = getYurucommuApiTransport();
+  const apiUrl = transport.resolveUrl(url);
+  const headers = new Headers(options.headers);
+
+  const authHeaders = transport.getAuthHeaders(url);
+  for (const [key, value] of Object.entries(authHeaders)) {
+    if (!headers.has(key)) {
+      headers.set(key, value);
+    }
+  }
+
+  return fetchWithTimeout(apiUrl, {
+    ...options,
+    headers,
+    credentials: options.credentials ?? transport.credentials,
+  });
+}
+
+function createApiMethod(method: string) {
+  return async (
+    url: string,
+    body?: unknown,
+    options: Omit<ApiRequestInit, "method" | "body"> = {},
+  ): Promise<Response> => {
+    const headers = new Headers(options.headers);
+    if (body) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    return await apiFetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      ...options,
+    });
+  };
+}
+
+export const apiPost = createApiMethod("POST");
+export const apiPut = createApiMethod("PUT");
+export const apiPatch = createApiMethod("PATCH");
+export const apiDelete = createApiMethod("DELETE");

package/packages/api/src/lib/api/follow.ts

@@ -0,0 +1,30 @@
+import { apiDelete, apiPost, assertOk } from "./fetch.ts";
+
+export async function follow(targetApId: string): Promise<{ status: string }> {
+  const res = await apiPost("/api/follow", { target_ap_id: targetApId });
+  await assertOk(res, "Failed to follow");
+  return (await res.json()) as { status: string };
+}
+
+export async function unfollow(targetApId: string): Promise<void> {
+  const res = await apiDelete("/api/follow", { target_ap_id: targetApId });
+  await assertOk(res, "Failed to unfollow");
+}
+
+export async function acceptFollowRequest(
+  requesterApId: string,
+): Promise<void> {
+  const res = await apiPost("/api/follow/accept", {
+    requester_ap_id: requesterApId,
+  });
+  await assertOk(res, "Failed to accept");
+}
+
+export async function rejectFollowRequest(
+  requesterApId: string,
+): Promise<void> {
+  const res = await apiPost("/api/follow/reject", {
+    requester_ap_id: requesterApId,
+  });
+  await assertOk(res, "Failed to reject");
+}

package/packages/api/src/lib/api/media.ts

@@ -0,0 +1,100 @@
+import { apiFetch, assertOk } from "./fetch.ts";
+import { UPLOAD_REQUEST_TIMEOUT_MS } from "../fetch-with-timeout.ts";
+
+// Allowed MIME types for media uploads
+export const allowedMimeTypes = [
+  // Images
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  // Videos
+  "video/mp4",
+  "video/webm",
+] as const;
+
+export type AllowedMimeType = (typeof allowedMimeTypes)[number];
+
+// Maximum file sizes MUST match the backend media route (MAX_IMAGE_SIZE /
+// MAX_VIDEO_SIZE in src/backend/routes/media.ts). When the client video cap was
+// 100MB but the server cap was 40MB (and the pre-route body limit 48 MiB), a
+// 48–100MB video passed client validation and was then rejected by the body
+// limit with an opaque "body_too_large" error instead of a friendly up-front
+// message. Keep these in lockstep with the backend.
+export const maxImageFileSize = 20 * 1024 * 1024;
+export const maxVideoFileSize = 40 * 1024 * 1024;
+
+// Filename validation regex: alphanumeric, dots, hyphens, underscores
+const filenameRegex = /^[\w\-. ]+$/;
+
+export class FileValidationError extends Error {
+  constructor(
+    message: string,
+    public code: "INVALID_TYPE" | "FILE_TOO_LARGE" | "INVALID_FILENAME",
+  ) {
+    super(message);
+    this.name = "FileValidationError";
+  }
+}
+
+/**
+ * Validate a file before upload
+ * @throws FileValidationError if validation fails
+ */
+export function validateFile(file: File): void {
+  // Check file type
+  if (!allowedMimeTypes.includes(file.type as AllowedMimeType)) {
+    throw new FileValidationError(
+      `Invalid file type: ${file.type}. Allowed types: ${allowedMimeTypes.join(
+        ", ",
+      )}`,
+      "INVALID_TYPE",
+    );
+  }
+
+  // Check file size
+  const maxFileSize = file.type.startsWith("video/")
+    ? maxVideoFileSize
+    : maxImageFileSize;
+  if (file.size > maxFileSize) {
+    const sizeMB = (file.size / (1024 * 1024)).toFixed(2);
+    const maxMB = maxFileSize / (1024 * 1024);
+    throw new FileValidationError(
+      `File too large: ${sizeMB}MB. Maximum size: ${maxMB}MB`,
+      "FILE_TOO_LARGE",
+    );
+  }
+
+  // Check filename
+  if (!filenameRegex.test(file.name)) {
+    throw new FileValidationError(
+      `Invalid filename: ${file.name}. Filename can only contain letters, numbers, dots, hyphens, underscores, and spaces.`,
+      "INVALID_FILENAME",
+    );
+  }
+}
+
+/**
+ * Upload a media file
+ * @throws FileValidationError if validation fails
+ * @throws Error if upload fails
+ */
+export async function uploadMedia(
+  file: File,
+): Promise<{ url: string; r2_key: string; content_type: string }> {
+  // Validate file before upload
+  validateFile(file);
+
+  const formData = new FormData();
+  formData.append("file", file);
+
+  const res = await apiFetch("/api/media/upload", {
+    method: "POST",
+    body: formData,
+    timeoutMs: UPLOAD_REQUEST_TIMEOUT_MS,
+  });
+
+  await assertOk(res, "Failed to upload");
+
+  return res.json();
+}

package/packages/api/src/lib/api/moderation.ts

@@ -0,0 +1,98 @@
+import { apiDelete, apiFetch, apiPost, assertOk } from "./fetch.ts";
+
+// Owner-only federation moderation surface. Mirrors the backend operator
+// routes mounted at /api/moderation (see src/backend/routes/moderation.ts).
+// Every call is gated server-side to the instance owner (role === "owner")
+// and returns 403 otherwise; the UI also hides the entry from non-owners.
+
+export interface BlockedDomain {
+  domain: string;
+  reason: string | null;
+  created_at: string;
+}
+
+export interface BlockedActor {
+  actor_ap_id: string;
+  reason: string | null;
+  created_at: string;
+}
+
+export interface ModerationReport {
+  id: string;
+  reporter_ap_id: string | null;
+  target_ap_id: string | null;
+  content: string | null;
+  instance: string | null;
+  created_at: string;
+  resolved_at: string | null;
+}
+
+export async function fetchBlockedDomains(): Promise<BlockedDomain[]> {
+  const res = await apiFetch("/api/moderation/domains");
+  await assertOk(res, "Failed to fetch blocked domains");
+  const data = (await res.json()) as { domains?: BlockedDomain[] };
+  return data.domains || [];
+}
+
+export async function blockDomain(
+  domain: string,
+  reason?: string,
+): Promise<void> {
+  const res = await apiPost("/api/moderation/domains", { domain, reason });
+  await assertOk(res, "Failed to block domain");
+}
+
+export async function unblockDomain(domain: string): Promise<void> {
+  const res = await apiDelete("/api/moderation/domains", { domain });
+  await assertOk(res, "Failed to unblock domain");
+}
+
+export async function fetchBlockedActors(): Promise<BlockedActor[]> {
+  const res = await apiFetch("/api/moderation/actors");
+  await assertOk(res, "Failed to fetch blocked actors");
+  const data = (await res.json()) as { actors?: BlockedActor[] };
+  return data.actors || [];
+}
+
+export async function blockActor(apId: string, reason?: string): Promise<void> {
+  const res = await apiPost("/api/moderation/actors", { ap_id: apId, reason });
+  await assertOk(res, "Failed to block actor");
+}
+
+export async function unblockActor(apId: string): Promise<void> {
+  const res = await apiDelete("/api/moderation/actors", { ap_id: apId });
+  await assertOk(res, "Failed to unblock actor");
+}
+
+export async function fetchReports(options?: {
+  onlyOpen?: boolean;
+}): Promise<ModerationReport[]> {
+  const query = options?.onlyOpen ? "?status=open" : "";
+  const res = await apiFetch(`/api/moderation/reports${query}`);
+  await assertOk(res, "Failed to fetch reports");
+  const data = (await res.json()) as { reports?: ModerationReport[] };
+  return data.reports || [];
+}
+
+export async function resolveReport(id: string, reopen = false): Promise<void> {
+  const res = await apiPost(
+    `/api/moderation/reports/${encodeURIComponent(id)}/resolve`,
+    { reopen },
+  );
+  await assertOk(res, "Failed to resolve report");
+}
+
+// File an outbound abuse Flag against a remote actor (and optionally one of
+// their posts), federated to their instance from this instance's actor.
+export async function reportContent(input: {
+  targetActorApId: string;
+  postApId?: string;
+  reason?: string;
+}): Promise<void> {
+  const res = await apiPost("/api/moderation/reports/outbound", {
+    target_actor_ap_id: input.targetActorApId,
+    post_ap_id: input.postApId,
+    reason: input.reason,
+  });
+  await assertOk(res, "Failed to submit report");
+}

package/packages/api/src/lib/api/normalize.ts

@@ -0,0 +1,71 @@
+import {
+  Actor,
+  ActorStories,
+  Notification,
+  Post,
+  Story,
+} from "../../types/index.ts";
+
+type ActorLike = {
+  ap_id: string;
+  username?: string;
+  preferred_username?: string;
+};
+
+function formatUsernameFromApId(
+  apId: string,
+  preferred?: string,
+): string | null {
+  try {
+    const url = new URL(apId);
+    const match = apId.match(/\/(users|groups)\/([^/]+)$/);
+    if (match) return `${match[2]}@${url.host}`;
+    if (preferred) return `${preferred}@${url.host}`;
+  } catch {
+    // Ignore malformed URLs and fallback to existing fields.
+  }
+  return null;
+}
+
+export function normalizeActor<T extends ActorLike>(actor: T): T {
+  if (!actor || !actor.ap_id) return actor;
+  const rawUsername = actor.username?.trim();
+  const formatted =
+    rawUsername ||
+    formatUsernameFromApId(actor.ap_id, actor.preferred_username) ||
+    actor.preferred_username ||
+    actor.username ||
+    actor.ap_id;
+  const preferred =
+    actor.preferred_username?.trim() ||
+    (formatted.includes("@") ? formatted.split("@")[0] : formatted);
+
+  return {
+    ...actor,
+    username: formatted,
+    preferred_username: preferred,
+  };
+}
+
+export const normalizePost = (post: Post): Post => ({
+  ...post,
+  author: normalizeActor(post.author),
+});
+
+export const normalizeStory = (story: Story): Story => ({
+  ...story,
+  author: normalizeActor(story.author),
+});
+
+export const normalizeActorStories = (stories: ActorStories): ActorStories => ({
+  ...stories,
+  actor: normalizeActor(stories.actor),
+  stories: (stories.stories || []).map(normalizeStory),
+});
+
+export const normalizeNotification = (
+  notification: Notification,
+): Notification => ({
+  ...notification,
+  actor: normalizeActor(notification.actor),
+});

package/packages/api/src/lib/api/notifications.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import { clearYurucommuApiTransport } from "../transport.ts";
+import type { Notification } from "../../types/index.ts";
+import { fetchNotifications } from "./notifications.ts";
+
+function makeNotification(id: string): Notification {
+  return {
+    id,
+    type: "like",
+    actor: {
+      ap_id: "https://example.com/ap/users/alice",
+      username: "alice@example.com",
+      preferred_username: "alice",
+      name: "Alice",
+      icon_url: null,
+    },
+    object_ap_id: null,
+    read: false,
+    created_at: "2026-01-01T00:00:00.000Z",
+  } as unknown as Notification;
+}
+
+async function withMockFetch<T>(
+  responseBody: unknown,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const originalFetch = globalThis.fetch;
+  clearYurucommuApiTransport();
+  globalThis.fetch = ((_input: RequestInfo | URL) =>
+    Promise.resolve(
+      new Response(JSON.stringify(responseBody), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    )) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearYurucommuApiTransport();
+  }
+}
+
+// Regression: the notifications "load older" affordance depends on the client
+// surfacing the server's `has_more` (it was previously discarded).
+test("fetchNotifications surfaces has_more as hasMore and maps notifications", async () => {
+  const result = await withMockFetch(
+    { notifications: [makeNotification("n1")], has_more: true },
+    () => fetchNotifications({ limit: 20 }),
+  );
+
+  expect(result.notifications.map((n) => n.id)).toEqual(["n1"]);
+  expect(result.hasMore).toBe(true);
+});
+
+test("fetchNotifications defaults hasMore to false when the server omits it", async () => {
+  const result = await withMockFetch({ notifications: [] }, () =>
+    fetchNotifications({ limit: 20 }),
+  );
+
+  expect(result.notifications).toEqual([]);
+  expect(result.hasMore).toBe(false);
+});

package/packages/api/src/lib/api/notifications.ts

@@ -0,0 +1,61 @@
+import type { Notification } from "../../types/index.ts";
+import { normalizeNotification } from "./normalize.ts";
+import { apiDelete, apiFetch, apiPost, assertOk } from "./fetch.ts";
+
+export async function fetchNotifications(options?: {
+  limit?: number;
+  type?: string;
+  before?: string;
+  archived?: boolean;
+}): Promise<{
+  notifications: Notification[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}> {
+  const params = new URLSearchParams();
+  if (options?.limit) params.set("limit", options.limit.toString());
+  if (options?.type && options.type !== "all") params.set("type", options.type);
+  if (options?.before) params.set("before", options.before);
+  if (options?.archived) params.set("archived", "true");
+  const query = params.toString() ? `?${params}` : "";
+  const res = await apiFetch(`/api/notifications${query}`);
+  await assertOk(res, "Failed to load notifications");
+  const data = (await res.json()) as {
+    notifications?: Notification[];
+    has_more?: boolean;
+    next_cursor?: string | null;
+  };
+  return {
+    notifications: (data.notifications || []).map(normalizeNotification),
+    hasMore: data.has_more ?? false,
+    nextCursor: data.next_cursor ?? null,
+  };
+}
+
+export async function fetchUnreadCount(): Promise<number> {
+  const res = await apiFetch("/api/notifications/unread/count");
+  const data = (await res.json()) as { count?: number };
+  return data.count || 0;
+}
+
+export async function markNotificationsRead(ids?: string[]): Promise<void> {
+  const res = await apiPost("/api/notifications/read", { ids });
+  await assertOk(res, "Failed to mark as read");
+}
+
+export async function archiveNotifications(ids: string[]): Promise<void> {
+  const res = await apiPost("/api/notifications/archive", { ids });
+  await assertOk(res, "Failed to archive");
+}
+
+export async function unarchiveNotifications(ids: string[]): Promise<void> {
+  const res = await apiDelete("/api/notifications/archive", { ids });
+  await assertOk(res, "Failed to unarchive");
+}
+
+export async function archiveAllNotifications(): Promise<number> {
+  const res = await apiPost("/api/notifications/archive/all", {});
+  await assertOk(res, "Failed to archive all");
+  const data = (await res.json()) as { archived_count?: number };
+  return data.archived_count ?? 0;
+}

package/packages/api/src/lib/api/posts.test.ts

@@ -0,0 +1,110 @@
+import { expect, test } from "bun:test";
+import { clearYurucommuApiTransport } from "../transport.ts";
+import type { Post } from "../../types/index.ts";
+import { createPost, fetchBookmarks, fetchTimeline } from "./posts.ts";
+
+function makePost(overrides: Partial<Post> = {}): Post {
+  return {
+    ap_id: "https://example.com/ap/objects/post-1",
+    type: "Note",
+    author: {
+      ap_id: "https://example.com/ap/users/alice",
+      username: "alice@example.com",
+      preferred_username: "alice",
+      name: "Alice",
+      icon_url: null,
+    },
+    content: "hello",
+    summary: null,
+    attachments: [],
+    in_reply_to: null,
+    visibility: "public",
+    community_ap_id: null,
+    like_count: 0,
+    reply_count: 0,
+    announce_count: 0,
+    published: "2026-01-01T00:00:00.000Z",
+    edited_at: null,
+    liked: false,
+    bookmarked: false,
+    reposted: false,
+    ...overrides,
+  };
+}
+
+async function withMockFetch<T>(
+  responseBody: unknown,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const originalFetch = globalThis.fetch;
+  clearYurucommuApiTransport();
+  globalThis.fetch = ((_input: RequestInfo | URL, _init?: RequestInit) => {
+    return Promise.resolve(
+      new Response(JSON.stringify(responseBody), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+  }) as typeof fetch;
+
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearYurucommuApiTransport();
+  }
+}
+
+test("createPost reads the current wrapped post response", async () => {
+  const post = makePost();
+
+  const result = await withMockFetch({ post }, () =>
+    createPost({ content: "hello" }),
+  );
+
+  expect(result.ap_id).toBe(post.ap_id);
+});
+
+test("fetchBookmarks reads the posts + pagination fields", async () => {
+  const post = makePost({ bookmarked: true });
+
+  const result = await withMockFetch(
+    { posts: [post], has_more: true, next_cursor: "c1" },
+    () => fetchBookmarks(),
+  );
+
+  expect(result.posts.map((p) => p.ap_id)).toEqual([post.ap_id]);
+  expect(result.hasMore).toBe(true);
+  expect(result.nextCursor).toBe("c1");
+});
+
+// Regression: the timeline client must SURFACE the server's composite cursor (so
+// loadMore can echo it back as `before`). It was discarding `next_cursor` and
+// paginating with a post's ap_id instead, which the server decodes as a
+// published-only cursor whose string compare matches every row → the feed
+// re-serves page 1 forever and never advances.
+test("fetchTimeline surfaces the server next_cursor and has_more", async () => {
+  const post = makePost();
+  const result = await withMockFetch(
+    {
+      posts: [post],
+      has_more: true,
+      next_cursor: "2026-01-01T00:00:00.000Z\u0000" + post.ap_id,
+    },
+    () => fetchTimeline({ limit: 20 }),
+  );
+
+  expect(result.posts.map((p) => p.ap_id)).toEqual([post.ap_id]);
+  expect(result.hasMore).toBe(true);
+  expect(result.nextCursor).toBe("2026-01-01T00:00:00.000Z\u0000" + post.ap_id);
+});
+
+test("fetchTimeline defaults to no cursor / hasMore=false when the server omits them", async () => {
+  const result = await withMockFetch({ posts: [] }, () =>
+    fetchTimeline({ limit: 20 }),
+  );
+
+  expect(result.posts).toEqual([]);
+  expect(result.hasMore).toBe(false);
+  expect(result.nextCursor).toBe(null);
+});