@assembly-js/app-foundation 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -19,6 +19,12 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.5.0
+- [new] `detectPdfFields` from `@assembly-js/app-foundation/server` finds the fields on a PDF form: AcroForm fields with their page, kind and options; an XFA form reported as such; or, for a PDF with only text, fields suggested by Assembly AI when an Assembly client is passed, with the page text returned either way. A file that is not a PDF throws `PdfUnreadableError`.
+
+## 0.4.3
+- [guidance] The build agent now knows `viewerClient` works for cross-app calls made by a client contact, and keeps `installerClient` for team members, cron, webhooks and background work.
+
 ## 0.4.2
 - [guidance] The build agent's main guide now says a client contact's cross-app calls use `viewerClient`, while team members and background work keep `installerClient`.
 

package/bin/foundation-exports.mjs

@@ -30,7 +30,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'InternalUserAccess', 'LEGACY_APP_IDS', 'LocationReporter', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'NotifyInternalUsersInput', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
-  'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
+  'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'DetectedPdfField', 'PdfFieldDetection', 'PdfFieldDetectionMethod', 'PdfFieldKind', 'PdfUnreadableError', 'PrincipalAllow', 'PrincipalKind',
   'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',
   'RequestSource', 'ResolveResourceOpts', 'ResourceError', 'ResourceFieldMap',
   'ResourceOption', 'ResourcePage', 'ScheduleCadence', 'SlackChannel',
@@ -42,7 +42,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'clearClientNotifications', 'collectHeaders', 'collectXhrResponseHeaders',
   'cookielessReexchangeHeaders', 'cookiesAreBlocked', 'createAssemblyProxy',
   'createAssemblyReexchangeHandler', 'cronRoute',
-  'decodeBearer', 'expandClientsByCompany', 'extractPdfText', 'fetchSessionFlags',
+  'decodeBearer', 'detectPdfFields', 'expandClientsByCompany', 'extractPdfText', 'fetchSessionFlags',
   'findResource', 'formatAirtableRecords', 'generateAppClient', 'getAirtableTableSchema', 'getCapturedRecords',
   'getClientAccessScope', 'getCookielessBearer', 'getDownloadUrl', 'getInstalledAppIds', 'getIntegration',
   'getInternalUserAccess', 'getLabels', 'getSessionIdentity', 'getUploadUrl',

package/dist/assembly.d.ts

