@assembly-js/app-foundation 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -19,6 +19,13 @@ 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.6.5
+- [guidance] The `assembly-storage` skill says the `assembly` option of `detectPdfFields` is only an opt-in flag. The `assembly-ai` skill and the `assembly.fetch()` prose now call the AI proxy on the installer client (`getInstallerAssembly()`, gated by `await getAssembly()` first) instead of the viewer's client.
+- [behavior] `detectPdfFields` now runs its AI step on the installer client, and degrades to a warning when there is no verified viewer. `options.assembly` is deprecated and ignored; passing it still opts in to the AI step.
+
+## 0.6.4
+- [behavior] An app's sandbox now sends its sandbox grant when minting an app bearer, so the platform can tell its calls from the deployed app's.
+
 ## 0.6.3
 - [fix] The client-call scan no longer reports `retrieveCompany` on the viewer client as breaking: the platform now lets a client read its own active company (`GET /v1/companies/{id}`), and refuses any other company. Nothing in the app changes.
 

package/CLAUDE.md

@@ -1260,9 +1260,11 @@ Convention-breakers to know up front:
 
 ### `assembly.fetch()` — for non-SDK endpoints
 
-The SDK exposes a generic `fetch(path, init?)` method for calling Assembly API endpoints that aren't in the generated SDK methods (e.g. the AI proxy). It prepends the base URL and injects auth headers (`Authorization: Bearer` from the `getAssembly()` client, plus `X-Assembly-SDK-Version`) automatically — never `X-API-Key` on data calls — returning a standard `Response`:
+The SDK exposes a generic `fetch(path, init?)` method for calling Assembly API endpoints that aren't in the generated SDK methods (e.g. the AI proxy). It prepends the base URL and injects auth headers (`Authorization: Bearer` from the client you call it on, plus `X-Assembly-SDK-Version`) automatically — never `X-API-Key` on data calls — returning a standard `Response`. The AI proxy is app-owned, so call it on the installer client (`getInstallerAssembly()`, server-side only), gated by `await getAssembly()` first because that throws without a verified viewer:
 
 ```ts
+await getAssembly(); // the gate: throws without a verified viewer
+const assembly = await getInstallerAssembly();
 const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
   method: 'POST',
   body: JSON.stringify({ model: 'gpt-4o-mini', messages }),

package/dist/mint-bearer.js

@@ -171,9 +171,15 @@ export async function mintBearerFromAppKey() {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
     try {
+        // Present only in the app's sandbox (written to .env.local, never to the deployed
+        // env); it lets the platform tell a sandbox call from a deployed one.
+        const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
         const resp = await fetch(`${base}/v1/token`, {
             method: 'POST',
-            headers: { 'X-API-Key': apiKey },
+            headers: sandboxGrant
+                ? { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }
+                : { 'X-API-Key': apiKey },
+            ...(sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {}),
             signal: controller.signal,
         });
         if (!resp.ok)

package/dist/pdf.d.ts

@@ -44,8 +44,12 @@ export declare class PdfUnreadableError extends Error {
  * 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.
+ * Server side only: the AI step runs through the installer client.
  */
 export declare function detectPdfFields(data: ArrayBuffer | Uint8Array, options?: {
+    /**
+     * @deprecated The client is ignored: the AI step uses the installer client, since the AI proxy
+     * is app-owned. Kept so existing apps that pass it keep working; its presence still opts in.
+     */
     assembly?: AssemblyAPI;
 }): Promise<PdfFieldDetection>;

package/dist/pdf.js

@@ -1,3 +1,4 @@
+import { getInstallerAssemblyForCaller } from './installer-caller.js';
 // pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
 function toBytes(data) {
     return data instanceof ArrayBuffer
@@ -98,7 +99,7 @@ const AI_RESPONSE_FORMAT = {
  * 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.
+ * Server side only: the AI step runs through the installer client.
  */
 export async function detectPdfFields(data, options) {
     const bytes = toBytes(data);
@@ -137,7 +138,7 @@ export async function detectPdfFields(data, options) {
         return { method: 'none', fields: [], pages, text, warnings };
     if (!options?.assembly)
         return { method: 'text', fields: [], pages, text, warnings };
-    const suggested = await suggestFieldsFromText(options.assembly, pageTexts);
+    const suggested = await suggestFieldsFromText(pageTexts);
     return {
         method: 'text',
         fields: suggested.fields,
@@ -247,7 +248,7 @@ async function extractPageTexts(bytes) {
         await pdf.loadingTask.destroy();
     }
 }
-async function suggestFieldsFromText(assembly, pageTexts) {
+async function suggestFieldsFromText(pageTexts) {
     const warnings = [];
     const prompt = pageTexts
         .map((pageText, index) => {
@@ -261,6 +262,9 @@ async function suggestFieldsFromText(assembly, pageTexts) {
         .join('\n\n');
     let suggested;
     try {
+        // Inside the try so a missing verified viewer degrades to a warning like any other AI failure.
+        // Same viewer gate as storage and connectors: an app with token exchange off has no verified viewer here, and that is accepted.
+        const assembly = await getInstallerAssemblyForCaller();
         const response = await assembly.fetch(AI_CHAT_COMPLETIONS_PATH, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },

package/dist/scripts.js

@@ -4652,9 +4652,11 @@ async function mintBearerFromAppKey() {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
   try {
+    const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
     const resp = await fetch(`${base}/v1/token`, {
       method: "POST",
-      headers: { "X-API-Key": apiKey },
+      headers: sandboxGrant ? { "X-API-Key": apiKey, "Content-Type": "application/json" } : { "X-API-Key": apiKey },
+      ...sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {},
       signal: controller.signal
     });
     if (!resp.ok) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-ai/SKILL.md

@@ -13,13 +13,15 @@ The proxy mirrors OpenAI's API shape. Call any OpenAI endpoint path via:
 
 ## Setup
 
-Create a helper in `lib/ai.ts` that uses the existing Assembly SDK instance:
+Create a helper in `lib/ai.ts` that calls the proxy on the installer client:
 
 ```typescript
