Dida365 SDK

TypeScript SDK and CLI for the Dida365 Open API with session-only OAuth2 credentials.

Browse the approved API documentation and SDK guide on Pontx Hub.

Pontx Hub: https://pontx.dev/en/sdks/dida365

Features

• OAuth2 authentication flow with browser-based authorization
• Session-only token handling; credentials are never written to disk
• Token refresh support
• TypeScript support with full type definitions
• Dual CommonJS and ESM module support
• Zero external OAuth dependencies (uses native fetch)

Installation

npm install @pontx/dida365

安装为全局包后，可以使用专用命令浏览和预览 Dida365 API：

npm install --global @pontx/dida365
pontx-dida365 --help
pontx-dida365 search task

Quick Start

import { createDida365Client, Dida365OAuthClient } from '@pontx/dida365';

const oauth = new Dida365OAuthClient({
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
});

// Authenticate (opens a browser and keeps tokens in memory only)
await oauth.authenticate();

// Get access token
const accessToken = await oauth.getAccessToken();

// Create an authenticated API client instance
const client = createDida365Client({ accessToken });
const projects = await client.project.getUserProjects();

Authentication Flow

1. First Run: Opens browser for user authorization

   • Starts local callback server on http://localhost:3000/callback
   • Opens browser to Dida365 authorization page
   • User logs in and authorizes the app
   • Token remains in memory for this client instance

2. Within the same process: Reuses the in-memory token

   • Credentials and tokens are never persisted to disk
   • Re-authenticates after the process exits or the token expires

API Reference

createDida365Client

Creates an isolated API client and applies the supplied OAuth access token to every request. Pass credentials at initialization instead of repeating an Authorization header at each Endpoint.

const client = createDida365Client({
  accessToken: process.env.DIDA365_ACCESS_TOKEN!,
});

Dida365OAuthClient

Constructor

new Dida365OAuthClient(config?: Partial<OAuthConfig>)

Options:

• client_id: OAuth client ID (or set DIDA365_CLIENT_ID)
• client_secret: OAuth client secret (or set DIDA365_CLIENT_SECRET)
• redirect_uri: OAuth callback URL (default: http://localhost:3000/callback)
• scope: Array of permission scopes (default: ['tasks:write', 'tasks:read'])

Methods

authenticate(): Promise<string>

Performs the complete OAuth flow. Returns the access token.

• Checks for a valid in-memory token
• If no valid token, starts OAuth flow:
  • Opens browser for authorization
  • Waits for callback
  • Exchanges authorization code for token
  • Keeps the token in memory
• Returns access token

getAccessToken(): Promise<string>

Returns a valid access token.

• Returns the in-memory token if valid
• Re-authenticates if token is expired
• Throws TokenExpiredError if no valid token and re-authentication fails

refreshAccessToken(): Promise<string>

Refreshes the access token using the refresh token.

• Uses the in-memory refresh token
• Exchanges refresh token for new access token
• Updates the in-memory token state
• Throws OAuthError if no refresh token available

getAuthorizationUrl(state: string): string

Generates the OAuth authorization URL.

• state: CSRF protection state parameter
• Returns full authorization URL

Credential handling

OAuth client credentials and tokens remain in memory for the lifetime of the client instance. Prefer the DIDA365_CLIENT_ID and DIDA365_CLIENT_SECRET environment variables; the SDK never writes either value to disk.

Error Handling

The SDK provides custom error classes:

• OAuthError: Base error class for OAuth-related errors
• TokenExpiredError: Thrown when access token has expired
• StateMismatchError: Thrown when OAuth state parameter doesn't match (CSRF protection)

import { Dida365OAuthClient, OAuthError, TokenExpiredError } from '@pontx/dida365';

try {
  await client.authenticate();
} catch (error) {
  if (error instanceof TokenExpiredError) {
    console.error('Token expired:', error.message);
  } else if (error instanceof OAuthError) {
    console.error('OAuth error:', error.message, error.code);
  }
}

Examples

See the examples/ directory for complete usage examples:

npm run example

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run examples
npm run example

# Watch mode (rebuild on changes)
npm run dev

License

MIT

OAuth Configuration

• Authorization URL: https://dida365.com/oauth/authorize
• Token URL: https://dida365.com/oauth/token
• API Base URL: https://api.dida365.com
• Default Scopes: tasks:write, tasks:read

Security Notes

• State parameter is used for CSRF protection
• Tokens remain in memory for the lifetime of the client process and are not written to disk
• Token expiration includes a 5-minute buffer for clock skew
• OAuth credentials should be kept secure
• Consider using environment variables for client credentials in production