Merge pull request #64 from takker99/api-route

refactor: Tidy API responses into each API route-like file

Author: takker99

api/commits/project/pageId.ts

@@ -0,0 +1,114 @@
+import type {
+  CommitId,
+  LineId,
+  PageId,
+  StringLc,
+  UnixTime,
+  UserId,
+} from "../../../base.ts";
+import type {
+  ChangeLine,
+  CharsCountChange,
+  DeleteChange,
+  DescriptionsChange,
+  FilesChange,
+  HelpFeelsChange,
+  ImageChange,
+  InfoboxDefinitionChange,
+  InsertChange,
+  LinesCountChange,
+  PinChange,
+} from "../../../change.ts";
+
+/** the response type of /api/commits/:projectname/:pageid */
+export interface CommitsResponse {
+  /** 指定したページのcommits */
+  commits: Commit[];
+}
+
+/** Scrapboxのページの編集commit */
+export interface Commit {
+  id: CommitId;
+
+  /** 一つ前のcommitのID
+   *
+   * 存在しないときは`null`になる
+   */
+  parentId: CommitId | null;
+
+  pageId: PageId;
+
+  /** commitの作成者 */
+  userId: UserId;
+
+  /** commitの作成日時 */
+  created: UnixTime;
+
+  /** 変更内容 */
+  changes: Change[];
+
+  /** 詳細不明 */
+  kind: "page";
+}
+/** ページの変更内容 */
+export type Change =
+  | InsertChange
+  | UpdateChange
+  | DeleteChange
+  | LinksChange
+  | ProjectLinksChange
+  | IconsChange
+  | DescriptionsChange
+  | ImageChange
+  | FilesChange
+  | HelpFeelsChange
+  | InfoboxDefinitionChange
+  | TitleChange
+  | LinesCountChange
+  | CharsCountChange
+  | PinChange;
+
+/** 既存の行を書き換える変更 */
+export interface UpdateChange {
+  /** 書き換える行のID */
+  _update: LineId;
+
+  /** 行の変更内容 */
+  lines: ChangeLine;
+}
+
+/** ページ中のリンクが変更されると発生する */
+export interface LinksChange {
+  /** 新しいリンク */
+  links: string[];
+
+  /** 新しいリンク */
+  linksLc: StringLc[];
+}
+
+/** ページ中のproject linksが変更されると発生する */
+export interface ProjectLinksChange {
+  /** 新しいリンク */
+  projectLinks: string[];
+
+  /** 新しいリンク */
+  projectLinksLc: StringLc[];
+}
+
+/** ページ中のiconsが変更されると発生する */
+export interface IconsChange {
+  /** 新しいicons */
+  icons: string[];
+
+  /** 新しいicons */
+  iconsLc: StringLc[];
+}
+
+/** ページのタイトルが変更されると発生する */
+export interface TitleChange {
+  /** 新しいタイトル */
+  title: string;
+
+  /** 新しいタイトル */
+  titleLc: StringLc;
+}

api/embed-text/twitter.ts

@@ -0,0 +1,11 @@
+/** the response type of /api/embed-text/twitter */
+export interface TweetInfo {
+  /** Tweet本文 */
+  description?: string;
+
+  /** Tweet投稿者の表示名 */
+  screenName: string;
+
+  /** Tweetに添付された画像 */
+  images: string[];
+}

api/page-data/export/project.ts

@@ -0,0 +1,35 @@
+import type { BaseLine, UnixTime } from "../../../base.ts";
+import type { Page, UserInfo } from "../../pages/project/title.ts";
+
+/** exportしたときのページデータ */
+export interface ExportedPage<hasMetadata extends true | false = false>
+  extends Pick<Page, "title" | "updated" | "created" | "id" | "views"> {
+  /** ページ本文
+   *
+   * `hasMetadata === true`のときは行のmetadataが入る
+   * それ以外の場合は行のテキストが入る
+   */
+  lines: hasMetadata extends true ? Omit<BaseLine, "id">[] : string[];
+}
+
+/** JSON data exported from https://scrapbox.io/api/page-data/export/:projectname.json  */
+export interface ExportedData<hasMetadata extends true | false = false> {
+  /** project's name */
+  name: string;
+
+  /** project's display name */
+  displayName: string;
+
+  /** このデータを生成した日時 (UNIX時刻) */
+  exported: UnixTime;
+
+  /** project members */
+  users: UserForExport[];
+
+  /** exported pages */
+  pages: ExportedPage<hasMetadata>[];
+}
+
+/** user infomation included in exported data */
+export interface UserForExport
+  extends Pick<UserInfo, "id" | "name" | "displayName" | "email"> {}

api/page-data/import/project.ts

