@vtecx/vtecxdocument 1.0.0

package/docs/api/data.md

@@ -0,0 +1,243 @@
+# データ操作
+
+エントリの取得・登録・更新・削除・ページネーションを行うメソッド群。
+
+---
+
+## データ取得
+
+### `getEntry(uri, targetService?)`
+
+```typescript
+getEntry(uri: string, targetService?: string): Promise<any>
+```
+
+指定した URI のエントリを 1 件取得する。データが存在しない場合は `null` / `undefined`（204）を返す。
+
+```typescript
+const entry = await vtecxnext.getEntry('/crm/customer/0000000001')
+if (entry == null) {
+  // データなし（204）
+}
+```
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `uri` | `string` | エントリの URI |
+| `targetService` | `string?` | 連携サービス名（省略可） |
+
+---
+
+### `getFeed(uri, targetService?)`
+
+```typescript
+getFeed(uri: string, targetService?: string): Promise<any>
+```
+
+指定した URI 配下のエントリ一覧を取得する。データが存在しない場合は `null` / `undefined`（204）を返す。
+
+```typescript
+const entries = await vtecxnext.getFeed('/crm/customer')
+```
+
+---
+
+### `getFeedResponse(uri, targetService?)`
+
+```typescript
+getFeedResponse(uri: string, targetService?: string): Promise<VtecxResponse>
+```
+
+`getFeed` と同様だが、ステータスコードやヘッダを含む `VtecxResponse` 形式で返す。
+
+---
+
+### `count(uri, targetService?)`
+
+```typescript
+count(uri: string, targetService?: string): Promise<number | null>
+```
+
+検索条件にマッチするエントリの件数を返す。
+
+```typescript
+const total = await vtecxnext.count('/crm/customer?f&customer.status-eq-active')
+```
+
+---
+
+### `countResponse(uri, targetService?)`
+
+```typescript
+countResponse(uri: string, targetService?: string): Promise<VtecxResponse>
+```
+
+`count` と同様だが `VtecxResponse` 形式で返す。
+
+---
+
+## データ登録・更新
+
+### `post(feed, uri?, targetService?)`
+
+```typescript
+post(feed: any, uri?: string, targetService?: string): Promise<any>
+```
+
+エントリを新規登録する。ID は vte.cx が自動採番する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `feed` | `any` | 登録する feed データ |
+| `uri` | `string?` | 親フォルダの URI（省略可） |
+| `targetService` | `string?` | 連携サービス名（省略可） |
+
+---
+
+### `put(feed, isbulk?, parallel?, async?, targetService?)`
+
+```typescript
+put(
+  feed: any,
+  isbulk?: boolean,
+  parallel?: boolean,
+  async?: boolean,
+  targetService?: string
+): Promise<any>
+```
+
+エントリを登録・更新する。複数エントリを 1 回の呼び出しにまとめること。
+
+```typescript
+await vtecxnext.put({
+  feed: {
+    entry: [
+      {
+        link: [{ ___rel: 'self', ___href: '/crm/customer/001' }],
+        customer: { name: '株式会社テスト' },
+        contributor: [{ uri: 'urn:vte.cx:acl:/_group/$admin,CURD' }],
+      },
+    ],
+  },
+})
+```
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `feed` | `any` | 登録・更新する feed データ |
+| `isbulk` | `boolean?` | 大量データフラグ（省略可） |
+| `parallel` | `boolean?` | 並列処理フラグ（省略可） |
+| `async` | `boolean?` | 非同期処理フラグ（省略可） |
+| `targetService` | `string?` | 連携サービス名（省略可） |
+
+---
+
+## データ削除
+
+### `deleteEntry(uri, revision?, targetService?)`
+
+```typescript
+deleteEntry(uri: string, revision?: number, targetService?: string): Promise<boolean>
+```
+
+指定した URI のエントリを 1 件削除する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `uri` | `string` | 削除するエントリの URI |
+| `revision` | `number?` | リビジョン番号（楽観的排他制御。省略時は強制削除） |
+| `targetService` | `string?` | 連携サービス名（省略可） |
+
+---
+
+### `deleteEntries(feed, isbulk?, parallel?, async?, targetService?)`
+
+```typescript
+deleteEntries(feed: any, isbulk?: boolean, parallel?: boolean, async?: boolean, targetService?: string): Promise<boolean>
+```
+
+複数エントリを一括削除する。
+
+---
+
+### `deleteFolder(uri, async?, targetService?)`
+
+```typescript
+deleteFolder(uri: string, async?: boolean, targetService?: string): Promise<boolean>
+```
+
+フォルダとその配下のエントリをすべて削除する。
+
+---
+
+### `clearFolder(uri, async?, targetService?)`
+
+```typescript
+clearFolder(uri: string, async?: boolean, targetService?: string): Promise<boolean>
+```
+
+フォルダ自体は残し、配下のエントリをすべて削除する。
+
+---
+
+## ページネーション
+
+vte.cx のページネーションは 2 ステップ方式。`getPageWithPagination` がこれを自動処理する。
+
+### `getPageWithPagination(uri, num, targetService?)`
+
+```typescript
+getPageWithPagination(uri: string, num: number, targetService?: string): Promise<any>
+```
+
+`num=1` のとき自動的に `pagination()` を呼び出してカーソルを作成し、指定ページのデータを返す。データなしの場合は `undefined`。
+
+```typescript
+const n = parseInt(vtecxnext.getParameter('n') ?? '1', 10)
+const entries = await vtecxnext.getPageWithPagination('/crm/customer?l=25', n)
+```
+
+---
+
+### `pagination(uri, pagerange, targetService?)`
+
+```typescript
+pagination(uri: string, pagerange: string, targetService?: string): Promise<PaginationInfo>
+```
+
+カーソルリスト（pageindex）を作成する。`pagerange` は `"1,50"` の形式。
+
+```typescript
+const info = await vtecxnext.pagination('/crm/customer?l=25', '1,50')
+// info.lastPageNumber: 最終ページ番号（0 = データなし）
+// info.hasNext: true = 50ページ以降にもデータがある
+```
+
+---
+
+### `getPage(uri, num, targetService?)`
+
+```typescript
+getPage(uri: string, num: number, targetService?: string): Promise<any>
+```
+
+作成済みカーソルを使って指定ページのデータを取得する。`pagination()` 実行後に使用。
+
+---
+
+## 型定義
+
+```typescript
+type VtecxResponse = {
+  status: number
+  header: any
+  data: any
+}
+
+type PaginationInfo = {
+  lastPageNumber: number    // 最終ページ番号（0 = データなし）
+  countWithinRange: number  // 指定ページ範囲内のエントリ数
+  hasNext: boolean          // true = endPage を超えるデータが存在する
+  isMemorysort: boolean     // メモリソートモードかどうか
+}
+```

