Merge pull request #238 from evex-dev/codex/album-release

feat: integrate reviewed album service and session docs (#214, #212)

Author: EdamAme-x

docs/.vitepress/config.mts

@@ -40,6 +40,7 @@ export default defineConfig({
 					// { text: "Utils", link: "/docs/utils" },
 					{ text: "Client Methods", link: "/docs/methods" },
 					{ text: "Calls", link: "/docs/call" },
+					{ text: "Album (Moa)", link: "/docs/moa" },
 				],
 			},
 			{

docs/docs/auth.md

@@ -59,3 +59,53 @@ const client = await loginWithAuthToken("YOUR_AUTH_TOKEN", {
   device: "IOSIPAD",
 });
 ```
+
+### Persisting authToken across sessions
+
+`FileStorage` automatically persists things like `cert`, `refreshToken` and
+`expire`, but **the `authToken` itself is not one of them** — you need to save
+it yourself if you want to reuse it on the next run. LINEJS emits an
+`update:authtoken` events when tokens are issued or refreshed. Attach the
+listener **before login**, since login itself can rotate the token:
+
+```ts
+import { Client } from "@evex/linejs";
+import { BaseClient } from "@evex/linejs/base";
+import { FileStorage } from "@evex/linejs/storage";
+
+const storage = new FileStorage("./session.json");
+const TOKEN_KEY = "userAuthToken";
+const base = new BaseClient({ device: "IOSIPAD", storage });
+
+// Event listeners are not awaited by the emitter. Queue writes in order and
+// handle failures without creating an unhandled rejection.
+let pendingSave = Promise.resolve();
+base.on("update:authtoken", (token) => {
+  base.authToken = token;
+  pendingSave = pendingSave.then(() => storage.set(TOKEN_KEY, token)).catch(() => {
+    console.error("Could not persist the LINE session token.");
+  });
+});
+base.on("pincall", (pin) => console.log("Enter this pincode:", pin));
+
+const saved = await storage.get(TOKEN_KEY);
+
+await base.loginProcess.login(typeof saved === "string" && saved
+  ? { authToken: saved }
+  : {
+    email: "you@example.com",
+    password: "password",
+  });
+await pendingSave;
+const client = new Client(base);
+// Use client here. Also await pendingSave before an explicit process exit.
+```
+
+The first run uses email + password (and PIN); later runs attempt to reuse the
+saved token. Expired or revoked credentials can still require manual login.
+Do not automatically loop password logins on every error.
+
+`session.json` contains plaintext credentials and E2EE key material. Exclude it
+from version control, restrict file access to your user, and do not log or share
+its contents. Load your password from a private configuration or environment
+variable rather than committing it. Token reuse does not guarantee account safety.

docs/docs/methods.md

@@ -80,3 +80,39 @@ for await (const operation of polling.listenTalkEvents()) {
 for await (const event of polling.listenSquareEvents()) {
 }
 ```
+
+# Calling LINE REST endpoints directly
+
+Some LINE subsystems (Album/Moa, Timeline REST helpers, ...) speak JSON over
+HTTPS through the LEGY proxy rather than Thrift, but LINEJS's default
+`getHeader("GET")` helper is tuned for Thrift and sets
+`accept: application/x-thrift` and `content-type: application/x-thrift`. If you
+call a JSON REST endpoint with those defaults you may get
+`{"code":102001,"message":"一時的なエラーが発生しました。"}` back with HTTP 200.
+
+When you hand-craft a REST request, **override both headers to
+`application/json`**:
+
+```ts
+const headers = {
+  ...client.base.request.getHeader("GET"),
+  accept: "application/json",
+  "content-type": "application/json; charset=UTF-8",
+  "X-Line-ChannelToken": token,
+  "X-Line-Mid": client.base.profile!.mid,
+};
+const res = await client.base.fetch(url, {
+  method: "POST",
+  headers,
+  body: new Uint8Array(),
+  signal: AbortSignal.timeout(client.base.config.timeout),
+});
+if (!res.ok) throw new Error(`REST request failed: HTTP ${res.status}`);
+const data = await res.json();
+if (data.code !== undefined && data.code !== 0) {
+  throw new Error(`REST request failed: code ${data.code}`);
+}
+```
+
+Use `client.base.moa` for [album operations](./moa.md); it handles these headers
+and checks HTTP and application errors for you.

docs/docs/moa.md

@@ -0,0 +1,93 @@
+# Album (Moa)
+
+`MoaService` exposes the LINE Album (Moa) REST API on `client.base.moa`. Unlike
+Talk / Square, Moa speaks JSON over HTTPS through the LEGY proxy, so this
+service uses `client.base.fetch` directly with a channel token issued for the album
+channel (`1375220249`).
+
+## Listing albums
+
+```ts
+import { loginWithAuthToken } from "@evex/linejs";
+
+const client = await loginWithAuthToken("YOUR_AUTH_TOKEN", {
+  device: "IOSIPAD",
+});
+
+let cursor = "";
+while (true) {
+  const resp = await client.base.moa.getAlbums({ cursor });
+  const result = resp.result;
+  for (const album of result?.albums ?? []) {
+    console.log(`[${album.albumId}] ${album.title} (${album.photoCount} photos)`);
+  }
+  const next = result?.nextCursor ?? result?.cursor ?? "";
+  if (!next || next === cursor || !(result?.hasMore ?? true)) break;
+  cursor = next;
+}
+```
+
+## Listing photos in an album
+
+```ts
+let cursor = "";
+while (true) {
+  const resp = await client.base.moa.getPhotos({
+    chatId: "cxxxxxxxxxxxxxxx",
+    albumId: "1234567890123456789",
+    cursor,
+    pageSize: 100,
+  });
+  for (const photo of resp.result?.photos ?? []) {
+    console.log(photo.oid, "shot at", photo.shotTime);
+  }
+  const next = resp.result?.nextCursor ?? "";
+  if (!next || next === cursor) break;
+  cursor = next;
+}
+```
+
+## Downloading the original bytes of a photo
+
+`downloadPhoto` returns a `Uint8Array` so the caller can save it or process it
+further.
+
+```ts
+import { writeFileSync } from "node:fs";
+
+const bytes = await client.base.moa.downloadPhoto({
+  chatId: "cxxxxxxxxxxxxxxx",
+  albumId: "1234567890123456789",
+  oid: "someOid",
+});
+writeFileSync("./out.jpg", bytes);
+```
+
+For videos, pass `prefix: "album/v"` (the `sid` field on `obsResourceId` tells
+you whether the item is an image or a video):
+
+```ts
+const isVideo = photo.obsResourceId?.sid === "v";
+const bytes = await client.base.moa.downloadPhoto({
+  chatId,
+  albumId,
+  oid: photo.obsResourceId!.oid!,
+  prefix: isVideo ? "album/v" : "album/a",
+});
+```
+
+## Notes
+
+- The channel token issued for `1375220249` is memoised inside the service and
+  reused within the same session. Changing the access token, MID or endpoint
+  invalidates it. If the token is rejected (expiry or revocation), call
+  `client.base.moa.clearAlbumChannelToken()` before an explicit retry. Requests
+  are not automatically retried. REST requests and downloads use
+  `client.base.config.timeout`.
+- Moa uses `X-Line-ChannelToken`, `X-Line-Mid` (your MID) and — for photo
+  fetches — `X-Line-Album` (the album id) and `X-Line-Mid` set to the *chat*
+  id. All of these are set for you automatically.
+- The header override `accept: application/json` is important: the default
+  `client.base.request.getHeader("GET")` returns `application/x-thrift`, which
+  LEGY rejects for REST endpoints with
+  `{"code":102001,"message":"一時的なエラーが発生しました。"}`.

packages/linejs/base/core/mod.ts

@@ -20,6 +20,7 @@ import {
 	CallService,
 	ChannelService,
 	LiffService,
+	MoaService,
 	RelationService,
 	SquareLiveTalkService,
 	SquareService,
@@ -130,6 +131,7 @@ export class BaseClient extends TypedEventEmitter<ClientEvents> {
 	readonly call: CallService;
 	readonly channel: ChannelService;
 	readonly liff: LiffService;
+	readonly moa: MoaService;
 	readonly relation: RelationService;
 	readonly livetalk: SquareLiveTalkService;
 	readonly square: SquareService;
@@ -206,6 +208,7 @@ export class BaseClient extends TypedEventEmitter<ClientEvents> {
 		this.channel = new ChannelService(this);
 		this.liff = new LiffService(this);
 		this.livetalk = new SquareLiveTalkService(this);
+		this.moa = new MoaService(this);
 		this.relation = new RelationService(this);
 		this.square = new SquareService(this);
 		this.talk = new TalkService(this);