@proveanything/smartlinks 2.0.31 → 2.0.33

package/dist/openapi.yaml

@@ -14509,6 +14509,21 @@ paths:
           required: false
           schema:
             type: string
+        - name: qFields
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: dataFilter
+          in: query
+          required: false
+          schema:
+            type: object
+            additionalProperties:
+              type: array
+              items:
+                type: object
+                additionalProperties: true
         - name: authorId
           in: query
           required: false
@@ -17108,12 +17123,42 @@ components:
           type: number
       required:
         - imageUrl
-    PdfCreateArgs:
+    ImageOcrArgs:
       type: object
       properties:
-        html:
+        imageUrl:
+          type: string
+        url:
+          type: string
+        page:
+          type: number
+        dpi:
+          type: number
+        clip:
+          $ref: "#/components/schemas/PdfClip"
+        languages:
+          type: array
+          items:
+            type: string
+    PdfClip:
+      type: object
+      properties:
+        x0:
           type: object
           additionalProperties: true
+      required:
+        - x0
+    PdfCreateArgs:
+      type: object
+      properties:
+        html:
+          type: string
+        format:
+          type: string
+        landscape:
+          type: boolean
+        margin:
+          type: string
       required:
         - html
     PdfFillArgs:
@@ -17145,8 +17190,13 @@ components:
       type: object
       properties:
         url:
-          type: object
-          additionalProperties: true
+          type: string
+        page:
+          type: number
+        dpi:
+          type: number
+        clip:
+          $ref: "#/components/schemas/PdfClip"
       required:
         - url
     PdfExtractArgs:
@@ -17222,6 +17272,8 @@ components:
           $ref: "#/components/schemas/ImageSearchStockArgs"
         image.transform:
           $ref: "#/components/schemas/ImageTransformArgs"
+        image.ocr:
+          $ref: "#/components/schemas/ImageOcrArgs"
         pdf.create:
           $ref: "#/components/schemas/PdfCreateArgs"
         pdf.fill:
@@ -17255,6 +17307,7 @@ components:
         - image.fromReference
         - image.searchStock
         - image.transform
+        - image.ocr
         - pdf.create
         - pdf.fill
         - pdf.merge
@@ -17371,6 +17424,75 @@ components:
           additionalProperties: true
       required:
         - url
+    PdfRenderTooLarge:
+      type: object
+      properties:
+        error:
+          type: object
+          additionalProperties: true
+      required:
+        - error
+    OcrBox:
+      type: object
+      properties:
+        x:
+          type: object
+          additionalProperties: true
+      required:
+        - x
+    OcrWord:
+      type: object
+      properties:
+        text:
+          type: object
+          additionalProperties: true
+      required:
+        - text
+    OcrLine:
+      type: object
+      properties:
+        text:
+          type: object
+          additionalProperties: true
+      required:
+        - text
+    ImageOcrResult:
+      type: object
+      properties:
+        words:
+          type: array
+          items:
+            $ref: "#/components/schemas/OcrWord"
+        lines:
+          type: array
+          items:
+            $ref: "#/components/schemas/OcrLine"
+        text:
+          type: string
+        width:
+          type: number
+        height:
+          type: number
+        languages:
+          type: array
+          items:
+            type: string
+        page:
+          type: number
+        dpi:
+          type: number
+        clip:
+          $ref: "#/components/schemas/PdfClip"
+        engine:
+          type: string
+      required:
+        - words
+        - lines
+        - text
+        - width
+        - height
+        - languages
+        - engine
     PdfFieldMeta:
       type: object
       properties:
@@ -17498,6 +17620,7 @@ components:
         - image.fromReference
         - image.searchStock
         - image.transform
+        - image.ocr
         - pdf.create
         - pdf.fill
         - pdf.merge
@@ -20052,6 +20175,15 @@ components:
           type: string
         q:
           type: string
+        qFields:
+          type: string
+        dataFilter:
+          type: object
+          additionalProperties:
+            type: array
+            items:
+              type: object
+              additionalProperties: true
         authorId:
           type: string
         parentType:

package/dist/types/ai.d.ts

