@assembly-js/app-foundation 0.0.41 → 0.0.43

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to `@assembly-js/app-foundation`, newest first. Each `## <version>` section
+lists what that version means for an app that already exists, one kind per bullet:
+
+- `[fix]` — fixed on install; the app's code doesn't change.
+- `[behavior]` — the app behaves differently on install with no code change; its owner should know.
+- `[action: <id>]` — the app's own code must change; `<id>` names the `fixes.json` entry that
+  detects the gap and tells the update agent how to close it.
+- `[new]` — something the app can adopt; nothing changes until it does.
+- `[guidance]` — changes what the build agent is taught for future work, not existing code.
+
+A foundation update reads the sections between an app's version and the target: owner-facing copy
+from every bullet except `[guidance]`, agent work from the `fixes.json` entries those `[action]`
+bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
+
+## 0.0.42
+- [action: package-proxy] Sign-in and cross-site request protection now come from the package instead of code the app owns, and are checked by sending real requests through the app.
+
+## 0.0.41
+- [guidance] Tell the build agent where an owner updates an API key that has expired or been rejected (App secrets in the builder chat, then republish), instead of sending them to support.
+
+## 0.0.40
+- [behavior] Confirm each viewer's session with the platform instead of trusting the token alone, cached briefly per server. If the platform can't be reached, the app fails closed instead of guessing who is signed in.
+- [action: identity-outage-states] Show a retry screen when the platform can't confirm the viewer instead of an error page, and stop a failing app from renewing its session over and over.
+
+## 0.0.39
+- [fix] Let an app keep a scheduled job it already runs more often than every 30 minutes: the cron check now warns about that schedule instead of failing the build.
+
+## 0.0.38
+- [guidance] Keep a usage-threshold alert going to the person whose own action crossed the threshold, and only record the alert as sent once it actually was, so a failed send can retry.
+
+## 0.0.37
+- [fix] Fix saves of records with nested rows (a proposal's packages, a retainer's allowances) failing with a 500 and leaving the parent without its children.
+- [action: inlined-child-rows-batch] Apps that copied the child-row helper into their own code carry the same bug and need the package's helper instead.
+
+## 0.0.36
+- [fix] Accept notification category ids with underscores (`past_due`), so a build no longer fails on the id the user asked for.
+
+## 0.0.35
+- [guidance] Tell the build agent which modules every workspace has (clients, companies, custom fields, notifications) and which it must confirm are installed before planning around them (forms, files, tasks, billing and the rest).
+- [new] Add `replaceChildRows`, a helper that replaces a record's child rows safely, so saving a form can't drop rows the user just added.
+
+## 0.0.34
+- [guidance] Teach the build agent to link to platform records (a client, a company, an invoice, another app) with `linkTo()` instead of hand-building host URLs.
+
+## 0.0.33
+- [fix] Report the right in-app location for apps whose client or internal surface lives at a custom path, not only `/c` and `/n`.
+
+## 0.0.32
+- [guidance] Teach the AI skill speech-to-text: record compressed audio in the browser and transcribe it on the server, within the request-size cap.
+
+## 0.0.31
+- [fix] Fix file downloads breaking under bearer-only auth: a partitioned cookie wasn't sent when the download opened in a new tab.
+
+## 0.0.30
+- [fix] Accept `privateRoutes` in the manifest validator.
+
+## 0.0.29
+- [guidance] Give generated apps the workspace admin role by default instead of leaving them to guess it.
+
+## 0.0.28
+- [guidance] Fix draft creation dropping fields the user had already submitted.
+
+## 0.0.27
+- [guidance] Let the build agent ask the user structured questions instead of free-text chat.
+
+## 0.0.27-rc.0
+- [guidance] Tell the build agent what a passing build actually proves, and what it still has to disclose to the user.
+
+## 0.0.26
+- [guidance] Warn the build agent that props passed into client components must be serializable.
+
+## 0.0.25-rc.6
+- [guidance] Teach server actions to return a refusal as data instead of throwing, so the UI can explain it.
+
+## 0.0.25-rc.5
+- [new] Alert Slack when one of an app's scheduled jobs fails.
+
+## 0.0.25-rc.4
+- [fix] Fix generated apps breaking in Safari, which refuses the bearer cookie under its default tracking protection.
+
+## 0.0.25-rc.3
+- [guidance] Add flag-gated guidance for apps that own their own header instead of the app bridge header.
+
+## 0.0.25-rc.2
+- [fix] Grandfather pre-existing cron wiring and declare `CRON_SECRET` from `vercel.json` automatically.
+
+## 0.0.25-rc.0
+- [guidance] Teach generated apps to run scheduled work on a Vercel cron.
+
+## 0.0.24
+- [fix] Fix Slack mention tokens not resolving to real names in built apps.
+
+## 0.0.23
+- [guidance] Update Slack guidance across all Nango-backed actions.
+
+## 0.0.22
+- [new] Ship vNext content: origin bootstrap and a cookie-outcome log line.
+- [action: paint-beacon] The builder preview now tells a page that rendered from one that only loaded, which needs the paint beacon in the app.
+
+## 0.0.21
+- [new] Add Slack error-code and channel-list helpers, and a tripwire against an accidental `useServerAction` fetch loop, ahead of connector GA.
+
+## 0.0.20
+- [action: next-config-wrapper] The live preview no longer hangs on networks that block its dev connection, which needs the app's Next config split into the platform wrapper and the app's own settings.
+
+## 0.0.19
+- [guidance] Align the connector action catalog's signatures with the vendored scripts' actual behavior.
+
+## 0.0.18
+- [guidance] Fill vendored-action and doc gaps for exposed connectors, plus spreadsheet metadata.
+
+## 0.0.17
+- [guidance] Revert: restore the pre-slim app-builder context. 0.0.11's slimmed-down context regressed build quality, so this release reverts it wholesale.
+
+## 0.0.16
+- [new] Deepen exposed-provider docs and add a `gmailSendEmail` foundation helper.
+
+## 0.0.15
+- [guidance] Tell the build agent not to promise Slack DMs the app can't actually send.
+
+## 0.0.14
+- [new] Add Airtable record labels and column formatting, with a matching provider doc and foundation helper.
+
+## 0.0.13
+- [guidance] Add per-provider doc rendering for the assembly-integrations skill.
+
+## 0.0.12
+- [behavior] Namespace each app's automation triggers and actions with a per-app `~<appId>.` prefix.
+
+## 0.0.11
+- [guidance] Release a slimmed-down build-agent context to migrated apps. (Reverted at 0.0.17.)
+
+## 0.0.10
+- [new] Add deterministic notification-clear and deferred-auth helper utilities.
+
+## 0.0.9
+- [fix] Fix custom-domain portals failing to frame the app by registering the framing origin with the app-bridge allowlist.
+
+## 0.0.8-rc.0
+- [new] Add sandbox bindings for the scoped platform MCP.
+
+## 0.0.7
+- [fix] Fix invalid YAML in skill frontmatter.
+
+## 0.0.6
+- [fix] Add identity-aware session-exchange rejection and single-flight, marker-gated bearer renewal.
+
+## 0.0.5
+- [guidance] Fix automation events firing from more than one code path by emitting them only inside `after()`.
+
+## 0.0.4
+- [guidance] Teach the build agent to reach for automations when a request describes a workflow.
+
+## 0.0.3
+- [guidance] Move the build guards into the app-foundation package tree.
+
+## 0.0.2
+- [guidance] Release the context package as 0.0.2.
+
+## 0.0.2-rc.2
+- [guidance] Render context prose in the sandbox so the package owns every skill.
+
+## 0.0.1
+- [new] First stable release of `@assembly-js/app-foundation`.
+
+## 0.0.1-rc.2
+- [fix] Fix the published package being unimportable by Node; drop `.js` extensions from `src` and add them back on emit.
+
+## 0.0.1-rc.1
+- [new] First published version, under the `rc` dist-tag.

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Assembly App Guide
 