@@ -115,8 +115,7 @@ export interface AppProxyOptions {
  *
  * `installer` calls as this app, with the same per-request mint as
  * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
- * which the platform refuses with `viewer_not_allowed` until it can prove which
- * person a cross-app call is for.
+ * which the platform scopes to that contact and refuses for a team member.
  */
 export declare function appProxyOptions(appId: string, caller: AppProxyCaller): AppProxyOptions;
 export declare function getAssemblyForRequest(req: NextRequest): Promise<AssemblyAPI | NextResponse>;

package/dist/assembly.js

@@ -389,8 +389,7 @@ export async function getInstallerAssembly() {
  *
  * `installer` calls as this app, with the same per-request mint as
  * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
- * which the platform refuses with `viewer_not_allowed` until it can prove which
- * person a cross-app call is for.
+ * which the platform scopes to that contact and refuses for a team member.
  */
 export function appProxyOptions(appId, caller) {
     const origin = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');

package/dist/codegen.js

@@ -131,10 +131,10 @@ import type { paths } from './types.js';
 
 export const APP_ID = ${JSON.stringify(appId)};
 
-// Calls as this app. Use it from pages, server actions, routes, cron and webhooks.
+// Calls as this app. Use it for team members, cron, webhooks and background work.
 export const installerClient = createClient<paths>(appProxyOptions(APP_ID, 'installer'));
 
-// Calls as the signed-in person. Refused with viewer_not_allowed for now.
+// Calls as the signed-in client contact. Refused for a team member.
 export const viewerClient = createClient<paths>(appProxyOptions(APP_ID, 'viewer'));
 `;
 }
@@ -155,8 +155,8 @@ const { data, error } = await installerClient.GET('/projects/{id}', {
 });
 \`\`\`
 
-- \`installerClient\` calls as this app. Use it from pages, server actions, routes, cron and webhooks, and filter anything you show to a client.
-- \`viewerClient\` calls as the signed-in person. The platform refuses it with \`viewer_not_allowed\` until it can prove which person the call is for, so use \`installerClient\` for now.
+- \`installerClient\` calls as this app. Use it for pages and actions a team member runs, and from cron, webhooks and background work. Filter anything you show to a client.
+- \`viewerClient\` calls as the signed-in client contact. The platform scopes the call to that contact, so do not filter what it returns. Use it for pages and actions a contact runs; it is refused for a team member.
 
 ## Operations
 

package/dist/pdf.d.ts

@@ -1,3 +1,4 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
 export interface PdfText {
     /** Every extracted page's text, pages separated by a newline. Empty when the PDF has no text layer (a scan). */
     text: string;
@@ -9,3 +10,42 @@ export interface PdfText {
 export declare function extractPdfText(data: ArrayBuffer | Uint8Array, opts?: {
     maxPages?: number;
 }): Promise<PdfText>;
+export type PdfFieldDetectionMethod = 'acroform' | 'text' | 'xfa' | 'none';
+export type PdfFieldKind = 'text' | 'multiline' | 'checkbox' | 'radio' | 'dropdown' | 'date' | 'signature' | 'unknown';
+export interface DetectedPdfField {
+    /** AcroForm field name, or a slug derived from the label for text detection. */
+    name: string;
+    /** Human label: the AcroForm name humanized, or the label the AI read. */
+    label: string;
+    kind: PdfFieldKind;
+    /** 1-based page number, null when it could not be resolved. */
+    page: number | null;
+    /** Radio and dropdown choices. */
+    options?: string[];
+    /** The AcroForm required flag, when the field sets it. */
+    required?: boolean;
+    source: 'acroform' | 'text';
+}
+export interface PdfFieldDetection {
+    method: PdfFieldDetectionMethod;
+    fields: DetectedPdfField[];
+    pages: number;
+    /** The page text when method is 'text' or 'none', so the app can run its own step. */
+    text?: string;
+    warnings: string[];
+}
+/** The bytes could not be parsed as a PDF; the message is safe to show to the user. */
+export declare class PdfUnreadableError extends Error {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Finds the fields a person has to fill in on a PDF form: its AcroForm fields when
+ * it has them, otherwise fields read from its text by Assembly AI when `assembly`
+ * is given. Throws PdfUnreadableError when the bytes are not a readable PDF.
+ * Server side only: the AI step runs through the app's Assembly client.
+ */
+export declare function detectPdfFields(data: ArrayBuffer | Uint8Array, options?: {
+    assembly?: AssemblyAPI;
+}): Promise<PdfFieldDetection>;

package/dist/pdf.js

@@ -1,15 +1,12 @@
-// unpdf ships a self-contained serverless build of pdf.js: the worker is inlined
-// and it never loads @napi-rs/canvas. pdf-parse and pdfjs-dist locate both at
-// runtime by paths computed from their own location, which the deploy tracer
-// can't follow, so they pass in the sandbox and 500 once published. Loaded
-// lazily so routes that never parse a PDF don't carry the bundle.
-export async function extractPdfText(data, opts) {
-    const { getDocumentProxy, extractText } = await import('unpdf');
-    // pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
-    const bytes = data instanceof ArrayBuffer
+// pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
+function toBytes(data) {
+    return data instanceof ArrayBuffer
         ? new Uint8Array(data)
         : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-    const pdf = await getDocumentProxy(bytes);
+}
+export async function extractPdfText(data, opts) {
+    const { getDocumentProxy, extractText } = await import('unpdf');
+    const pdf = await getDocumentProxy(toBytes(data));
     try {
         const total = pdf.numPages;
         const maxPages = opts?.maxPages;
@@ -41,3 +38,268 @@ export async function extractPdfText(data, opts) {
         await pdf.loadingTask.destroy();
     }
 }
+/** The bytes could not be parsed as a PDF; the message is safe to show to the user. */
+export class PdfUnreadableError extends Error {
+    constructor(options) {
+        super('This file could not be opened as a PDF. It may be damaged, or not a PDF at all.', options);
+        this.name = 'PdfUnreadableError';
+    }
+}
+const PDF_FIELD_DETECTION_MODEL = 'gpt-4o-mini';
+// A form's labels fit well inside this; the cap keeps a long PDF within one request.
+const PDF_FIELD_DETECTION_MAX_CHARS_PER_PAGE = 4000;
+const PDF_FIELD_DETECTION_PROMPT = [
+    'You read the text of a PDF form and list the fields a person would have to fill in.',
+    'Return one entry per blank, checkbox, choice or signature line, in reading order.',
+    'Use the label printed next to the blank. Do not invent fields that are not in the text.',
+    'page is the number from the "--- Page N ---" marker the field appears under, or null if unclear.',
+    'options lists the printed choices for radio and dropdown fields, and is empty otherwise.',
+].join('\n');
+const AI_CHAT_COMPLETIONS_PATH = '/v1/ai/openai/chat/completions';
+const PDF_FIELD_KINDS = [
+    'text',
+    'multiline',
+    'checkbox',
+    'radio',
+    'dropdown',
+    'date',
+    'signature',
+    'unknown',
+];
+const AI_RESPONSE_FORMAT = {
+    type: 'json_schema',
+    json_schema: {
+        name: 'pdf_form_fields',
+        strict: true,
+        schema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['fields'],
+            properties: {
+                fields: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['label', 'kind', 'page', 'options'],
+                        properties: {
+                            label: { type: 'string' },
+                            kind: { type: 'string', enum: PDF_FIELD_KINDS },
+                            page: { type: ['integer', 'null'] },
+                            options: { type: 'array', items: { type: 'string' } },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Finds the fields a person has to fill in on a PDF form: its AcroForm fields when
+ * it has them, otherwise fields read from its text by Assembly AI when `assembly`
+ * is given. Throws PdfUnreadableError when the bytes are not a readable PDF.
+ * Server side only: the AI step runs through the app's Assembly client.
+ */
+export async function detectPdfFields(data, options) {
+    const bytes = toBytes(data);
+    const pdfLib = await import('pdf-lib');
+    let doc;
+    try {
+        doc = await pdfLib.PDFDocument.load(bytes, { ignoreEncryption: true });
+    }
+    catch (cause) {
+        throw new PdfUnreadableError({ cause });
+    }
+    const pages = doc.getPageCount();
+    // XFA forms look fillable in Acrobat but pdf-lib reads only AcroForm fields, so
+    // without this the app would silently report a fillable form as having none.
+    // Checked before getForm(), which strips the XFA entry from the catalog.
+    const hasXfa = doc.catalog.getAcroForm()?.dict.has(pdfLib.PDFName.of('XFA')) ?? false;
+    // pdf-lib cannot decrypt, so an encrypted form's field names and choices would come
+    // back as ciphertext; pdf.js can, so such a PDF goes on to text detection instead.
+    const warnings = doc.isEncrypted ? ['encrypted PDF: form fields read from its text instead'] : [];
+    // A Print or Submit button is not a field a person fills in, so a PDF whose only
+    // widgets are buttons still goes on to text detection.
+    const fields = doc.isEncrypted
+        ? []
+        : doc
+            .getForm()
+            .getFields()
+            .filter((field) => !(field instanceof pdfLib.PDFButton));
+    if (fields.length > 0)
+        return readAcroFormFields(doc, fields, pdfLib);
+    if (hasXfa)
+        return { method: 'xfa', fields: [], pages, warnings };
+    // pdf.js may detach the buffer it is handed, so it gets its own copy.
+    const pageTexts = await extractPageTexts(bytes.slice());
+    const text = pageTexts.join('\n');
+    if (text.trim() === '')
+        return { method: 'none', fields: [], pages, text, warnings };
+    if (!options?.assembly)
+        return { method: 'text', fields: [], pages, text, warnings };
+    const suggested = await suggestFieldsFromText(options.assembly, pageTexts);
+    return {
+        method: 'text',
+        fields: suggested.fields,
+        pages,
+        text,
+        warnings: [...warnings, ...suggested.warnings],
+    };
+}
+function readAcroFormFields(doc, fields, pdfLib) {
+    const pageByRef = new Map();
+    const pageByWidget = new Map();
+    const rotationByPage = new Map();
+    doc.getPages().forEach((page, index) => {
+        pageByRef.set(page.ref, index + 1);
+        rotationByPage.set(index + 1, ((page.getRotation().angle % 360) + 360) % 360);
+        // Some generators omit a widget's /P, so the page's Annots are the fallback.
+        const annots = page.node.Annots();
+        for (let i = 0; annots && i < annots.size(); i++) {
+            const annot = annots.lookup(i);
+            if (annot instanceof pdfLib.PDFDict)
+                pageByWidget.set(annot, index + 1);
+        }
+    });
+    const warnings = [];
+    const located = [];
+    for (const field of fields) {
+        const name = field.getName();
+        const widget = field.acroField.getWidgets()[0];
+        const pageRef = widget?.P();
+        const page = (pageRef && pageByRef.get(pageRef)) || (widget && pageByWidget.get(widget.dict)) || null;
+        if (page === null)
+            warnings.push(`page for field ${name} unknown`);
+        const rect = widget?.getRectangle() ?? { x: 0, y: 0 };
+        const detected = {
+            name,
+            label: humanizeFieldName(name),
+            kind: acroFieldKind(field, pdfLib),
+            page,
+            source: 'acroform',
+        };
+        if (field instanceof pdfLib.PDFRadioGroup ||
+            field instanceof pdfLib.PDFDropdown ||
+            field instanceof pdfLib.PDFOptionList) {
+            detected.options = field.getOptions();
+        }
+        if (field.isRequired())
+            detected.required = true;
+        located.push({ field: detected, ...readingPosition(rect, page ? rotationByPage.get(page) : 0) });
+    }
+    // Unknown pages go last.
+    located.sort((a, b) => (a.field.page ?? Infinity) - (b.field.page ?? Infinity) || a.down - b.down || a.across - b.across);
+    return { method: 'acroform', fields: located.map((l) => l.field), pages: doc.getPageCount(), warnings };
+}
+// Sort keys in the page as displayed: `down` grows top to bottom, `across` left to
+// right. PDF y grows upward, and a page's /Rotate turns it clockwise for display,
+// so on a landscape page rotated 90 degrees the visual top is the stored left edge.
+function readingPosition(rect, rotation = 0) {
+    switch (rotation) {
+        case 90:
+            return { down: rect.x, across: rect.y };
+        case 180:
+            return { down: rect.y, across: -rect.x };
+        case 270:
+            return { down: -rect.x, across: -rect.y };
+        default:
+            return { down: -rect.y, across: rect.x };
+    }
+}
+function acroFieldKind(field, pdfLib) {
+    if (field instanceof pdfLib.PDFTextField)
+        return field.isMultiline() ? 'multiline' : 'text';
+    if (field instanceof pdfLib.PDFCheckBox)
+        return 'checkbox';
+    if (field instanceof pdfLib.PDFRadioGroup)
+        return 'radio';
+    if (field instanceof pdfLib.PDFDropdown || field instanceof pdfLib.PDFOptionList)
+        return 'dropdown';
+    if (field instanceof pdfLib.PDFSignature)
+        return 'signature';
+    return 'unknown';
+}
+// `form1[0].page1[0].full_name[0]` → `Full name`: the last segment is the field's
+// own name, the rest is the authoring tool's container hierarchy.
+function humanizeFieldName(name) {
+    const words = (name.split('.').pop() ?? '')
+        .replace(/\[\d+\]/g, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_\-\s]+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return words ? words[0].toUpperCase() + words.slice(1) : name;
+}
+function slugify(label) {
+    return (label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '') || 'field');
+}
+async function extractPageTexts(bytes) {
+    const { getDocumentProxy, extractText } = await import('unpdf');
+    const pdf = await getDocumentProxy(bytes);
+    try {
+        const { text } = await extractText(pdf, { mergePages: false });
+        return text;
+    }
+    finally {
+        await pdf.loadingTask.destroy();
+    }
+}
+async function suggestFieldsFromText(assembly, pageTexts) {
+    const warnings = [];
+    const prompt = pageTexts
+        .map((pageText, index) => {
+        let body = pageText;
+        if (body.length > PDF_FIELD_DETECTION_MAX_CHARS_PER_PAGE) {
+            body = body.slice(0, PDF_FIELD_DETECTION_MAX_CHARS_PER_PAGE);
+            warnings.push(`page ${index + 1} text truncated to ${PDF_FIELD_DETECTION_MAX_CHARS_PER_PAGE} characters`);
+        }
+        return `--- Page ${index + 1} ---\n${body}`;
+    })
+        .join('\n\n');
+    let suggested;
+    try {
+        const response = await assembly.fetch(AI_CHAT_COMPLETIONS_PATH, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: PDF_FIELD_DETECTION_MODEL,
+                messages: [
+                    { role: 'system', content: PDF_FIELD_DETECTION_PROMPT },
+                    { role: 'user', content: prompt },
+                ],
+                response_format: AI_RESPONSE_FORMAT,
+                stream: false,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(String(response.status));
+        const completion = await response.json();
+        suggested = JSON.parse(completion.choices[0].message.content).fields;
+        if (!Array.isArray(suggested))
+            throw new Error('no fields in response');
+    }
+    catch (err) {
+        warnings.push(`AI suggestion failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { fields: [], warnings };
+    }
+    const usedNames = new Set();
+    const fields = suggested.map((s) => {
+        const base = slugify(s.label);
+        let name = base;
+        for (let n = 2; usedNames.has(name); n++)
+            name = `${base}_${n}`;
+        usedNames.add(name);
+        const page = typeof s.page === 'number' && s.page >= 1 && s.page <= pageTexts.length ? s.page : null;
+        if (page === null)
+            warnings.push(`page for field ${name} unknown`);
+        const kind = PDF_FIELD_KINDS.includes(s.kind) ? s.kind : 'unknown';
+        const field = { name, label: s.label, kind, page, source: 'text' };
+        if ((kind === 'radio' || kind === 'dropdown') && s.options?.length)
+            field.options = s.options;
+        return field;
+    });
+    return { fields, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -78,6 +78,7 @@
   "dependencies": {
     "openapi-fetch": "^0.17.0",
     "openapi-typescript": "^7.13.0",
+    "pdf-lib": "^1.17.1",
     "unpdf": "^1.9.1"
   }
 }

package/skills/assembly-app-clients/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:cross-app-apis -->
 ---
 name: assembly-app-clients
-description: Use when the app calls another workspace app and `generated/apps/<appId>/` exists for it. Covers reading the generated README and types, calling `installerClient` by verb and path, and rendering an empty state that names the app when the call is refused (app_not_found, operation_not_found, viewer_not_allowed, callee_error) instead of throwing a 500.
+description: Use when the app calls another workspace app and `generated/apps/<appId>/` exists for it. Covers reading the generated README and types, calling `viewerClient` or `installerClient` by verb and path, and rendering an empty state that names the app when the call is refused (app_not_found, operation_not_found, viewer_not_allowed, callee_error) instead of throwing a 500.
 ---
 
 ## Where the client lives
@@ -31,9 +31,11 @@ Call it from server code only: pages, server actions, route handlers, cron and w
 
 ## Installer or viewer
 
-Use `installerClient`. It calls as this app, so filter anything it returns to what the viewing client may see before you show it to a client.
+`viewerClient` calls as the signed-in client contact. The platform scopes the call to that contact, so do not filter or double-check what it returns. Use it for pages and actions a contact runs. The platform refuses it for a team member.
 
-`viewerClient` calls as the signed-in person. The platform refuses it with `viewer_not_allowed` until it can prove which person the call is for, so use `installerClient` for now.
+`installerClient` calls as this app, not as a person. Use it for pages and actions a team member runs, and from cron, webhooks and other background work. Filter anything you show to a client.
+
+If an operation can be called by a contact, it must not make platform calls about clients, companies or the workspace as the caller. Contacts are refused on those routes and the call surfaces as a generic failure. Look things up with the app's own access, or store the display names on the row when the item is assigned.
 
 ## When the other app cannot answer
 
@@ -43,7 +45,7 @@ The other app can be uninstalled, can drop an operation, or can fail on its own.
 |---|---|---|
 | `app_not_found` | The app is not installed in this workspace, or this app may not call it. | Empty state: "<App name> is not available in this workspace." |
 | `operation_not_found` | The app no longer offers this operation. | Empty state: "<App name> no longer provides this." |
-| `viewer_not_allowed` | The call used `viewerClient`. | Nothing at runtime: switch the call to `installerClient`. |
+| `viewer_not_allowed` | The platform refused the call for this person: a team member used `viewerClient`, or a contact could not be resolved. | For a team member, call with `installerClient`. For a contact, render an empty or permission state naming the app and never retry with `installerClient`. |
 | `callee_error` | The other app answered with its own failure. The most common case at runtime. | Error state: "<App name> could not load this right now." |
 
 Branch on the result and render a state that names the app: