@vtecx/vtecxdocument 1.0.0

package/docs/api/notify.md

@@ -0,0 +1,123 @@
+# メール・通知
+
+メール送信・プッシュ通知・メッセージキューを操作するメソッド群。
+
+---
+
+## メール送信
+
+### `sendMail(entry, to, cc?, bcc?, attachments?)`
+
+```typescript
+sendMail(
+  entry: any,
+  to: string[],
+  cc?: string[],
+  bcc?: string[],
+  attachments?: string[]
+): Promise<boolean>
+```
+
+メールを送信する。件名・本文は `entry`（title = 件名、content = 本文など）で指定する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `entry` | `any` | メールの件名・本文を含むエントリ |
+| `to` | `string[]` | 送信先メールアドレスの配列 |
+| `cc` | `string[]?` | CC |
+| `bcc` | `string[]?` | BCC |
+| `attachments` | `string[]?` | 添付ファイルの URI 配列 |
+
+```typescript
+await vtecxnext.sendMail(
+  { title: 'お知らせ', summary: 'テキスト本文', content: { ______text: '<p>HTML本文</p>' } },
+  ['user@example.com']
+)
+```
+
+---
+
+## プッシュ通知
+
+### `pushNotification(message, to, title?, subtitle?, imageUrl?, data?)`
+
+```typescript
+pushNotification(
+  message: string,
+  to: string[],
+  title?: string,
+  subtitle?: string,
+  imageUrl?: string,
+  data?: any
+): Promise<boolean>
+```
+
+モバイルデバイスへのプッシュ通知を送信する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `message` | `string` | 通知本文 |
+| `to` | `string[]` | 送信先（デバイストークン／グループなど）の配列 |
+| `title` | `string?` | 通知タイトル |
+| `subtitle` | `string?` | サブタイトル |
+| `imageUrl` | `string?` | 画像 URL |
+| `data` | `any?` | 追加データ |
+
+```typescript
+await vtecxnext.pushNotification('メッセージが届きました', [deviceToken], '新しいメッセージ')
+```
+
+---
+
+## メッセージキュー
+
+非同期処理の要求をキューに積み、処理状態を管理するための機能。`channel` 単位でキューを識別する。
+
+### `setMessageQueue(feed, channel)`
+
+```typescript
+setMessageQueue(feed: any, channel: string): Promise<boolean>
+```
+
+指定チャネルのキューに feed を登録する。
+
+```typescript
+await vtecxnext.setMessageQueue(
+  { feed: { entry: [{ title: 'export-job' }] } },
+  'export'
+)
+```
+
+---
+
+### `getMessageQueue(channel)`
+
+```typescript
+getMessageQueue(channel: string): Promise<any>
+```
+
+指定チャネルのキューに登録された feed を取得する。
+
+---
+
+### `setMessageQueueStatus(flag, channel)`
+
+```typescript
+setMessageQueueStatus(flag: boolean, channel: string): Promise<boolean>
+```
+
+指定チャネルのメッセージキューの有効・無効状態を設定する。
+
+```typescript
+await vtecxnext.setMessageQueueStatus(true, 'export')
+```
+
+---
+
+### `getMessageQueueStatus(channel)`
+
+```typescript
+getMessageQueueStatus(channel: string): Promise<any>
+```
+
+指定チャネルのメッセージキューの状態を取得する。

package/docs/api/oauth.md

