@proveanything/smartlinks 2.0.34 → 2.0.35

package/dist/ai-tools.d.ts

@@ -32,6 +32,9 @@ export declare const AI_TOOL_NAMES: {
     readonly PDF_EXTRACT: "pdf.extract";
     readonly PDF_DECODE_BARCODES: "pdf.decodeBarcodes";
     readonly PDF_INSPECT_GRAPHICS: "pdf.inspectGraphics";
+    readonly PDF_EDIT: "pdf.edit";
+    readonly PDF_PREFLIGHT: "pdf.preflight";
+    readonly PDF_PRINT_READY: "pdf.printReady";
     readonly HTTP_REQUEST: "http.request";
     readonly TRANSLATE: "translate";
 };

package/dist/ai-tools.js

@@ -29,6 +29,9 @@ export const AI_TOOL_NAMES = {
     PDF_EXTRACT: 'pdf.extract',
     PDF_DECODE_BARCODES: 'pdf.decodeBarcodes',
     PDF_INSPECT_GRAPHICS: 'pdf.inspectGraphics',
+    PDF_EDIT: 'pdf.edit',
+    PDF_PREFLIGHT: 'pdf.preflight',
+    PDF_PRINT_READY: 'pdf.printReady',
     HTTP_REQUEST: 'http.request',
     TRANSLATE: 'translate',
 };
@@ -76,6 +79,12 @@ export const BUILTIN_AI_TOOLS = [
         description: 'Deterministically decode 1D/2D barcodes (EAN/UPC/QR/Code128/DataMatrix/…) on a PDF page by rasterizing and running a WASM decoder — reliable barcode/QR values where vision hallucinates. Returns value, symbology, page, bbox, confidence. No AI.' },
     { name: 'pdf.inspectGraphics', group: 'media', capabilities: ['web:read'],
         description: 'Prepress structural inspection: per-page vector-path/image/outlined-text counts + colour spaces used, plus document-level named SPOT colours (e.g. "PANTONE 871 C"). Answers whether spot/foil plates survived. Deterministic, no AI.' },
