Merge pull request #669 from tako0614/feature/TASK-0072-outgoing-follow-status

Expose viewer-scoped outgoing Follow status on Actor reads

Author: tako0614

README.md

@@ -65,6 +65,10 @@ public export をすべて import します。Core の `client-api` と独立し
 bundle、Core の Worker bundle も検査します。依存はインストール済みのローカル module を
 使うため registry への接続は不要です。公開後の registry readback は deploy の別検証です。
 
+Actor GET の閲覧者別Follow状態は
+[outgoing Follow契約](docs/design/actor-outgoing-follow-status.md)を参照してください。
+未公開sourceの契約と、registry公開済みpackageのconsumer利用は別に検証します。
+
 ### core → product の release 順序
 
 新しい API 契約 (例: ブラウザ通知の public API と `0019_notification_push_delivery.sql`、core / API `3.1.0` から)

docs/design/actor-outgoing-follow-status.md

@@ -0,0 +1,35 @@
+# Viewer-scoped outgoing Follow state
+
+Authenticated `GET /api/actors/:identifier` returns
+`actor.outgoing_follow_status`: `none`, `pending`, or `accepted`. It describes
+the current authenticated actor's outgoing relationship to the resolved target,
+including cached remote profiles. Self reads return `none`; anonymous reads
+omit the field. The SDK preserves legacy omission and rejects a present value
+outside this enum. Consumers can restore an approval-pending control from a
+read rather than issuing a duplicate Follow mutation. Duplicate POST refusal
+is unchanged.
+
+`is_following` and `is_followed_by` remain accepted-only. Remote profile reads
+now compute these booleans from the same viewer-scoped relationship instead of
+hardcoding false. Pending/absent/rejected legacy edges do not grant accepted
+authority or change counters or follower/following lists. Accepted wins if
+legacy cosmetic duplicates coexist; a read does not repair those stored rows.
+
+For remote targets, match only the cosmetic Actor IRI equivalence already used
+by verified federation mutations: scheme/host case, default port, fragment,
+and one trailing slash. Path/query identity stays significant. SQL narrows to
+the indexed exact local viewer endpoint before applying the existing
+materialized identity matcher, with a fixed number of parameters. A remote
+cache recovery relationship belonging to another viewer never supplies this
+viewer state. Operator-blocked actors still fail their existing read gate.
+
+Authenticated profile responses use `Cache-Control: private, no-store`; every
+profile response varies on Cookie and Authorization. The field is not added
+to generic summaries, search or follow-list projections. This reusable Core
+contract imposes no product ownership model and makes no schema transition.
+
+Source/SDK and disposable native D1 qualification are separate from publication
+and actual consumer use. Both npm packages still await their owning paired
+immutable publication and registry readback; products must then adopt the
+published contract and pass their own gates. Operator-data and live federation
+qualification remain independent.

packages/api/src/lib/api/actor-follow-status.test.ts

@@ -0,0 +1,61 @@
+import { expect, test } from "bun:test";
+
+import { clearYurucommuApiTransport } from "../transport.ts";
+import { fetchActor } from "./actors.ts";
+import { InvalidApiResponseError } from "./response.ts";
+
+function actor(outgoing_follow_status?: unknown) {
+  return {
+    ap_id: "https://example.com/ap/users/alice",
+    preferred_username: "alice",
+    ...(outgoing_follow_status === undefined ? {} : { outgoing_follow_status }),
+  };
+}
+
+function outgoingStatus(value: object): unknown {
+  return (value as Record<string, unknown>).outgoing_follow_status;
+}
+
+async function withMockFetch<T>(
+  body: unknown,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const originalFetch = globalThis.fetch;
+  clearYurucommuApiTransport();
+  globalThis.fetch = Object.assign(
+    async () =>
+      new Response(JSON.stringify({ actor: body }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    { preconnect: originalFetch.preconnect },
+  );
+
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearYurucommuApiTransport();
+  }
+}
+
+test("fetchActor accepts legacy omission and preserves valid outgoing status", async () => {
+  const legacy = await withMockFetch(actor(), () => fetchActor("alice"));
+  expect(legacy).not.toHaveProperty("outgoing_follow_status");
+
+  for (const status of ["none", "pending", "accepted"] as const) {
+    const result = await withMockFetch(actor(status), () =>
+      fetchActor("alice"),
+    );
+    expect(outgoingStatus(result)).toBe(status);
+    expect(result.username).toBe("alice@example.com");
+  }
+});
+
+test("fetchActor rejects malformed outgoing status values as invalid API responses", async () => {
+  for (const status of [null, 1, false, "rejected", "unknown"]) {
+    await expect(
+      withMockFetch(actor(status), () => fetchActor("alice")),
+    ).rejects.toBeInstanceOf(InvalidApiResponseError);
+  }
+});

packages/api/src/lib/api/response.ts

@@ -103,6 +103,14 @@ export function validateActor(value: unknown): void {
     requiredString(actor.username, "actor.username");
   for (const key of ["preferred_username", "name", "icon_url"])
     optionalString(actor, key);
+  if (
+    actor.outgoing_follow_status !== undefined &&
+    actor.outgoing_follow_status !== "none" &&
+    actor.outgoing_follow_status !== "pending" &&
+    actor.outgoing_follow_status !== "accepted"
+  ) {
+    throw new InvalidApiResponseError("actor.outgoing_follow_status");
+  }
 }
 
 export function validatePost(value: unknown): void {

packages/api/src/types/index.ts

@@ -23,6 +23,9 @@ export interface Actor {
   created_at: string;
   is_following?: boolean;
   is_followed_by?: boolean;
+  // Authenticated Actor GET only; legacy servers and anonymous reads omit it.
+  // Pending requests never contribute to accepted-only booleans/counts/lists.
+  outgoing_follow_status?: "none" | "pending" | "accepted";
   // Structured PropertyValue profile fields (Mastodon-parity, capped at 4 on
   // the backend). Rendered as a small label/value list on the profile.
   fields?: { name: string; value: string }[];