• 日本語 🇯🇵

@growi/sdk-typescript

@growi/sdk-typescript is a TypeScript SDK automatically generated from the official GROWI OpenAPI specifications using orval. 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:

# npm
npm install @growi/sdk-typescript

# yarn
yarn add @growi/sdk-typescript

# pnpm
pnpm add @growi/sdk-typescript

Basic Usage

Client Initialization

import { axiosInstanceManager } from '@growi/sdk-typescript';

axiosInstanceManager.addAxiosInstance({
  appName: 'app-1', // Identifier name
  baseURL: 'https://your-growi-instance-1.com', // GROWI instance URL
  token: 'your-api-token-1', // Authentication token (optional)
})

// Example of adding a second instance
axiosInstanceManager.addAxiosInstance({
  appName: 'app-2',
  baseURL: 'https://your-growi-instance-2.com',
  token: 'your-api-token-2',
})

// Example with Digest authentication when GROWI is behind Digest auth protection
axiosInstanceManager.addAxiosInstance({
  appName: 'app-3',
  baseURL: 'https://your-growi-instance-3.com',
  token: 'your-growi-access-token',
  authorizationHeader: 'Digest username="user", realm="Protected Area", nonce="abc123", uri="/", response="xyz789"', // Digest auth header
})

API v3 Usage Example

import apiv3 from '@growi/sdk-typescript/v3';

// Get page content
try {
  const page = await apiv3.getPage({ pageId: "your-page-id" }, { appName: 'app-1' });
  console.log(page);
} catch (error) {
  console.error('Failed to fetch page:', error);
}

// Create a page
try {
  const createdPage = await apiv3.postPage({ path: 'your-page-path', body: "# New Page" }, { appName: 'app-2' });
  console.log(createdPage);
} catch (error) {
  console.error('Failed to create page:', error);
}

API v1 Usage Example

import apiv1 from '@growi/sdk-typescript/v1';

// Search pages
try {
  const searchResult = await apiv1.searchPages({ q: 'search term' }, { appName: 'app-1' });
  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' }, { appName: 'app-2' });
  console.log(comments);
} catch (error) {
  console.error('Failed to fetch comments:', error);
}

API Client Details

Directory Structure

src/
├── utils/
│   └── axios-instance-manager.ts     # Axios instance management
├── 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.

Authentication Header Override

The SDK now supports overriding the default Bearer token authorization method. When the authorizationHeader option is provided:

• The Authorization header will be set to the provided custom value
• The GROWI access token will be sent via the X-GROWI-ACCESS-TOKEN header

This feature is particularly useful when GROWI is behind authentication systems such as Digest authentication, Basic authentication, or custom proxy authentication that require specific authorization header formats.

Default behavior (Bearer token):

axiosInstanceManager.addAxiosInstance({
  appName: 'default-auth',
  baseURL: 'https://growi.example.com',
  token: 'your-growi-api-token',
  // Authorization header will be: "Bearer your-growi-api-token"
});

Digest authentication example:

axiosInstanceManager.addAxiosInstance({
  appName: 'digest-auth',
  baseURL: 'https://growi.example.com',
  token: 'growi-api-token',
  authorizationHeader: 'Digest username="admin", realm="GROWI Protected", nonce="abc123def456", uri="/", response="calculated-response-hash"',
  // Authorization header will be set to the Digest auth string
  // X-GROWI-ACCESS-TOKEN header will be: "growi-api-token"
});

Basic authentication example:

axiosInstanceManager.addAxiosInstance({
  appName: 'basic-auth',
  baseURL: 'https://growi.example.com',
  token: 'growi-api-token',
  authorizationHeader: 'Basic ' + btoa('username:password'),
  // Authorization header will be: "Basic base64-encoded-credentials"
  // X-GROWI-ACCESS-TOKEN header will be: "growi-api-token"
});

Type Definition

All API requests and responses are type-safe:

// 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:

git clone https://github.com/growilabs/growi-sdk-typescript.git
cd growi-sdk-typescript

2. Install dependencies:

pnpm install

3. Generate API client:

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
• Linting: pnpm run lint
• Build: pnpm run build

How to Contribute

1. Report Issues: Report bugs and feature requests on GitHub 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.

Notice

This SDK is under development. APIs may change without notice. Please thoroughly test before using in production environments.