@utilix-tech/sdk 0.2.0 → 0.3.0

package/README.md

@@ -26,13 +26,13 @@ yarn add @utilix-tech/sdk
 pnpm add @utilix-tech/sdk
 ```
 
-**Requires Node.js 18 or later.** TypeScript types are bundled — no `@types/` package needed.
+**Requires Node.js 18 or later.** The public npm package includes bundled TypeScript types, so no `@types/` package is needed.
 
 ---
 
 ## Quick Start
 
-Each of the 14 modules is available as a dedicated subpath import. Import only what you use; bundlers automatically tree-shake the rest.
+Each of the 16 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
@@ -127,7 +127,7 @@ generateHtpasswdFile([{ username: "alice", password: "secret" }]);
 
 ```ts
 import { convertCase, slugify, countWords, generateWords, generateParagraphs,
-         escapeString, htmlToMarkdown, applyOps } from "@utilix-tech/sdk/text";
+         escapeString, htmlToMarkdown, applyOps, detectPassiveVoice } from "@utilix-tech/sdk/text";
 
 convertCase("hello world", "camelCase");   // "helloWorld"
 convertCase("hello world", "PascalCase");  // "HelloWorld"
@@ -145,6 +145,9 @@ generateParagraphs(3);  // lorem ipsum paragraphs
 applyOps(text, ["sort", "deduplicate", "trim"]);
 
 htmlToMarkdown("<h1>Hello</h1><p>World</p>");
+
+// Flag passive-voice sentences, e.g. "was written", "were approved by the team"
+detectPassiveVoice("The report was reviewed by the committee. They approved it.");
 ```
 
 ---
@@ -397,6 +400,22 @@ analyzeString("café");          // { length: 4, codePoints: [...], ... }
 
 ---
 
+### `/media` — Image Header Parsing
+
+```ts
+import { readImageInfo } from "@utilix-tech/sdk/media";
+
+// Reads format, dimensions, bit depth, and alpha channel straight from
+// file bytes — no decoding, no canvas, no image library.
+const bytes = await fs.promises.readFile("photo.png");
+readImageInfo(new Uint8Array(bytes));
+// { format: "png", width: 1920, height: 1080, bitDepth: 8, colorType: "rgba", hasAlpha: true }
+```
+
+Supports PNG, JPEG, GIF, WebP, and BMP.
+
+---
+
 ## All Modules at a Glance
 
 | Import | What it does |
@@ -415,6 +434,8 @@ analyzeString("café");          // { length: 4, codePoints: [...], ... }
 | `@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 |
+| `@utilix-tech/sdk/ai_agent` | Token estimate/trim, chunk text, extract URLs/JSON/keywords, sanitize HTML, flatten/merge JSON, dedupe lines, validate schema, PII/secret/injection detect |
+| `@utilix-tech/sdk/media` | Image format & dimension reading from raw bytes — PNG, JPEG, GIF, WebP, BMP |
 
 ---
 
@@ -430,14 +451,30 @@ Both SDKs return plain JSON-serializable objects so you can share test fixtures
 
 ---
 
-## Surface A vs Surface B
+## REST API
 
 **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.
+The same 100+ tools are also available as a hosted **REST API** at `https://api.utilix.tech/v1` for environments where you can't ship a Node.js runtime, or for cross-language teams.
+
+```bash
+curl -X POST https://api.utilix.tech/v1/tools/hash \
+  -H "Authorization: Bearer utx_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{"input": "hello world", "algorithm": "sha256"}'
+```
+
+- **Free**: 1,000 requests/day — no credit card required
+- **Pro**: 10,000 requests/day — $9/month
+- Try it live at **[utilix.tech/api](https://utilix.tech/api)** — no signup needed for the first 10 endpoints
+- Get your API key at **[utilix.tech/dashboard](https://utilix.tech/dashboard)**
 
 ---
 
+## Publishing (maintainers)
+
+CI publishes automatically via npm Trusted Publishing (OIDC) on every push to `main` that bumps `version`. Requires npm **>=11.5.1** — older versions (e.g. the npm bundled with Node 20) sign provenance but skip the OIDC auth exchange, so `npm publish` fails with a 404 as if unauthenticated.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE) for details.

package/dist/chunk-T3JTY2M5.js

@@ -0,0 +1,134 @@
+import { __export } from './chunk-MLKGABMK.js';
+
+// src/tools/media.ts
+var media_exports = {};
+__export(media_exports, {
+  readImageInfo: () => readImageInfo
+});
+function readU32BE(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+function readI32LE(bytes, offset) {
+  return bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24;
+}
+var PNG_COLOR_TYPES = {
+  0: "grayscale",
+  2: "rgb",
+  3: "palette",
+  4: "grayscale+alpha",
+  6: "rgba"
+};
+function readPng(bytes) {
+  if (bytes.length < 33) return { error: "Truncated PNG file" };
+  const width = readU32BE(bytes, 16);
+  const height = readU32BE(bytes, 20);
+  const bitDepth = bytes[24];
+  const colorTypeNum = bytes[25];
+  const colorType = PNG_COLOR_TYPES[colorTypeNum] ?? "unknown";
+  const hasAlpha = colorTypeNum === 4 || colorTypeNum === 6;
+  return { format: "png", width, height, bitDepth, colorType, hasAlpha };
+}
+function readGif(bytes) {
+  if (bytes.length < 10) return { error: "Truncated GIF file" };
+  const width = bytes[6] | bytes[7] << 8;
+  const height = bytes[8] | bytes[9] << 8;
+  return { format: "gif", width, height };
+}
+function readBmp(bytes) {
+  if (bytes.length < 30) return { error: "Truncated BMP file" };
+  const width = readI32LE(bytes, 18);
+  const heightRaw = readI32LE(bytes, 22);
+  const bitDepth = bytes[28] | bytes[29] << 8;
+  return { format: "bmp", width: Math.abs(width), height: Math.abs(heightRaw), bitDepth };
+}
+function readWebp(bytes) {
+  if (bytes.length < 16) return { error: "Truncated WebP file" };
+  const fourCC = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+  if (fourCC === "VP8 ") {
+    if (bytes.length < 30) return { error: "Truncated WebP file" };
+    const width = (bytes[26] | bytes[27] << 8) & 16383;
+    const height = (bytes[28] | bytes[29] << 8) & 16383;
+    return { format: "webp", width, height };
+  }
+  if (fourCC === "VP8L") {
+    if (bytes.length < 25) return { error: "Truncated WebP file" };
+    const bits = bytes[21] | bytes[22] << 8 | bytes[23] << 16 | bytes[24] << 24;
+    const width = (bits & 16383) + 1;
+    const height = (bits >>> 14 & 16383) + 1;
+    const hasAlpha = !!(bits >>> 28 & 1);
+    return { format: "webp", width, height, hasAlpha };
+  }
+  if (fourCC === "VP8X") {
+    if (bytes.length < 30) return { error: "Truncated WebP file" };
+    const flags = bytes[20];
+    const hasAlpha = !!(flags & 16);
+    const width = (bytes[24] | bytes[25] << 8 | bytes[26] << 16) + 1;
+    const height = (bytes[27] | bytes[28] << 8 | bytes[29] << 16) + 1;
+    return { format: "webp", width, height, hasAlpha };
+  }
+  return { error: "Unrecognized WebP chunk format" };
+}
+var JPEG_SOF_MARKERS = /* @__PURE__ */ new Set([
+  192,
+  193,
+  194,
+  195,
+  197,
+  198,
+  199,
+  201,
+  202,
+  203,
+  205,
+  206,
+  207
+]);
+function readJpeg(bytes) {
+  let offset = 2;
+  while (offset < bytes.length - 1) {
+    if (bytes[offset] !== 255) {
+      offset++;
+      continue;
+    }
+    const marker = bytes[offset + 1];
+    if (marker === 216 || marker === 1 || marker >= 208 && marker <= 215) {
+      offset += 2;
+      continue;
+    }
+    if (marker === 217) break;
+    if (offset + 3 >= bytes.length) break;
+    const segmentLength = bytes[offset + 2] << 8 | bytes[offset + 3];
+    if (JPEG_SOF_MARKERS.has(marker)) {
+      if (offset + 9 >= bytes.length) return { error: "Truncated JPEG SOF segment" };
+      const bitDepth = bytes[offset + 4];
+      const height = bytes[offset + 5] << 8 | bytes[offset + 6];
+      const width = bytes[offset + 7] << 8 | bytes[offset + 8];
+      const components = bytes[offset + 9];
+      const colorType = components === 1 ? "grayscale" : components === 3 ? "rgb" : components === 4 ? "cmyk" : "unknown";
+      return { format: "jpeg", width, height, bitDepth, colorType };
+    }
+    offset += 2 + segmentLength;
+  }
+  return { error: "No SOF marker found in JPEG (file may be corrupt)" };
+}
+function readImageInfo(bytes) {
+  if (bytes.length < 10) return { error: "File too small to determine format" };
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) {
+    return readPng(bytes);
+  }
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70) {
+    return readGif(bytes);
+  }
+  if (bytes[0] === 66 && bytes[1] === 77) {
+    return readBmp(bytes);
+  }
+  if (bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) {
+    return readWebp(bytes);
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    return readJpeg(bytes);
+  }
+  return { error: "Unrecognized image format \u2014 supported: PNG, JPEG, GIF, WebP, BMP" };
+}
+
+export { media_exports, readImageInfo };

package/dist/{chunk-XXYZLLHI.js → chunk-YBBYFAOV.js}