-import { getAssembly } from '@assembly-js/app-foundation/server';
+import { getAssembly, getInstallerAssembly } from '@assembly-js/app-foundation/server';
 
 export async function chatCompletion(messages: Array<{ role: string; content: string }>, options?: { model?: string; stream?: boolean }) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
     method: 'POST',
     body: JSON.stringify({
@@ -41,7 +43,9 @@ export async function aiErrorMessage(response: Response): Promise<string> {
 }
 ```
 
-`assembly.fetch()` automatically prepends the base URL and injects auth headers (`Authorization: Bearer` from `getAssembly()`, plus `X-Assembly-SDK-Version`). It never sends `X-API-Key` on data calls. You only provide the path and request body.
+`assembly.fetch()` automatically prepends the base URL and injects auth headers (`Authorization: Bearer` from the installer client, plus `X-Assembly-SDK-Version`). It never sends `X-API-Key` on data calls. You only provide the path and request body.
+
+The AI proxy belongs to the app, not to the person using it, so these calls use the installer client from `getInstallerAssembly()` rather than the viewer's `getAssembly()` client. It is server-side only. Call `await getAssembly()` first: it throws when there is no verified viewer, which keeps the installer's authority from being used by an anonymous caller. Let that throw propagate out of the server action so the bearer renewal can retry it; return `{ ok: false, message }` only for the proxy's own refusals.
 
 ## Server-side only
 
@@ -87,7 +91,9 @@ The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content
 
 ```typescript
 export async function analyzeImage(base64DataUrl: string, prompt: string) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
     method: 'POST',
     body: JSON.stringify({
@@ -128,7 +134,9 @@ Transcribe on the server. Post the file as `multipart/form-data` to `/v1/ai/open
 
 ```typescript
 export async function transcribeAudio(file: File) {
-  const assembly = await getAssembly();
+  // The AI proxy is app-owned, so it uses the installer client; getAssembly() is the gate, it throws without a verified viewer.
+  await getAssembly();
+  const assembly = await getInstallerAssembly();
   const body = new FormData();
   body.append('file', file);
   body.append('model', 'gpt-4o-mini-transcribe');

package/skills/assembly-storage/SKILL.md

@@ -168,8 +168,9 @@ free — no second upload.
 ### Detecting form fields in an uploaded PDF
 
 A PDF-to-form feature calls the helper in the processing route and lets `method` decide the UI. Passing
-`assembly` (from `getAssemblyForRequest(request)`) lets a text-only PDF get AI-suggested fields; without
-it, `text` comes back with no fields. A file that is not a PDF throws `PdfUnreadableError`, whose message
+`assembly` (from `getAssemblyForRequest(request)`) opts a text-only PDF in to AI-suggested fields; without
+it, `text` comes back with no fields. The AI step runs on the installer client, so the client you pass is
+only the opt-in flag and is otherwise ignored (the option is deprecated). A file that is not a PDF throws `PdfUnreadableError`, whose message
 is safe to show.
 
 ```typescript