package/docs/api/db.md

@@ -0,0 +1,148 @@
+# 外部DB連携
+
+BigQuery・RDB（リレーショナルDB）との連携を行うメソッド群。
+
+SQL には `?` プレースホルダを使い、`values` でバインド値を渡す。
+
+---
+
+## BigQuery（クエリ実行）
+
+### `getBQ(sql, values?, parent?)`
+
+```typescript
+getBQ(sql: string, values?: any[], parent?: string): Promise<any>
+```
+
+BigQuery に SELECT クエリを実行し、結果を取得する。
+
+```typescript
+const result = await vtecxnext.getBQ(
+  'SELECT * FROM `dataset.table` WHERE status = ? LIMIT 100',
+  ['active']
+)
+```
+
+---
+
+### `execBQ(sql, values?, parent?)`
+
+```typescript
+execBQ(sql: string, values?: any[], parent?: string): Promise<any>
+```
+
+BigQuery に INSERT / UPDATE / DELETE などのクエリを実行する。
+
+---
+
+### `getBQCsv(sql, values?, filename?, parent?)`
+
+```typescript
+getBQCsv(sql: string, values?: any[], filename?: string, parent?: string): Promise<boolean>
+```
+
+BigQuery クエリの結果を CSV としてレスポンスへ出力する。成功したかどうかを `boolean` で返す。
+
+---
+
+## BigQuery（エントリ連携）
+
+vte.cx のエントリを BigQuery にエクスポート・削除する。`tablenames` でエンティティとテーブルの対応を指定する。
+
+### `postBQ(feed, async?, tablenames?)`
+
+```typescript
+postBQ(feed: any, async?: boolean, tablenames?: any): Promise<boolean>
+```
+
+feed のエントリを BigQuery に登録する。
+
+---
+
+### `deleteBQ(keys, async?, tablenames?)`
+
+```typescript
+deleteBQ(keys: string[], async?: boolean, tablenames?: any): Promise<boolean>
+```
+
+指定したキー（URI）のエントリを BigQuery から削除する。
+
+---
+
+## BigQuery DB（BDBQ）
+
+vte.cx データストアと BigQuery を同時に更新する機能。
+
+### `postBDBQ(feed, uri?, tablenames?, async?)`
+
+```typescript
+postBDBQ(feed: any, uri?: string, tablenames?: any, async?: boolean): Promise<any>
+```
+
+エントリをデータストアと BigQuery に新規登録する。
+
+---
+
+### `putBDBQ(feed, uri?, tablenames?, async?, isbulk?)`
+
+```typescript
+putBDBQ(feed: any, uri?: string, tablenames?: any, async?: boolean, isbulk?: boolean): Promise<any>
+```
+
+エントリをデータストアと BigQuery で更新する。
+
+---
+
+### `deleteBDBQ(keys, tablenames?, async?)`
+
+```typescript
+deleteBDBQ(keys: string[], tablenames?: any, async?: boolean): Promise<boolean>
+```
+
+指定したキー（URI）のエントリをデータストアと BigQuery から削除する。
+
+---
+
+## RDB（リレーショナルDB）
+
+### `queryRDB(sql, values?, parent?)`
+
+```typescript
+queryRDB(sql: string, values?: any[], parent?: string): Promise<any>
+```
+
+RDB に SELECT クエリを実行し、結果を返す。
+
+```typescript
+const rows = await vtecxnext.queryRDB(
+  'SELECT * FROM customers WHERE status = ?',
+  ['active']
+)
+```
+
+---
+
+### `queryRDBCsv(sql, values?, filename?, parent?)`
+
+```typescript
+queryRDBCsv(sql: string, values?: any[], filename?: string, parent?: string): Promise<boolean>
+```
+
+RDB クエリの結果を CSV としてレスポンスへ出力する。成功したかどうかを `boolean` で返す。
+
+---
+
+### `execRDB(sqls, values?, async?, isbulk?)`
+
+```typescript
+execRDB(sqls: string[], values?: any[][], async?: boolean, isbulk?: boolean): Promise<any>
+```
+
+RDB に複数の INSERT / UPDATE / DELETE を実行する。`sqls` は SQL の配列、`values` はそれぞれに対応するバインド値の配列。
+
+```typescript
+await vtecxnext.execRDB(
+  ['UPDATE customers SET status = ? WHERE id = ?'],
+  [['inactive', customerId]]
+)
+```

