@nodetool-ai/node-sdk 0.8.4-a24.3 → 0.8.4

package/dist/_sandbox/sandbox-markdown/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: sandbox-markdown
+description: Parse markdown into a token stream inside a Code node or CodeAct action, with marked's lexer running in the guest
+---
+
+# Markdown in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-markdown`. One module, the `marked` root
+export. Import it at the top of the body.
+
+`marked` is pure JavaScript — no Node builtins, no DOM — so it compiles
+straight into the QuickJS guest. There is no pre-built "extract headers"
+helper; `marked.lexer` gives you the token stream and you read what you need
+out of it.
+
+## lexer — markdown text to tokens
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const tokens = marked.lexer(inputs.markdown);
+return { tokenCount: tokens.length };
+```
+
+Each token carries a `type` (`heading`, `paragraph`, `list`, `code`, `table`,
+`link` tokens nested inside `paragraph`/`text` tokens, etc.) and the fields
+that type needs.
+
+## Headers → a document outline
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const headers = marked.lexer(inputs.markdown)
+  .filter((t) => t.type === "heading")
+  .map((t) => ({ level: t.depth, text: t.text }));
+return { headers };
+```
+
+## Links → a flat list
+
+`marked` nests inline tokens (links, emphasis) inside block tokens. Walk
+`tokens.links` for a document's reference-style link definitions, or walk each
+block's `.tokens` for inline links:
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+function collectLinks(tokens, out = []) {
+  for (const t of tokens) {
+    if (t.type === "link") out.push({ href: t.href, text: t.text });
+    if (t.tokens) collectLinks(t.tokens, out);
+    if (t.items) collectLinks(t.items, out);
+  }
+  return out;
+}
+
+const links = collectLinks(marked.lexer(inputs.markdown));
+return { links };
+```
+
+## Lists → nested items
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const lists = marked.lexer(inputs.markdown)
+  .filter((t) => t.type === "list")
+  .map((t) => ({
+    ordered: t.ordered,
+    items: t.items.map((item) => item.text)
+  }));
+return { lists };
+```
+
+## Code blocks → language + source
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const codeBlocks = marked.lexer(inputs.markdown)
+  .filter((t) => t.type === "code")
+  .map((t) => ({ language: t.lang || "text", code: t.text }));
+return { codeBlocks };
+```
+
+## Tables → rows of records
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const tables = marked.lexer(inputs.markdown)
+  .filter((t) => t.type === "table")
+  .map((t) => {
+    const headers = t.header.map((cell) => cell.text);
+    return t.rows.map((row) =>
+      Object.fromEntries(row.map((cell, i) => [headers[i], cell.text]))
+    );
+  });
+return { tables };
+```
+
+## Markdown → HTML
+
+```js
+import { marked } from "@nodetool-ai/sandbox-markdown";
+
+const html = marked.parse(inputs.markdown);
+return { html };
+```
+
+## Gotchas
+
+- **Everything runs in the guest.** The 64 MB guest heap holds your input text,
+  the token tree, and the returned value at once.
+- **`marked.lexer` is synchronous**, unlike `marked.parse` (which can be async
+  when you register an async extension — the default configuration is not).
+- **Token shapes differ by type.** A `list` token's items are themselves
+  tokens with their own `.tokens`; a `table` token has `header`/`rows`, not a
+  flat `cells` array. Log a sample token when a shape is unclear.
+- **This pack is the only route to markdown parsing.** There is no
+  `data.parseMarkdown` global; every library the sandbox offers is an
+  importable module, and this is the one for markdown.

package/dist/_sandbox/sandbox-markdown/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nodetool-ai/sandbox-markdown",
+  "version": "0.8.4",
+  "description": "Markdown parsing inside the NodeTool sandbox, from marked's lexer running in the guest",
+  "license": "MIT",
+  "dependencies": {
+    "marked": "^12.0.2"
+  },
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "js",
+        "npm": "marked"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-markdown"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "markdown"
+  ]
+}