@@ -20,6 +20,7 @@ __export(text_exports, {
   csvToHtml: () => csvToHtml,
   csvToMarkdown: () => csvToMarkdown,
   detectDelimiter: () => detectDelimiter,
+  detectPassiveVoice: () => detectPassiveVoice,
   diffLines: () => diffLines,
   diffLinesSimple: () => diffLinesSimple,
   diffStats: () => diffStats,
@@ -2223,5 +2224,170 @@ function getMorseTiming(morse) {
   }
   return result;
 }
+var BE_VERBS = /* @__PURE__ */ new Set(["am", "is", "are", "was", "were", "be", "been", "being"]);
+var IRREGULAR_PARTICIPLES = /* @__PURE__ */ new Set([
+  "awoken",
+  "been",
+  "become",
+  "begun",
+  "bent",
+  "bet",
+  "bitten",
+  "bled",
+  "blown",
+  "born",
+  "bought",
+  "bound",
+  "bred",
+  "broken",
+  "brought",
+  "built",
+  "burnt",
+  "burst",
+  "caught",
+  "chosen",
+  "clung",
+  "come",
+  "cost",
+  "crept",
+  "cut",
+  "dealt",
+  "dived",
+  "done",
+  "drawn",
+  "dreamt",
+  "driven",
+  "drunk",
+  "dug",
+  "eaten",
+  "fallen",
+  "fed",
+  "felt",
+  "fit",
+  "fled",
+  "flown",
+  "forbidden",
+  "forgiven",
+  "forgotten",
+  "fought",
+  "found",
+  "frozen",
+  "given",
+  "gone",
+  "gotten",
+  "grown",
+  "hidden",
+  "held",
+  "hung",
+  "hurt",
+  "kept",
+  "knelt",
+  "knit",
+  "known",
+  "laid",
+  "lain",
+  "led",
+  "left",
+  "lent",
+  "let",
+  "lit",
+  "lost",
+  "made",
+  "meant",
+  "met",
+  "mistaken",
+  "paid",
+  "proven",
+  "put",
+  "quit",
+  "read",
+  "rid",
+  "ridden",
+  "risen",
+  "run",
+  "said",
+  "sat",
+  "sawn",
+  "seen",
+  "sent",
+  "set",
+  "sewn",
+  "shaken",
+  "shed",
+  "shone",
+  "shot",
+  "shown",
+  "shrunk",
+  "shut",
+  "sold",
+  "sought",
+  "sown",
+  "spent",
+  "spoken",
+  "spread",
+  "sprung",
+  "stolen",
+  "stood",
+  "stuck",
+  "stung",
+  "struck",
+  "strung",
+  "sung",
+  "sunk",
+  "swept",
+  "sworn",
+  "swum",
+  "swung",
+  "taken",
+  "taught",
+  "thought",
+  "thrown",
+  "told",
+  "torn",
+  "understood",
+  "upset",
+  "woken",
+  "won",
+  "worn",
+  "wound",
+  "woven",
+  "written"
+]);
+function isPastParticiple(word) {
+  const w = word.toLowerCase();
+  if (IRREGULAR_PARTICIPLES.has(w)) return true;
+  return w.length > 3 && /^[a-z]+ed$/.test(w);
+}
+function splitIntoSentences(text) {
+  const matches = text.match(/[^.!?]+[.!?]*/g);
+  if (!matches) return [];
+  return matches.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function detectPassiveVoice(text) {
+  const sentences = splitIntoSentences(text);
+  const analyzed = sentences.map((sentence, index) => {
+    const words = sentence.match(/[a-zA-Z']+/g) ?? [];
+    const matches = [];
+    for (let i = 0; i < words.length; i++) {
+      if (!BE_VERBS.has(words[i].toLowerCase())) continue;
+      let j = i + 1;
+      let adverbCount = 0;
+      while (j < words.length && adverbCount < 2 && /ly$/i.test(words[j]) && !isPastParticiple(words[j])) {
+        j++;
+        adverbCount++;
+      }
+      if (j < words.length && isPastParticiple(words[j])) {
+        const hasAgent = words.slice(j + 1, j + 5).some((w) => w.toLowerCase() === "by");
+        matches.push({ phrase: words.slice(i, j + 1).join(" "), hasAgent });
+        i = j;
+      }
+    }
+    return { index, text: sentence, isPassive: matches.length > 0, matches };
+  });
+  const totalSentences = analyzed.length;
+  const passiveSentences = analyzed.filter((s) => s.isPassive).length;
+  const passivePercent = totalSentences > 0 ? Math.round(passiveSentences / totalSentences * 1e3) / 10 : 0;
+  return { sentences: analyzed, totalSentences, passiveSentences, passivePercent };
+}
 
-export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };
+export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, detectPassiveVoice, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };