@growi/sdk-typescript 1.0.0-RC.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [2025-06-02] - SDK Update
+
+### OpenAPI Spec Versions
+- apiv1: 7.2.6-RC.0
+- apiv3: 7.2.6-RC.0
+
+### Changes
+- Reflected the latest version of OpenAPI specifications
+- Regenerated SDK code
+- Code formatting with Biome
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GROWI Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+- [日本語 🇯🇵](./README_JP.md)
+
+# @growi/sdk-typescript
+
+[![npm version](https://badge.fury.io/js/%40growilabs%2Fgrowi-sdk-typescript.svg)](https://badge.fury.io/js/%40growilabs%2Fgrowi-sdk-typescript)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@growi/sdk-typescript` is a TypeScript SDK automatically generated from the official [GROWI](https://growi.org/) OpenAPI specifications using [orval](https://orval.dev/). It supports both GROWI API v1 and v3, enabling type-safe API operations.
+
+### Key Features
+
+- 🏢 **Official SDK by the GROWI Development Team**
+- 🔄 **Automatic code generation from OpenAPI specifications**
+- 🛡️ **Type-safe API operations with TypeScript**
+- 🚀 **axios-based HTTP client**
+- 🔗 **Support for GROWI API v1 and v3**
+- 🎯 **Node.js 18+ support**
+
+## Supported GROWI Versions
+
+This SDK is generated from GROWI's official OpenAPI specifications and supports the specifications obtained from the following endpoints:
+
+- **API v1**: https://docs.growi.org/openapi-spec-apiv1.json
+- **API v3**: https://docs.growi.org/openapi-spec-apiv3.json
+
+The SDK's compatibility depends on the compatibility of GROWI's API specifications. When new API versions are released, the SDK will be automatically updated.
+
+## Installation
+
+You can install it using npm, yarn, or pnpm:
+
+```bash
+# npm
+npm install @growi/sdk-typescript
+
+# yarn
+yarn add @growi/sdk-typescript
+
+# pnpm
+pnpm add @growi/sdk-typescript
+```
+
+## Basic Usage
+
+### Client Initialization
+
+```typescript
+import { AXIOS_INSTANCE } from '@growi/sdk-typescript';
+
+// Set the base URL of your GROWI instance
+AXIOS_INSTANCE.defaults.baseURL = 'https://your-growi-instance.com';
+
+// Set authentication token (if needed)
+AXIOS_INSTANCE.defaults.headers.common['Authorization'] = `Bearer ${your-api-token}`;
+```
+
+### API v3 Usage Example
+
+```typescript
+import apiv3 from '@growi/sdk-typescript/v3';
+
+// Get page list
+try {
+  const pages = await apiv3.getPagesList();
+  console.log(pages);
+} catch (error) {
+  console.error('Failed to fetch pages:', error);
+}
+
+// Get recent pages
+try {
+  const recentPages = await apiv3.getPagesRecent();
+  console.log(recentPages);
+} catch (error) {
+  console.error('Failed to fetch recent pages:', error);
+}
+
+// Using with parameters
+const pagesWithParams = await apiv3.getPagesList({
+  limit: 20,
+  offset: 0
+});
+```
+
+### API v1 Usage Example
+
+```typescript
+import apiv1 from '@growi/sdk-typescript/v1';
+
+// Search pages
+try {
+  const searchResult = await apiv1.searchPages({ q: 'search term' });
+  console.log(searchResult);
+} catch (error) {
+  console.error('Failed to search pages:', error);
+}
+
+// Get comments
+try {
+  const comments = await apiv1.getComments({ page_id: 'your-page-id' });
+  console.log(comments);
+} catch (error) {
+  console.error('Failed to fetch comments:', error);
+}
+```
+
+## API Client Details
+
+### Directory Structure
+
+```
+src/
+├── utils/
+│   └── axios-instance.ts      # Custom axios instance
+├── generated/                  # Codes generated by Orval
+│   ├── v1/                      # API v1 client
+│   │   ├── index.ts
+│   │   └── index.schemas.ts
+│   └── v3/                      # API v3 client
+│       ├── index.ts
+│       └── index.schemas.ts
+```
+
+### API Version Selection
+
+- **API v3**: Contains new features and improved API endpoints. We recommend using v3 whenever possible.
+- **API v1**: Use when you need features not available in v3 or for legacy compatibility.
+
+## Type Definition
+
+All API requests and responses are type-safe:
+
+```typescript
+// Utilize auto-generated type definitions
+import type { 
+  Page, 
+  PageInfo,
+  Comment,
+  SyncStatus
+} from '@growi/sdk-typescript/v3';
+
+// TypeScript's type checking detects errors at compile time
+const pageInfo: PageInfo = {
+  path: '/test',
+  // Other required properties...
+};
+```
+
+## Code Generation and Supported GROWI Versions
+
+This project automatically generates code from GROWI's official OpenAPI specifications:
+
+- **Code generation command**: `pnpm run generate:api`
+- **Configuration file**: `orval.config.ts`
+- **Automatic updates**: GitHub Actions periodically checks for specification updates
+
+## Contributing to Development
+
+### Development Environment Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/weseek/growi-sdk-typescript.git
+cd growi-sdk-typescript
+```
+
+2. Install dependencies:
+```bash
+pnpm install
+```
+
+3. Generate API client:
+```bash
+pnpm run generate:api
+```
+
+### Development Workflow
+
+The following workflows are automatically executed by GitHub Actions:
+
+1. **Specification update detection**: GitHub Actions periodically checks for changes in OpenAPI specifications
+2. **Automatic code generation**: When changes are detected, new client code is automatically generated
+3. **Diff review**: Review the generated code differences and check for breaking changes
+4. **Pull request creation**: Automatically create pull requests when changes are found
+
+### Development Guidelines
+
+- **Coding standards**: Uses [Biome](https://biomejs.dev/)
+- **Linting**: `pnpm run lint`
+- **Build**: `pnpm run build`
+
+### How to Contribute
+
+1. **Report Issues**: Report bugs and feature requests on [GitHub Issues](https://github.com/weseek/growi-sdk-typescript/issues)
+2. **Pull Requests**: 
+   - Fork and create a branch
+   - Implement changes
+   - Add tests (if applicable)
+   - Create a pull request
+
+## License
+
+This project is released under the [MIT License](./LICENSE).
+
+---
+
+## **Notice**
+
+This SDK is under development. APIs may change without notice. Please thoroughly test before using in production environments.
+

package/README_JP.md

@@ -0,0 +1,211 @@
+- [English 🇺🇸](./README.md)
+
+# @growi/sdk-typescript
+
+[![npm version](https://badge.fury.io/js/%40growilabs%2Fgrowi-sdk-typescript.svg)](https://badge.fury.io/js/%40growilabs%2Fgrowi-sdk-typescript)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@growi/sdk-typescript` は、[GROWI](https://growi.org/) の公式 OpenAPI 仕様書から [orval](https://orval.dev/) を使用して自動生成された TypeScript SDK です。GROWI API v1 および v3 の両方をサポートし、型安全な API 操作を可能にします。
+
+### 主な特徴
+
+- 🏢 **GROWI 開発チームによるオフィシャル SDK**
+- 🔄 **OpenAPI 仕様書からの自動コード生成**
+- 🛡️ **TypeScript による型安全な API 操作**
+- 🚀 **axios ベースの HTTP クライアント**
+- 🔗 **GROWI API v1 および v3 のサポート**
+- 🎯 **Node.js 18+ サポート**
+
+## 対応 GROWI バージョン
+
+この SDK は GROWI の公式 OpenAPI 仕様書から生成されており、以下のエンドポイントから取得される仕様に対応しています：
+
+- **API v1**: https://docs.growi.org/openapi-spec-apiv1.json
+- **API v3**: https://docs.growi.org/openapi-spec-apiv3.json
+
+SDK の対応状況は GROWI の API 仕様の互換性に依存します。新しい API バージョンがリリースされると、SDK も自動的に更新されます。
+
+## インストール
+
+npm、yarn、または pnpm を使用してインストールできます：
+
+```bash
+# npm
+npm install @growi/sdk-typescript
+
+# yarn
+yarn add @growi/sdk-typescript
+
+# pnpm
+pnpm add @growi/sdk-typescript
+```
+
+## 基本的な使用方法
+
+### クライアントの初期化
+
+```typescript
+import { AXIOS_INSTANCE } from '@growi/sdk-typescript';
+
+// GROWI インスタンスのベース URL を設定
+AXIOS_INSTANCE.defaults.baseURL = 'https://your-growi-instance.com';
+
+// 認証トークンを設定（必要に応じて）
+AXIOS_INSTANCE.defaults.headers.common['Authorization'] = `Bearer ${your-api-token}`;
+```
+
+### API v3 の使用例
+
+```typescript
+import apiv3 from '@growi/sdk-typescript/v3';
+
+// ページ一覧を取得
+try {
+  const pages = await apiv3.getPagesList();
+  console.log(pages);
+} catch (error) {
+  console.error('ページ一覧の取得に失敗しました:', error);
+}
+
+// 最近更新されたページの取得
+try {
+  const recentPages = await apiv3.getPagesRecent();
+  console.log(recentPages);
+} catch (error) {
+  console.error('最近更新されたページの取得に失敗しました:', error);
+}
+
+// パラメーターの指定
+const pagesWithParams = await apiv3.getPagesList({
+  limit: 20,
+  offset: 0
+});
+```
+
+### API v1 の使用例
+
+```typescript
+import apiv1 from '@growi/sdk-typescript/v1';
+
+// ページの検索
+try {
+  const searchResult = await apiv1.searchPages({ q: 'search term' });
+  console.log(searchResult);
+} catch (error) {
+  console.error('ページの検索に失敗しました:', error);
+}
+
+// コメントの取得
+try {
+  const comments = await apiv1.getComments({ page_id: 'your-page-id' });
+  console.log(comments);
+} catch (error) {
+  console.error('コメントの取得に失敗しました:', error);
+}
+```
+
+## API クライアント詳細
+
+### ディレクトリ構成
+
+```
+src/
+├── utils/
+│   └── axios-instance.ts      # カスタム axios インスタンス
+├── generated/                  # Orval で生成されるソースコード群
+│   ├── v1/                      # API v1 クライアント
+│   │   ├── index.ts
+│   │   └── index.schemas.ts
+│   └── v3/                      # API v3 クライアント
+│       ├── index.ts
+│       └── index.schemas.ts
+```
+
+### API バージョンの使い分け
+
+- **API v3**: 新機能や改良された API エンドポイントが含まれています。可能な限り v3 の使用を推奨します。
+- **API v1**: v3 で提供されていない機能や、レガシー対応が必要な場合に使用してください。
+
+## 型定義
+
+すべての API リクエスト・レスポンスは型安全です：
+
+```typescript
+// 自動生成された型定義を利用
+import type { 
+  Page, 
+  PageInfo,
+  Comment,
+  SyncStatus
+} from '@growi/sdk-typescript/v3';
+
+// TypeScript の型チェックにより、コンパイル時にエラーを検出
+const pageInfo: PageInfo = {
+  path: '/test',
+  // 他の必要なプロパティ...
+};
+```
+
+## コード生成、対応する GROWI バージョンについて
+
+このプロジェクトは、GROWI の公式 OpenAPI 仕様書から自動的にコードを生成します：
+
+- **コード生成コマンド**: `pnpm run generate:api`
+- **設定ファイル**: `orval.config.ts`
+- **自動更新**: GitHub Actions により定期的に仕様書の更新をチェック
+
+
+
+## 開発への貢献
+
+### 開発環境のセットアップ
+
+1. リポジトリをクローン：
+```bash
+git clone https://github.com/weseek/growi-sdk-typescript.git
+cd growi-sdk-typescript
+```
+
+2. 依存関係をインストール：
+```bash
+pnpm install
+```
+
+3. API クライアントを生成：
+```bash
+pnpm run generate:api
+```
+
+### 開発ワークフロー
+
+GitHub Actions により、以下のワークフローが定期実行される
+
+1. **仕様書の更新検知**: GitHub Actions が定期的に OpenAPI 仕様書の変更をチェック
+2. **自動コード生成**: 変更が検知されると、新しいクライアントコードを自動生成
+3. **差分確認**: 生成されたコードの差分を確認し、破壊的変更がないかチェック
+4. **プルリクエスト作成**: 変更があった場合、自動的にプルリクエストを作成
+
+### 開発ガイドライン
+
+- **コーディング規約**: [Biome](https://biomejs.dev/) を使用
+- **リント**: `pnpm run lint`
+- **ビルド**: `pnpm run build`
+
+### 貢献方法
+
+1. **Issue の報告**: バグや機能要求は [GitHub Issues](https://github.com/weseek/growi-sdk-typescript/issues) で報告してください
+2. **プルリクエスト**: 
+   - フォークしてブランチを作成
+   - 変更を実装
+   - テストを追加（該当する場合）
+   - プルリクエストを作成
+
+## ライセンス
+
+このプロジェクトは [MIT License](./LICENSE) の下で公開されています。
+
+---
+
+## **注意**
+
+このSDKは開発中です。API は予告なく変更される可能性があります。本番環境での使用前に十分なテストを行ってください。

package/dist/apiv1/index.d.ts

@@ -0,0 +1,22 @@
+export type * from '../generated/v1/index.js';
+export type * from '../generated/v1/index.schemas.js';
+declare const _default: {
+    getComments: (params?: import("../generated/v1/index.schemas.js").GetCommentsParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").GetComments200>;
+    addComment: (addCommentBody: import("../generated/v1/index.schemas.js").AddCommentBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").AddComment200>;
+    updateComment: (updateCommentBody: import("../generated/v1/index.schemas.js").UpdateCommentBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").UpdateComment200>;
+    removeComment: (removeCommentBody: import("../generated/v1/index.schemas.js").RemoveCommentBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").RemoveComment200>;
+    postLogin: (postLoginBody: import("../generated/v1/index.schemas.js").PostLoginBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").PostLogin200>;
+    postRegister: (postRegisterBody: import("../generated/v1/index.schemas.js").PostRegisterBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").PostRegister200>;
+    getPageTag: (params?: import("../generated/v1/index.schemas.js").GetPageTagParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").GetPageTag200>;
+    getUpdatePostPage: (params?: import("../generated/v1/index.schemas.js").GetUpdatePostPageParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").GetUpdatePostPage200>;
+    searchPages: (params: import("../generated/v1/index.schemas.js").SearchPagesParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").SearchPages200>;
+    searchTags: (params?: import("../generated/v1/index.schemas.js").SearchTagsParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").SearchTags200>;
+    updateTag: (updateTagBody: import("../generated/v1/index.schemas.js").UpdateTagBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").UpdateTag200>;
+    listTags: (params?: import("../generated/v1/index.schemas.js").ListTagsParams, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").ListTags200>;
+    getUserActivationToken: (token: string, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<string>;
+    uploadProfileImage: (uploadProfileImageBody: import("../generated/v1/index.schemas.js").UploadProfileImageBodyOne | import("../generated/v1/index.schemas.js").UploadProfileImageBodyTwo, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").UploadProfileImage200>;
+    removeAttachment: (removeAttachmentBody: import("../generated/v1/index.schemas.js").RemoveAttachmentBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").RemoveAttachment200>;
+    removeProfileImage: (removeProfileImageBody: import("../generated/v1/index.schemas.js").RemoveProfileImageBody, options?: import("axios").AxiosRequestConfig<any> | undefined) => Promise<import("../generated/v1/index.schemas.js").RemoveProfileImage200>;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/apiv1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/apiv1/index.ts"],"names":[],"mappings":"AACA,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,kCAAkC,CAAC;;;;;;;;;;;;;;;;;;;AAItD,wBAAmC"}

package/dist/apiv1/index.js

@@ -0,0 +1,3 @@
+import { getGrowirestapiv1 } from '../generated/v1/index.js';
+export default getGrowirestapiv1();
+//# sourceMappingURL=index.js.map

package/dist/apiv1/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/apiv1/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,eAAe,iBAAiB,EAAE,CAAC"}