-You are an expert frontend engineer building a custom app that runs **inside an Assembly portal as an iframe**. You create beautiful, performant, mobile-first applications that follow UI/UX and shadcn best practices and provide clear user feedback. **Design mobile-first: every component and layout must start from a single-column, narrow-viewport base (down to 320px) and scale up using `sm:`, `md:`, and `lg:` breakpoints.** This applies to grids, padding, typography, tabs, and any horizontal arrangement. If a task description gives you non-responsive CSS, adapt it to be mobile-first yourself. Read this whole file before writing any code — it contains the platform model, the data model, the SDK surface, and the iframe constraints. The information here is more current than your training data. **Before any SDK call, read `node_modules/@assembly-js/node-sdk/dist/codegen/api/index.d.ts` for what exists and the matching `services/<Resource>Service.d.ts` for its parameter shapes** — the type definitions are the source of truth.
+You are an expert frontend engineer building a custom app that runs **inside an Assembly portal as an iframe**. You create beautiful, performant, mobile-first applications that follow UI/UX and shadcn best practices and provide clear user feedback. **Design mobile-first: every component and layout must start from a single-column, narrow-viewport base (down to 320px) and scale up using `sm:`, `md:`, and `lg:` breakpoints.** This applies to grids, padding, typography, tabs, and any horizontal arrangement. If a task description gives you non-responsive CSS, adapt it to be mobile-first yourself. Read this whole file before writing any code — it contains the platform model, the data model, the SDK surface, and the iframe constraints. The information here is more current than your training data. **The SDK method tables below are generated from the SDK's type definitions; read `node_modules/@assembly-js/node-sdk/dist/codegen/api/services/<Resource>Service.d.ts` only for nested parameter shapes.**
 
 ## Communication rules
 
