WoodsPortal Client SDK

Official TypeScript/JavaScript SDK for WoodsPortal API. This SDK provides a comprehensive client library for interacting with WoodsPortal services including authentication, user management, pipelines, objects, and more.

Features

• 🔐 Authentication - Complete authentication flow including login, logout, password reset, and email verification
• 👤 User Management - User profile management and password changes
• 📊 Pipelines & Objects - List and manage pipelines and objects
• 🍞 Breadcrumbs - Built-in breadcrumb utilities for navigation
• 🔗 URL Utilities - URL generation and routing helpers
• 🔄 Token Management - Automatic token refresh and management
• 📦 TypeScript Support - Full TypeScript definitions included
• 🌳 Tree-shakeable - Optimized for modern bundlers

Installation

npm install woodsportal-client-sdk

or

yarn add woodsportal-client-sdk

or

pnpm add woodsportal-client-sdk

Quick Start

Basic Setup

import { initialize, api } from 'woodsportal-client-sdk';

// Initialize the SDK with your configuration
initialize({
  baseURL: 'https://api.woodsportal.com',
  timeout: 30000,
  hubId: 'your-hub-id', // Optional
  devPortalId: 'your-dev-portal-id', // Optional
});

// Use the API
const { login, isLoading } = api.login({
  onSuccess: (data) => {
    console.log('Login successful!', data);
  },
  onError: (error) => {
    console.error('Login failed:', error);
  },
});

// Perform login
await login({
  username: '[email protected]',
  password: 'your-password',
});

Configuration

Initialize SDK

The SDK must be initialized before use. Call initialize() with your configuration:

import { initialize } from 'woodsportal-client-sdk';

initialize({
  baseURL: 'https://api.woodsportal.com', // Required: Your API base URL
  timeout: 30000, // Optional: Request timeout in milliseconds (default: 50000)
  hubId: 'your-hub-id', // Optional: Hub ID for API requests
  devPortalId: 'your-dev-portal-id', // Optional: Dev Portal ID
  headers: { // Optional: Custom headers
    'X-Custom-Header': 'value',
  },
  routes: { // Optional: Route configuration
    unauthorized: '/login',
    login: '/login',
  },
  skipCurrentPublicPath: () => false, // Optional: Function to skip auth error handling
  onLogout: async () => { // Optional: Logout handler
    // Handle logout
  },
});

API Reference

Authentication

Login

import { api } from 'woodsportal-client-sdk';

const { login, isLoading } = api.login({
  onSuccess: (data) => {
    // Handle successful login
    // Tokens are automatically stored
  },
  onError: (error) => {
    // Handle error
  },
  onLoadingChange: (loading) => {
    // Handle loading state
  },
});

await login({
  username: '[email protected]',
  password: 'password123',
});

Pre-Login

const { preLogin, isLoading } = api.preLogin({
  onSuccess: (data) => {
    // Handle pre-login response
  },
});

await preLogin({
  username: '[email protected]',
});

Logout

const { logout, isLoading } = api.logout({
  onSuccess: () => {
    // Handle successful logout
    // Cookies are automatically cleared
  },
});

await logout();

Verify Email

const { verifyEmail, isLoading } = api.verifyEmail({
  onSuccess: (data) => {
    // Email verified successfully
  },
});

await verifyEmail({
  token: 'verification-token',
});

Forget Password

const { forgetPassword, isLoading } = api.forgetPassword({
  onSuccess: (data) => {
    // Password reset email sent
  },
});

await forgetPassword({
  email: '[email protected]',
});

Reset Password

// Step 1: Verify reset token
const { resetPasswordVerifyToken, isLoading } = api.resetPasswordVerifyToken({
  onSuccess: (data) => {
    // Token verified, proceed to reset
  },
});

await resetPasswordVerifyToken({
  token: 'reset-token',
});

// Step 2: Reset password
const { resetPassword } = api.resetPassword({
  onSuccess: (data) => {
    // Password reset successful
  },
});

await resetPassword({
  newPassword: 'newPassword123',
  confirmPassword: 'newPassword123',
});

User Management

Get Current User

const { me, isLoading } = api.me({
  onSuccess: (user) => {
    console.log('Current user:', user);
  },
});

await me();

Get User Profile

const { profile, isLoading } = api.profile({
  onSuccess: (profile) => {
    console.log('User profile:', profile);
  },
});

await profile();

Change Password

const { changePassword, isLoading } = api.changePassword({
  onSuccess: () => {
    // Password changed successfully
  },
});