@@ -0,0 +1,100 @@
+# OAuth・TOTP
+
+LINE OAuth 連携および TOTP（時刻ベースワンタイムパスワード）の管理を行うメソッド群。
+
+---
+
+## LINE OAuth
+
+### `oauthLine()`
+
+```typescript
+oauthLine(): Promise<boolean>
+```
+
+LINE ログインの認可フローを開始する（認可エンドポイントへのリダイレクトを行う）。
+
+---
+
+### `oauthCallbackLine()`
+
+```typescript
+oauthCallbackLine(): Promise<boolean>
+```
+
+LINE ログインのコールバック処理を行い、セッションを確立する。LINE から渡される `code` / `state` はリクエスト（コンストラクタの `NextRequest`）から読み取られる。
+
+---
+
+### `mergeOAuthUserLine(rxid)`
+
+```typescript
+mergeOAuthUserLine(rxid: string): Promise<any>
+```
+
+LINE アカウントを既存の vte.cx アカウントに紐付ける。`rxid` でセッションを特定する。
+
+---
+
+## TOTP（多要素認証）
+
+### `getTotpLink(chs?)`
+
+```typescript
+getTotpLink(chs?: number): Promise<any>
+```
+
+TOTP 設定用の QR コード URL を含む feed を返す。`chs` で QR コード画像のサイズ（一辺のピクセル数）を指定できる。
+
+```typescript
+const totp = await vtecxnext.getTotpLink()
+```
+
+---
+
+### `createTotp(feed)`
+
+```typescript
+createTotp(feed: any): Promise<any>
+```
+
+TOTP を有効化する。認証アプリに表示されるワンタイムコードを feed で渡す。
+
+---
+
+### `deleteTotp(account?)`
+
+```typescript
+deleteTotp(account?: string): Promise<any>
+```
+
+TOTP を無効化する。`account` を指定すると管理者が対象ユーザーの TOTP を解除する。省略時は自分自身。
+
+---
+
+### `loginWithTotp(totp, isTrustedDevice)`
+
+```typescript
+loginWithTotp(totp: string, isTrustedDevice: boolean): Promise<StatusMessage>
+```
+
+TOTP コードを検証してログインを完了する。通常ログイン後に呼び出す。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `totp` | `string` | 認証アプリに表示されているワンタイムコード |
+| `isTrustedDevice` | `boolean` | `true` にすると次回以降 TOTP をスキップする |
+
+```typescript
+await vtecxnext.loginWithTotp('123456', false)
+```
+
+---
+
+### `changeTdid()`
+
+```typescript
+changeTdid(): Promise<any>
+```
+
+信頼済みデバイス ID（TDID）をリセットする。信頼済みデバイスの登録を無効化する用途で使用。

package/docs/api/pdf.md

@@ -0,0 +1,75 @@
+# PDF・署名
+
+PDF 生成・電子署名の付与・検証を行うメソッド群。
+
+---
+
+## PDF 生成
+
+### `toPdf(htmlTemplate, filename?)`
+
+```typescript
+toPdf(htmlTemplate: string, filename?: string): Promise<boolean>
+```
+
+HTML テンプレート文字列を PDF に変換し、レスポンスへ出力する。成功したかどうかを `boolean` で返す。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `htmlTemplate` | `string` | PDF 化する HTML テンプレート |
+| `filename` | `string?` | ダウンロード時のファイル名（省略可） |
+
+```typescript
+await vtecxnext.toPdf('<html><body><h1>請求書</h1></body></html>', 'invoice.pdf')
+```
+
+---
+
+## 電子署名
+
+### `putSignature(uri, revision?)`
+
+```typescript
+putSignature(uri: string, revision?: number): Promise<any>
+```
+
+指定した URI のエントリに電子署名を付与する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `uri` | `string` | 署名対象エントリの URI |
+| `revision` | `number?` | リビジョン（楽観的排他制御。省略可） |
+
+---
+
+### `putSignatures(feed)`
+
+```typescript
+putSignatures(feed: any): Promise<any>
+```
+
+feed で指定した複数エントリに電子署名を一括で付与する。
+
+---
+
+### `deleteSignature(uri, revision?)`
+
+```typescript
+deleteSignature(uri: string, revision?: number): Promise<boolean>
+```
+
+指定した URI のエントリの署名を削除する。
+
+---
+
+### `checkSignature(uri)`
+
+```typescript
+checkSignature(uri: string): Promise<boolean>
+```
+
+指定した URI のエントリの署名が有効かどうかを検証し、`boolean` で返す。
+
+```typescript
+const isValid = await vtecxnext.checkSignature('/files/contract/001')
+```

package/docs/api/session.md