@@ -164,17 +164,14 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 
 **Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or calling its SDK, confirm it is installed — call `listAppInstalls`. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
 
-| Module | What it does | Reach via SDK |
-|---|---|---|
-| Messages | Direct messaging between staff and clients | `sendMessage`, `listMessages`, `createMessageChannel`, `listMessageChannels`, `retrieveMessageChannel` |
-| Files | Secure file/folder sharing | `createFile`, `listFiles`, `retrieveFile`, `deleteFile`, `retrieveDownloadUrlOfAFile`, `createFileChannel`, `listFileChannels` |
-| | *For app-private uploads (attachments, exports) use the storage helpers from `@assembly-js/app-foundation/server` (see the `assembly-storage` skill) instead — Files is only for files the user wants in the portal Files tab.* | |
-| Contracts | eSignature contracts | `sendContract`, `listContracts`, `retrieveContract`, `listContractTemplates`, `retrieveContractTemplate` |
-| Forms | Intake forms / surveys (6 question types) | `listForms`, `retrieveForm`, `requestFormResponse`, `listFormResponses` |
-| Billing | Invoices, subscriptions, payments | `createInvoice`, `listInvoices`, `retrieveInvoice`, `listInvoiceTemplates`, `createSubscription`, `listSubscriptions`, `retrieveSubscription`, `cancelSubscription`, `listSubscriptionTemplates`, `listProducts`, `retrieveProduct`, `listPrices`, `retrievePrice`, `listPayments` |
-| Knowledge Base | Help articles / docs | (no SDK methods today; render-only) |
-| Tasks | Assign tasks to clients/team | `retrieveTasks`, `createTask`, `retrieveTask`, `updateTask`, `deleteTask`, `listTaskTemplates`, `retrieveTaskTemplate` |
-| Notes | Per-client/company internal notes | `createNote`, `listNotes`, `retrieveNote`, `updateNote`, `deleteNote` |
+- **Messages** — Direct messaging between staff and clients.
+- **Files** — Secure file/folder sharing. *For app-private uploads (attachments, exports) use the storage helpers from `@assembly-js/app-foundation/server` (see the `assembly-storage` skill) instead — Files is only for files the user wants in the portal Files tab.*
+- **Contracts** — eSignature contracts.
+- **Forms** — Intake forms / surveys (6 question types).
+- **Billing** — Invoices, subscriptions, payments.
+- **Knowledge Base** — Help articles / docs.
+- **Tasks** — Assign tasks to clients/team.
+- **Notes** — Per-client/company internal notes.
 
 If the user's prompt says "build a CRM," the answer is mostly **wire up the existing Clients + Companies** (and any optional modules that are actually installed) **in a custom view** — not invent your own.
 
@@ -182,14 +179,273 @@ If the user's prompt says "build a CRM," the answer is mostly **wire up the exis
 
 ## The data model
 
-| Resource | What it is | SDK methods |
+- **Workspace** — The portal itself (one per Assembly account)
+- **Internal user** — Staff at the business
+- **Client** — A client user — represents a person, has email/name
+- **Company** — A business that a Client belongs to (groups clients by org)
+- **Custom field** — Workspace-defined extra fields on Client/Company records
+- **App install** — Reference to your app + others installed in the portal
+
+**SDK methods** (every service, not only the resources above):
+
+<!-- generated: sdk-methods -->
+Generated from the SDK's service classes. Methods are called flat (`assembly.listClients(...)`); every method takes a single object of the named parameters (`?` = optional), and a service with no methods listed is not callable. Read the `.d.ts` only for nested parameter shapes. Named return types that could not be resolved to a `{ data, nextToken }` list envelope are shown by name and need a `.d.ts` lookup.
+
+**Clients**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listClients` | `limit?`, `nextToken?`, `companyId?`, `givenName?`, `familyName?`, `email?`, `customFields?` | `{ data: Array<api_ClientItem>, nextToken }` |
+| `createClient` | `requestBody`, `sendInvite?` | `api_ClientItem` |
+| `deleteClient` | `id` | `api_ClientItem` |
+| `retrieveClient` | `id` | `api_ClientItem` |
+| `updateClient` | `id`, `requestBody`, `sendInvite?` | `api_ClientItem` |
+| `retrieveClientAppVisibility` | `id` | `api_ClientItem` |
+
+**Comments**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `getV1Comments` | `limit?`, `nextToken?`, `taskId?` | `{ data?: Array<marketplace_application_TaskComment>, nextToken }` |
+| `deleteV1CommentsCommentid` | `commentId` | `marketplace_application_TaskComment` |
+| `getV1CommentsCommentid` | `commentId` | `marketplace_application_TaskComment` |
+
+**Companies**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listCompanies` | `limit?`, `nextToken?`, `name?`, `isPlaceholder?` | `{ data: Array<api_CompanyItem>, nextToken }` |
+| `createCompany` | `requestBody` | `api_CompanyItem` |
+| `deleteCompany` | `id` | `api_ItemFields` |
+| `retrieveCompany` | `id` | `api_CompanyItem` |
+| `updateCompany` | `id`, `requestBody` | `api_CompanyItem` |
+| `addClientsToCompany` | `id`, `requestBody`, `confirmPromotePlaceholder?` | `company_addClientToCompanyResponse` |
+
+**ContractTemplates**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listContractTemplates` | `name?`, `limit?`, `nextToken?` | `{ data: Array<contracts_ContractTemplate>, nextToken }` |
+| `retrieveContractTemplate` | `id` | `contracts_ContractTemplate` |
+
+**Contracts**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listContracts` | `status?`, `contractTemplateId?`, `recipientId?`, `clientId?`, `name?`, `limit?`, `nextToken?` | `{ data: Array<contracts_Contract>, nextToken }` |
+| `sendContract` | `requestBody` | `contracts_Contract` |
+| `retrieveContract` | `id` | `contracts_Contract` |
+
+**CustomFields**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listCustomFields` | `name?`, `entityType?` | `{ data: Array<customfields_ClientCustomField>, nextToken }` |
+| `createCustomField` | `requestBody` | `customfields_createCustomFieldsResponse` |
+| `listCustomFieldOptions` | `id`, `label?` | `{ data: Array<customfields_ClientCustomFieldOption>, nextToken }` |
+
+**Events**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listEvents` | `startDate?`, `endDate?`, `eventType?`, `actorId?`, `nextToken?`, `limit?` | `{ data: Array<audit_log_AuditLog>, nextToken }` |
+| `createEvent` | `requestBody` | `audit_log_AuditLog` |
+| `retrieveEvent` | `id` | `audit_log_AuditLog` |
+
+**FileChannels**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listFileChannels` | `companyId?`, `clientId?`, `membershipType?`, `memberId?`, `membershipEntityId?`, `limit?`, `nextToken?` | `{ data: Array<filechannels_FileChannel>, nextToken }` |
+| `createFileChannel` | `requestBody` | `filechannels_FileChannel` |
+| `retrieveFileChannel` | `id` | `filechannels_FileChannel` |
+
+**Files**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listFiles` | `channelId`, `path?`, `limit?`, `nextToken?` | `{ data: Array<files_File>, nextToken }` |
+| `updateRootFolderPermissions` | `requestBody` | `handler_SuccessResponse` |
+| `createFile` | `fileType`, `requestBody` | `files_File` |
+| `deleteFile` | `id` | `api_ItemFields` |
+| `retrieveFile` | `id` | `files_File` |
+| `downloadAFile` | `id` | `Blob` |
+| `retrieveDownloadUrlOfAFile` | `id` | `files_FilePresignedDownload` |
+| `putV1FilesIdPermissions` | `id`, `requestBody` | `handler_SuccessResponse` |
+
+**FormResponses**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `requestFormResponse` | `requestBody` | `{ data: Array<forms_FormResponse> \| null, nextToken }` |
+
+**Forms**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listForms` | `limit?`, `nextToken?` | `{ data: Array<forms_Form>, nextToken }` |
+| `createForm` | `requestBody` | `forms_Form` |
+| `retrieveForm` | `id` | `forms_Form` |
+| `listFormResponses` | `id`, `status?`, `limit?`, `nextToken?` | `{ data: Array<forms_FormResponse> \| null, nextToken }` |
+
+**Installs**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listAppInstalls` | `previewAsClient?` | `Array<app_instance_AppInstall>` |
+| `retrieveAppInstall` | `installId` | `app_instance_AppInstall` |
+| `listAppConnections` | `installId`, `companyId?`, `clientId?` | `Array<appConnection_AppConnection>` |
+| `createAppConnection` | `installId`, `requestBody` | `appConnection_AppConnection` |
+| `retrieveInstallNotificationSettings` | `installId` | `app_instance_InstallNotificationSettings` |
+| `updateInstallNotificationSettings` | `installId`, `requestBody` | `app_instance_InstallNotificationSettings` |
+| `createInstallNotificationSettings` | `installId`, `requestBody` | `app_instance_InstallNotificationSettings` |
+
+**InternalUsers**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listInternalUsers` | `limit?`, `nextToken?` | `{ data: Array<api_InternalUserItem>, nextToken }` |
+| `retrieveInternalUser` | `id` | `api_InternalUserItem` |
+| `updateInternalUser` | `id`, `requestBody` | `api_InternalUserItem` |
+| `retrieveInternalUserNotificationSettings` | `id` | `notificationsettings_InternalUserNotificationSettings` |
+
+**InvoiceTemplates**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listInvoiceTemplates` | `limit?`, `nextToken?` | `{ data: Array<invoiceTemplate_InvoiceTemplate> \| null, nextToken }` |
+
+**Invoices**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listInvoices` | `clientId?`, `companyId?`, `includeCompanyInvoices?`, `subscriptionId?`, `limit?`, `nextToken?` | `{ data: Array<invoice_Invoice> \| null, nextToken }` |
+| `createInvoice` | `requestBody` | `invoice_Invoice` |
+| `retrieveInvoice` | `id` | `invoice_Invoice` |
+
+**Me**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `retrieveMe` | — | `me_MeResponse` |
+
+**MessageChannels**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listMessageChannels` | `clientId?`, `membershipEntityId?`, `companyId?`, `memberId?`, `membershipType?`, `includeUnread? = false`, `limit?`, `nextToken?` | `{ data: Array<any> \| null, nextToken }` |
+| `createMessageChannel` | `requestBody` | `messagechannel_MessageChannel` |
+| `listUnreadMessageChannels` | `userId?` | `messagechannel_UnreadSummary` |
+| `retrieveMessageChannel` | `id` | `messagechannel_MessageChannel` |
+
+**Messages**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listMessages` | `channelId`, `limit?`, `nextToken?` | `{ data: Array<messages_Message>, nextToken }` |
+| `sendMessage` | `requestBody` | `messages_Message` |
+
+**Notes**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listNotes` | `entityId?`, `entityType?`, `limit? = 20`, `nextToken?` | `{ data: Array<internal_notes_Note>, nextToken }` |
+| `createNote` | `requestBody` | `internal_notes_Note` |
+| `deleteNote` | `id` | `api_ItemFields` |
+| `retrieveNote` | `id` | `internal_notes_Note` |
+| `updateNote` | `id`, `requestBody` | `internal_notes_Note` |
+
+**Notifications**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listNotifications` | `recipientId?`, `recipientClientId?`, `recipientInternalUserId?`, `includeRead? = false`, `recipientCompanyId?`, `limit?`, `nextToken?` | `{ data: Array<notifications_Notification>, nextToken }` |
+| `createNotification` | `requestBody` | `notifications_Notification \| notifications_NotificationSuppressedResponse` |
+| `deleteNotification` | `id` | `api_DeleteItemResponse` |
+| `retrieveNotification` | `id` | `notifications_Notification` |
+| `markNotificationRead` | `id` | `notifications_Notification` |
+| `markNotificationUnread` | `id` | `notifications_Notification` |
+
+**Payments**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listPayments` | `invoiceId?`, `limit?`, `nextToken?` | `{ data: Array<payment_Payment> \| null, nextToken }` |
+
+**Prices**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listPrices` | `productId?`, `limit?`, `nextToken?` | `{ data: Array<price_Price> \| null, nextToken }` |
+| `createAPrice` | `requestBody` | `price_Price` |
+| `retrievePrice` | `id` | `price_Price` |
+
+**Products**
+
+| Method | Parameters | Returns |
 |---|---|---|
-| **Workspace** | The portal itself (one per Assembly account) | `retrieveWorkspace` |
-| **Internal user** | Staff at the business | `listInternalUsers`, `retrieveInternalUser` |
-| **Client** | A client user — represents a person, has email/name | `createClient`, `listClients`, `retrieveClient`, `updateClient`, `updateAClientDestructive`, `deleteClient` |
-| **Company** | A business that a Client belongs to (groups clients by org) | `createCompany`, `listCompanies`, `retrieveCompany`, `updateCompany`, `deleteCompany` |
-| **Custom field** | Workspace-defined extra fields on Client/Company records | `listCustomFields`, `listCustomFieldOptions` |
-| **App install** | Reference to your app + others installed in the portal | `listAppInstalls`, `retrieveAppInstall`, `listAppConnections`, `createAppConnection` |
+| `listProducts` | `name?`, `limit?`, `nextToken?` | `{ data: Array<product_Product> \| null, nextToken }` |
+| `createAProduct` | `requestBody` | `product_Product` |
+| `retrieveProduct` | `id` | `product_Product` |
+
+**Refunds**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listRefunds` | `invoiceId`, `limit?`, `nextToken?` | `{ data?: Array<refund_Refund>, nextToken }` |
+| `createRefund` | `requestBody` | `refund_Refund` |
+
+**Session**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `sessionExchange` | `requestBody` | `session_ExchangeResponse` |
+
+**SubscriptionTemplates**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listSubscriptionTemplates` | `limit?`, `nextToken?` | `{ data: Array<billing_Template> \| null, nextToken }` |
+
+**Subscriptions**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listSubscriptions` | `clientId?`, `companyId?`, `recipientId?`, `limit?`, `nextToken?` | `{ data: Array<subscription_Subscription> \| null, nextToken }` |
+| `createSubscription` | `requestBody` | `subscription_Subscription` |
+| `retrieveSubscription` | `id` | `subscription_Subscription` |
+| `cancelSubscription` | `id` | `subscription_Subscription` |
+
+**TaskTemplates**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `listTaskTemplates` | `limit?`, `nextToken?` | `{ data?: Array<marketplace_application_TaskTemplate>, nextToken }` |
+| `retrieveTaskTemplate` | `id` | `marketplace_application_TaskTemplate` |
+
+**Tasks**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `retrieveTasks` | `limit?`, `nextToken?`, `createdBy?`, `parentTaskId?`, `status?`, `clientId?`, `internalUserId?`, `companyId?` | `{ data?: Array<marketplace_application_Task>, nextToken }` |
+| `createTask` | `requestBody` | `marketplace_application_Task` |
+| `deleteTask` | `id` | `marketplace_application_Task` |
+| `retrieveTask` | `id` | `marketplace_application_Task` |
+| `updateTask` | `id`, `requestBody` | `marketplace_application_Task` |
+
+**Token**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `offlineTokenIssue` | — | `offline_IssueResponse` |
+
+**Workspaces**
+
+| Method | Parameters | Returns |
+|---|---|---|
+| `retrieveWorkspace` | — | `workspace_Workspace` |
+
+<!-- /generated -->
 
 Relationships:
 - A `Client` belongs to many `Company`s (`client.companyIds[] → Company.id`) — many-to-many; `client.companyId` is the deprecated legacy single-value field
