From fa9d8012ba848446a675c0ef051fd82a2eaa1447 Mon Sep 17 00:00:00 2001
From: takker99 <37929109+takker99@users.noreply.github.com>
Date: Sun, 10 Aug 2025 20:15:12 +0900
Subject: [PATCH] feat(api): add smart context endpoints for 1-hop and 2-hop
 links

---
 api.ts                                        |  1 +
 api/smart-context.ts                          |  2 +
 .../export-1hop-links/project.ts              | 72 +++++++++++++++++++
 .../export-2hop-links/project.ts              | 72 +++++++++++++++++++
 deno.jsonc                                    |  3 +
 5 files changed, 150 insertions(+)
 create mode 100644 api/smart-context.ts
 create mode 100644 api/smart-context/export-1hop-links/project.ts
 create mode 100644 api/smart-context/export-2hop-links/project.ts

diff --git a/api.ts b/api.ts
index fc4d2f1..6c9ab85 100644
--- a/api.ts
+++ b/api.ts
@@ -1,5 +1,6 @@
 export * from "./api/pages.ts";
 export * from "./api/projects.ts";
 export * from "./api/users.ts";
+export * from "./api/smart-context.ts";
 export type { HTTPError, TypedError } from "./error.ts";
 export type { BaseOptions, ExtendedOptions, OAuthOptions } from "./util.ts";
