trackgenie-common

Shared utilities and types for TrackGenie. This package is designed to be used in:

• Node.js backends (ESM or CommonJS)
• React frontends (via your bundler: Vite, Webpack, Rollup, Next.js)

It ships dual module formats (ESM + CJS) and TypeScript declarations.

Installation

npm install trackgenie-common

Node.js 18+ is recommended.

Importing

ESM (Node or Browser):

import {
	// date utils
	DATE_FORMAT,
	DATETIME_FORMAT,
	getUTCToday,
	getUTCNow,
	parse,
	parseDate,
	parseDateTime,
	isSame,
	isAfter,
	isBefore,
	isSameOrAfter,
	isSameOrBefore,
	addHours,
	addMinutes,
	addDays,
	addMonths,
	addYears,
	toStartOfDateTime,
	toEndOfDateTime,
	toISO,
	toJSDate,
	// string utils
	capitalize,
	toCamelCase,
	toKebabCase,
	truncate,
	normalizeWhitespace,
	randomString,
	guid,
} from "trackgenie-common";

CommonJS (Node):

const {
	DATE_FORMAT,
	DATETIME_FORMAT,
	getUTCToday,
	getUTCNow,
	parse,
	parseDate,
	parseDateTime,
	isSame,
	isAfter,
	isBefore,
	isSameOrAfter,
	isSameOrBefore,
	addHours,
	addMinutes,
	addDays,
	addMonths,
	addYears,
	toStartOfDateTime,
	toEndOfDateTime,
	toISO,
	toJSDate,
	capitalize,
	toCamelCase,
	toKebabCase,
	truncate,
	normalizeWhitespace,
	randomString,
	guid,
} = require("trackgenie-common");

Date Utilities

Internally powered by moment in UTC. Accepted input formats:

• Date: "YYYY-MM-DD"
• Datetime: "YYYY-MM-DD HH:mm:ss"

Returned strings follow the format rules of each function. ISO strings include a trailing Z to indicate UTC.

Formats

• DATE_FORMAT = "YYYY-MM-DD"
• DATETIME_FORMAT = "YYYY-MM-DD HH:mm:ss"

Generate

• getUTCToday(): string → e.g., "2025-11-24"
• getUTCNow(): string → e.g., "2025-11-24 21:15:32"

Parse

• parse(value: string): moment.Moment | null
  Strictly parses either date or datetime in UTC.
• parseDate(date: string): moment.Moment | null
  Strictly parses "YYYY-MM-DD" in UTC.
• parseDateTime(datetime: string): moment.Moment | null
  Strictly parses "YYYY-MM-DD HH:mm:ss" in UTC.

Examples:

parse("2025-11-24"); // Moment or null
parse("2025-11-24 10:00:00"); // Moment or null
parse("bad"); // null

Compare (UTC)

All return boolean. If either input is invalid, they return false.

• isSame(a: string, b: string)
• isAfter(a: string, b: string)
• isBefore(a: string, b: string)
• isSameOrAfter(a: string, b: string)
• isSameOrBefore(a: string, b: string)

Examples:

isSame("2025-01-01", "2025-01-01 00:00:00"); // true
isAfter("2025-01-01 00:00:01", "2025-01-01 00:00:00"); // true

Arithmetic (UTC)

• addHours(value: string, hours: number): string | null
  Always returns a datetime string (YYYY-MM-DD HH:mm:ss).
• addMinutes(value: string, minutes: number): string | null
  Always returns a datetime string.
• addDays(value: string, days: number): string | null
  Retains the input format (date stays date; datetime stays datetime).
• addMonths(value: string, months: number): string | null
  Retains input format; handles month rollovers (e.g., Jan 31 → Feb end).
• addYears(value: string, years: number): string | null
  Retains input format; leap-year aware.

Examples:

addHours("2025-11-24", 1); // "2025-11-24 01:00:00"
addMinutes("2025-11-24 23:59:30", 45); // "2025-11-25 00:44:30"
addDays("2025-11-24", 1); // "2025-11-25"
addMonths("2025-01-31", 1); // "2025-02-28"
addYears("2024-02-29", 1); // "2025-02-28"

Day Boundaries (UTC)

• toStartOfDateTime(value: string): string | null → "YYYY-MM-DD 00:00:00"
• toEndOfDateTime(value: string): string | null → "YYYY-MM-DD 23:59:59"

Conversions

• toISO(value: string): string | null
  ISO 8601 string with Z (e.g., "2025-11-24T13:45:10.000Z").
  Recommended for API payloads and cross-environment usage.
• toJSDate(value: string): Date | null
  Native Date by first converting to ISO (ensures consistent UTC parsing).

String Utilities

Internally powered by the string package and small helpers.

• capitalize(input: string): string
  Trim + capitalize first letter, lowercases following characters in first word.
• toCamelCase(input: string): string
  Lower camelCase (first char lowercased).
• toKebabCase(input: string): string
  Slug/kebab-case.
• truncate(input: string, maxLength: number, suffix = "..."): string
  Ensures final length ≤ maxLength, appends suffix when truncated.