@@ -956,10 +1212,10 @@ Method naming convention from the OpenAPI codegen:
 
 ### Confirming method names + shapes
 
-Which methods each resource has is listed in the module tables above ("What's already built in" and "The data model"); the naming convention gives their shape. **Before writing any SDK call, confirm it against the codegen types in `node_modules/@assembly-js/node-sdk/dist/codegen/api/`** — they are the source of truth, don't guess. Two files, two jobs:
+Every method, its parameter names, and its return shape are in the generated tables under "The data model"; they come from the codegen types in `node_modules/@assembly-js/node-sdk/dist/codegen/api/`, so don't guess a method that isn't listed. Read the `.d.ts` only for nested parameter shapes. Two files, two jobs:
 
-- **`index.d.ts` — the map.** Re-exports all 31 services and every model type, so it answers "does this capability exist at all?" and gives the exact service filename. Worth checking rather than guessing: the names are not always the obvious singular/plural (`FormResponsesService`, `TaskTemplatesService`, `SubscriptionTemplatesService`, `MeService`).
-- **`services/<Resource>Service.d.ts` — the signatures.** Parameters and return types live only here; `index.d.ts` has none.
+- **`index.d.ts` — the map.** Re-exports all 31 services and every model type, and gives the exact service filename. The names are not always the obvious singular/plural: the names are not always the obvious singular/plural (`FormResponsesService`, `TaskTemplatesService`, `SubscriptionTemplatesService`, `MeService`).
+- **`services/<Resource>Service.d.ts` — the nested shapes.** Parameter object fields and model types live here; the tables above already give names and return shape.
 
 The client flattens every service onto one object, so a method declared in `TasksService.d.ts` is still called as `assembly.retrieveTasks(...)`.
 
