@venturialstd/toolbox

Toolbox Module for Venturial - Shortcode generation and resolution utilities.

Installation

``bash
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

$3

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

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

$3

`typescript
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

$3

#### generate(options: GenerateShortcodeOptions): Promise

Generates a unique shortcode.

Options:
- data: Record - 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

Resolves a shortcode and retrieves its data.

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

Returns:
- data: Record - 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:

`bash
npm run migration:run
`

Development

$3

`bash
npm run build
`

$3

`bash
npm run test:dev
`

$3

`bash
npm run release:patch
``