refactor(rest): redesign REST API to use ScrapboxResponse

BREAKING CHANGE: Replace option-t Result with ScrapboxResponse

- Remove option-t dependency
- Add ScrapboxResponse class extending web standard Response
- Improve type safety with status-based type switching
- Allow direct access to Response.body and headers
- Add migration guide for v0.30.0

This change follows the implementation pattern from @takker/gyazo@0.4.0
and prepares for release as version 0.30.0.

Resolves takker99#213

Author: devin-ai-integration[bot]

docs/migration-guide-0.30.0.md

@@ -0,0 +1,139 @@
+# Migration Guide to v0.30.0
+
+## Breaking Changes
+
+### REST API Changes
+
+The REST API has been completely redesigned to improve type safety, reduce dependencies, and better align with web standards. The main changes are:
+
+1. Removal of `option-t` dependency
+   - All `Result` types from `option-t/plain_result` have been replaced with `ScrapboxResponse`
+   - No more `unwrapOk`, `isErr`, or other option-t utilities
+
+2. New `ScrapboxResponse` class
+   - Extends the web standard `Response` class
+   - Direct access to `body`, `headers`, and other standard Response properties
+   - Type-safe error handling based on HTTP status codes
+   - Built-in JSON parsing with proper typing for success/error cases
+
+### Before and After Examples
+
+#### Before (v0.29.x):
+```typescript
+import { isErr, unwrapOk } from "option-t/plain_result";
+
+const result = await getProfile();
+if (isErr(result)) {
+  console.error("Failed:", result);
+  return;
+}
+const profile = unwrapOk(result);
+console.log("Name:", profile.name);
+```
+
+#### After (v0.30.0):
+```typescript
+const response = await getProfile();
+if (!response.ok) {
+  console.error("Failed:", response.error);
+  return;
+}
+console.log("Name:", response.data.name);
+```
+
+### Key Benefits
+
+1. **Simpler Error Handling**
+   - HTTP status codes determine error types
+   - No need to unwrap results manually
+   - Type-safe error objects with proper typing
+
+2. **Web Standard Compatibility**
+   - Works with standard web APIs without conversion
+   - Direct access to Response properties
+   - Compatible with standard fetch patterns
+
+3. **Better Type Safety**
+   - Response types change based on HTTP status
+   - Proper typing for both success and error cases
+   - No runtime overhead for type checking
+
+### Migration Steps
+
+1. Replace `option-t` imports:
+   ```diff
+   - import { isErr, unwrapOk } from "option-t/plain_result";
+   ```
+
+2. Update error checking:
+   ```diff
+   - if (isErr(result)) {
+   -   console.error(result);
+   + if (!response.ok) {
+   +   console.error(response.error);
+   ```
+
+3. Access response data:
+   ```diff
+   - const data = unwrapOk(result);
+   + const data = response.data;
+   ```
+
+4. For direct Response access:
+   ```typescript
+   // Access headers
+   const contentType = response.headers.get("content-type");
+   
+   // Access raw body
+   const text = await response.text();
+   
+   // Parse JSON with type safety
+   const json = await response.json();
+   ```
+
+### Common Patterns
+
+1. **Status-based Error Handling**:
+```typescript
+const response = await getSnapshot(project, pageId, timestampId);
+
+if (response.status === 422) {
+  // Handle invalid snapshot ID
+  console.error("Invalid snapshot:", response.error);
+  return;
+}
+
+if (!response.ok) {
+  // Handle other errors
+  console.error("Failed:", response.error);
+  return;
+}
+
+// Use the data
+console.log(response.data);
+```
+
+2. **Type-safe JSON Parsing**:
+```typescript
+const response = await getTweetInfo(tweetUrl);
+if (response.ok) {
+  const tweet = response.data;  // Properly typed as TweetInfo
+  console.log(tweet.text);
+}
+```
+
+3. **Working with Headers**:
+```typescript
+const response = await uploadToGCS(file, projectId);
+if (!response.ok && response.headers.get("Content-Type")?.includes("/xml")) {
+  console.error("GCS Error:", await response.text());
+  return;
+}
+```
+
+### Need Help?
+
+If you encounter any issues during migration, please:
+1. Check the examples in this guide
+2. Review the [API documentation](https://jsr.io/@takker/scrapbox-userscript-std)
+3. Open an issue on GitHub if you need further assistance

rest/auth.ts

@@ -1,5 +1,5 @@
-import { createOk, mapForResult, type Result } from "option-t/plain_result";
 import { getProfile } from "./profile.ts";
+import { ScrapboxResponse } from "./response.ts";
 import type { HTTPError } from "./responseIntoResult.ts";
 import type { AbortError, NetworkError } from "./robustFetch.ts";
 import type { ExtendedOptions } from "./options.ts";
@@ -16,11 +16,11 @@ export const cookie = (sid: string): string => `connect.sid=${sid}`;
  */
 export const getCSRFToken = async (
   init?: ExtendedOptions,
-): Promise<Result<string, NetworkError | AbortError | HTTPError>> => {
+): Promise<ScrapboxResponse<string, NetworkError | AbortError | HTTPError>> => {
   // deno-lint-ignore no-explicit-any
   const csrf = init?.csrf ?? (globalThis as any)._csrf;
-  return csrf ? createOk(csrf) : mapForResult(
-    await getProfile(init),
-    (user) => user.csrfToken,
-  );
+  if (csrf) return ScrapboxResponse.ok(csrf);
+
+  const profile = await getProfile(init);
+  return profile.ok ? ScrapboxResponse.ok(profile.data.csrfToken) : profile;
 };

rest/getCodeBlock.ts

@@ -6,14 +6,7 @@ import type {
 import { cookie } from "./auth.ts";
 import { encodeTitleURI } from "../title.ts";
 import { type BaseOptions, setDefaults } from "./options.ts";
-import {
-  isErr,
-  mapAsyncForResult,
-  mapErrAsyncForResult,
-  type Result,
-  unwrapOk,
-} from "option-t/plain_result";
-import { type HTTPError, responseIntoResult } from "./responseIntoResult.ts";
+import { ScrapboxResponse } from "./response.ts";
 import { parseHTTPError } from "./parseHTTPError.ts";
 import type { FetchError } from "./mod.ts";
 
@@ -33,21 +26,28 @@ const getCodeBlock_toRequest: GetCodeBlock["toRequest"] = (
   );
 };
 
-const getCodeBlock_fromResponse: GetCodeBlock["fromResponse"] = async (res) =>
-  mapAsyncForResult(
-    await mapErrAsyncForResult(
-      responseIntoResult(res),
-      async (res) =>
-        res.response.status === 404 &&
-          res.response.headers.get("Content-Type")?.includes?.("text/plain")
-          ? { name: "NotFoundError", message: "Code block is not found" }
-          : (await parseHTTPError(res, [
-            "NotLoggedInError",
-            "NotMemberError",
-          ])) ?? res,
-    ),
-    (res) => res.text(),
-  );
+const getCodeBlock_fromResponse: GetCodeBlock["fromResponse"] = async (res) => {
+  const response = ScrapboxResponse.from<string, CodeBlockError>(res);
+
+  if (response.status === 404 && response.headers.get("Content-Type")?.includes?.("text/plain")) {
+    return ScrapboxResponse.error({
+      name: "NotFoundError",
+      message: "Code block is not found",
+    });
+  }
+
+  await parseHTTPError(response, [
+    "NotLoggedInError",
+    "NotMemberError",
+  ]);
+
+  if (response.ok) {
+    const text = await response.text();
+    return ScrapboxResponse.ok(text);
+  }
+
+  return response;
+};
 
 export interface GetCodeBlock {
   /** /api/code/:project/:title/:filename の要求を組み立てる
@@ -70,14 +70,14 @@ export interface GetCodeBlock {
    * @param res 応答
    * @return コード
    */
-  fromResponse: (res: Response) => Promise<Result<string, CodeBlockError>>;
+  fromResponse: (res: Response) => Promise<ScrapboxResponse<string, CodeBlockError>>;
 
   (
     project: string,
     title: string,
     filename: string,
     options?: BaseOptions,
-  ): Promise<Result<string, CodeBlockError | FetchError>>;
+  ): Promise<ScrapboxResponse<string, CodeBlockError | FetchError>>;
 }
 export type CodeBlockError =
   | NotFoundError