package/dist/_sandbox/sandbox-notion/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sandbox-notion
+description: Call the Notion API from a Code node or CodeAct action, with NodeTool's request builder and rich-text/block readers running on the host
+---
+
+# Notion in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-notion`. Import it at the top of the body.
+
+Notion is an ordinary HTTPS API and `fetch` reaches it. What costs a script its
+first three attempts is everything around the call — the `Notion-Version`
+header, the rich-text arrays every piece of text is wrapped in, and the block
+tree a page's content comes back as. Those three are this pack.
+
+**Nothing here sends a request.** `request` builds one; the guest's own `fetch`
+sends it, under the run's fetch cap and SSRF guard.
+
+## request — an authenticated Notion request
+
+```js
+import { request } from "@nodetool-ai/sandbox-notion";
+
+const token = await nodetool.secrets.get("NOTION_API_KEY");
+const req = await request({
+  token,
+  path: "search",
+  method: "POST",
+  body: { query: inputs.query, page_size: 10 }
+});
+const res = await fetch(req.url, req);
+if (!res.ok) throw new Error(`Notion search failed: ${res.status}`);
+return { results: res.json.results };
+```
+
+Options: `token` (required), `path` (required — relative to `/v1` unless it
+starts with `/`), `method` (default `GET`), `body` (JSON-encoded when present),
+`query` (query-string bag), `version` (default `2022-06-28`).
+
+Returns `{url, method, headers, body?}`, which `fetch(req.url, req)` takes
+whole.
+
+## plainText — a rich-text array as a string
+
+```js
+import { plainText } from "@nodetool-ai/sandbox-notion";
+
+const title = await plainText(page.properties.Name.title);
+```
+
+Takes the array Notion puts under every `title`, `rich_text` and heading.
+Anything else gives `""`.
+
+## toMarkdown — a page's blocks as markdown
+
+```js
+import { request, toMarkdown } from "@nodetool-ai/sandbox-notion";
+
+const req = await request({ token, path: `blocks/${inputs.page_id}/children`, query: { page_size: 100 } });
+const blocks = (await fetch(req.url, req)).json.results;
+return { markdown: await toMarkdown(blocks) };
+```
+
+Handles paragraphs, the three heading levels, bulleted and numbered items,
+to-dos, quotes, code fences and dividers. A block markdown has no form for —
+a database, an embed, a synced block — contributes nothing rather than a
+placeholder, so the result is text a model or a file can take as-is.
+
+## Common flows
+
+**Create a page in a database**
+
+```js
+const req = await request({
+  token, path: "pages", method: "POST",
+  body: {
+    parent: { database_id: inputs.database_id },
+    properties: { Name: { title: [{ text: { content: inputs.title } }] } }
+  }
+});
+const page = (await fetch(req.url, req)).json;
+```
+
+**Query a database**
+
+```js
+const req = await request({
+  token, path: `databases/${inputs.database_id}/query`, method: "POST",
+  body: { filter: { property: "Status", select: { equals: "Open" } }, page_size: 50 }
+});
+```
+
+## Gotchas
+
+- **Every export is async.** A host call is a round trip.
+- **Nested blocks are not fetched.** `toMarkdown` is pure over the blocks you
+  hand it. A block with `has_children` needs its own
+  `blocks/{id}/children` call.
+- **Notion paginates at 100.** Follow `next_cursor` with
+  `query: { start_cursor }` and watch the run's fetch cap.
+- **The integration needs access.** A page shared with nobody returns 404 even
+  with a valid token — share it with the integration in Notion first.

package/dist/_sandbox/sandbox-notion/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nodetool-ai/sandbox-notion",
+  "version": "0.8.4",
+  "description": "Build Notion API requests and read Notion rich text and blocks inside the NodeTool sandbox, from NodeTool's helper running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "notion"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-notion"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "notion"
+  ]
+}