diff --git a/api/smart-context.ts b/api/smart-context.ts
new file mode 100644
index 0000000..bc715e8
--- /dev/null
+++ b/api/smart-context.ts
@@ -0,0 +1,2 @@
+export * from "./smart-context/export-1hop-links/project.ts";
+export * from "./smart-context/export-2hop-links/project.ts";
diff --git a/api/smart-context/export-1hop-links/project.ts b/api/smart-context/export-1hop-links/project.ts
new file mode 100644
index 0000000..8f3201a
--- /dev/null
+++ b/api/smart-context/export-1hop-links/project.ts
@@ -0,0 +1,72 @@
+import type {
+  BadRequestError,
+  NotFoundError,
+  NotLoggedInError,
+  NotMemberError,
+} from "@cosense/types/rest";
+import { type BaseOptions, setDefaults } from "../../../util.ts";
+import { cookie } from "../../../rest/auth.ts";
+import type { ResponseOfEndpoint } from "../../../targeted_response.ts";
+
+/** Options for {@linkcode export1HopLinks}
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ */
+export type Export1HopLinksOptions<R extends Response | undefined> =
+  BaseOptions<R>;
+
+/** Constructs a request for the `/api/smart-context/export-1hop-links/:project.txt` endpoint
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @param project The project name to export 1-hop links for
+ * @param title The title of the page to export 1-hop links for
+ * @param options - Configuration options
+ * @returns A {@linkcode Request} object for the API endpoint
+ */
+export const makeExport1HopLinksRequest = <R extends Response | undefined>(
+  project: string,
+  title: string,
+  options?: Export1HopLinksOptions<R>,
+): Request => {
+  const { sid, baseURL } = setDefaults(options ?? {});
+  const params = new URLSearchParams({ title: title });
+
+  return new Request(
+    `${baseURL}api/smart-context/export-1hop-links/${project}.txt?${params}`,
+    sid ? { headers: { Cookie: cookie(sid) } } : undefined,
+  );
+};
+
+/** Exports 1-hop links for a given page in a project as AI-readable text format.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @param project The project name to export 1-hop links for
+ * @param title The title of the page to export 1-hop links for
+ * @param options - Configuration options. **Make sure to set `sid` or you will never get the 200 OK response.**
+ */
+export const export1HopLinks = <R extends Response | undefined = Response>(
+  project: string,
+  title: string,
+  options?: Export1HopLinksOptions<R>,
+): Promise<
+  ResponseOfEndpoint<{
+    200: string;
+    404: NotFoundError;
+    400: BadRequestError;
+    401: NotLoggedInError;
+    403: NotMemberError;
+  }, R>
+> =>
+  setDefaults(options ?? {}).fetch(
+    makeExport1HopLinksRequest(project, title, options),
+  ) as Promise<
+    ResponseOfEndpoint<{
+      200: string;
+      400: BadRequestError;
+      404: NotFoundError;
+      401: NotLoggedInError;
+      403: NotMemberError;
+    }, R>
+  >;
diff --git a/api/smart-context/export-2hop-links/project.ts b/api/smart-context/export-2hop-links/project.ts
new file mode 100644
index 0000000..04e3ca6
--- /dev/null
+++ b/api/smart-context/export-2hop-links/project.ts
@@ -0,0 +1,72 @@
+import type {
+  BadRequestError,
+  NotFoundError,
+  NotLoggedInError,
+  NotMemberError,
+} from "@cosense/types/rest";
+import { type BaseOptions, setDefaults } from "../../../util.ts";
+import { cookie } from "../../../rest/auth.ts";
+import type { ResponseOfEndpoint } from "../../../targeted_response.ts";
+
+/** Options for {@linkcode export2HopLinks}
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ */
+export type Export2HopLinksOptions<R extends Response | undefined> =
+  BaseOptions<R>;
+
+/** Constructs a request for the `/api/smart-context/export-2hop-links/:project.txt` endpoint
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @param project The project name to export 2-hop links for
+ * @param title The title of the page to export 2-hop links for
+ * @param options - Configuration options
+ * @returns A {@linkcode Request} object for the API endpoint
+ */
+export const makeExport2HopLinksRequest = <R extends Response | undefined>(
+  project: string,
+  title: string,
+  options?: Export2HopLinksOptions<R>,
+): Request => {
+  const { sid, baseURL } = setDefaults(options ?? {});
+  const params = new URLSearchParams({ title: title });
+
+  return new Request(
+    `${baseURL}api/smart-context/export-2hop-links/${project}.txt?${params}`,
+    sid ? { headers: { Cookie: cookie(sid) } } : undefined,
+  );
+};
+
+/** Exports 2-hop links for a given page in a project as AI-readable text format.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @param project The project name to export 2-hop links for
+ * @param title The title of the page to export 2-hop links for
+ * @param options - Configuration options. **Make sure to set `sid` or you will never get the 200 OK response.**
+ */
+export const export2HopLinks = <R extends Response | undefined = Response>(
+  project: string,
+  title: string,
+  options?: Export2HopLinksOptions<R>,
+): Promise<
+  ResponseOfEndpoint<{
+    200: string;
+    404: NotFoundError;
+    400: BadRequestError;
+    401: NotLoggedInError;
+    403: NotMemberError;
+  }, R>
+> =>
+  setDefaults(options ?? {}).fetch(
+    makeExport2HopLinksRequest(project, title, options),
+  ) as Promise<
+    ResponseOfEndpoint<{
+      200: string;
+      400: BadRequestError;
+      404: NotFoundError;
+      401: NotLoggedInError;
+      403: NotMemberError;
+    }, R>
+  >;
diff --git a/deno.jsonc b/deno.jsonc
index 4ec10d1..8b69b7b 100644
--- a/deno.jsonc
+++ b/deno.jsonc
@@ -34,6 +34,9 @@
     "./unstable-api/pages/projects/project": "./api/projects/project.ts",
     "./unstable-api/pages/project/title/text": "./api/pages/project/title/text.ts",
     "./unstable-api/pages/project/title/icon": "./api/pages/project/title/icon.ts",
+    "./unstable-api/pages/smart-context": "./api/smart-context.ts",
+    "./unstable-api/pages/smart-context/export-1hop-links": "./api/smart-context/export-1hop-links/project.ts",
+    "./unstable-api/pages/smart-context/export-2hop-links": "./api/smart-context/export-2hop-links/project.ts",
     "./unstable-api/users": "./api/users.ts",
     "./unstable-api/users/me": "./api/users/me.ts"
   },