@venturialstd/toolbox

Toolbox Module for Venturial - Shortcode generation and resolution utilities.

Installation

npm install @venturialstd/toolbox

Features

• Generate Shortcodes: Create unique alphanumeric codes with associated data
• Resolve Shortcodes: Retrieve stored data by code
• Expiration Support: Configurable expiration times (1 minute to 1 year)
• One-Time Use: Optional one-time use codes that are marked as used after resolution

Usage

Import the Module

import { ToolboxModule } from '@venturialstd/toolbox';

@Module({
  imports: [ToolboxModule],
  // ...
})
export class YourModule {}

Use the Service

import { ShortcodeService } from '@venturialstd/toolbox';

@Injectable()
export class YourService {
  constructor(private readonly shortcodeService: ShortcodeService) {}

  async createShortcode() {
    const result = await this.shortcodeService.generate({
      data: { userId: '123', action: 'verify-email' },
      oneTime: true,
      length: 8,
      expirationInMinutes: 30,
    });
    
    console.log(result.code); // e.g., "ABC12345"
  }

  async resolveShortcode(code: string) {
    const result = await this.shortcodeService.resolve(code);
    console.log(result.data); // { userId: '123', action: 'verify-email' }
  }
}

API

ShortcodeService

generate(options: GenerateShortcodeOptions): Promise<ShortcodeResult>

Generates a unique shortcode.

Options:

• data: Record<string, unknown> - Data to store (required)
• oneTime?: boolean - If true, code can only be used once (default: false)
• length?: number - Code length, 4-20 characters (default: 6)
• expirationInMinutes?: number - Expiration time, 1-525600 minutes (default: 10)

Returns:

• code: string - The generated shortcode
• expiresAt: string | null - ISO timestamp when code expires
• oneTime: boolean - Whether this is a one-time use code
• createdAt: string - ISO timestamp when code was created

resolve(code: string): Promise<ResolveShortcodeResult>

Resolves a shortcode and retrieves its data.

Parameters:

• code: string - The shortcode to resolve (required)

Returns:

• data: Record<string, unknown> - The stored data
• code: string - The shortcode that was resolved
• expiresAt: string | null - ISO timestamp when code expires
• oneTime: boolean - Whether this was a one-time use code (true if it was used)
• createdAt: string - ISO timestamp when code was created

Throws:

• NotFoundException - If code not found, expired, or already used

Database

The module requires a PostgreSQL database with the toolbox_shortcode table. Run migrations to create the table:

npm run migration:run

Development

Build

npm run build

Test

npm run test:dev

Publish

npm run release:patch