@assembly-js/app-foundation 0.0.31 → 0.0.32

package/CLAUDE.md

@@ -43,7 +43,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-app-surfaces` — REQUIRED before writing `.assembly/app.json`: declare which surfaces (dashboard, client portal, notification) the app exposes; omitting the client surface keeps the app off client portal nav entirely
 - `assembly-app-bridge-header` — breadcrumbs (don't include app name), CTAs
 - `assembly-app-bridge-toast` — show toast notifications in the parent dashboard
-- `assembly-ai` — AI features via Assembly's OpenAI proxy (no API keys needed)
+- `assembly-ai` — AI features, including speech-to-text, via Assembly's OpenAI proxy (no API keys needed)
 - `assembly-storage` — app-private file uploads/downloads (NOT the portal Files module). The storage helpers come from `@assembly-js/app-foundation/server` — import them, don't rewrite them. POST only `{ fileName }` (a bare name) and store the key the platform returns; never build the S3 key yourself.
 - `assembly-integrations` (present only when third-party integrations are enabled for this workspace) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`. If this skill is present, read it and `.claude/skills/assembly-integrations/providers/<slug>.md` before declaring an integration or writing any provider call — the skill lists what's connectable, the provider doc has that provider's gotchas — and read them first when provider data displays wrongly (wrong format, raw IDs). If it is absent, managed OAuth integrations are not available here; use `requiredSecrets` for any external service
 - `assembly-avatar-sub` — AvatarSub company badge wherever a client is rendered, including tables of your own records that reference a client; row duplication only for lists OF clients

package/dist/bridge-vnext.d.ts

@@ -0,0 +1,73 @@
+import '@assembly-js/app-bridge';
+export type NavigateDestination = {
+    to: 'home';
+} | {
+    to: 'client';
+    clientId: string;
+    tab?: string;
+} | {
+    to: 'company';
+    companyId: string;
+    tab?: string;
+} | {
+    to: 'channel';
+    channelId?: string;
+} | {
+    to: 'files';
+    channelId?: string;
+} | {
+    to: 'contract';
+    contractId: string;
+} | {
+    to: 'form';
+    formId: string;
+} | {
+    to: 'formResponse';
+    formId: string;
+    responseId: string;
+} | {
+    to: 'invoice';
+    invoiceId: string;
+} | {
+    to: 'subscription';
+    subscriptionId: string;
+} | {
+    to: 'product';
+} | {
+    to: 'helpdesk';
+} | {
+    to: 'article';
+    articleId: string;
+} | {
+    to: 'notifications';
+} | {
+    to: 'automations';
+} | {
+    to: 'settings';
+    page?: string;
+} | {
+    to: 'app';
+    installId: string;
+};
+export type NavigateToOptions = {
+    replace?: boolean;
+    newTab?: boolean;
+    timeout?: number;
+};
+export type NavigateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+declare module '@assembly-js/app-bridge' {
+    interface AssemblyBridgeApi {
+        postToParent(message: {
+            type: string;
+            [key: string]: unknown;
+        }, options?: {
+            droppable?: boolean;
+        }): void;
+        navigateTo(destination: NavigateDestination, options?: NavigateToOptions): Promise<NavigateResult>;
+    }
+}

package/dist/bridge-vnext.js

@@ -0,0 +1,13 @@
+// The published @assembly-js/app-bridge types this package typechecks against
+// (peer >=1.3.0) predate the public postToParent and navigateTo. Both land on
+// the 2.0.0 set, where they're required interface members. Augment rather
+// than depending on an unpublished tarball; call sites guard with `?.` /
+// truthiness checks since older peers lack these at runtime.
+//
+// Exported as real types (not just declared ambiently) because an ambient
+// .d.ts that nothing imports never reaches a published package's declaration
+// output — tsc only emits/carries declarations that are part of the module
+// graph. lib-client.ts imports these types from this module instead of from
+// '@assembly-js/app-bridge' so the augmentation travels with it to consumers
+// on older peers, which don't export these names at all.
+import '@assembly-js/app-bridge';

