@bagooon/chatease-node-client 0.1.0

package/README.md

@@ -0,0 +1,273 @@
+# @bagooon/chatease-node-client
+
+Node.js 向けの **ChatEase チャットボード API クライアント** です。  
+サーバーサイド（Node.js）専用で、ブラウザからの利用は想定していません。
+
+> ⚠️ This package is **Node.js-only**.  
+> Do **NOT** use it in browser environments. Your API token will be exposed.
+
+---
+
+## Features
+
+- ChatEase の「チャットボード生成 API」を安全にラップ
+- 3パターンのメソッドを提供
+  - チャットボード生成のみ
+  - チャットボード + 初期ステータス
+  - チャットボード + 初期ステータス + 初期投稿
+- TypeScript フルサポート（型定義同梱）
+- 実行時バリデーション
+  - `timeLimit` の日付妥当性（`YYYY-MM-DD` & 実在日付）
+  - `guest.email` の簡易フォーマットチェック
+  - `boardUniqueKey` の妥当性チェック
+
+---
+
+## Requirements
+
+- Node.js **18+** （グローバル `fetch` が必要）
+- ChatEase のワークスペーススラッグ & API トークン
+- サーバーサイド（Node.js）環境のみ
+
+---
+
+## Installation
+
+```bash
+npm install @bagooon/chatease-node-client
+# or
+yarn add @bagooon/chatease-node-client
+# or
+pnpm add @bagooon/chatease-node-client
+```
+
+---
+
+## Quick Start
+
+```ts
+import { ChatEaseClient } from '@hashimoto-giken/chatease-node-client'
+
+const chatease = new ChatEaseClient({
+  apiToken: process.env.CHATEASE_API_TOKEN!,
+  workspaceSlug: 'your-workspace-slug',
+})
+
+// 1) チャットボードのみ生成
+const res1 = await chatease.createBoard({
+  title: 'お問い合わせ #1001',
+  guest: {
+    name: '田中太郎',
+    email: 'taro@example.com',
+  },
+  boardUniqueKey: '20260225-1001',
+})
+
+console.log(res1.guestURL)
+
+// 2) 初期ステータス付きで生成
+const res2 = await chatease.createBoardWithStatus({
+  title: '見積依頼 #1002',
+  guest: {
+    name: 'Suzuki Hanako',
+    email: 'hanako@example.com',
+  },
+  boardUniqueKey: '20260225-1002',
+  initialStatus: {
+    statusKey: 'scheduled_for_response',
+    timeLimit: '2026-02-28', // YYYY-MM-DD
+  },
+})
+
+// 3) 初期ステータス + 初期投稿付きで生成
+const res3 = await chatease.createBoardWithStatusAndMessage({
+  title: 'デザイン相談 #1003',
+  guest: {
+    name: 'John Smith',
+    email: 'john@example.com',
+  },
+  boardUniqueKey: '20260225-1003',
+  initialStatus: {
+    statusKey: 'scheduled_for_proof',
+    timeLimit: '2026-03-05',
+  },
+  initialGuestComment: {
+    content: 'ロゴデザインについて相談したいです。現在の案を添付しました。',
+  },
+})
+```
+
+---
+
+## API
+
+### `new ChatEaseClient(options)`
+
+```ts
+interface ChatEaseClientOptions {
+  apiToken: string
+  workspaceSlug: string
+  baseUrl?: string // default: 'https://chatease.jp'
+}
+```
+
+- `apiToken` – ChatEase の API トークン
+- `workspaceSlug` – ワークスペースの slug
+- `baseUrl` – ステージングなどを使う場合に差し替え。通常は指定不要。
+
+ブラウザ環境（window が存在する）で呼び出すと、即座にエラーを投げます。
+
+---
+
+### `createBoard(params)`
+
+```ts
+interface GuestInfo {
+  name: string
+  email: string
+}
+
+interface CreateBoardBaseParams {
+  title: string
+  guest: GuestInfo
+  boardUniqueKey: string
+  inReplyTo?: string
+}
+
+createBoard(params: CreateBoardBaseParams): Promise<CreateBoardResponse>
+```
+
+最低限の情報でチャットボードを生成します。
+
+- `boardUniqueKey` は同じ値で再度呼び出すと、既存ボードが返ってくる仕様です
+- `guest.email` は簡易フォーマットチェックが行われます
+- `boardUniqueKey` は空文字や空白を含む値は拒否されます
+
+---
+
+### `createBoardWithStatus(params)`
+
+```ts
+type ChatEaseStatusKey =
+  | 'scheduled_for_proof'
+  | 'scheduled_for_response'
+  | 'scheduled_for_completion'
+  | 'waiting_for_reply'
+
+type InitialStatus =
+  | {
+      statusKey:
+        | 'scheduled_for_proof'
+        | 'scheduled_for_response'
+        | 'scheduled_for_completion'
+      timeLimit: string // YYYY-MM-DD
+    }
+  | {
+      statusKey: 'waiting_for_reply'
+      timeLimit?: never
+    }
+
+interface CreateBoardWithStatusParams extends CreateBoardBaseParams {
+  initialStatus: InitialStatus
+}
+
+createBoardWithStatus(
+  params: CreateBoardWithStatusParams
+): Promise<CreateBoardResponse>
+```
+
+- `scheduled_for_*` の場合は timeLimit が必須
+- `waiting_for_reply` の場合は timeLimit は指定できません（型でも実行時でも防止）
+
+---
+
+### `createBoardWithStatusAndMessage(params)`
+
+```ts
+interface InitialGuestComment {
+  content: string
+}
+
+interface CreateBoardWithStatusAndMessageParams
+  extends CreateBoardBaseParams {
+  initialStatus: InitialStatus
+  initialGuestComment: InitialGuestComment
+}
+
+createBoardWithStatusAndMessage(
+  params: CreateBoardWithStatusAndMessageParams
+): Promise<CreateBoardResponse>
+```
+
+初回のゲスト投稿までまとめて登録する場合に使います。
+
+---
+
+### `CreateBoardResponse`
+
+```ts
+interface CreateBoardResponse {
+  slug: string
+  hostURL: string
+  guestURL: string
+}
+```
+
+- `slug` – ボードの識別子
+- `hostURL` – ホスト（管理側）用 URL
+- `guestURL` – ゲスト側 URL（メールに貼るなど）
+
+---
+
+## Validation
+
+このクライアントは、API 呼び出し前に以下の実行時チェックを行います：
+
+- guest.email – 簡易メール形式チェック
+- boardUniqueKey
+    - 空文字禁止
+    - 前後の空白禁止
+    - 空白文字（スペース・タブ・改行など）を含まない
+    - 最大 255 文字まで
+- initialStatus.timeLimit
+    - scheduled_for_* の場合は必須
+    - YYYY-MM-DD 形式
+    - 実在する日付か確認（うるう年を含む）
+
+バリデーションエラーの場合、API は呼び出されず Error が投げられます。
+
+---
+
+## Development
+
+ローカル開発用コマンド：
+
+```bash
+# 依存関係インストール
+npm install
+
+# テスト実行（1回）
+npm run test
+
+# テストをウォッチモードで実行
+npm run test:watch
+
+# ビルド
+npm run build
+```
+
+リリース前チェック：
+
+```bash
+# テスト & ビルド
+npm run test
+npm run build
+```
+
+`npm publish` 時には自動的に `npm run test && npm run build` が実行されます。
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { ChatEaseClientOptions, CreateBoardBaseParams, CreateBoardWithStatusParams, CreateBoardWithStatusAndMessageParams, CreateBoardResponse } from './types.js';
+export declare class ChatEaseClient {
+    private readonly apiToken;
+    private readonly workspaceSlug;
+    private readonly baseUrl;
+    constructor(options: ChatEaseClientOptions);
+    createBoard(params: CreateBoardBaseParams): Promise<CreateBoardResponse>;
+    createBoardWithStatus(params: CreateBoardWithStatusParams): Promise<CreateBoardResponse>;
+    createBoardWithStatusAndMessage(params: CreateBoardWithStatusAndMessageParams): Promise<CreateBoardResponse>;
+    /**
+     * 実処理 + 共通バリデーション
+     */
+    private _createBoard;
+    /**
+     * 呼び出しパラメータのバリデーション
+     * - email 形式チェック
+     * - boardUniqueKey 妥当性チェック
+     * - initialStatus があれば timeLimit を検証
+     */
+    private validateParams;
+    private buildUrl;
+}