package/docs/api/group.md

@@ -0,0 +1,151 @@
+# グループ管理
+
+ユーザーのグループ参加・脱退・管理者操作などを行うメソッド群。
+
+グループは `folderacls.json` に事前登録が必要。詳細は [framework.md](../framework.md#グループ管理) を参照。
+
+---
+
+## グループ参加・脱退
+
+### `addGroup(group, selfid?)`
+
+```typescript
+addGroup(group: string, selfid?: string): Promise<any>
+```
+
+自分自身をグループに登録する。グループが存在しない場合は作成される。
+
+```typescript
+await vtecxnext.addGroup('/_group/sales')
+```
+
+---
+
+### `joinGroup(group, selfid?)`
+
+```typescript
+joinGroup(group: string, selfid?: string): Promise<any>
+```
+
+管理者から招待されたグループへの参加を確認する。
+
+---
+
+### `leaveGroup(group)`
+
+```typescript
+leaveGroup(group: string): Promise<boolean>
+```
+
+自分自身をグループから脱退させる。
+
+---
+
+## 管理者によるグループ操作
+
+### `addGroupByAdmin(uids, group, selfid?)`
+
+```typescript
+addGroupByAdmin(uids: string[], group: string, selfid?: string): Promise<any>
+```
+
+管理者権限で指定ユーザー（複数）をグループに追加する。
+
+```typescript
+await vtecxnext.addGroupByAdmin(['uid1', 'uid2'], '/_group/sales')
+```
+
+---
+
+### `leaveGroupByAdmin(uids, group)`
+
+```typescript
+leaveGroupByAdmin(uids: string[], group: string): Promise<any>
+```
+
+管理者権限で指定ユーザーをグループから削除する。
+
+---
+
+### `noGroupMember(uri)`
+
+```typescript
+noGroupMember(uri: string): Promise<any>
+```
+
+グループに登録されているが、正式なメンバーになっていないエントリの一覧を取得する（グループが署名を要求する場合に、署名が無い／不正なエントリが対象）。
+
+---
+
+## グループ情報取得
+
+### `getGroups()`
+
+```typescript
+getGroups(): Promise<string[] | null>
+```
+
+ログインユーザーが所属するグループ名の一覧を取得する。所属がない場合は `null`。
+
+```typescript
+const groups = await vtecxnext.getGroups()
+```
+
+---
+
+### `isGroupMember(uri)`
+
+```typescript
+isGroupMember(uri: string): Promise<boolean>
+```
+
+ログイン中のユーザーが指定グループに所属しているかどうかを返す。
+
+```typescript
+const isSales = await vtecxnext.isGroupMember('/_group/sales')
+// true: 所属, false: 非所属
+```
+
+---
+
+### `isAdmin()`
+
+```typescript
+isAdmin(): Promise<boolean>
+```
+
+ログイン中のユーザーが管理者グループ（`/_group/$admin`）に所属しているかどうかを返す。
+
+```typescript
+const isAdmin = await vtecxnext.isAdmin()
+```
+
+---
+
+## グループ管理者
+
+### `createGroupadmin(createGroupadminInfos)`
+
+```typescript
+createGroupadmin(createGroupadminInfos: CreateGroupadminInfo[]): Promise<any>
+```
+
+グループ管理者を作成する。グループ名と管理者 UID の組を配列で渡す。
+
+```typescript
+type CreateGroupadminInfo = {
+  group: string    // グループ名
+  uids: string[]   // 管理者にする UID の配列
+}
+```
+
+---
+
+### `deleteGroupadmin(groupNames, async?)`
+
+```typescript
+deleteGroupadmin(groupNames: string[], async?: boolean): Promise<any>
+```
+
+指定したグループ（複数）の管理者を削除する。

package/docs/api/index.md

@@ -0,0 +1,117 @@
+# vtecxnext API インデックス
+
+`@vtecx/vtecxnext` v2.3.1 の全メソッド一覧です。
+
+公式リファレンス: https://zenn.dev/vtecx/articles/6a02ab2440ef05
+
+---
+
+## カテゴリ一覧
+
+| カテゴリ | ファイル | 主なメソッド |
+| --- | --- | --- |
+| 認証・セッション | [auth.md](auth.md) | `uid`, `login`, `logout`, `loginWithRxid`, `isLoggedin` |
+| データ操作 | [data.md](data.md) | `getEntry`, `getFeed`, `put`, `post`, `deleteEntry`, `pagination` |
+| ユーザー管理 | [user.md](user.md) | `adduser`, `changepass`, `revokeuser`, `deleteuser` |
+| グループ管理 | [group.md](group.md) | `addGroup`, `joinGroup`, `leaveGroup`, `isGroupMember`, `isAdmin` |
+| 採番・カウンタ | [counter.md](counter.md) | `allocids`, `addids`, `getids`, `setids` |
+| サーバーセッション | [session.md](session.md) | `setSessionFeed`, `getSessionFeed`, `setSessionString` |
+| コンテンツ・ファイル | [content.md](content.md) | `putcontent`, `getcontent`, `savefiles`, `getSignedUrlToPutContent` |
+| メール・通知 | [notify.md](notify.md) | `sendMail`, `pushNotification`, `setMessageQueue` |
+| 外部DB連携 | [db.md](db.md) | `getBQ`, `execBQ`, `queryRDB`, `execRDB`, `postBDBQ` |
+| PDF・署名 | [pdf.md](pdf.md) | `toPdf`, `putSignature`, `checkSignature` |
+| OAuth・TOTP | [oauth.md](oauth.md) | `oauthLine`, `getTotpLink`, `createTotp`, `loginWithTotp` |
+| ACL・エイリアス | [acl.md](acl.md) | `addacl`, `removeacl`, `addalias`, `removealias` |
+| ユーティリティ | [util.md](util.md) | `checkXRequestedWith`, `response`, `getParameter`, `log`, `property` |
+
+---
+
+## 全メソッド索引
+
+### 認証・セッション
+`isLoggedin` / `uid` / `account` / `service` / `now` / `rxid` / `whoami` /
+`login` / `loginWithRxid` / `loginWithTotp` / `logout`
+
+### データ操作
+`getEntry` / `getFeed` / `getFeedResponse` / `count` / `countResponse` /
+`post` / `put` / `deleteEntry` / `deleteEntries` / `deleteFolder` / `clearFolder` /
+`pagination` / `getPage` / `getPageWithPagination`
+
+### ユーザー管理
+`adduser` / `adduserByAdmin` / `adduserByGroupadmin` /
+`passreset` / `changepass` / `changepassByAdmin` /
+`changeaccount` / `changeaccount_verify` /
+`userstatus` / `revokeuser` / `revokeusers` / `activateuser` / `activateusers` /
+`canceluser` / `deleteuser` / `deleteusers`
+
+### グループ管理
+`addGroup` / `addGroupByAdmin` / `joinGroup` / `leaveGroup` / `leaveGroupByAdmin` /
+`noGroupMember` / `getGroups` / `isGroupMember` / `isAdmin` /
+`createGroupadmin` / `deleteGroupadmin`
+
+### 採番・カウンタ
+`allocids` / `addids` / `getids` / `setids` / `rangeids` / `getRangeids`
+
+### サーバーセッション
+`setSessionFeed` / `getSessionFeed` / `deleteSessionFeed` /
+`setSessionEntry` / `getSessionEntry` / `deleteSessionEntry` /
+`setSessionString` / `getSessionString` / `deleteSessionString` /
+`setSessionLong` / `getSessionLong` / `deleteSessionLong` / `incrementSession`
+
+### コンテンツ・ファイル
+`getcontenturl` / `savefiles` / `savefilesBySize` /
+`putcontent` / `putcontentBySize` / `postcontent` / `deletecontent` / `getcontent` /
+`getSignedUrlToPutContent` / `getSignedUrlToPostContent` / `getSignedUrlToGetContent`
+
+### メール・通知
+`sendMail` / `pushNotification` /
+`setMessageQueueStatus` / `getMessageQueueStatus` / `setMessageQueue` / `getMessageQueue`
+
+### 外部DB連携
+`postBQ` / `deleteBQ` / `getBQ` / `execBQ` / `getBQCsv` /
+`postBDBQ` / `putBDBQ` / `deleteBDBQ` /
+`queryRDB` / `queryRDBCsv` / `execRDB`
+
+### PDF・署名
+`toPdf` / `putSignature` / `putSignatures` / `deleteSignature` / `checkSignature`
+
+### OAuth・TOTP
+`oauthLine` / `oauthCallbackLine` / `mergeOAuthUserLine` /
+`getTotpLink` / `createTotp` / `deleteTotp` / `loginWithTotp` / `changeTdid`
+
+### ACL・エイリアス
+`addacl` / `removeacl` / `addalias` / `removealias`
+
+### ユーティリティ
+`getParameter` / `hasParameter` / `buffer` / `isBlank` / `null2blank` /
+`checkXRequestedWith` / `setResponseHeader` / `response` / `sendMessage` /
+`property` / `log` / `isVtecxNextError`
+
+---
+
+## 初期化
+
+```typescript
+import { VtecxNext } from '@vtecx/vtecxnext'
+
+// Next.js API Route 内で初期化
+const vtecxnext = new VtecxNext(req)
+
+// バッチ処理（アクセストークン使用）
+const vtecxnext = new VtecxNext(undefined, accessToken)
+```
+
+## エラークラス
+
+| クラス | 説明 |
+| --- | --- |
+| `VtecxNextError` | vte.cx 関連エラー |
+| `FetchError` | fetch 処理エラー（VtecxNextError を継承） |
+
+```typescript
+import { isVtecxNextError } from '@vtecx/vtecxnext'
+
+if (isVtecxNextError(e)) {
+  // VtecxNextError の処理
+}
+```