@vtecx/vtecxdocument 1.0.0

package/README.md

@@ -0,0 +1,21 @@
+# @vtecx/vtecxdocument
+
+vte.cx BaaS framework and API documentation package.
+
+## Contents
+
+- `docs/framework.md` — Framework overview
+- `docs/vtecxnext-api.md` — vte.cx Next API guide
+- `docs/api/` — Individual API reference documents
+
+## Usage
+
+```bash
+npm install @vtecx/vtecxdocument
+```
+
+After installation, documentation is available under `node_modules/@vtecx/vtecxdocument/docs/`.
+
+## Source
+
+[https://github.com/reflexworks/vtecxdocument](https://github.com/reflexworks/vtecxdocument)

package/docs/api/acl.md

@@ -0,0 +1,68 @@
+# ACL・エイリアス
+
+エントリのアクセス権限（ACL）とエイリアス（複数パス参照）を操作するメソッド群。
+
+> これらのメソッドは引数に **feed** を取る。対象エントリと追加・削除する ACL／エイリアスを `link` に含めた feed を渡す。
+> 通常は `put()` でエントリ登録・更新時に `contributor`（ACL）や `link` の `rel="alternate"`（エイリアス）を設定すれば足りる。以下は既存エントリの ACL／エイリアスを部分的に増減したい場合に使う。
+
+---
+
+## ACL 操作
+
+### `addacl(feed)`
+
+```typescript
+addacl(feed: any): Promise<any>
+```
+
+feed で指定したエントリに ACL を追加する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `feed` | `any` | 対象エントリと追加する ACL（`contributor`）を含む feed |
+
+#### ACL 文字列の形式
+
+```
+urn:vte.cx:acl:/_group/$admin,CURD    ← 管理者グループにCURD権限
+urn:vte.cx:acl:+,CURDE                ← ログインユーザー全員にCURDE権限
+urn:vte.cx:acl:{uid},CURD             ← 特定ユーザーにCURD権限
+urn:vte.cx:acl:/_group/viewer,R       ← viewerグループに読み取り権限のみ
+```
+
+---
+
+### `removeacl(feed)`
+
+```typescript
+removeacl(feed: any): Promise<any>
+```
+
+feed で指定したエントリから ACL を削除する。
+
+---
+
+## エイリアス操作
+
+エイリアスは同一エントリを複数のパスから参照する仕組み。
+通常は `put()` で `link` 配列に `___rel: 'alternate'` を追加することで設定するが、`addalias` / `removealias` でも操作できる。
+
+詳細は [framework.md](../framework.md#エイリアス横断検索) を参照。
+
+### `addalias(feed)`
+
+```typescript
+addalias(feed: any): Promise<any>
+```
+
+feed で指定したエントリにエイリアスパスを追加する。
+
+---
+
+### `removealias(feed)`
+
+```typescript
+removealias(feed: any): Promise<any>
+```
+
+feed で指定したエントリからエイリアスパスを削除する。

package/docs/api/auth.md

@@ -0,0 +1,153 @@
+# 認証・セッション
+
+ログイン状態の確認・ログイン・ログアウト・ユーザー情報取得を行うメソッド群。
+
+---
+
+## ログイン状態確認
+
+### `isLoggedin()`
+
+```typescript
+isLoggedin(): Promise<boolean>
+```
+
+現在のリクエストがログイン済みかどうかを返す。
+
+---
+
+### `uid()`
+
+```typescript
+uid(): Promise<string>
+```
+
+ログインユーザーの UID を返す。未ログインの場合はエラーをスロー。
+
+```typescript
+const uid = await vtecxnext.uid()
+```
+
+---
+
+### `account()`
+
+```typescript
+account(): Promise<string>
+```
+
+ログインユーザーのアカウント名（メールアドレス）を返す。
+
+---
+
+### `service()`
+
+```typescript
+service(): Promise<string>
+```
+
+現在のサービス名を返す。
+
+```typescript
+const serviceName = await vtecxnext.service()
+```
+
+---
+
+### `now()`
+
+```typescript
+now(): Promise<string>
+```
+
+サーバーの現在日時を ISO 8601 形式で返す。
+
+---
+
+### `rxid()`
+
+```typescript
+rxid(): Promise<string>
+```
+
+リクエスト ID を返す。
+
+---
+
+### `whoami()`
+
+```typescript
+whoami(): Promise<any>
+```
+
+ログインユーザーの詳細情報を feed 形式で返す。
+
+---
+
+## ログイン
+
+### `login(wsse, reCaptchaToken?)`
+
+```typescript
+login(wsse: string, reCaptchaToken?: string): Promise<StatusMessage>
+```
+
+WSSE 認証情報を使ってログインする。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `wsse` | `string` | WSSE 認証情報 |
+| `reCaptchaToken` | `string?` | reCAPTCHA トークン（省略可） |
+
+---
+
+### `loginWithRxid(rxid)`
+
+```typescript
+loginWithRxid(rxid: string): Promise<StatusMessage>
+```
+
+RXID を使ってセッションを確立する。パスワードリセットフローや仮登録完了フローで使用。
+
+```typescript
+const rxid = vtecxnext.getParameter('_RXID') ?? ''
+await vtecxnext.loginWithRxid(rxid)
+```
+
+---
+
+### `loginWithTotp(totp, isTrustedDevice)`
+
+```typescript
+loginWithTotp(totp: string, isTrustedDevice: boolean): Promise<StatusMessage>
+```
+
+TOTP（ワンタイムパスワード）を使ってログインする。多要素認証（MFA）フローで使用。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `totp` | `string` | ワンタイムパスワード |
+| `isTrustedDevice` | `boolean` | 信頼済みデバイスとして登録するか |
+
+---
+
+## ログアウト
+
+### `logout()`
+
+```typescript
+logout(): Promise<StatusMessage>
+```
+
+現在のセッションをログアウトする。
+
+---
+
+## 型定義
+
+```typescript
+type StatusMessage = {
+  status: number
+  message: string
+}
+```

package/docs/api/content.md

@@ -0,0 +1,177 @@
+# コンテンツ・ファイル
+
+バイナリファイルの保存・取得・削除・署名付き URL の発行を行うメソッド群。
+
+> アップロード対象のデータは、`VtecxNext` のコンストラクタに渡した `NextRequest`（リクエストボディ）から読み取られる。メソッド引数でコンテンツ本体を直接渡すのは `putcontent` の `arrayBuffer` のみ。
+
+---
+
+## URL 取得
+
+### `getcontenturl(uri)`
+
+```typescript
+getcontenturl(uri: string): Promise<string>
+```
+
+コンテンツ（ファイル）の URL を取得する。
+
+```typescript
+const url = await vtecxnext.getcontenturl('/files/image/001')
+```
+
+---
+
+## ファイルアップロード
+
+### `savefiles(uri, bysize?)`
+
+```typescript
+savefiles(uri: string, bysize?: boolean): Promise<any>
+```
+
+リクエスト（コンストラクタに渡した `NextRequest`）に含まれるマルチパートフォームデータのファイルを、指定 URI 配下に保存する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `uri` | `string` | 保存先の URI |
+| `bysize` | `boolean?` | サイズ指定モードで保存するか（省略可） |
+
+```typescript
+const result = await vtecxnext.savefiles('/files/image')
+```
+
+---
+
+### `savefilesBySize(uri)`
+
+```typescript
+savefilesBySize(uri: string): Promise<any>
+```
+
+`savefiles(uri, true)` 相当。ファイルをサイズ指定モードで保存する。
+
+---
+
+## コンテンツ操作
+
+### `putcontent(uri, filename?, arrayBuffer?)`
+
+```typescript
+putcontent(uri: string, filename?: string, arrayBuffer?: ArrayBuffer): Promise<any>
+```
+
+コンテンツを指定 URI に保存（上書き）する。`arrayBuffer` を省略した場合はリクエストボディから読み取る。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `uri` | `string` | 保存先 URI |
+| `filename` | `string?` | ファイル名（省略可） |
+| `arrayBuffer` | `ArrayBuffer?` | 保存するコンテンツ本体（省略時はリクエストボディ） |
+
+```typescript
+await vtecxnext.putcontent('/files/report/001', 'report.pdf', pdfArrayBuffer)
+```
+
+---
+
+### `putcontentBySize(uri)`
+
+```typescript
+putcontentBySize(uri: string): Promise<any>
+```
+
+`putcontent` のサイズ指定モード版。
+
+---
+
+### `postcontent(parenturi, extension?, filename?)`
+
+```typescript
+postcontent(parenturi: string, extension?: string, filename?: string): Promise<any>
+```
+
+コンテンツを新規作成する。ID は `parenturi` 配下に vte.cx が自動採番する。
+
+| 引数 | 型 | 説明 |
+| --- | --- | --- |
+| `parenturi` | `string` | 親フォルダの URI |
+| `extension` | `string?` | 拡張子（省略可） |
+| `filename` | `string?` | ファイル名（省略可） |
+
+---
+
+### `getcontent(uri)`
+
+```typescript
+getcontent(uri: string): Promise<boolean>
+```
+
+指定 URI のコンテンツを取得し、レスポンスへ書き出す。取得に成功したかどうかを `boolean` で返す。
+
+```typescript
+const ok = await vtecxnext.getcontent('/files/report/001')
+```
+
+---
+
+### `deletecontent(uri)`
+
+```typescript
+deletecontent(uri: string): Promise<any>
+```
+
+指定 URI のコンテンツを削除する。
+
+---
+
+## 署名付き URL
+
+大容量ファイルの直接アップロード・ダウンロード向け。クライアントが署名付き URL を使って直接 GCS などと通信するため、サーバーを経由しない。戻り値は `ContentSignedUrl` 型。
+
+### `getSignedUrlToPutContent(uri, filename?)`
+
+```typescript
+getSignedUrlToPutContent(uri: string, filename?: string): Promise<ContentSignedUrl>
+```
+
+PUT（上書き保存）用の署名付き URL を発行する。
+
+```typescript
+const signed = await vtecxnext.getSignedUrlToPutContent('/files/video/001', 'movie.mp4')
+```
+
+---
+
+### `getSignedUrlToPostContent(parenturi, extension?, filename?)`
+
+```typescript
+getSignedUrlToPostContent(
+  parenturi: string,
+  extension?: string,
+  filename?: string
+): Promise<ContentSignedUrl>
+```
+
+POST（新規作成）用の署名付き URL を発行する。
+
+---
+
+### `getSignedUrlToGetContent(uri)`
+
+```typescript
+getSignedUrlToGetContent(uri: string): Promise<ContentSignedUrl>
+```
+
+GET（ダウンロード）用の署名付き URL を発行する。
+
+---
+
+## 型定義
+
+```typescript
+type ContentSignedUrl = {
+  url: string    // 署名付き URL
+  key: string    // 対象コンテンツのキー
+}
+```

package/docs/api/counter.md

@@ -0,0 +1,96 @@
+# 採番・カウンタ
+
+連番 ID の払い出しや、カウンタ値の操作を行うメソッド群。
+vte.cx のカウンタ機能は、原子性が保証された連番採番に使用する。
+
+---
+
+## 連番採番
+
+### `allocids(uri, num, targetService?)`
+
+```typescript
+allocids(uri: string, num: number, targetService?: string): Promise<string>
+```
+
+指定した URI のカウンタから `num` 個の連番を払い出す。
+`"{開始},{終了}"` 形式の文字列を返す。
+
+```typescript
+const range = await vtecxnext.allocids('/crm/customer/_ids', 1)
+// 例: "42,43" → 42 を払い出し（num=1 で 1 件）
+const id = range.split(',')[0]           // "42"
+const paddedId = id.padStart(10, '0')   // "0000000042"
+```
+
+---
+
+### `addids(uri, num, targetService?)`
+
+```typescript
+addids(uri: string, num: number, targetService?: string): Promise<number | null>
+```
+
+カウンタに `num` を加算し、加算後の値を返す。
+
+```typescript
+const next = await vtecxnext.addids('/counter/order', 1)
+```
+
+---
+
+## カウンタ参照・設定
+
+### `getids(uri, targetService?)`
+
+```typescript
+getids(uri: string, targetService?: string): Promise<number | null>
+```
+
+カウンタの現在値を取得する。
+
+```typescript
+const current = await vtecxnext.getids('/counter/order')
+```
+
+---
+
+### `setids(uri, num, targetService?)`
+
+```typescript
+setids(uri: string, num: number, targetService?: string): Promise<number | null>
+```
+
+カウンタの値を指定した値に設定する。設定後の値を返す。
+
+```typescript
+await vtecxnext.setids('/counter/order', 1000)
+```
+
+---
+
+## 範囲採番
+
+### `rangeids(uri, range)`
+
+```typescript
+rangeids(uri: string, range: string): Promise<string>
+```
+
+カウンタから指定した範囲を確保する。`range` は `"{開始}-{終了}"` 形式。
+確保した範囲を文字列で返す。
+
+```typescript
+const result = await vtecxnext.rangeids('/counter/order', '1-100')
+// 例: "1-100"
+```
+
+---
+
+### `getRangeids(uri)`
+
+```typescript
+getRangeids(uri: string): Promise<string>
+```
+
+`rangeids()` で確保した範囲の現在値を文字列で返す。