package/dist/client.js

@@ -0,0 +1,83 @@
+import { isValidBoardUniqueKey, isValidEmail, validateInitialStatus, } from './validators.js';
+export class ChatEaseClient {
+    constructor(options) {
+        if (typeof window !== 'undefined') {
+            throw new Error('ChatEaseClient is for Node.js only. Do not use it in the browser (API token leak risk).');
+        }
+        if (!options.apiToken) {
+            throw new Error('ChatEaseClient: apiToken is required');
+        }
+        if (!options.workspaceSlug) {
+            throw new Error('ChatEaseClient: workspaceSlug is required');
+        }
+        this.apiToken = options.apiToken;
+        this.workspaceSlug = options.workspaceSlug;
+        this.baseUrl = options.baseUrl ?? 'https://chatease.jp';
+        if (typeof fetch !== 'function') {
+            throw new Error('ChatEaseClient requires global fetch (Node.js v18+).');
+        }
+    }
+    async createBoard(params) {
+        return this._createBoard(params);
+    }
+    async createBoardWithStatus(params) {
+        return this._createBoard(params);
+    }
+    async createBoardWithStatusAndMessage(params) {
+        return this._createBoard(params);
+    }
+    /**
+     * 実処理 + 共通バリデーション
+     */
+    async _createBoard(params) {
+        this.validateParams(params);
+        const body = {
+            workspaceSlug: this.workspaceSlug,
+            ...params,
+        };
+        const res = await fetch(this.buildUrl('/api/v1/board'), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Chatease-API-Token': this.apiToken,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            const message = [
+                `ChatEase API error: ${res.status} ${res.statusText}`,
+                text && `Body: ${text}`,
+            ]
+                .filter(Boolean)
+                .join(' - ');
+            throw new Error(message);
+        }
+        const json = (await res.json());
+        return json;
+    }
+    /**
+     * 呼び出しパラメータのバリデーション
+     * - email 形式チェック
+     * - boardUniqueKey 妥当性チェック
+     * - initialStatus があれば timeLimit を検証
+     */
+    validateParams(params) {
+        const { guest, boardUniqueKey } = params;
+        if (!guest?.email) {
+            throw new Error('guest.email is required');
+        }
+        if (!isValidEmail(guest.email)) {
+            throw new Error(`guest.email is invalid: ${guest.email}`);
+        }
+        if (!isValidBoardUniqueKey(boardUniqueKey)) {
+            throw new Error(`boardUniqueKey is invalid. It must be a non-empty string without whitespace and <= 255 chars. Got: "${boardUniqueKey}"`);
+        }
+        if ('initialStatus' in params && params.initialStatus) {
+            validateInitialStatus(params.initialStatus);
+        }
+    }
+    buildUrl(path) {
+        return `${this.baseUrl.replace(/\/+$/, '')}${path}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './client.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// src/index.ts
+export * from './types.js';
+export * from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export type ChatEaseStatusKey = 'scheduled_for_proof' | 'scheduled_for_response' | 'scheduled_for_completion' | 'waiting_for_reply';
+type ScheduledStatusKey = 'scheduled_for_proof' | 'scheduled_for_response' | 'scheduled_for_completion';
+type NonScheduledStatusKey = 'waiting_for_reply';
+export type InitialStatus = {
+    statusKey: ScheduledStatusKey;
+    /**
+     * scheduled_for_* の場合は必須
+     * YYYY-MM-DD
+     */
+    timeLimit: string;
+} | {
+    statusKey: NonScheduledStatusKey;
+    /**
+     * scheduled 以外は timeLimit を指定させない
+     */
+    timeLimit?: never;
+};
+export interface ChatEaseClientOptions {
+    apiToken: string;
+    workspaceSlug: string;
+    baseUrl?: string;
+}
+export interface GuestInfo {
+    name: string;
+    email: string;
+}
+export interface InitialGuestComment {
+    content: string;
+}
+export interface CreateBoardBaseParams {
+    title: string;
+    guest: GuestInfo;
+    boardUniqueKey: string;
+    inReplyTo?: string;
+}
+export interface CreateBoardWithStatusParams extends CreateBoardBaseParams {
+    initialStatus: InitialStatus;
+}
+export interface CreateBoardWithStatusAndMessageParams extends CreateBoardBaseParams {
+    initialStatus: InitialStatus;
+    initialGuestComment: InitialGuestComment;
+}
+export interface CreateBoardRequestBody extends CreateBoardBaseParams {
+    workspaceSlug: string;
+    inReplyTo?: string;
+    initialStatus?: InitialStatus;
+    initialGuestComment?: InitialGuestComment;
+}
+export interface CreateBoardResponse {
+    slug: string;
+    hostURL: string;
+    guestURL: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+// src/types.ts
+export {};

package/dist/validators.d.ts

@@ -0,0 +1,27 @@
+import type { InitialStatus } from './types.js';
+/**
+ * YYYY-MM-DD 形式 & 実在する日付かをチェック
+ */
+export declare function isValidISODate(dateStr: string): boolean;
+/**
+ * メールアドレスの簡易バリデーション
+ * RFC完全準拠ではなく、実務的な最低限チェック。
+ * 「本気の検証」は呼び出し側に任せる。
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * boardUniqueKey のバリデーション
+ *
+ * ここは仕様に合わせて調整する想定。
+ * 現状は：
+ * - 空文字禁止
+ * - 前後空白を許可しない（trimして変化するならNG）
+ * - 制御文字・空白を含まない
+ * - 長さ 1〜255 文字
+ */
+export declare function isValidBoardUniqueKey(key: string): boolean;
+/**
+ * InitialStatus の timeLimit を検証
+ * scheduled_for_* のときは timeLimit 必須（型でも実行時でも保証）
+ */
+export declare function validateInitialStatus(status: InitialStatus): void;

package/dist/validators.js

@@ -0,0 +1,63 @@
+// src/validators.ts
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * YYYY-MM-DD 形式 & 実在する日付かをチェック
+ */
+export function isValidISODate(dateStr) {
+    if (!ISO_DATE_REGEX.test(dateStr))
+        return false;
+    const [y, m, d] = dateStr.split('-').map(Number);
+    // UTC で日付オブジェクトを作成（タイムゾーン非依存）
+    const date = new Date(Date.UTC(y, m - 1, d));
+    return (date.getUTCFullYear() === y &&
+        date.getUTCMonth() === m - 1 &&
+        date.getUTCDate() === d);
+}
+/**
+ * メールアドレスの簡易バリデーション
+ * RFC完全準拠ではなく、実務的な最低限チェック。
+ * 「本気の検証」は呼び出し側に任せる。
+ */
+export function isValidEmail(email) {
+    // かなり緩めのチェック（@の前後にそれなりの文字列があるか）
+    const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return EMAIL_REGEX.test(email);
+}
+/**
+ * boardUniqueKey のバリデーション
+ *
+ * ここは仕様に合わせて調整する想定。
+ * 現状は：
+ * - 空文字禁止
+ * - 前後空白を許可しない（trimして変化するならNG）
+ * - 制御文字・空白を含まない
+ * - 長さ 1〜255 文字
+ */
+export function isValidBoardUniqueKey(key) {
+    if (!key)
+        return false;
+    if (key.trim() !== key)
+        return false;
+    if (key.length > 255)
+        return false;
+    // 空白や制御文字を禁止（必要に応じて緩めてもOK）
+    const INVALID_CHARS_REGEX = /[\s]/;
+    if (INVALID_CHARS_REGEX.test(key))
+        return false;
+    return true;
+}
+/**
+ * InitialStatus の timeLimit を検証
+ * scheduled_for_* のときは timeLimit 必須（型でも実行時でも保証）
+ */
+export function validateInitialStatus(status) {
+    if ('timeLimit' in status) {
+        const { timeLimit } = status;
+        if (!timeLimit) {
+            throw new Error('initialStatus.timeLimit is required when statusKey is scheduled_for_*');
+        }
+        if (!isValidISODate(timeLimit)) {
+            throw new Error(`initialStatus.timeLimit must be a valid date in YYYY-MM-DD format. Got: ${timeLimit}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bagooon/chatease-node-client",
+  "version": "0.1.0",
+  "description": "Node.js-only client for ChatEase board API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "chatease",
+    "chat",
+    "board",
+    "api",
+    "node"
+  ],
+  "author": "Hashimoto Giken",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "browser": {
+    "./dist/index.js": false
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@vitest/ui": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}