@@ -0,0 +1,170 @@
+# サーバーセッション
+
+サーバーサイドのセッション領域にデータを保存・取得・削除するメソッド群。
+セッションデータはリクエストをまたいで保持される（ユーザーセッションに紐付く）。
+
+データ型に応じて 4 種類のサブタイプがある: `Feed`（エントリ一覧）、`Entry`（1 件）、`String`（文字列）、`Long`（整数）。
+
+---
+
+## Feed（エントリ一覧）
+
+### `setSessionFeed(key, feed)`
+
+```typescript
+setSessionFeed(key: string, feed: any): Promise<boolean>
+```
+
+feed データをセッションに保存する。
+
+```typescript
+await vtecxnext.setSessionFeed('cart', { feed: { entry: [...] } })
+```
+
+---
+
+### `getSessionFeed(key)`
+
+```typescript
+getSessionFeed(key: string): Promise<any>
+```
+
+セッションから feed データを取得する。
+
+```typescript
+const cart = await vtecxnext.getSessionFeed('cart')
+```
+
+---
+
+### `deleteSessionFeed(key)`
+
+```typescript
+deleteSessionFeed(key: string): Promise<boolean>
+```
+
+セッションから feed データを削除する。
+
+---
+
+## Entry（1 件）
+
+### `setSessionEntry(key, entry)`
+
+```typescript
+setSessionEntry(key: string, entry: any): Promise<boolean>
+```
+
+エントリ 1 件をセッションに保存する。
+
+---
+
+### `getSessionEntry(key)`
+
+```typescript
+getSessionEntry(key: string): Promise<any>
+```
+
+セッションからエントリ 1 件を取得する。
+
+---
+
+### `deleteSessionEntry(key)`
+
+```typescript
+deleteSessionEntry(key: string): Promise<boolean>
+```
+
+セッションからエントリを削除する。
+
+---
+
+## String（文字列）
+
+### `setSessionString(key, value)`
+
+```typescript
+setSessionString(key: string, value: string): Promise<boolean>
+```
+
+文字列をセッションに保存する。
+
+```typescript
+await vtecxnext.setSessionString('selectedTab', 'overview')
+```
+
+---
+
+### `getSessionString(key)`
+
+```typescript
+getSessionString(key: string): Promise<string | null>
+```
+
+セッションから文字列を取得する。
+
+```typescript
+const tab = await vtecxnext.getSessionString('selectedTab')
+```
+
+---
+
+### `deleteSessionString(key)`
+
+```typescript
+deleteSessionString(key: string): Promise<boolean>
+```
+
+セッションから文字列を削除する。
+
+---
+
+## Long（整数）
+
+### `setSessionLong(key, value)`
+
+```typescript
+setSessionLong(key: string, value: number): Promise<boolean>
+```
+
+整数値をセッションに保存する。
+
+```typescript
+await vtecxnext.setSessionLong('stepIndex', 2)
+```
+
+---
+
+### `getSessionLong(key)`
+
+```typescript
+getSessionLong(key: string): Promise<number | null>
+```
+
+セッションから整数値を取得する。
+
+---
+
+### `deleteSessionLong(key)`
+
+```typescript
+deleteSessionLong(key: string): Promise<boolean>
+```
+
+セッションから整数値を削除する。
+
+---
+
+## カウンタ
+
+### `incrementSession(key, num)`
+
+```typescript
+incrementSession(key: string, num: number): Promise<number | null>
+```
+
+セッション上の整数カウンタに `num` を加算する。加算後の値を返す。
+
+```typescript
+const count = await vtecxnext.incrementSession('viewCount', 1)
+```

package/docs/api/user.md