package/dist/_sandbox/sandbox-ocr/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sandbox-ocr
+description: Read the text in an image from a Code node or CodeAct action, with tesseract.js running on the host
+---
+
+# OCR in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-ocr`. Import it at the top of the body.
+
+tesseract.js runs a WASM engine, spawns workers, and downloads its language
+data on first use — none of which the guest can do. This pack is a **host
+module**: the import resolves to a generated facade over NodeTool's own
+implementation.
+
+## recognize — image bytes to text
+
+```js
+import { recognize } from "@nodetool-ai/sandbox-ocr";
+
+const { text, confidence, words } = await recognize(
+  await workspace.readBytes("receipt.png")
+);
+const total = words.find((w) => /^\d+[.,]\d{2}$/.test(w.text));
+return { text, confidence, total: total?.text ?? null };
+```
+
+One call gives you all three readings:
+
+- `text` — the whole page as one string.
+- `confidence` — the page mean, 0–100.
+- `words` — `{text, confidence, bbox: {x, y, width, height}}` per word, in
+  reading order, with the box in image pixels.
+
+Pass `{ language: "eng+deu" }` for anything other than English; the codes are
+Tesseract's, `+`-joined. The data file for a language it has not seen before is
+downloaded the first time you ask for it, so that call is slower.
+
+Get the bytes from `workspace.readBytes`, from `await response.bytes()`, or
+from an asset with `assetToSandbox`.
+
+## Gotchas
+
+- **`recognize` is async**, and the first call to it pays for engine startup.
+- **10 MB per image.** Larger input is refused by name.
+- **20 000 words per page.**
+- **Straight, sharp scans read best.** Use `image.rotate` and `image.adjust` to
+  deskew and raise contrast before you hand the bytes over.

package/dist/_sandbox/sandbox-ocr/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-ocr",
+  "version": "0.8.4",
+  "description": "Read text out of images inside the NodeTool sandbox, from tesseract.js running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "ocr"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-ocr"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "ocr",
+    "tesseract",
+    "text-recognition"
+  ]
+}

package/dist/_sandbox/sandbox-pdf/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sandbox-pdf
+description: Extract the embedded text of a PDF, whole or per page, in a Code node or CodeAct action, with pdf-parse running on the host. It reads text the PDF already carries; it does not OCR a scanned page.
+---
+
+# PDF text in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-pdf`. Import it at the top of the body.
+
+pdf-parse drives pdf.js, which needs Node builtins and a canvas; it is not a
+guest-module candidate. This pack is a **host module**: the import resolves to a
+generated facade over NodeTool's own implementation.
+
+## extractText — whole document to plain text
+
+```js
+import { extractText } from "@nodetool-ai/sandbox-pdf";
+
+const bytes = await workspace.readBytes("report.pdf");
+const text = await extractText(bytes);
+```
+
+All pages concatenated, in order, with no page markers.
+
+## extractPages — one item per page
+
+```js
+import { extractPages } from "@nodetool-ai/sandbox-pdf";
+
+const pages = await extractPages(bytes);
+// [{ index: 0, pageNumber: 1, text: "Quarterly report" }, ...]
+```
+
+Get the bytes from `workspace.readBytes`, or from a fetched body with
+`await response.bytes()`.
+
+## Gotchas
+
+- **Both exports are async.**
+- **10 MB per document.** Larger input is refused by name.
+- **No OCR.** Both exports read the text layer the PDF already carries. A
+  scanned page is an image and comes back empty — run
+  `@nodetool-ai/sandbox-ocr` over the page image, or a vision model, for that.
+- **Text only.** Neither export reads images, tables as tables, or form fields.
+  Layout is approximated from text positions, so column order in a
+  multi-column page is not guaranteed.
+- **An encrypted or malformed PDF throws** with the reason pdf.js gives.

package/dist/_sandbox/sandbox-pdf/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nodetool-ai/sandbox-pdf",
+  "version": "0.8.4",
+  "description": "Extract text from PDF files inside the NodeTool sandbox, from pdf-parse running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "pdf"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-pdf"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "pdf",
+    "text-extraction"
+  ]
+}