await changePassword({
  currentPassword: 'oldPassword123',
  newPassword: 'newPassword123',
  confirmPassword: 'newPassword123',
});

Pipelines

const { pipelines, isLoading } = api.pipelines({
  onSuccess: (data) => {
    console.log('Pipelines:', data);
  },
});

await pipelines({
  // Optional query parameters
  queryParams: {
    page: 1,
    limit: 10,
  },
});

Objects

const { objects, isLoading } = api.objects({
  onSuccess: (data) => {
    console.log('Objects:', data);
  },
});

await objects({
  // Optional query parameters
  queryParams: {
    page: 1,
    limit: 10,
  },
});

Token Management

The SDK automatically handles token refresh. You can also manually check token status:

import { api } from 'woodsportal-client-sdk';

// Check if user is authenticated
const isAuthenticated = api.isAuthenticateApp();

// Check if access token is expired
const isExpired = api.isExpiresAccessToken();

// Get current access token
const token = api.getAccessToken();

// Get refresh token
const refreshToken = api.getRefreshToken();

Breadcrumbs

import { breadcrumbsDetails } from 'woodsportal-client-sdk';

// Get breadcrumbs from URL
const breadcrumbs = breadcrumbsDetails.getBreadcrumbs();

// Get table title
const { tableTitle, singularTableTitle } = breadcrumbsDetails.getTableTitle(
  'component-name',
  'Title',
  'Tickets'
);

// Get form title
const { dialogTitle } = breadcrumbsDetails.getFormTitle(
  'type',
  'Title',
  'addNew'
);

URL Utilities

import { url } from 'woodsportal-client-sdk';

// Generate link
const link = url.useMakeLink('/path', { param: 'value' });

// Update link
const updatedLink = url.useUpdateLink('/path', { param: 'new-value' });

Route Parameters

import { routeParam } from 'woodsportal-client-sdk';

// Get route details
const routeDetails = routeParam.getRouteDetails();

// Get parameter details
const paramDetails = routeParam.getParamDetails('param-name');

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All types are exported for your convenience:

import type {
  HttpClientConfig,
  LoginPayload,
  PreLoginPayload,
  VerifyEmailPayload,
  ResetPasswordPayload,
  ForgetPasswordPayload,
  ChangePasswordPayload,
  MutationOptions,
} from 'woodsportal-client-sdk';

Error Handling

All API methods support error handling through the onError callback:

const { login } = api.login({
  onSuccess: (data) => {
    // Success handler
  },
  onError: (error) => {
    // Error handler
    console.error('Error:', error);
    
    // Access error details
    if (error.response) {
      console.error('Status:', error.response.status);
      console.error('Data:', error.response.data);
    }
  },
});

Loading States

All mutation methods return an isLoading state:

const { login, isLoading } = api.login();

// isLoading is a boolean that indicates if the request is in progress
console.log('Loading:', isLoading);

await login({ username: 'user', password: 'pass' });

Examples

React Example

import { useState, useEffect } from 'react';
import { initialize, api } from 'woodsportal-client-sdk';

function App() {
  useEffect(() => {
    // Initialize SDK
    initialize({
      baseURL: 'https://api.woodsportal.com',
    });
  }, []);

  const handleLogin = async () => {
    const { login } = api.login({
      onSuccess: (data) => {
        console.log('Logged in!', data);
      },
      onError: (error) => {
        console.error('Login error:', error);
      },
    });

    await login({
      username: '[email protected]',
      password: 'password',
    });
  };

  return (
    <button onClick={handleLogin}>
      Login
    </button>
  );
}

Node.js Example

import { initialize, api } from 'woodsportal-client-sdk';

// Initialize SDK
initialize({
  baseURL: 'https://api.woodsportal.com',
});

// Login
const { login } = api.login({
  onSuccess: async (data) => {
    console.log('Login successful');
    
    // Fetch user profile
    const { me } = api.me({
      onSuccess: (user) => {
        console.log('User:', user);
      },
    });
    
    await me();
  },
});

await login({
  username: '[email protected]',
  password: 'password',
});

Building from Source

# Clone the repository
git clone https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-sdk.git
cd digitalwoods.io-woodsportal-client-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

Development

# Development mode with watch
npm run dev

# Run tests in watch mode
npm run test:watch

# Check code formatting
npm run format:check

# Fix code formatting
npm run format

# Type checking
npm run type-check

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC License

Copyright (c) 2025, Digital Woods

See LICENSE file for details.

Support

For issues, questions, or contributions, please visit our GitHub repository.

Changelog

See CHANGELOG.md for a list of changes and version history.