• normalizeWhitespace(input: string): string
  Trim and collapse whitespace.
• randomString(length: number, charset = 'A-Za-z0-9'): string
  Crypto-backed when available; falls back to Math.random.
• guid(): string
  UUID v4 using uuid.

Examples:

capitalize(" hello WORLD "); // "Hello world"
toCamelCase("Hello world-example"); // "helloWorldExample"
toKebabCase("HelloWorld example"); // "helloworld-example"
truncate("This is a long sentence", 10); // "This is..."
normalizeWhitespace("  a \n b\t c  "); // "a b c"
randomString(16); // 16-char random
guid(); // v4 UUID string

Domain Enums

The library exposes a set of domain enums for common TrackGenie concepts.

Available enums:

• SubscriptionPlan: FREE, STARTER, GROWTH, PRO, ENTERPRISE
• SubscriptionStatus: ACTIVE, CANCELED
• ShipmentStatus: PENDING, INFO_RECEIVED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, EXCEPTION, RETURNED, CANCELED
• ShipmentSource: MANUAL, API, SHOPIFY, WOOCOMMERCE
• Channel: EMAIL, SMS, WHATSAPP

Import:

import {
	SubscriptionPlan,
	SubscriptionStatus,
	ShipmentStatus,
	ShipmentSource,
	Channel,
} from "trackgenie-common";

Example usage:

function isPaidPlan(plan: SubscriptionPlan): boolean {
	return (
		plan === SubscriptionPlan.GROWTH ||
		plan === SubscriptionPlan.PRO ||
		plan === SubscriptionPlan.ENTERPRISE
	);
}

const status: SubscriptionStatus = SubscriptionStatus.ACTIVE;
const source: ShipmentSource = ShipmentSource.API;
const channel: Channel = Channel.WHATSAPP;

Domain Entities

BrandSettings

Represents organization branding configuration.

Fields:

• primary_color?: string
• secondary_color?: string
• logo_url?: string

Organization

Represents a customer organization in TrackGenie.

Fields:

• id: string
• name: string
• slug: string
• email: string
• phone?: string
• website?: string
• subscription_plan: SubscriptionPlan
• subscription_status: SubscriptionStatus
• brand_settings: BrandSettings
• default_timezone: string
• default_language: string
• default_currency: string
• metadata?: Record<string, any>
• created_at: Date
• updated_at: Date

Import:

import {
	Organization,
	BrandSettings,
	SubscriptionPlan,
	SubscriptionStatus,
} from "trackgenie-common";

Example:

const org: Organization = {
	id: "org_123",
	name: "Acme Inc.",
	slug: "acme",
	email: "[email protected]",
	subscription_plan: SubscriptionPlan.PRO,
	subscription_status: SubscriptionStatus.ACTIVE,
	brand_settings: {
		primary_color: "#1a73e8",
		secondary_color: "#0f5bd7",
		logo_url: "https://cdn.example.com/acme-logo.png",
	},
	default_timezone: "America/New_York",
	default_language: "en",
	default_currency: "USD",
	created_at: new Date(),
	updated_at: new Date(),
};

Scripts

• build → bundle ESM + CJS to dist/ with type declarations
• test → run unit tests with Vitest
• lint → ESLint (flat config)
• format → Prettier write

Pre-commit hook (via Husky) runs in this order:

1. lint
2. test
3. format staged files (lint-staged)

If lint or tests fail, the commit is blocked.

Development

# install dependencies
npm install

# run tests
npm test

# lint and format
npm run lint
npm run format

# build the library
npm run build

Publishing

This package is configured for npm publishing (public). Recommended flow:

# bump version in package.json
npm test
npm run build
npm publish --access public

Exports map

• import → dist/index.mjs (ESM)
• require → dist/index.cjs (CJS)
• types → dist/index.d.ts

Compatibility

• Node.js ≥ 18
• Browser usage via bundlers (no Node-only APIs in exposed helpers)
• Tree-shakeable (sideEffects: false)

License

MIT © Dromanis

trackgenie-common

Shared utilities and types for TrackGenie, designed to run in Node.js backends and React frontends.

Installation

npm install trackgenie-common

Usage (ESM)

import { buildGreeting, sum } from "trackgenie-common";

console.log(buildGreeting({ name: "World" })); // Hello, World!
console.log(sum([1, 2, 3])); // 6

Usage (CommonJS)

const { buildGreeting, sum } = require("trackgenie-common");

console.log(buildGreeting({ name: "World" })); // Hello, World!
console.log(sum([1, 2, 3])); // 6

Scripts

• build: Builds ESM and CJS bundles with type declarations into dist/
• dev: Watch mode for local development
• test: Runs unit tests with Vitest
• typecheck: Runs TypeScript type checking
• lint: Lints the source
• format: Formats the repo with Prettier

Publishing

1. Ensure package.json version is updated appropriately.
2. Run:

   npm run test
   npm run build
   npm publish --access public

This package ships dual module formats via exports:

• import: ESM at dist/index.mjs
• require: CJS at dist/index.cjs
• types: Type declarations at dist/index.d.ts