package/dist/_sandbox/sandbox-pdflib/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sandbox-pdflib
+description: Build and merge PDF files in a Code node or CodeAct action, with pdf-lib running on the host
+---
+
+# PDF writing in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-pdflib`. Import it at the top of the body.
+
+This pack **writes** PDFs. To extract text from an existing file, use
+`@nodetool-ai/sandbox-pdf` instead.
+
+## build — pages to PDF bytes
+
+Coordinates are **top-left**, in PDF points (72 per inch). A US Letter page
+is 612×792.
+
+```js
+import { build } from "@nodetool-ai/sandbox-pdflib";
+
+const bytes = await build({
+  pages: [
+    {
+      width: 612,
+      height: 792,
+      items: [
+        { type: "text", x: 72, y: 72, text: "Hello", size: 24, color: "#111827" },
+        { type: "image", x: 72, y: 120, width: 200, height: 120, data: inputs.logo }
+      ]
+    }
+  ]
+});
+await workspace.writeBytes("hello.pdf", bytes);
+```
+
+Item types:
+
+- `text` — `x`, `y`, `text`, `size` (points, default 12), `color` (hex)
+- `image` — `x`, `y`, `width`, `height`, `data` (`Uint8Array` PNG or JPEG)
+
+## merge — concatenate PDFs
+
+```js
+import { merge } from "@nodetool-ai/sandbox-pdflib";
+
+const bytes = await merge([inputs.first, inputs.second]);
+await workspace.writeBytes("combined.pdf", bytes);
+```
+
+Each entry is a `Uint8Array` of an existing PDF.
+
+## Gotchas
+
+- **Host module.** `build` and `merge` are async and return a `Uint8Array`.
+- **At most 200 pages** (or 200 source documents for `merge`).
+- **Images are PNG or JPEG bytes**, sniffed from the magic header.

package/dist/_sandbox/sandbox-pdflib/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nodetool-ai/sandbox-pdflib",
+  "version": "0.8.4",
+  "description": "Build and merge PDF files inside the NodeTool sandbox, with pdf-lib running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "pdflib"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-pdflib"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "pdf"
+  ]
+}

package/dist/_sandbox/sandbox-pptx/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: sandbox-pptx
+description: Extract text from a PowerPoint file, whole or per slide, in a Code node or CodeAct action, with office-text-extractor running on the host
+---
+
+# PowerPoint text in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-pptx`. Import it at the top of the body.
+
+office-text-extractor reads a `.pptx` buffer through Node's own zip/XML stack;
+it is not a guest-module candidate. This pack is a **host module**: the import
+resolves to a generated facade over NodeTool's own implementation.
+
+## extractText — whole deck to plain text
+
+```js
+import { extractText } from "@nodetool-ai/sandbox-pptx";
+
+const bytes = await workspace.readBytes("deck.pptx");
+const text = await extractText(bytes);
+```
+
+All slides concatenated, in order.
+
+## extractSlides — one item per slide
+
+```js
+import { extractSlides } from "@nodetool-ai/sandbox-pptx";
+
+const slides = await extractSlides(bytes);
+// [{ index: 0, slideNumber: 1, text: "Welcome to slide one" }, ...]
+```
+
+Get the bytes from `workspace.readBytes`, or from a fetched body with
+`await response.bytes()`.
+
+## Gotchas
+
+- **Both exports are async.**
+- **10 MB per deck.** Larger input is refused by name.
+- **Text only.** Neither export reads speaker notes, images, or slide layout —
+  just the text runs on each slide.

package/dist/_sandbox/sandbox-pptx/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-pptx",
+  "version": "0.8.4",
+  "description": "Extract text from PowerPoint files inside the NodeTool sandbox, from office-text-extractor running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "pptx"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-pptx"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "pptx",
+    "powerpoint",
+    "slides"
+  ]
+}