@@ -101,7 +101,7 @@ export const getCodeBlock: GetCodeBlock = /* @__PURE__ */ (() => {
   ) => {
     const req = getCodeBlock_toRequest(project, title, filename, options);
     const res = await setDefaults(options ?? {}).fetch(req);
-    return isErr(res) ? res : getCodeBlock_fromResponse(unwrapOk(res));
+    return getCodeBlock_fromResponse(res);
   };
 
   fn.toRequest = getCodeBlock_toRequest;

rest/getGyazoToken.ts

@@ -1,14 +1,7 @@
-import {
-  isErr,
-  mapAsyncForResult,
-  mapErrAsyncForResult,
-  type Result,
-  unwrapOk,
-} from "option-t/plain_result";
 import type { NotLoggedInError } from "@cosense/types/rest";
 import { cookie } from "./auth.ts";
 import { parseHTTPError } from "./parseHTTPError.ts";
-import { type HTTPError, responseIntoResult } from "./responseIntoResult.ts";
+import { ScrapboxResponse } from "./response.ts";
 import { type BaseOptions, setDefaults } from "./options.ts";
 import type { FetchError } from "./mod.ts";
 
@@ -29,7 +22,7 @@ export type GyazoTokenError = NotLoggedInError | HTTPError;
  */
 export const getGyazoToken = async (
   init?: GetGyazoTokenOptions,
-): Promise<Result<string | undefined, GyazoTokenError | FetchError>> => {
+): Promise<ScrapboxResponse<string | undefined, GyazoTokenError | FetchError>> => {
   const { fetch, sid, hostName, gyazoTeamsName } = setDefaults(init ?? {});
   const req = new Request(
     `https://${hostName}/api/login/gyazo/oauth-upload/token${
@@ -39,14 +32,14 @@ export const getGyazoToken = async (
   );
 
   const res = await fetch(req);
-  if (isErr(res)) return res;
+  const response = ScrapboxResponse.from<string | undefined, GyazoTokenError>(res);
 
-  return mapAsyncForResult(
-    await mapErrAsyncForResult(
-      responseIntoResult(unwrapOk(res)),
-      async (error) =>
-        (await parseHTTPError(error, ["NotLoggedInError"])) ?? error,
-    ),
-    (res) => res.json().then((json) => json.token as string | undefined),
-  );
+  await parseHTTPError(response, ["NotLoggedInError"]);
+
+  if (response.ok) {
+    const json = await response.json();
+    return ScrapboxResponse.ok(json.token as string | undefined);
+  }
+
+  return response;
 };

rest/getTweetInfo.ts

@@ -1,10 +1,3 @@
-import {
-  isErr,
-  mapAsyncForResult,
-  mapErrAsyncForResult,
-  type Result,
-  unwrapOk,
-} from "option-t/plain_result";
 import type {
   BadRequestError,
   InvalidURLError,
@@ -13,7 +6,7 @@ import type {
 } from "@cosense/types/rest";
 import { cookie, getCSRFToken } from "./auth.ts";
 import { parseHTTPError } from "./parseHTTPError.ts";
-import { type HTTPError, responseIntoResult } from "./responseIntoResult.ts";
+import { ScrapboxResponse } from "./response.ts";
 import { type ExtendedOptions, setDefaults } from "./options.ts";
 import type { FetchError } from "./mod.ts";
 
@@ -32,11 +25,11 @@ export type TweetInfoError =
 export const getTweetInfo = async (
   url: string | URL,
   init?: ExtendedOptions,
-): Promise<Result<TweetInfo, TweetInfoError | FetchError>> => {
+): Promise<ScrapboxResponse<TweetInfo, TweetInfoError | FetchError>> => {
   const { sid, hostName, fetch } = setDefaults(init ?? {});
 
-  const csrfResult = await getCSRFToken(init);
-  if (isErr(csrfResult)) return csrfResult;
+  const csrfToken = await getCSRFToken(init);
+  if (!csrfToken.ok) return csrfToken;
 
   const req = new Request(
     `https://${hostName}/api/embed-text/twitter?url=${
@@ -46,33 +39,28 @@ export const getTweetInfo = async (
       method: "POST",
       headers: {
         "Content-Type": "application/json;charset=utf-8",
-        "X-CSRF-TOKEN": unwrapOk(csrfResult),
+        "X-CSRF-TOKEN": csrfToken.data,
         ...(sid ? { Cookie: cookie(sid) } : {}),
       },
       body: JSON.stringify({ timeout: 3000 }),
     },
   );
 
   const res = await fetch(req);
-  if (isErr(res)) return res;
+  const response = ScrapboxResponse.from<TweetInfo, TweetInfoError>(res);
 
-  return mapErrAsyncForResult(
-    await mapAsyncForResult(
-      responseIntoResult(unwrapOk(res)),
-      (res) => res.json() as Promise<TweetInfo>,
-    ),
-    async (res) => {
-      if (res.response.status === 422) {
-        return {
-          name: "InvalidURLError",
-          message: (await res.response.json()).message as string,
-        };
-      }
-      const parsed = await parseHTTPError(res, [
-        "SessionError",
-        "BadRequestError",
-      ]);
-      return parsed ?? res;
-    },
-  );
+  if (response.status === 422) {
+    const json = await response.json();
+    return ScrapboxResponse.error({
+      name: "InvalidURLError",
+      message: json.message as string,
+    });
+  }
+
+  await parseHTTPError(response, [
+    "SessionError",
+    "BadRequestError",
+  ]);
+
+  return response;
 };