+    { name: 'pdf.edit', group: 'media', capabilities: ['web:read', 'media:pdf'],
+        description: 'Edit an existing PDF: replace LIVE text (glyph-exact removal so neighbouring text never moves; redrawn in the original font when it has the glyphs, else an embedded fallback; CMYK/spot colour kept; matches may span lines), add text and images in boxes (cmyk converts images for print). Returns url + per-item results with verified flags. Outlined text cannot be edited.' },
+    { name: 'pdf.preflight', group: 'media', capabilities: ['web:read'],
+        description: 'Prepress preflight without changing the PDF: non-embedded fonts, RGB/Lab content, missing TrimBox/BleedBox and short bleed, low effective image resolution, transparency, white overprint, missing PDF/X output intent. Severity follows the target profile. No AI.' },
+    { name: 'pdf.printReady', group: 'media', capabilities: ['web:read', 'media:pdf'],
+        description: 'Prepare a PDF for print: RGB/Lab -> CMYK with a real press profile (spot colours kept), embed fonts, optional transparency flattening, mark as PDF/X-1a or PDF/X-4 with the output intent embedded, then preflight the RESULT. Returns url + report { compliant, findings, changes }.' },
     { name: 'http.request', group: 'net', capabilities: ['net:http'],
         description: 'SSRF-guarded outbound HTTP(S) request to a public URL; returns status/headers/body.' },
     { name: 'translate', group: 'text', capabilities: ['ai:text'],

package/dist/api/functions.d.ts

@@ -11,14 +11,24 @@ export interface FunctionListResponse {
 /**
  * Options for a function call.
  * - `appId` scopes resolution to one app (recommended; falls back to the SDK app context).
- * - `channel` selects which release to run when addressing an app that is NOT enabled on the
- *   collection (enablement isn't required — the app is resolved directly by id). Defaults to
- *   `stable` server-side, so pass `channel: 'dev'` to test a dev build before installing it.
+ * - `channel` runs a specific release ('dev' | 'alpha' | 'beta' | 'stable') instead of the one the
+ *   collection has installed — normally left unset (see RELEASE CHANNEL above); `null` forces the
+ *   installed release even when the app/host set a channel. The app must be installed on the
+ *   collection, restricted to it (e.g. the developer's sandbox), or a platform-approved public app.
  */
 export interface FunctionCallOptions {
     appId?: string;
-    channel?: string;
+    channel?: string | null;
 }
+/**
+ * The release channel a call targets, or undefined for "the collection's installed release".
+ * A host context `appChannel` can be scoped to ONE app with `appChannelApp` — needed where several
+ * apps share a page (Forge's portal preview of a dev component), so only the app under development
+ * calls its dev build.
+ */
+export declare function resolveFunctionChannel(opts?: FunctionCallOptions, appId?: string): string | undefined;
+/** The API path a function call goes to (exported for hosts/tests that need the exact URL). */
+export declare function functionPath(surface: 'public' | 'admin', collectionId: string, name: string, opts?: FunctionCallOptions): string;
 export declare namespace functions {
     /**
      * Call a PUBLIC app server function inline (surface `'public'`).

package/dist/api/functions.js

@@ -13,17 +13,55 @@
 // available, the call falls back to the DEPRECATED flat path `/collection/:c/functions/:name`,
 // which the server resolves by bare name and REJECTS with 409 AMBIGUOUS_FUNCTION when more than one
 // installed app defines that name. Always prefer an appId.
-import { post, request, getAppContext } from "../http.js";
-function fnPath(surface, collectionId, name, opts = {}) {
+//
+// RELEASE CHANNEL. The channel is part of the URL — /collection/:c/app/:appId/<channel>/functions/:name
+// — never a query param (the function owns its query string, and a configured URL such as a webhook
+// can only ever hit the channel it names). With NO channel the server runs the release the collection
+// has installed, which is what production wants. A channel comes from, in order: `opts.channel`, the
+// app's channel (initializeApi({ appChannel }) / setAppChannel), or the host's `appChannel` context
+// param (Forge's preview of a Test build passes appChannel=dev). Pass `channel: null` to force the
+// installed release regardless.
+import { post, request, getAppContext, getAppChannel } from "../http.js";
+import { readContext } from "../context.js";
+const CHANNELS = ['dev', 'alpha', 'beta', 'stable'];
+/**
+ * The release channel a call targets, or undefined for "the collection's installed release".
+ * A host context `appChannel` can be scoped to ONE app with `appChannelApp` — needed where several
+ * apps share a page (Forge's portal preview of a dev component), so only the app under development
+ * calls its dev build.
+ */
+export function resolveFunctionChannel(opts = {}, appId) {
+    var _a, _b;
+    if (opts.channel === null)
+        return undefined;
+    let raw = (_a = opts.channel) !== null && _a !== void 0 ? _a : getAppChannel();
+    if (raw == null) {
+        const ctx = readContext();
+        const scopedTo = ctx.appChannelApp;
+        if (ctx.appChannel && (!scopedTo || scopedTo === ((_b = appId !== null && appId !== void 0 ? appId : opts.appId) !== null && _b !== void 0 ? _b : getAppContext())))
+            raw = ctx.appChannel;
+    }
+    if (!raw)
+        return undefined;
+    const ch = String(raw).trim().toLowerCase();
+    if (!CHANNELS.includes(ch))
+        throw new Error(`Unknown release channel "${raw}" (expected ${CHANNELS.join(' | ')})`);
+    return ch;
+}
+function appBase(surface, collectionId, opts) {
     var _a;
     const c = encodeURIComponent(collectionId);
-    const n = encodeURIComponent(name);
     const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
-    const q = opts.channel ? `?channel=${encodeURIComponent(opts.channel)}` : '';
-    return app
-        ? `/${surface}/collection/${c}/app/${encodeURIComponent(app)}/functions/${n}${q}`
-        : `/${surface}/collection/${c}/functions/${n}${q}`; // deprecated flat alias
+    if (!app)
+        return `/${surface}/collection/${c}`; // deprecated flat alias — resolves installed apps only
+    const ch = resolveFunctionChannel(opts, app);
+    return `/${surface}/collection/${c}/app/${encodeURIComponent(app)}${ch ? `/${ch}` : ''}`;
+}
+/** The API path a function call goes to (exported for hosts/tests that need the exact URL). */
+export function functionPath(surface, collectionId, name, opts = {}) {
+    return `${appBase(surface, collectionId, opts)}/functions/${encodeURIComponent(name)}`;
 }
+const fnPath = functionPath;
 export var functions;
 (function (functions) {
     /**
@@ -53,14 +91,7 @@ export var functions;
      * appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
      */
     async function list(collectionId, opts = {}) {
-        var _a;
-        const c = encodeURIComponent(collectionId);
-        const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
-        const q = opts.channel ? `?channel=${encodeURIComponent(opts.channel)}` : '';
-        const path = app
-            ? `/public/collection/${c}/app/${encodeURIComponent(app)}/functions${q}`
-            : `/public/collection/${c}/functions${q}`;
-        return request(path);
+        return request(`${appBase('public', collectionId, opts)}/functions`);
     }
     functions.list = list;
 })(functions || (functions = {}));

package/dist/context.d.ts

@@ -3,6 +3,13 @@ export interface SmartLinksContext {
     appId?: string;
     productId?: string;
     proofId?: string;
+    /**
+     * The release channel the host is running this build as (e.g. 'dev' in Forge's preview of a Test
+     * build). SL.functions uses it to call that channel's server functions. Absent in production.
+     */
+    appChannel?: string;
+    /** Limits `appChannel` to one app (where several apps share a page, e.g. a portal preview). */
+    appChannelApp?: string;
     /** Any other declared view params (e.g. pageId, voteId, orientation, tvMode). */
     [key: string]: string | undefined;
 }

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.34  |  Generated: 2026-10-02T16:06:32.154Z
+Version: 2.0.35  |  Generated: 2026-10-03T12:37:51.058Z
 
 This is a concise summary of all available API functions and types.
 
@@ -172,17 +172,23 @@ The current app context (appId), if the SDK was initialized with one.
 **setAppContext**(id: string | undefined) → `void`
 Set (or clear) the current app context — the appId used to scope SL.functions calls.
 
-**initializeApi**(options: {
-  baseURL: string
-  apiKey?: string
-  bearerToken?: string
-  proxyMode?: boolean
-  ngrokSkipBrowserWarning?: boolean
-  extraHeaders?: Record<string, string>
-  /**
-   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
-   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
-   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
+**getAppChannel**() → `string | undefined`
+The release channel explicitly set for this app build (initializeApi({ appChannel }) / setAppChannel).
+
+**setAppChannel**(channel: string | undefined) → `void`
+Set (or clear) the release channel SL.functions calls target.
+
+**initializeApi**(options: {
+  baseURL: string
+  apiKey?: string
+  bearerToken?: string
+  proxyMode?: boolean
+  ngrokSkipBrowserWarning?: boolean
+  extraHeaders?: Record<string, string>
+  /**
+   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
+   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
+   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
    * short-lived access token. Omit (or `'web'`) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 
@@ -213,56 +219,56 @@ Returns true if initializeApi() has been called at least once. Useful for guards
 **hasAuthCredentials**() → `boolean`
 Returns true if the SDK currently has any auth credential set (bearer token or API key). Use this as a cheap pre-flight check before calling endpoints that require authentication, to avoid issuing a network request that you already know will return a 401. ```ts if (hasAuthCredentials()) { const account = await auth.getAccount() } ```
 
-**configureSdkCache**(options: {
-  enabled?: boolean
-  ttlMs?: number
-  maxEntries?: number
-  persistence?: 'none' | 'indexeddb'
-  persistenceTtlMs?: number
-  serveStaleOnOffline?: boolean
-  clearOnPageLoad?: boolean
+**configureSdkCache**(options: {
+  enabled?: boolean
+  ttlMs?: number
+  maxEntries?: number
+  persistence?: 'none' | 'indexeddb'
+  persistenceTtlMs?: number
+  serveStaleOnOffline?: boolean
+  clearOnPageLoad?: boolean
 }) → `void`
 Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
 **invalidateCache**(urlPattern?: string, options?: InvalidateCacheOptions) → `void`
 Manually invalidate entries in the SDK's GET cache. Note: the GET cache is **in-memory, per page load** (with an optional L2 IndexedDB layer when persistence is enabled) — it does not persist across reloads unless you opt into persistence, so it rarely needs disabling "for correctness". *contains* this string is removed). With `{ exact: true }`, matches the path precisely. Omit to wipe the entire cache. ```ts invalidateCache()                                  // clear everything invalidateCache('/collection/abc123')              // that collection AND everything under it invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry invalidateCache('/products/')                      // all canonical plural product responses ```
 
-**proxyUploadFormData**(path: string,
-  formData: FormData,
+**proxyUploadFormData**(path: string,
+  formData: FormData,
   onProgress?: (percent: number) → `void`
 Upload a FormData payload via proxy with progress events using chunked postMessage. Parent is expected to implement the counterpart protocol.
 
 **request**(path: string) → `Promise<T>`
 Internal helper that performs a GET request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Cache pipeline (when caching is not skipped): L1 hit  → return from memory (no I/O) L2 hit  → return from IndexedDB, promote to L1 (no network) Miss    → fetch from network, store in L1 + L2 Offline → serve stale L2 entry via SmartlinksOfflineError (if persistence enabled) Concurrent identical GETs share one in-flight promise (deduplication). Node-safe: IndexedDB calls are no-ops when IDB is unavailable.
 
-**post**(path: string,
-  body: any,
+**post**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a POST request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**put**(path: string,
-  body: any,
+**put**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a PUT request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**patch**(path: string,
-  body: any,
+**patch**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a PATCH request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**requestWithOptions**(path: string,
+**requestWithOptions**(path: string,
   options: RequestInit) → `Promise<T>`
 Internal helper that performs a request to `${baseURL}${path}` with custom options, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
-**requestStream**(path: string,
-  options?: {
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-    body?: any
-    headers?: Record<string, string>
+**requestStream**(path: string,
+  options?: {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+    body?: any
+    headers?: Record<string, string>
   }) → `Promise<AsyncIterable<T>>`
 Internal helper that performs a streaming request using the shared auth and proxy transport. The response is expected to be `text/event-stream` with JSON payloads in `data:` frames.
 
-**del**(path: string,
+**del**(path: string,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a DELETE request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
@@ -1528,6 +1534,45 @@ interface PdfInspectGraphicsArgs {
 }
 ```
 
+**PdfBox** (interface)
+```typescript
+interface PdfBox {
+  x: number; y: number; w: number; h: number
+}
+```
+
+**PdfEditArgs** (interface)
+```typescript
+interface PdfEditArgs {
+  url: string
+  replaceText?: { id?: string; page?: number; find: string; replace: string; bold?: boolean; align?: 'left' | 'center' | 'right' }[]
+  addText?: { id?: string; page: number; box: PdfBox; text: string; size?: number; bold?: boolean; colour?: PdfColour; align?: 'left' | 'center' | 'right' }[]
+  addImages?: { id?: string; page: number; box: PdfBox; imageUrl: string; colorSpace?: 'rgb' | 'cmyk' }[]
+  preserveColour?: boolean
+}
+```
+
+**PdfPreflightArgs** (interface)
+```typescript
+interface PdfPreflightArgs {
+  url: string; profile?: PdfXProfile; bleed?: { mm: number }; minDpi?: number
+}
+```
+
+**PdfPrintReadyArgs** (interface)
+```typescript
+interface PdfPrintReadyArgs {
+  url: string
+  profile?: PdfXProfile
+  outputIntent?: string
+  convertToCmyk?: boolean
+  embedFonts?: boolean
+  bleed?: { mm: number }
+  flattenTransparency?: boolean
+  minDpi?: number
+}
+```
+
 **HttpRequestArgs** (interface)
 ```typescript
 interface HttpRequestArgs {
@@ -1566,6 +1611,9 @@ interface AiToolArgsMap {
   'pdf.extract': PdfExtractArgs
   'pdf.decodeBarcodes': PdfDecodeBarcodesArgs
   'pdf.inspectGraphics': PdfInspectGraphicsArgs
+  'pdf.edit': PdfEditArgs
+  'pdf.preflight': PdfPreflightArgs
+  'pdf.printReady': PdfPrintReadyArgs
   'http.request': HttpRequestArgs
   'translate': TranslateArgs
 }
@@ -1741,6 +1789,68 @@ interface PdfInspectGraphicsResult {
 }
 ```
 
+**PdfEditItemResult** (interface)
+```typescript
+interface PdfEditItemResult {
+  id: string
+  status: 'done' | 'failed'
+  note?: string
+  verified?: boolean
+  usedFallbackFont?: boolean
+}
+```
+
+**PdfEditResult** (interface)
+```typescript
+interface PdfEditResult {
+  url: string; results: PdfEditItemResult[]; warnings: string[]
+}
+```
+
+**PdfPreflightFinding** (interface)
+```typescript
+interface PdfPreflightFinding {
+  severity: 'error' | 'warning'; code: string; page?: number; message: string
+}
+```
+
+**PdfPreflightResult** (interface)
+```typescript
+interface PdfPreflightResult {
+  url: string
+  compliant: boolean
+  profile: PdfXProfile | null
+  version: string | null
+  findings: PdfPreflightFinding[]
+  stats: {
+  pageCount: number
+  fonts: { name: string; embedded: boolean; subset: boolean; type: string; pages: number[] }[]
+  spotColours: string[]
+  images: { page: number; dpi: number; width: number; height: number; space: string; placedMm: { w: number; h: number } }[]
+  transparency: boolean
+  outputIntent: { identifier: string | null; hasProfile: boolean } | null
+  [key: string]: any
+  }
+}
+```
+
+**PdfPrintReadyResult** (interface)
+```typescript
+interface PdfPrintReadyResult {
+  url: string
+  report: {
+  compliant: boolean
+  profile: PdfXProfile
+  outputIntent: string
+  findings: PdfPreflightFinding[]
+  changes: { code: string; message: string }[]
+  before: { compliant: boolean; errors: number; findings: PdfPreflightFinding[] }
+  stats: Record<string, any>
+  note: string
+  }
+}
+```
+
 **ResponsesAgentTrace** (interface)
 ```typescript
 interface ResponsesAgentTrace {
@@ -1778,6 +1888,10 @@ interface AgentResponseCompletedEvent {
 
 **AiToolName** = ``
 
+**PdfColour** = `string | [number, number, number, number]`
+
+**PdfXProfile** = `'pdfx-1a' | 'pdfx-4'`
+
 **AgentStreamEvent** = ``
 
 ### analytics
@@ -9476,7 +9590,7 @@ interface FunctionListResponse {
 **FunctionCallOptions** (interface)
 ```typescript
 interface FunctionCallOptions {
-  appId?: string; channel?: string
+  appId?: string; channel?: string | null
 }
 ```
 
@@ -10988,6 +11102,12 @@ Delete a form for a collection (admin only).
 
 ### functions
 
+**resolveFunctionChannel**(opts: FunctionCallOptions = {}, appId?: string) → `string | undefined`
+The release channel a call targets, or undefined for "the collection's installed release". A host context `appChannel` can be scoped to ONE app with `appChannelApp` — needed where several apps share a page (Forge's portal preview of a dev component), so only the app under development calls its dev build.
+
+**functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
+The API path a function call goes to (exported for hosts/tests that need the exact URL).
+
 **call**(collectionId: string,
     name: string,
     body: Record<string, any> = {},