@@ -0,0 +1,225 @@
+# ユーザー管理
+
+ユーザーの登録・パスワード変更・無効化・削除などを行うメソッド群。
+
+---
+
+## ユーザー登録
+
+### `adduser(adduserInfo, reCaptchaToken)`
+
+```typescript
+adduser(adduserInfo: AdduserInfo, reCaptchaToken: string): Promise<any>
+```
+
+新規ユーザーを登録し、確認メールを送信する。
+
+```typescript
+await vtecxnext.adduser(
+  {
+    username: 'user@example.com',
+    pswd: hashedPassword,
+    nickname: 'ユーザー名',
+    emailSubject: '登録確認',
+    emailText: '本登録URLをクリックしてください。',
+    emailHtml: '<p>本登録URLをクリックしてください。</p>',
+  },
+  reCaptchaToken
+)
+```
+
+---
+
+### `adduserByAdmin(adduserInfos)`
+
+```typescript
+adduserByAdmin(adduserInfos: AdduserInfo[]): Promise<any>
+```
+
+管理者権限で複数ユーザーを一括登録する。reCAPTCHA 不要。
+
+---
+
+### `adduserByGroupadmin(adduserInfos, groupname)`
+
+```typescript
+adduserByGroupadmin(adduserInfos: AdduserInfo[], groupname: string): Promise<any>
+```
+
+グループ管理者権限で複数ユーザーを登録する。
+
+---
+
+## パスワード操作
+
+### `passreset(adduserInfo, reCaptchaToken?)`
+
+```typescript
+passreset(adduserInfo: AdduserInfo, reCaptchaToken?: string): Promise<any>
+```
+
+パスワードリセットメールを送信する。
+
+---
+
+### `changepass(newpswd, oldpswd?, passresetToken?)`
+
+```typescript
+changepass(newpswd: string, oldpswd?: string, passresetToken?: string): Promise<any>
+```
+
+パスワードを変更する。2 つのフローがある。
+
+**ログイン済みフロー（現在のパスワードで変更）**
+
+```typescript
+await vtecxnext.changepass(newpswd, oldpswd)
+```
+
+**メールリセットフロー（未ログイン）**
+
+```typescript
+await vtecxnext.loginWithRxid(rxid)
+await vtecxnext.changepass(newpswd, undefined, passresetToken)
+```
+
+パスワードは `getHashpass(password)`（`@vtecx/vtecxauth`）でハッシュしてから渡す。
+
+---
+
+### `changepassByAdmin(changepassByAdminInfos)`
+
+```typescript
+changepassByAdmin(changepassByAdminInfos: ChangepassByAdminInfo[]): Promise<any>
+```
+
+管理者権限で指定ユーザーのパスワードを変更する。
+
+---
+
+## アカウント変更
+
+### `changeaccount(adduserInfo)`
+
+```typescript
+changeaccount(adduserInfo: AdduserInfo): Promise<any>
+```
+
+メールアドレスなどのアカウント情報を変更する。変更確認メールが送信される。
+
+---
+
+### `changeaccount_verify(verifyCode)`
+
+```typescript
+changeaccount_verify(verifyCode: string): Promise<any>
+```
+
+`changeaccount()` で送信された確認コードを検証し、変更を確定する。
+
+---
+
+## ユーザー状態管理
+
+### `userstatus(account?)`
+
+```typescript
+userstatus(account?: string): Promise<string | any>
+```
+
+ユーザーの状態を取得する。`account` を省略すると全ユーザーの一覧を返す。
+
+状態値: `Activated`（本登録）/ `Interim`（仮登録）
+
+---
+
+### `revokeuser(account, isDeleteGroups?)`
+
+```typescript
+revokeuser(account: string, isDeleteGroups?: boolean): Promise<any>
+```
+
+ユーザーを無効化する（ログイン不可になる）。
+
+---
+
+### `revokeusers(accounts?, uids?, isDeleteGroups?)`
+
+```typescript
+revokeusers(accounts?: string[], uids?: string[], isDeleteGroups?: boolean): Promise<any>
+```
+
+複数ユーザーを一括無効化する。
+
+---
+
+### `activateuser(account)`
+
+```typescript
+activateuser(account: string): Promise<any>
+```
+
+無効化されたユーザーを有効化する。
+
+---
+
+### `activateusers(accounts?, uids?)`
+
+```typescript
+activateusers(accounts?: string[], uids?: string[]): Promise<any>
+```
+
+複数の無効化されたユーザーを一括有効化する。
+
+---
+
+### `canceluser(isDeleteGroups?)`
+
+```typescript
+canceluser(isDeleteGroups?: boolean): Promise<any>
+```
+
+ログイン中のユーザー自身がアカウントを退会する。
+
+---
+
+## ユーザー削除
+
+### `deleteuser(account)`
+
+```typescript
+deleteuser(account: string): Promise<any>
+```
+
+指定ユーザーをサービスから削除する。
+
+---
+
+### `deleteusers(accounts?, uids?)`
+
+```typescript
+deleteusers(accounts?: string[], uids?: string[]): Promise<any>
+```
+
+複数ユーザーを一括削除する。
+
+---
+
+## 型定義
+
+```typescript
+// SDK 上はすべて省略可（用途に応じて必要なフィールドを設定する）
+type AdduserInfo = {
+  username?: string      // メールアドレス
+  pswd?: string          // パスワード（ハッシュ済み）
+  nickname?: string      // ニックネーム
+  emailSubject?: string  // 確認メール件名
+  emailText?: string     // 確認メール本文（テキスト）
+  emailHtml?: string     // 確認メール本文（HTML）
+}
+
+type ChangepassByAdminInfo = {
+  uid: string            // 対象ユーザーの UID
+  pswd: string           // 新しいパスワード（ハッシュ済み）
+}
+```