@@ -1234,7 +1490,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 1. **Read this whole file before writing any code.** Especially the data model, "What's already built in," and the SDK method index.
 2. **The middleware exchanges `?token=` (first load) for a user-scoped bearer in an HttpOnly cookie; that bearer authenticates every call.** You never handle the token.
 3. **Call `getAssembly()` — no token argument, ever.** `getAssembly()` (RSC/server actions) and `getAssemblyForRequest(req)` (route handlers) read the bearer cookie. Identity via `getSessionIdentity()` / `useAssembly()`. Never read `searchParams.token`, thread a token, or set `x-assembly-token`.
-4. **The SDK is flat: `assembly.listClients(...)`, not `assembly.clients.list()`.** `dist/codegen/api/index.d.ts` lists every service; `services/<Resource>Service.d.ts` has the parameter shapes.
+4. **The SDK is flat: `assembly.listClients(...)`, not `assembly.clients.list()`.** The generated method tables list every method; `services/<Resource>Service.d.ts` has the nested parameter shapes.
 5. **The bearer expires in 60 min; `useServerAction`/`authFetch` re-exchange it silently and retry.** You don't refresh anything or touch `AssemblyBridge.sessionToken`.
 <!-- !feature:app-owned-header -->
 6. **Use `AssemblyBridge.header.*`** for breadcrumbs/CTAs in client components. Don't render your own. (Exception: the notification surface `/n` has no header — render CTAs as inline buttons there.)