package/dist/lib-client.d.ts

@@ -1,3 +1,4 @@
+import type { NavigateDestination, NavigateToOptions } from './bridge-vnext.js';
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 export declare function downloadViaBlob(url: string, filename: string): Promise<void>;
@@ -9,3 +10,13 @@ export declare function downloadViaBlob(url: string, filename: string): Promise<
  * Exported for tests; runs once at module load in the browser.
  */
 export declare function bootstrapCookielessBearer(): Promise<boolean>;
+/**
+ * Returns an onClick handler that navigates the parent Assembly portal to the
+ * given typed destination. Use in button or anchor onClick props.
+ *
+ * @example
+ * <button onClick={linkTo({ to: 'invoice', invoiceId: invoice.id })}>
+ *   View invoice
+ * </button>
+ */
+export declare function linkTo(destination: NavigateDestination, options?: NavigateToOptions): () => void;

package/dist/lib-client.js

@@ -166,3 +166,22 @@ export function bootstrapCookielessBearer() {
 // Self-running, mirroring origin-bootstrap: module evaluation precedes
 // hydration, so the bearer is in hand before any component's first fetch.
 void bootstrapCookielessBearer();
+/**
+ * Returns an onClick handler that navigates the parent Assembly portal to the
+ * given typed destination. Use in button or anchor onClick props.
+ *
+ * @example
+ * <button onClick={linkTo({ to: 'invoice', invoiceId: invoice.id })}>
+ *   View invoice
+ * </button>
+ */
+export function linkTo(destination, options) {
+    return () => {
+        // navigateTo rejects when the host never answers (e.g. the nav v2 flag is
+        // off) — catch it here, since the caller only gets a void onClick handler
+        // back and has no promise of its own to attach a handler to.
+        AssemblyBridge.navigateTo?.(destination, options)?.catch((err) => {
+            console.error('linkTo: navigateTo failed', err);
+        });
+    };
+}

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-ai
-description: Use when the app needs AI features like text generation, summarization, analysis, or any LLM capability. Apps call Assembly's AI proxy — no API keys or external SDKs needed.
+description: Use when the app needs AI features like text generation, summarization, analysis, vision, speech-to-text, or any LLM capability. Apps call Assembly's AI proxy — no API keys or external SDKs needed.
 ---
 
 ## How it works
@@ -96,6 +96,29 @@ const toDataUrl = (file: File): Promise<string> =>
 
 Keep images under ~4 MB to stay within the 6 MB Lambda payload limit (base64 adds ~33% overhead). For larger images, resize on the client before converting.
 
+## Audio (speech-to-text)
+
+Record in the browser with `MediaRecorder` in the browser's native container: `audio/webm;codecs=opus`, or `audio/mp4` on Safari. Use a speech bitrate such as 24 kbps. Do not decode the recording to PCM or WAV in the browser.
+
+Transcribe on the server. Post the file as `multipart/form-data` to `/v1/ai/openai/audio/transcriptions` through `assembly.fetch()`. Use `gpt-4o-mini-transcribe` (`whisper-1` is the alternative). Do not set a JSON `Content-Type` on this call. Pass the `FormData` as the body and let the runtime set the multipart header.
+
+```typescript
+export async function transcribeAudio(file: File) {
+  const assembly = await getAssembly();
+  const body = new FormData();
+  body.append('file', file);
+  body.append('model', 'gpt-4o-mini-transcribe');
+  const response = await assembly.fetch('/v1/ai/openai/audio/transcriptions', {
+    method: 'POST',
+    body,
+  });
+  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
+  return response;
+}
+```
+
+Keep each uploaded file under 4 MB. The platform API rejects request bodies above roughly 4.5 MB with HTTP 413 before the proxy runs, and there is no richer error to catch. Keep each file under about five minutes so the upstream call also finishes inside the proxy's 27 second first-byte timeout. For longer recordings, split the recording into files that meet both bounds and persist each transcript piece as it completes.
+
 ## Model selection
 
 - Default to `gpt-4o-mini` for most tasks (fast, cheap, good enough)