@@ -0,0 +1,47 @@
+import type { UnixTime } from "../../../base.ts";
+
+/** JSON data for importing by https://scrapbox.io/api/page-data/import/:projectname.json  */
+export interface ImportedData<hasMetadata extends true | false = false> {
+  /** pages importing to a project */
+  pages: hasMetadata extends true ? ImportedPage[] : ImportedLightPage[];
+}
+
+/** メタデータ無しインポート用ページデータ */
+export interface ImportedLightPage {
+  /** page's title
+   *
+   * `title` should be equal to `lines[0]`
+   */
+  title: string;
+
+  /** page's text
+   *
+   * `lines[0]` should be equal to `title`
+   */
+  lines: string[];
+}
+/** インポート用メタデータ付き行データ */
+export interface ImportedLine {
+  /** line text */
+  text: string;
+
+  /** 行の最終更新日時 (UNIX時刻) */
+  updated?: UnixTime;
+
+  /** 行の最終作成日時 (UNIX時刻) */
+  created?: UnixTime;
+}
+/** メタデータ付きインポート用ページデータ */
+export interface ImportedPage {
+  /** page's title
+   *
+   * `title` should be equal to `lines[0].text`
+   */
+  title: string;
+
+  /** page's line data
+   *
+   * `lines[0].text` should be equal to `title`
+   */
+  lines: ImportedLine[];
+}

api/page-snapshots/project/pageId.ts

@@ -0,0 +1,14 @@
+import type { PageId, UnixTime } from "../../../base.ts";
+
+/** the response type of /api/page-snapshots/:projectname/:pageid */
+export interface PageSnapshotList {
+  pageId: PageId;
+
+  /** 作成されているsnapshotsのtimestamp idのリスト */
+  timestamps: SnapshotTimestamp[];
+}
+
+export interface SnapshotTimestamp {
+  id: string;
+  created: UnixTime;
+}

api/page-snapshots/project/pageId/timestampId.ts

@@ -0,0 +1,26 @@
+import type { BaseLine, BasePage, UnixTime } from "../../../../base.ts";
+import type { User } from "../../../pages/project/title.ts";
+
+/** the response type of /api/page-snapshots/:projectname/:pageid/:timestampid */
+export interface PageSnapshotResult {
+  page: PageWithSnapshot;
+
+  snapshot: Snapshot;
+}
+
+export interface PageWithSnapshot extends BasePage {
+  user: Pick<User, "id">;
+  lastupdateUser: Pick<User, "id"> | null;
+}
+
+/** a page snapshot */
+export interface Snapshot {
+  /** snapshotを撮ったときのページタイトル */
+  title: string;
+
+  /** snapshotの作成日時 */
+  created: UnixTime;
+
+  /** snapshotしたページ本文 */
+  lines: BaseLine[];
+}

api/pages/project.ts

@@ -0,0 +1,19 @@
+import type { BasePage } from "../../base.ts";
+
+/** the response type of https://scrpabox.io/api/pages/:projectname */
+export interface PageList {
+  /** data取得先のproject名 */
+  projectName: string;
+
+  /** parameterに渡したskipと同じ */
+  skip: number;
+
+  /** parameterに渡したlimitと同じ */
+  limit: number;
+
+  /** projectの全ページ数 (中身のないページを除く) */
+  count: number;
+
+  /** 取得できたページ情報 */
+  pages: BasePage[];
+}

api/pages/project/search/files.ts

@@ -0,0 +1,13 @@
+import type { FoundPage, SearchResult } from "./query.ts";
+
+/** the response type of /api/pages/:projectname/search/files */
+export interface FileSearchResult
+  extends Omit<SearchResult, "field" | "pages"> {
+  /** 見つかったページ */
+  pages: FoundPageByFile[];
+}
+
+/** /api/pages/:projectname/search/files で見つかったページ */
+export interface FoundPageByFile extends FoundPage {
+  file: string;
+}

api/pages/project/search/query.ts

@@ -0,0 +1,62 @@
+import type { PageId } from "../../../../base.ts";
+
+/** the response type of /api/pages/:projectname/search/query */
+export interface SearchResult {
+  /** 検索したprojectの名前 */
+  projectName: string;
+
+  /** 検索文字列 */
+  searchQuery: string;
+
+  /** 検索語句 */
+  query: SearchQuery;
+
+  /** 検索件数の上限 */
+  limit: number;
+
+  /** 検索件数 */
+  count: number;
+
+  /** 検索文字列と完全一致するタイトルが見つかったら`true` */
+  existsExactTitleMatch: boolean;
+
+  field: "title" | "helpfeels" | "lines";
+
+  /** 全文検索エンジンの名前 */
+  backend: string;
+
+  /** 見つかったページ */
+  pages: FoundPage[];
+}
+
+/** /api/pages/:projectname/search/query で見つかったページ */
+export interface FoundPage {
+  id: PageId;
+
+  /** page title */
+  title: string;
+
+  /** page thumbnail
+   *
+   * 無いときは空文字が入る
+   */
+  image: string;
+
+  /** 検索語句の中で、このページに含まれている語句 */
+  words: string[];
+
+  /** 検索語句に一致した行
+   *
+   * タイトル行のみが一致した場合は、検索語句の有無にかかわらずその次の行のみが入る
+   */
+  lines: string[];
+}
+
+/** 検索クエリ */
+export interface SearchQuery {
+  /** AND検索に使う語句 */
+  words: string[];
+
+  /** NOT検索に使う語句 */
+  excludes: string[];
+}

api/pages/project/search/titles.ts

@@ -0,0 +1,11 @@
+import type { BasePage } from "../../../../base.ts";
+
+/** the response type of https://scrapbox.io/api/pages/:projectname/search/titles */
+export interface SearchedTitle
+  extends Pick<BasePage, "id" | "title" | "updated"> {
+  /** thumbnail URL */
+  image?: string;
+
+  /** ページ内のリンク */
+  links: string[];
+}