@utilix-tech/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,196 +1,440 @@
-# @utilix/sdk
+# @utilix-tech/sdk
 
-**100+ developer utility tools that run entirely in Node.js — no API key, no internet required.**
+**100+ developer utility functions for Node.js — runs locally, no API key required.**
 
-[![npm version](https://img.shields.io/npm/v/@utilix/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix/sdk)
-[![npm downloads](https://img.shields.io/npm/dm/@utilix/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix/sdk)
-[![Node.js version](https://img.shields.io/node/v/@utilix/sdk?style=flat-square)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
+[![Node.js version](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6?style=flat-square)](https://www.typescriptlang.org/)
 
-The same tools available at [utilix.tech](https://utilix.tech), packaged for local use in your Node.js projects. Works offline, ships zero runtime secrets, and is fully tree-shakeable via subpath imports.
+The same tools available at **[utilix.tech](https://utilix.tech)**, packaged as a tree-shakeable Node.js SDK. Works offline, ships zero runtime secrets, and has full TypeScript types included.
 
 ---
 
 ## Installation
 
 ```bash
-npm install @utilix/sdk
+npm install @utilix-tech/sdk
 ```
 
 ```bash
-yarn add @utilix/sdk
+yarn add @utilix-tech/sdk
 ```
 
 ```bash
-pnpm add @utilix/sdk
+pnpm add @utilix-tech/sdk
 ```
 
+**Requires Node.js 18 or later.** TypeScript types are bundled — no `@types/` package needed.
+
 ---
 
 ## Quick Start
 
-Each module is available as a dedicated subpath import so your bundler only pulls in what you use.
+Each of the 14 modules is available as a dedicated subpath import. Import only what you use; bundlers automatically tree-shake the rest.
+
+```ts
+// Pick exactly the modules you need
+import { formatJson, diffJson } from "@utilix-tech/sdk/json";
+import { encodeBase64, decodeBase64 } from "@utilix-tech/sdk/encoding";
+import { hashAll, hashPassword } from "@utilix-tech/sdk/hashing";
+import { convertColor, generatePalette } from "@utilix-tech/sdk/color";
+import { generateUuid, generatePassword } from "@utilix-tech/sdk/generators";
+import { buildCurl, decodeJwt } from "@utilix-tech/sdk/api";
+import { formatSql, testRegex } from "@utilix-tech/sdk/code";
+import { convertCase, slugify } from "@utilix-tech/sdk/text";
+import { parseCsv, yamlToJson } from "@utilix-tech/sdk/data";
+import { diffDates, parseCron } from "@utilix-tech/sdk/time";
+import { convertBytes, pxToAll } from "@utilix-tech/sdk/units";
+import { parseUrl, getStatusCode } from "@utilix-tech/sdk/network";
+import { generateGradient, generateBoxShadow } from "@utilix-tech/sdk/css";
+import { generateQrCode, optimizeSvg } from "@utilix-tech/sdk/misc";
+```
 
-### Format JSON
+CommonJS works too:
 
 ```js
-import { formatJson } from "@utilix/sdk/json";
+const { formatJson } = require("@utilix-tech/sdk/json");
+```
+
+---
+
+## Modules
+
+### `/json` — JSON Tools
+
+```ts
+import { formatJson, minifyJson, diffJson, jsonToTypescript, validateJson,
+         evaluateJsonPath, jsonToCsv, yamlToJson, jsonToYaml, getJsonStats } from "@utilix-tech/sdk/json";
+
+// Format with 2-space indent
+formatJson('{"name":"alice","age":30}', { indent: 2 });
+
+// Diff two JSON strings — returns line-by-line diff
+diffJson(jsonA, jsonB);
+
+// Generate TypeScript interface from JSON
+jsonToTypescript('{"id":1,"name":"Alice"}', { rootName: "User" });
+
+// Query with JSONPath
+evaluateJsonPath(obj, "$.users[*].name");
+
+// Convert JSON to CSV
+jsonToCsv('[{"a":1,"b":2}]');
 
-const pretty = formatJson('{"name":"alice","age":30}', { indent: 2 });
-console.log(pretty);
-// {
-//   "name": "alice",
-//   "age": 30
-// }
+// Validate against JSON Schema
+validateJson(data, schema);
 ```
 
-### Encode / Decode Base64
+---
 
-```js
-import { encodeBase64 } from "@utilix/sdk/encoding";
+### `/encoding` — Encode & Decode
 
-const encoded = encodeBase64("Hello, World!");
-console.log(encoded); // SGVsbG8sIFdvcmxkIQ==
+```ts
+import { encodeBase64, decodeBase64, encodeUrl, decodeUrl,
+         encodeHtmlEntities, decodeHtmlEntities, base32Encode, base32Decode } from "@utilix-tech/sdk/encoding";
+
+encodeBase64("Hello, World!");    // "SGVsbG8sIFdvcmxkIQ=="
+decodeBase64("SGVsbG8sIFdvcmxkIQ==");  // "Hello, World!"
+encodeUrl("hello world?");        // "hello%20world%3F"
+encodeHtmlEntities("<div class=\"a\">");  // "&lt;div class=&quot;a&quot;&gt;"
+base32Encode("hello");            // "NBSWY3DPEB3W64TMMQ======"
 ```
 
-### Hash a Value (async)
+---
 
-```js
-import { hashAll } from "@utilix/sdk/hashing";
+### `/hashing` — Hash & Password
+
+```ts
+import { hashAll, hashOne, hashPassword, verifyPassword, generateHtpasswdFile } from "@utilix-tech/sdk/hashing";
 
-const results = await hashAll("my-secret-string");
-console.log(results);
+// Hash with MD5, SHA-1, SHA-256, SHA-512 in one call
+const hashes = await hashAll("my-string");
 // { md5: "...", sha1: "...", sha256: "...", sha512: "..." }
+
+// bcrypt
+const hash = await hashPassword("my-password", 12);
+const valid = await verifyPassword("my-password", hash);
+
+// Generate .htpasswd file
+generateHtpasswdFile([{ username: "alice", password: "secret" }]);
 ```
 
-### Convert Color Formats
+---
 
-```js
-import { convertColor } from "@utilix/sdk/color";
+### `/text` — String & Text
+
+```ts
+import { convertCase, slugify, countWords, generateWords, generateParagraphs,
+         escapeString, htmlToMarkdown, applyOps } from "@utilix-tech/sdk/text";
+
+convertCase("hello world", "camelCase");   // "helloWorld"
+convertCase("hello world", "PascalCase");  // "HelloWorld"
+convertCase("hello world", "kebab-case");  // "hello-world"
+convertCase("hello world", "snake_case");  // "hello_world"
+convertCase("hello world", "CONSTANT");    // "HELLO_WORLD"
+
+slugify("Hello, World! 123");  // "hello-world-123"
 
-const result = convertColor("#1a2b3c");
-console.log(result);
-// { hex: "#1a2b3c", rgb: "rgb(26, 43, 60)", hsl: "hsl(210, 40%, 17%)" }
+const { words, sentences, readingTime } = countWords("some long text...");
+
+generateParagraphs(3);  // lorem ipsum paragraphs
+
+// Apply line operations: sort, deduplicate, trim, reverse, shuffle
+applyOps(text, ["sort", "deduplicate", "trim"]);
+
+htmlToMarkdown("<h1>Hello</h1><p>World</p>");
 ```
 
-### Build a cURL Command
+---
 
-```js
-import { buildCurlCommand } from "@utilix/sdk/api";
+### `/data` — CSV / YAML / TOML / XML / INI
+
+```ts
+import { parseCsv, csvToJson, validateYaml, tomlToJson, jsonToToml,
+         formatXml, xmlToJson, jsonToXml, parseIni } from "@utilix-tech/sdk/data";
+
+// CSV
+const rows = parseCsv("name,age\nalice,30\nbob,25");
+csvToJson("name,age\nalice,30");  // [{ name: "alice", age: "30" }]
+
+// YAML
+validateYaml("key: value\nlist:\n  - a\n  - b");
+
+// TOML
+tomlToJson('[server]\nhost = "localhost"\nport = 8080');
+jsonToToml({ server: { host: "localhost", port: 8080 } });
+
+// XML
+formatXml("<root><item>hello</item></root>");
+xmlToJson("<root><item>hello</item></root>");
+
+// INI
+parseIni("[db]\nhost=localhost\nport=5432");
+```
+
+---
+
+### `/generators` — UUID, Passwords, Fake Data
+
+```ts
+import { generateUuid, generateV4, generateV7, generateUlid,
+         generatePassword, checkStrength, generateData } from "@utilix-tech/sdk/generators";
+
+generateUuid();       // "f47ac10b-58cc-4372-a567-0e02b2c3d479"  (v4)
+generateV7();         // time-ordered UUID v7
+generateUlid();       // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+
+generatePassword({ length: 16, symbols: true, numbers: true });
+checkStrength("P@ssw0rd!");  // { score: 4, label: "Strong", entropy: 52.4 }
+
+// Generate fake data rows
+generateData([
+  { name: "id", type: "uuid" },
+  { name: "email", type: "email" },
+  { name: "age", type: "number" },
+], 10);  // 10 rows
+```
+
+---
+
+### `/time` — Dates, Timezones, Cron
+
+```ts
+import { diffDates, parseCron, convertTime, formatRelative,
+         getNextRuns, humanizeDiff } from "@utilix-tech/sdk/time";
+
+formatRelative(new Date("2024-01-01"));  // "2 years ago"
+
+diffDates("2024-01-01", "2025-06-15");
+// { years: 1, months: 5, days: 14, ... }
+
+// Timezone conversion
+convertTime("2025-01-01T12:00:00", "America/New_York", "Asia/Tokyo");
 
-const curl = buildCurlCommand({
+// Cron parser
+parseCron("0 9 * * MON-FRI");
+// { description: "At 09:00, Monday through Friday", ... }
+
+getNextRuns("*/5 * * * *", 5);  // next 5 run timestamps
+```
+
+---
+
+### `/units` — Conversions
+
+```ts
+import { convertBytes, pxToAll, convert, formatValue } from "@utilix-tech/sdk/units";
+
+// File sizes
+convertBytes(1073741824, "GB");  // 1
+convertBytes(1073741824);        // "1 GB" (auto-format)
+
+// CSS units
+pxToAll(16);
+// { rem: "1rem", em: "1em", pt: "12pt", vw: "...", vh: "..." }
+
+// Number bases
+convert("255", 10, 16);   // "ff"
+convert("ff", 16, 10);    // "255"
+convert("11111111", 2, 10); // "255"
+
+// Currency / locale formatting
+formatValue(1234567.89, { locale: "en-US", currency: "USD" });
+// "$1,234,567.89"
+```
+
+---
+
+### `/network` — URLs, IPs, HTTP
+
+```ts
+import { getStatusCode, isValidIp, isValidIpv4, isValidIpv6,
+         searchStatusCodes, buildGeoUrl, countryCodeToFlag } from "@utilix-tech/sdk/network";
+
+getStatusCode(404);
+// { code: 404, text: "Not Found", description: "...", category: "Client Error" }
+
+searchStatusCodes("unauthorized");
+
+isValidIpv4("192.168.1.1");   // true
+isValidIpv6("::1");            // true
+isValidIp("256.0.0.1");       // false
+
+countryCodeToFlag("US");       // "🇺🇸"
+```
+
+---
+
+### `/api` — cURL, JWT, CORS, HTTP
+
+```ts
+import { buildCurl, parseCurlCommand, decodeJwt, signJwt,
+         generateCors, generateCspHeader } from "@utilix-tech/sdk/api";
+
+buildCurl({
   method: "POST",
   url: "https://api.example.com/data",
   headers: { "Content-Type": "application/json" },
   body: { key: "value" },
 });
-console.log(curl);
 // curl -X POST https://api.example.com/data \
 //   -H "Content-Type: application/json" \
 //   -d '{"key":"value"}'
-```
 
-### Generate a UUID
+// Parse a curl command back into its parts
+parseCurlCommand('curl -X GET https://api.example.com -H "Authorization: Bearer token"');
 
-```js
-import { generateUuid } from "@utilix/sdk/generators";
+// JWT — decode without verification
+decodeJwt("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");
+// { header: {...}, payload: {...}, isExpired: false, expiresIn: "2h" }
 
-const id = generateUuid();
-console.log(id); // e.g. "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+// Generate CORS headers
+generateCors({ origins: ["https://myapp.com"], methods: ["GET", "POST"] });
+
+// Generate Content-Security-Policy header
+generateCspHeader({ "default-src": ["'self'"], "script-src": ["'self'", "cdn.example.com"] });
 ```
 
-### Diff Two Strings
+---
 
-```js
-import { diffText } from "@utilix/sdk/diff";
+### `/code` — SQL, HTML, RegEx, GQL
 
-const result = diffText("foo bar", "foo baz");
-console.log(result.unified);
-```
+```ts
+import { formatSql, minifySql, testRegex, formatHtml, formatGql,
+         detectDialect, splitStatements } from "@utilix-tech/sdk/code";
 
-### Parse a JWT
+// SQL
+formatSql("SELECT id,name FROM users WHERE active=1 ORDER BY name");
+// SELECT
+//   id,
+//   name
+// FROM users
+// WHERE active = 1
+// ORDER BY name
 
-```js
-import { decodeJwt } from "@utilix/sdk/jwt";
+detectDialect("SELECT TOP 10 * FROM users");  // "tsql"
+splitStatements("SELECT 1; SELECT 2; SELECT 3;");
+
+// Regex
+testRegex("^\\d+$", "12345", ["g"]);
+// { isValid: true, matches: ["12345"], ... }
+
+// HTML
+formatHtml("<div><p>hello</p></div>", { indent: 2 });
+minifyHtml("<div>  <p>  hello  </p>  </div>");
 
-const decoded = decodeJwt("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");
-console.log(decoded.payload);
+// GraphQL
+formatGql("query { user(id: 1) { name email } }");
 ```
 
 ---
 
-## Modules
+### `/color` — Color Conversion & Palettes
 
-All 14 subpath modules and what they cover:
+```ts
+import { parseColor, convertColor, generatePalette, checkContrast } from "@utilix-tech/sdk/color";
 
-| Subpath | Description |
-|---|---|
-| `@utilix/sdk/json` | Format, minify, validate, sort keys, and diff JSON documents |
-| `@utilix/sdk/encoding` | Base64, URL, HTML, hex, and binary encode/decode |
-| `@utilix/sdk/hashing` | MD5, SHA-1, SHA-256, SHA-512, bcrypt, and HMAC helpers (async) |
-| `@utilix/sdk/color` | Convert between hex, RGB, HSL, HSV, CMYK; generate palettes |
-| `@utilix/sdk/api` | Build cURL commands, parse HTTP headers, format request/response pairs |
-| `@utilix/sdk/generators` | UUID v4/v7, nanoid, random strings, passwords, and lorem ipsum |
-| `@utilix/sdk/diff` | Line, word, and character diffs with unified and side-by-side output |
-| `@utilix/sdk/jwt` | Decode and inspect JWT headers, payloads, and expiry without verification |
-| `@utilix/sdk/text` | Case conversion, slugify, truncate, word count, and string transforms |
-| `@utilix/sdk/number` | Format currency, bytes, percentages, and perform unit conversions |
-| `@utilix/sdk/date` | Parse, format, and calculate durations between dates and timestamps |
-| `@utilix/sdk/regex` | Common regex patterns, test strings, and extract capture groups |
-| `@utilix/sdk/network` | Parse URLs, query strings, IP addresses, and CIDR ranges |
-| `@utilix/sdk/crypto` | AES encrypt/decrypt, generate key pairs, and compute checksums |
+parseColor("#1a2b3c");
+// { hex: "#1a2b3c", rgb: { r: 26, g: 43, b: 60 }, hsl: { h: 210, s: 40, l: 17 } }
+
+// Generate a color palette
+generatePalette("#3b82f6", "analogous");   // 5 analogous colors
+generatePalette("#3b82f6", "complementary");
+generatePalette("#3b82f6", "triadic");
+
+// WCAG contrast check
+checkContrast("#ffffff", "#000000");
+// { ratio: 21, aa: true, aaa: true, level: "AAA" }
+```
 
 ---
 
-## Node.js SDK vs Python SDK
+### `/css` — CSS Generators
 
-`@utilix/sdk` is the Node.js companion to [`utilix-sdk`](https://pypi.org/project/utilix-sdk/) on PyPI. Both SDKs expose the same 100+ tools and return identically shaped results so you can share logic and test fixtures across stacks.
+```ts
+import { generateGradient, generateBoxShadow, generateBorderRadius,
+         generateAnimationCSS, generateKeyframesCSS } from "@utilix-tech/sdk/css";
 
-| | Node.js | Python |
-|---|---|---|
-| Install | `npm install @utilix/sdk` | `pip install utilix-sdk` |
-| Import style | Subpath imports (`@utilix/sdk/json`) | Module imports (`from utilix_sdk import json`) |
-| Tree-shaking | Yes — only the subpaths you import are bundled | Not applicable |
-| Async tools | `async/await` (e.g. `hashAll`) | `async def` / `asyncio` equivalents |
-| Return shapes | Identical JSON-serializable objects | Identical JSON-serializable dicts |
-| Runtime | Node 18+ | Python 3.9+ |
+generateGradient({
+  type: "linear",
+  angle: 135,
+  stops: [{ color: "#6366f1", position: 0 }, { color: "#8b5cf6", position: 100 }],
+});
+// "linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%)"
 
-Subpath imports are a deliberate design choice for Node.js: they allow bundlers (webpack, esbuild, Rollup, Vite) to eliminate any modules you do not use, keeping your bundle size minimal.
+generateBoxShadow([{ x: 0, y: 4, blur: 6, spread: -1, color: "rgba(0,0,0,0.1)" }]);
+// "0px 4px 6px -1px rgba(0,0,0,0.1)"
+
+generateBorderRadius({ tl: 8, tr: 8, br: 0, bl: 0 });
+// "8px 8px 0px 0px"
+```
 
 ---
 
-## Surface A (Local) vs Surface B (REST API)
+### `/misc` — SVG, QR, Unicode
 
-### Surface A — Local (this package)
+```ts
+import { optimizeSvg, sanitizeSvg, analyzeString, toUnicodeEscape,
+         formatBytes, calcSavings } from "@utilix-tech/sdk/misc";
 
-`@utilix/sdk` is **Surface A**: everything runs in-process, in your Node.js runtime. No outbound network requests are made. This is ideal for:
+// SVG
+optimizeSvg("<svg>...</svg>");   // minified, cleaned SVG
+sanitizeSvg("<svg>...</svg>");   // XSS-safe SVG
 
-- CI pipelines and build scripts
-- CLI tools and developer tooling
-- Server-side Node.js applications
-- Offline or air-gapped environments
-- Use cases where you cannot send data to an external service
+// QR code (returns SVG or data URL)
+// Note: QR generation requires the browser canvas API; use the utilix.tech API for server-side QR codes
 
-### Surface B — REST API (coming soon)
+// File size
+formatBytes(1048576);           // "1 MB"
+calcSavings(1048576, 524288);   // { saved: 524288, percent: 50 }
 
-**Surface B** is a language-agnostic REST API hosted at `api.utilix.tech`. It exposes the same tools over HTTP so any language or environment can call them with a single `fetch`. Surface B is currently in development and will be announced on [utilix.tech](https://utilix.tech).
+// Unicode
+toUnicodeEscape("Hello");       // "\\u0048\\u0065\\u006C\\u006C\\u006F"
+analyzeString("café");          // { length: 4, codePoints: [...], ... }
+```
 
 ---
 
-## Requirements
+## All Modules at a Glance
 
-- **Node.js 18 or later** — the SDK uses the built-in `crypto` module APIs stabilized in Node 18, as well as native `fetch`.
-- **ESM and CommonJS both supported** — the package ships dual exports. Use `import` in ESM projects or `require` in CommonJS projects without any extra configuration.
+| Import | What it does |
+|---|---|
+| `@utilix-tech/sdk/json` | Format, minify, diff, validate, JSONPath, CSV↔JSON, YAML↔JSON, TS types |
+| `@utilix-tech/sdk/encoding` | Base64, URL, HTML entities, Base32 encode/decode |
+| `@utilix-tech/sdk/hashing` | MD5, SHA-1/256/512, bcrypt, HMAC, .htpasswd |
+| `@utilix-tech/sdk/text` | Case convert, slugify, word count, lorem ipsum, line ops, HTML→Markdown |
+| `@utilix-tech/sdk/data` | CSV, YAML, TOML, XML, INI parse and convert |
+| `@utilix-tech/sdk/generators` | UUID v4/v7, ULID, passwords, strength check, fake data |
+| `@utilix-tech/sdk/time` | Date diff, timezone convert, cron parse, relative time |
+| `@utilix-tech/sdk/units` | Bytes, CSS px/rem, number bases, currency format |
+| `@utilix-tech/sdk/network` | HTTP status codes, IP validation, country flags, geolocation URLs |
+| `@utilix-tech/sdk/api` | cURL build/parse, JWT decode/sign, CORS headers, CSP header |
+| `@utilix-tech/sdk/code` | SQL format/minify, HTML format/minify, regex tester, GraphQL format |
+| `@utilix-tech/sdk/color` | Hex/RGB/HSL/HSV/CMYK convert, palette generation, contrast check |
+| `@utilix-tech/sdk/css` | CSS gradient, box-shadow, border-radius, keyframe animation generators |
+| `@utilix-tech/sdk/misc` | SVG optimize/sanitize, file size format, Unicode inspector |
 
-```js
-// ESM
-import { formatJson } from "@utilix/sdk/json";
+---
+
+## Python SDK
+
+`@utilix-tech/sdk` has a Python companion — [`utilix-sdk`](https://pypi.org/project/utilix-sdk/) on PyPI — with the same 100+ tools and identical return shapes.
 
-// CommonJS
-const { formatJson } = require("@utilix/sdk/json");
+```bash
+pip install utilix-sdk
 ```
 
-TypeScript types are included — no `@types/` package needed.
+Both SDKs return plain JSON-serializable objects so you can share test fixtures and API contracts across languages.
+
+---
+
+## Surface A vs Surface B
+
+**This package is Surface A** — everything runs in-process in your Node.js runtime. No outbound requests, no API key, no rate limits.
+
+A **Surface B REST API** (`api.utilix.tech`) is coming soon for use cases where you can't ship a Node.js or Python runtime. Same tools, callable from any language over HTTP.
 
 ---
 

package/package.json

@@ -1,17 +1,10 @@
 {
   "name": "@utilix-tech/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "100+ developer utility tools for Node.js — JSON, encoding, hashing, color, CSS, network and more. Runs locally, no API key required.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",
   "homepage": "https://utilix.tech",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/utilix-tech/utilix-sdk-node"
-  },
-  "bugs": {
-    "url": "https://github.com/utilix-tech/utilix-sdk-node/issues"
-  },
   "keywords": [
     "developer-tools",
     "utilities",