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-hub.vercel.app/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/api-dida365

Quick Start

import { Dida365OAuthClient } from '@pontx/api-dida365';

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

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

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

// Use token for API requests
const response = await fetch('https://api.dida365.com/open/v1/project', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

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/api-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 are stored locally in ~/.pontx/dida365/config.json
• 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