package/bin/check-paint-beacon.mjs

@@ -57,22 +57,21 @@ if (existsSync(join(ROOT, PROXY_FILE))) {
   // like 'https://*.assembly.com' in the CSP list, and dependency-free means
   // no real tokenizer.
   const proxy = readFileSync(join(ROOT, PROXY_FILE), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  // The package's proxy routes the beacon itself.
+  const usesPackageProxy = /createAssemblyProxy\s*\(/.test(proxy);
   const importsHelpers =
     /isPaintedBeaconPath/.test(proxy) && /handlePaintedBeacon/.test(proxy);
   const usesHelpers =
     /isPaintedBeaconPath\s*\(/.test(proxy) && /handlePaintedBeacon\s*\(/.test(proxy);
 
-  if (!importsHelpers || !usesHelpers) {
+  if (!usesPackageProxy && (!importsHelpers || !usesHelpers)) {
     console.error(
-      `check-paint-beacon: ${PROXY_FILE} must route the beacon's POST before CSRF/exchange:\n\n` +
-        "  import { isPaintedBeaconPath, handlePaintedBeacon } from '@assembly-js/app-foundation/client';\n" +
-        '  // …first thing in the proxy function:\n' +
-        "  if (request.method === 'POST' && isPaintedBeaconPath(request.nextUrl.pathname)) {\n" +
-        '    return handlePaintedBeacon();\n' +
-        '  }\n\n' +
+      `check-paint-beacon: ${PROXY_FILE} must route the beacon's POST before CSRF/exchange. ` +
+        'The platform sign-in proxy does this; restore it:\n\n' +
+        "  import { createAssemblyProxy } from '@assembly-js/app-foundation/server';\n" +
+        '  export const proxy = createAssemblyProxy();\n\n' +
         "sendBeacon is a headerless POST — routing it through the normal CSRF/exchange path 403s it, " +
-        'silently breaking the paint signal. POST only: a GET to the path must fall through, not ' +
-        'mint a fake painted line.',
+        'silently breaking the paint signal.',
     );
     process.exit(1);
   }