@@ -848,7 +848,7 @@ export interface CatalogResponse {
 /** Capability tags a tool requires; scope a run with `allowCapabilities`. */
 export type AiToolCapability = 'web:read' | 'ai:vision' | 'ai:image' | 'ai:text' | 'media:image' | 'media:pdf' | 'net:http';
 /** The names of the built-in server-side agent tools (run via `server_tools`). */
-export type AiToolName = 'web.fetchPage' | 'web.extractSchema' | 'web.screenshot' | 'web.search' | 'brand.assets' | 'document.read' | 'data.extract' | 'image.describe' | 'image.generate' | 'image.fromReference' | 'image.searchStock' | 'image.transform' | 'pdf.create' | 'pdf.fill' | 'pdf.merge' | 'pdf.inspect' | 'pdf.render' | 'pdf.extract' | 'pdf.decodeBarcodes' | 'pdf.inspectGraphics' | 'http.request' | 'translate';
+export type AiToolName = 'web.fetchPage' | 'web.extractSchema' | 'web.screenshot' | 'web.search' | 'brand.assets' | 'document.read' | 'data.extract' | 'image.describe' | 'image.generate' | 'image.fromReference' | 'image.searchStock' | 'image.transform' | 'image.ocr' | 'pdf.create' | 'pdf.fill' | 'pdf.merge' | 'pdf.inspect' | 'pdf.render' | 'pdf.extract' | 'pdf.decodeBarcodes' | 'pdf.inspectGraphics' | 'http.request' | 'translate';
 export interface WebFetchPageArgs {
     url: string;
     type?: string;
@@ -927,10 +927,32 @@ export interface ImageTransformArgs {
     format?: 'jpeg' | 'png' | 'webp' | 'avif';
     quality?: number;
 }
+/** Deterministic OCR (Google Vision; no generative model). Give `imageUrl`, or a PDF `url` (+ page/dpi/clip). */
+export interface ImageOcrArgs {
+    imageUrl?: string;
+    url?: string;
+    /** PDF page, 1-based (default 1). */
+    page?: number;
+    /** PDF render dpi (default 300, max 600). */
+    dpi?: number;
+    /** PDF region, normalised 0–1 from the page top-left. */
+    clip?: PdfClip;
+    /** Language hints, e.g. ['en','fr','de','es','it','nl']. Optional — auto-detected otherwise. */
+    languages?: string[];
+}
+/** A region of a PDF page, normalised 0–1 from the page's top-left corner (x1 > x0, y1 > y0). */
+export interface PdfClip {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
 export interface PdfCreateArgs {
     html: string;
     format?: string;
     landscape?: boolean;
+    /** Page margin for all sides, e.g. "0" or "12mm" (default 18mm/14mm). Use "0" when the HTML sets its own margins. */
+    margin?: string;
 }
 export interface PdfFillArgs {
     url: string;
@@ -948,7 +970,10 @@ export interface PdfInspectArgs {
 export interface PdfRenderArgs {
     url: string;
     page?: number;
+    /** Default 150, max 600. Renders over 40 megapixels return `code: 'too_large'` with `suggestedDpi`. */
     dpi?: number;
+    /** Render only this region (at the requested dpi) — read a panel of a large dieline without rasterising the whole sheet. */
+    clip?: PdfClip;
 }
 export interface PdfExtractArgs {
     url: string;
@@ -993,6 +1018,7 @@ export interface AiToolArgsMap {
     'image.fromReference': ImageFromReferenceArgs;
     'image.searchStock': ImageSearchStockArgs;
     'image.transform': ImageTransformArgs;
+    'image.ocr': ImageOcrArgs;
     'pdf.create': PdfCreateArgs;
     'pdf.fill': PdfFillArgs;
     'pdf.merge': PdfMergeArgs;
@@ -1041,7 +1067,8 @@ export interface ImageDescribeResult {
 }
 /** Result of a tool that produces a hosted binary (image.transform, pdf.*). */
 export interface HostedAssetResult {
-    hostedUrl: string | null;
+    hostedUrl: string | null; /** Same as hostedUrl (pdf.create). */
+    url?: string | null;
     contentType?: string;
     info?: {
         width?: number;
@@ -1082,6 +1109,7 @@ export interface PdfInspectResult {
     note: string;
     pages: PdfInspectPage[];
 }
+/** Hosted URLs are permanent (safe to pass to later tools in the same run). */
 export interface PdfRenderResult {
     url: string | null;
     page: number;
@@ -1089,6 +1117,52 @@ export interface PdfRenderResult {
     dpi: number;
     width: number;
     height: number;
+    clip?: PdfClip;
+}
+/** Error shape when a render would exceed the pixel cap (pdf.render / image.ocr). */
+export interface PdfRenderTooLarge {
+    error: string;
+    code: 'too_large';
+    requestedPixels: number;
+    maxPixels: number;
+    suggestedDpi: number;
+    width: number;
+    height: number;
+}
+/** Pixel box within the OCR'd image (top-left origin). */
+export interface OcrBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** One OCR word. Punctuation is usually its own word. `confidence` is 0–1 — flag low values for review. */
+export interface OcrWord {
+    text: string;
+    confidence: number;
+    bbox: OcrBox;
+}
+/** One OCR line, with spacing as printed; `confidence` is the mean of its words. */
+export interface OcrLine {
+    text: string;
+    confidence: number;
+    bbox: OcrBox;
+}
+export interface ImageOcrResult {
+    words: OcrWord[];
+    lines: OcrLine[];
+    /** Full text with line breaks. */
+    text: string;
+    /** Pixel size of the image that was read. */
+    width: number | null;
+    height: number | null;
+    /** Detected languages (BCP-47). */
+    languages: string[];
+    /** Present when a PDF page was rendered. */
+    page?: number;
+    dpi?: number;
+    clip?: PdfClip;
+    engine: string;
 }
 /** Per-field metadata from pdf.extract when includeConfidence / includeBoxes is set. */
 export interface PdfFieldMeta {

package/dist/types/appObjects.d.ts

@@ -620,8 +620,19 @@ export interface RecordListQueryParams extends ListQueryParams {
     variantId?: string;
     /** Filter by batchId (indexed flat column) */
     batchId?: string;
-    /** Full-text filter on data.label (case-insensitive substring) */
+    /** Full-text filter (case-insensitive substring) on data.label — or on `qFields` (admin) */
     q?: string;
+    /**
+     * Admin only: which top-level `data` keys `q` searches (comma-separated, max 5).
+     * Default `label`. Example: `'value,label'`.
+     */
+    qFields?: string;
+    /**
+     * Admin only: filter on top-level `data` keys. Each value is an exact match, an
+     * `in:a,b,c` list, or an array of values (any match). Max 10 keys.
+     * Example: `{ versionId: 'v1', zone: 'in:on_pack,unclear' }`.
+     */
+    dataFilter?: Record<string, string | string[]>;
     authorId?: string;
     parentType?: string;
     parentId?: string;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.31  |  Generated: 2026-09-29T19:37:17.528Z
+Version: 2.0.33  |  Generated: 2026-10-01T17:58:12.047Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1447,10 +1447,32 @@ interface ImageTransformArgs {
 }
 ```
 
+**ImageOcrArgs** (interface)
+```typescript
+interface ImageOcrArgs {
+  imageUrl?: string
+  url?: string
+  page?: number
+  dpi?: number
+  clip?: PdfClip
+  languages?: string[]
+}
+```
+
+**PdfClip** (interface)
+```typescript
+interface PdfClip {
+  x0: number; y0: number; x1: number; y1: number
+}
+```
+
 **PdfCreateArgs** (interface)
 ```typescript
 interface PdfCreateArgs {
-  html: string; format?: string; landscape?: boolean
+  html: string
+  format?: string
+  landscape?: boolean
+  margin?: string
 }
 ```
 
@@ -1478,7 +1500,10 @@ interface PdfInspectArgs {
 **PdfRenderArgs** (interface)
 ```typescript
 interface PdfRenderArgs {
-  url: string; page?: number; dpi?: number
+  url: string
+  page?: number
+  dpi?: number
+  clip?: PdfClip
 }
 ```
 
@@ -1532,6 +1557,7 @@ interface AiToolArgsMap {
   'image.fromReference': ImageFromReferenceArgs
   'image.searchStock': ImageSearchStockArgs
   'image.transform': ImageTransformArgs
+  'image.ocr': ImageOcrArgs
   'pdf.create': PdfCreateArgs
   'pdf.fill': PdfFillArgs
   'pdf.merge': PdfMergeArgs
@@ -1590,7 +1616,7 @@ interface ImageDescribeResult {
 **HostedAssetResult** (interface)
 ```typescript
 interface HostedAssetResult {
-  hostedUrl: string | null; contentType?: string; info?: { width?: number; height?: number; format?: string; size?: number }
+
 }
 ```
 
@@ -1625,7 +1651,51 @@ interface PdfInspectResult {
 **PdfRenderResult** (interface)
 ```typescript
 interface PdfRenderResult {
-  url: string | null; page: number; pageCount: number; dpi: number; width: number; height: number
+  url: string | null; page: number; pageCount: number; dpi: number; width: number; height: number; clip?: PdfClip
+}
+```
+
+**PdfRenderTooLarge** (interface)
+```typescript
+interface PdfRenderTooLarge {
+  error: string; code: 'too_large'; requestedPixels: number; maxPixels: number; suggestedDpi: number; width: number; height: number
+}
+```
+
+**OcrBox** (interface)
+```typescript
+interface OcrBox {
+  x: number; y: number; w: number; h: number
+}
+```
+
+**OcrWord** (interface)
+```typescript
+interface OcrWord {
+  text: string; confidence: number; bbox: OcrBox
+}
+```
+
+**OcrLine** (interface)
+```typescript
+interface OcrLine {
+  text: string; confidence: number; bbox: OcrBox
+}
+```
+
+**ImageOcrResult** (interface)
+```typescript
+interface ImageOcrResult {
+  words: OcrWord[]
+  lines: OcrLine[]
+  text: string
+  width: number | null
+  height: number | null
+  languages: string[]
+  page?: number
+  dpi?: number
+  clip?: PdfClip
+  engine: string
 }
 ```
 

package/docs/ai.md

@@ -327,7 +327,8 @@ in `input`.
 | `pdf.fill` | Fill an AcroForm PDF's fields (`{ field: value }`) → hosted URL. |
 | `pdf.merge` | Merge several PDFs into one, in order → hosted URL. |
 | `pdf.inspect` | Cheap, no-AI introspection: page count/sizes, which pages have a real text layer, raster present, and a routing hint (`text` vs `vision`). |
-| `pdf.render` | Rasterize one page to a PNG at a chosen DPI → hosted image URL (feed to vision, or screenshot a page). |
+| `pdf.render` | Rasterize one page — or just a region (`clip: { x0, y0, x1, y1 }`, 0–1 from top-left) — to a PNG at a chosen DPI → hosted image URL (permanent). Max 40 MP per call; larger requests return `code: "too_large"` + `suggestedDpi`. |
+| `image.ocr` | **Deterministic OCR** (Google Vision, no generative model): exact characters with per-word `confidence` (0–1) and pixel `bbox`, plus lines with spacing as printed. Input: `imageUrl`, or a PDF `url` + `page` + `dpi` + optional `clip`. Optional `languages` hints. Use for small print and text outlined to curves. |
 | `pdf.extract` | PDF → typed JSON in one call (schema and/or prompt). Auto-routes text vs vision. Optional per-field `confidence`/`source` (`includeConfidence`) and `bbox` (`includeBoxes`) in `fieldsMeta`. |
 | `pdf.decodeBarcodes` | Deterministically decode barcodes/QR on a page (WASM, no AI) → value + symbology + page + bbox + confidence. Use this for barcode digits, never vision. |
 | `pdf.inspectGraphics` | Prepress inspection: per-page path/image/outlined-text counts + colour spaces, plus named SPOT colours (e.g. "PANTONE 871 C"). No AI. |
@@ -341,18 +342,36 @@ in `input`.
   returns typed JSON). It routes itself, but you can drive the route yourself: call `pdf.inspect`
   first (deterministic, no AI) to see whether each page has a real text layer, then `pdf.extract`
   (cheap text path) or `pdf.render` → `image.describe`/vision for curve-only or raster artwork.
-- **Zoom in on small print** (INCI/allergen lists) → `pdf.render` at a high DPI (e.g. 300), then read
-  the PNG with vision.
+- **Read small print exactly** (INCI/allergen lists, net weight, text outlined to curves) → `image.ocr`
+  with a PDF `url`, `page`, `dpi: 300–400` and a `clip` around the panel. It returns the characters it
+  sees with a per-word confidence — it never "corrects" a misspelling the way a vision model can, so
+  flag words below ~0.9 for human review rather than re-reading them with a model.
+- **Zoom in visually** (layout, artwork) → `pdf.render` with `clip` to rasterise just a region at a high
+  DPI, instead of the whole sheet. Renders over 40 MP return `code: "too_large"` with `suggestedDpi`
+  — retry at that dpi or with a smaller clip, don't blind-retry.
 - **Barcodes / QR** → `pdf.decodeBarcodes` (deterministic WASM decode) — never trust vision for barcode
   digits; it hallucinates them.
 - **Prepress / print QA** (spot colours, colour spaces, vector vs raster) → `pdf.inspectGraphics`.
 - **A review UI that flags guessed fields** → `pdf.extract` with `includeConfidence` (per-field
   confidence + source) and `includeBoxes` (per-field bbox on text-native pages) in `fieldsMeta`.
 - **Produce a PDF** → `pdf.create` (HTML → PDF), `pdf.fill` (populate an AcroForm's fields),
-  `pdf.merge` (combine several). These return a hosted `hostedUrl`.
+  `pdf.merge` (combine several). These return a hosted `hostedUrl` (`pdf.create` also returns it as
+  `url`). `pdf.create` loads remote `<img>` URLs before rendering and honours `page-break-inside`; pass
+  `margin: "0"` when your HTML sets its own body margin (default page margin is 18mm/14mm).
 
 Every tool is also directly callable without the model loop via `ai.tools.run(collectionId, name,
-args)` — e.g. render a page or extract fields straight from a UI, no agent round-trip.
+args)` — e.g. render a page or extract fields straight from a UI, no agent round-trip:
+
+```ts
+// Read the ingredients panel of a sleeve exactly (deterministic OCR of a clipped region)
+const { result } = await SL.ai.tools.run(collectionId, 'image.ocr', {
+  url: sleevePdfUrl, page: 1, dpi: 400,
+  clip: { x0: 0.40, y0: 0.20, x1: 0.60, y1: 0.40 },
+  languages: ['en', 'fr'],
+})
+// result.lines → [{ text: 'INGREDIENTS: Aqua, Glycerin, …', confidence: 0.97, bbox: {…} }]
+const toReview = result.words.filter((w) => w.confidence < 0.9)
+```
 
 Discover tools two ways:
 - **Design time (typed):** import `BUILTIN_AI_TOOLS`, `AI_TOOL_NAMES`, and the per-tool arg types

package/docs/app-objects.md

@@ -747,6 +747,39 @@ const results = await app.records.list(collectionId, appId, {
 
 > `q` is not a full-text index and does not return ranked results. For ranked relevance search over large corpora, use the Elasticsearch integration.
 
+**Admin: search other data fields (`qFields`).** On the admin endpoint, `qFields` chooses which top-level `data` keys `q` searches (comma-separated, max 5; default `label`):
+
+```typescript
+const page = await app.records.list(collectionId, appId, {
+  recordType: 'packaging-field',
+  q: 'best before',
+  qFields: 'value,label',       // match data.value OR data.label
+  limit: 100, offset: 0,
+}, true);
+```
+
+### Filtering on data fields (admin)
+
+On the admin endpoint, `dataFilter` filters on **top-level `data` keys** — an exact match, an `in:a,b,c` list, or an array (any value matches). Up to 10 keys; combine freely with `recordType`, `status`, `q`/`qFields` and pagination:
+
+```typescript
+const page = await app.records.list(collectionId, appId, {
+  recordType: 'packaging-field',
+  dataFilter: {
+    versionId: 'ver_123',               // data.versionId = 'ver_123'
+    zone: 'in:on_pack,unclear',         // data.zone is one of these
+  },
+  limit: 100, offset: 0,
+}, true);
+
+page.pagination.total    // matches across all pages
+page.pagination.hasMore  // keep paging while true
+```
+
+- Values are compared as text (`data->>key`); nested keys and joins aren't supported.
+- `limit` is capped at **100** per page — page with `offset` while `hasMore` is true.
+- `status` also accepts `in:a,b` (e.g. `status: 'in:active,draft'`).
+
 ### External ID / ETL Workflow
 
 `customId` and `sourceSystem` provide a stable external key pair for loading records from external systems (CMS, ERP, PIM, etc.):