@salsita-ai/sdk 0.50.0-develop.ae52227c7e → 0.50.0-develop.aec0f535bf

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/authentication.js

@@ -0,0 +1,42 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let s=`Dealers arrive from a portal with a code; everyone else browses with retail prices:
+
+\`\`\`yaml
+# spec/session.yaml
+useAuthHook: true
+sessionData:
+  type: object
+  properties:
+    customerGroup:
+      type: string
+      enum:
+        - retail
+        - dealer
+  additionalProperties: false
+\`\`\`
+
+\`\`\`ts
+// src/webhooks/auth.ts
+export const authHandler = phx.webhooks.authHandlerBuilder
+  .withCodeHandler(async ({ accessToken }, { logger }) => {
+    const response = await fetch(\`\${phx.webhooksEnv.CRM_API_URL}/dealers/me\`, {
+      headers: { authorization: \`Bearer \${accessToken}\` },
+    })
+
+    if (!response.ok) {
+      logger.warn(\`The CRM refused the dealer token with status \${response.status}.\`)
+
+      return { success: false }
+    }
+
+    const dealer: { readonly id: string } = await response.json()
+
+    return {
+      success: true,
+      role: 'user',
+      data: { customerGroup: 'dealer' },
+      userId: dealer.id,
+    }
+  })
+  .withAnonymousHandler(async () => ({ success: true, role: 'anonymous', data: { customerGroup: 'retail' } }))
+  .build()
+\`\`\``;export const generatePhoenixWebhookAuthenticationFeature=()=>e({path:"features/webhooks/authentication.md",title:"Authentication",summary:"The auth hook: code, refresh, anonymous and Clerk flows, roles, session data and expiry; read when the configurator signs users in or treats some of them differently.",whenToUse:"Read when configurator users sign in, arrive from a host application, need different roles or prices, or when anonymous access must be refused.",capabilities:"### When the hook runs\n\n- With `useAuthHook: true` every configurator session starts with a call to the hook. Without it every configurator user gets an anonymous session and the hook never runs. Clerk sign-in needs `useClerk: true` as well, which adds the Clerk credentials to the webhook.\n- Build the hook with `phx.webhooks.authHandlerBuilder` and register it with `withAuthHook` in the [entry](entry-and-environment.md). What the browser sends picks the flow:\n  - **Code** — a host application's backend deposited its token with the platform and handed the configurator a one-time code. `withCodeHandler` receives `{ accessToken, refreshToken?, idToken? }` and decides who the configurator user is.\n  - **Refresh** — the session expired and the browser holds a refresh token an earlier answer returned. `withRefreshHandler` receives `{ refreshToken }`.\n  - **Anonymous** — neither. `withAnonymousHandler` grants or refuses a session to configurator users who are not signed in; without it their sessions fail.\n- `withClerkCodeHandler()`, `withClerkSessionHandler()` and `withClerkRefreshHandler()` add the Clerk flows, which are tried before the custom handlers. The session handler rejects banned Clerk users.\n- Under `phoenix dev` the hook has 15 seconds to answer.\n\n### What a handler returns\n\n- `{ success: false }` refuses the session. `{ success: true, role, data }` grants it:\n  - `role` — `anonymous`, `user`, `admin` or `superadmin`. The admin roles also open Project Admin.\n  - `data` — the session data, validated strictly against the spec's `sessionData` schema. The schema declares no required properties, because Admin and preset sessions carry no custom session data, so code reading it handles a missing field. Later webhook calls read it as `data.sessionPayload`, and the configurator reads it as session data. It is readable in the browser, so it never holds a credential configurator users must not see, such as an API key.\n  - `userId` — the stable id of the person, so their configurations and assistant threads follow them.\n  - `refreshToken` — returned to the browser for the refresh flow; return one only together with a refresh handler.\n  - `expirationTime` — when the session ends, as a Unix timestamp in seconds, not a duration. Leave it out: the three-hour default is what the platform's session tracking assumes, so change it only when the client needs other session lengths.\n- `withPublishedChunkScopes(({ role, data }) => [...])` grants the published-data chunk scopes a session may read; `public` is always granted. Read `docs/phoenix/publishing.mdx` before scoping chunks.",example:s,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/sessions-and-access.mdx` — sessions, roles, the session user and access to configurations.\n- `docs/phoenix/clerk-sign-in.mdx` — Clerk sign-in, its handlers and pages.\n- `docs/phoenix/integration/authentication-internal.mdx` and `authentication-external.mdx` — a host application signing its users in with a code.",phxMembers:["webhooks.authHandlerBuilder"]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/backend-data.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Backend data: the webhook handler that fetches per-session data, when it runs and how the project reads it. */
+export declare const generatePhoenixWebhookBackendDataFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/backend-data.js

@@ -0,0 +1,45 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let a=`Lead times depend on the customer group and come from the CRM:
+
+\`\`\`yaml
+# spec/backend-data.yaml
+backendData:
+  type: object
+  properties:
+    leadTimeDays:
+      type: number
+  required:
+    - leadTimeDays
+  additionalProperties: false
+\`\`\`
+
+\`\`\`ts
+// src/webhooks/backend-data.ts
+type FetchBackendData = Parameters<typeof phx.webhooks.webhookBuilder.withFetchBackendData>[0]
+
+const FALLBACK_LEAD_TIME_DAYS = 28
+
+const fetchLeadTimeDays = async (customerGroup: string): Promise<number> => {
+  const response = await fetch(\`\${phx.webhooksEnv.CRM_API_URL}/lead-times/\${customerGroup}\`, {
+    headers: { authorization: \`Bearer \${phx.webhooksEnv.CRM_API_TOKEN}\` },
+  })
+
+  if (!response.ok) {
+    throw new Error(\`The CRM answered with status \${response.status}.\`)
+  }
+
+  const { days }: { readonly days: number } = await response.json()
+
+  return days
+}
+
+export const fetchBackendData: FetchBackendData = async ({ sessionPayload }, { logger }) => {
+  try {
+    return { backendData: { leadTimeDays: await fetchLeadTimeDays(sessionPayload.customerGroup ?? 'retail') } }
+  } catch (error) {
+    // The fallback keeps the configurator and every finalization working while the CRM is down
+    logger.warn(\`Lead times are unavailable (\${String(error)}); using \${FALLBACK_LEAD_TIME_DAYS} days.\`)
+
+    return { backendData: { leadTimeDays: FALLBACK_LEAD_TIME_DAYS } }
+  }
+}
+\`\`\``;export const generatePhoenixWebhookBackendDataFeature=()=>e({path:"features/webhooks/backend-data.md",title:"Backend data",summary:"Data the webhook fetches per session, such as stock, lead times or customer prices, and how expressions and tasks read it; read when the configurator needs data only the server may fetch.",whenToUse:"Read when a value depends on who is configuring or changes faster than published content, and fetching it needs a credential the browser must not see.",capabilities:"### When it runs\n\n- Declare a `backendData` schema; without one the configurator never asks for backend data. Register the handler with `withFetchBackendData` in the [entry](entry-and-environment.md).\n- The configurator asks for it when it loads and again whenever its frontend data changes, and the webhook runs the handler again before every [finalization](finalization.md). The two answers can differ, and finalization uses its own.\n- A failure in the browser's request leaves backend data `undefined` and the configurator keeps running, so expressions handle `undefined`. A failure before finalization fails the finalization: catch what may fail and return a safe value when one exists.\n- Under `phoenix dev` the handler has 15 seconds to answer, and an answer above 5 MiB is refused.\n\n### What it receives and returns\n\n- The handler receives `{ sessionRole, sessionPayload, frontendData, frontendUrl, deploymentId }` and the `logger`, and returns `{ backendData }`, validated against the schema.\n- Backend data is readable in the browser. Fetch with the credentials in the webhook and return only what the configurator may show.\n- Expressions read it as `ctx.backendData` ([Expressions](../domain-model/expressions.md)) and webhook tasks as `data.backendData`. Both are `Record<string, unknown> | undefined`: the schema validates the handler's answer but does not type what reads it, so narrow each value before use.\n- Choose backend data for values that depend on who is configuring or change too often to publish: stock, lead times, customer prices. Published data suits catalogue content, frontend data what the embedding page passes in.",example:a,documentation:"Read `docs/phoenix/data-sources.mdx` with `pnpm phoenix docs -r docs/phoenix/data-sources.mdx` for every data source and its lifetime; its backend data section shows the frontend side.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/entry-and-environment.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The webhook entry, which project code joins the webhook, and its environment variables. */
+export declare const generatePhoenixWebhookEntryFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/entry-and-environment.js

@@ -0,0 +1,38 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A quote configurator reads its CRM and integration credentials from the environment and registers the hooks the other webhook guides implement:
+
+\`\`\`yaml
+# spec/webhook-env.yaml
+env:
+  webhook:
+    CRM_API_URL:
+      type: url
+      required: true
+      devDefault: http://localhost:4000
+    CRM_API_TOKEN:
+      type: str
+      required: true
+    QUOTE_SENDER:
+      type: str
+      default: quotes@example.com
+    WOOCOMMERCE_SHOP_URL:
+      type: url
+    WOOCOMMERCE_API_KEY:
+      type: str
+    QUOTES_SPREADSHEET_ID:
+      type: str
+    GOOGLE_SERVICE_ACCOUNT_JSON:
+      type: str
+\`\`\`
+
+\`\`\`ts
+// src/webhooks/index.ts
+import { authHandler } from './auth.js'
+import { fetchBackendData } from './backend-data.js'
+import { quoteFinalization } from './finalization.js'
+
+export default phx.webhooks.webhookBuilder
+  .withAuthHook(authHandler)
+  .withFetchBackendData(fetchBackendData)
+  .withConfiguratorFinalize(quoteFinalization)
+  .build()
+\`\`\``;export const generatePhoenixWebhookEntryFeature=()=>e({path:"features/webhooks/entry-and-environment.md",title:"Webhook entry and environment",summary:"`src/webhooks/index.ts`, which project code runs on the server, browser-import limits and `env.webhook` variables; read when creating the webhook, adding server code or a secret, or fixing a webhook parse or build error.",whenToUse:"Read when the project needs server-side code — sign-in, backend data, finalization — or a credential, or when parsing or the build names a webhook file.",capabilities:"### The entry\n\n- The webhook is the project's server side: one bundle the platform calls for sign-in, backend data, finalization and its callback, Admin publishing and assistant setup. A deployed environment runs it as a cloud function; `phoenix dev` runs it on the developer's machine through the development tunnel.\n- `src/webhooks/index.ts` is the entry and default-exports `phx.webhooks.webhookBuilder` with its hooks, then `.build()`. Only that file is imported; other files in `src/webhooks/` run when it imports them. Files in `src/webhooks/` without an `index.ts` fail with `MISSING_WEBHOOK_INDEX`.\n- The builder takes `withAuthHook` ([Authentication](authentication.md)), `withFetchBackendData` ([Backend data](backend-data.md)) and `withConfiguratorFinalize` ([Finalization](finalization.md)). Register only what the project uses. The SDK adds [Admin publishing](publishing.md) itself, and [assistant setup](assistant-setup.md) when the spec configures the assistant.\n- Without an entry the SDK builds a webhook that signs every configurator user in anonymously. `useAuthHook: true` or `useClerk: true` without an entry reports `AUTH_WITHOUT_PROJECT_WEBHOOK`.\n- A hook that throws answers with an error: the sign-in, the finalization or the publish fails. Its message reaches the server log, not the configurator user, so log what went wrong with the `logger` each hook receives.\n\n### Project code in the webhook\n\n- The spec's domain, expressions and invariants also run in the webhook. Action modules load in its shared domain assembly, but action implementations currently execute only in the browser, including assistant custom mutations. Components, admin components and handlers are frontend-only by default.\n- A handler module that calls `phx.domain.createAssistantSetupHandler` or one of the `phx.domain.admin` publishing and validation factories joins the webhook automatically. The call is detected literally, so do not alias it.\n- Make `'use webhook'` the first statement of another component or handler the server needs, such as one that prepares the scene for server rendering. Leading comments may precede it.\n- An included file and every local file it imports must not import the browser SDK entry points (`admin`, `application`, `configurator`, `editor`, `react`, `ui`, `extras/clerk`) or style, font and image files. Type-only imports are allowed. For files included by `'use webhook'` or a detected handler registration, parsing reports `WEBHOOK_UNSAFE_IMPORT` with the import chain; action modules are not covered by that parse-time check. Unsafe action imports can fail when the webhook is built or loaded. Move logic both sides need into a module without them, and keep rendering in a frontend-only file.\n\n### Environment variables and secrets\n\n- Declare variables under `env.webhook`: `type` is `bool`, `str`, `num` or `url`, with an optional `default`, `devDefault` (the value under `phoenix dev`) and `required`. A variable that is neither required nor defaulted is `undefined` when unset. Read them as `phx.webhooksEnv.NAME`.\n- Values are fixed when the webhook is built: a changed value needs a restart of `phoenix dev` locally and a new deploy on an environment. Deployed builds take values from the environment variables a workspace or project Superadmin sets in Studio; `phoenix dev` takes them from `.env`, which is not committed.\n- Keep credentials in the webhook. Session data, backend data and the finalization result all reach the browser, and `env.frontend` values are public.\n- `budgets.webhookGzipMb` fails the build when the compressed webhook grows past it; `phoenix build --onlyWebhook` builds the webhook alone.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/webhooks.mdx` — the entry, the built-in webhook and environment variables.\n- `docs/phoenix/webhook-membership.mdx` — which files join the webhook and the server-safe import rule.\n- `docs/phoenix/sdk-builder-workflow.mdx` — setting environment variables in Studio.",phxMembers:["webhooks.webhookBuilder"]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/finalization.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Configurator finalization: the pipeline, task data and context, prefetch, resources, execution order and failure. */
+export declare const generatePhoenixWebhookFinalizationFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/finalization.js

@@ -0,0 +1,92 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A quote request declares what the configurator sends, the quote number computed once, the callback's data and result, and the resources the tasks produce:
+
+\`\`\`yaml
+# spec/finalization.yaml
+finalizeData:
+  type: object
+  properties:
+    email:
+      type: string
+    views:
+      type: array
+      items:
+        type: string
+    cartSession:
+      type: string
+    addToCartUrl:
+      type: string
+  additionalProperties: false
+prefetchedFinalizeData:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+  required:
+    - quoteNumber
+  additionalProperties: false
+callbackData:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+  required:
+    - quoteNumber
+  additionalProperties: false
+finalizeResult:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+    pdfUrl:
+      type: string
+    shareUrl:
+      type: string
+  required:
+    - quoteNumber
+    - pdfUrl
+    - shareUrl
+  additionalProperties: false
+resources:
+  - type: ConfigurationLink
+    name: shareLink
+  - type: Image
+    name: studioRender
+    s3Key: studio-render.png
+  - type: Pdf
+    name: quotePdf
+    s3Key: quote.pdf
+  - type: Csv
+    name: quoteCsv
+    s3Key: quote.csv
+\`\`\`
+
+\`\`\`ts
+// src/webhooks/finalization.ts
+import { quoteCallback } from './tasks/callback.js'
+import { quoteCsvTask, quotePdfTask } from './tasks/documents.js'
+import { quoteEmailTask } from './tasks/email.js'
+import { cartTask, crmQuoteTask, quoteSheetTask } from './tasks/integrations.js'
+import { shareLinkTask, studioRenderTask } from './tasks/links-and-images.js'
+import { viewRenderResources, viewRendersTask } from './tasks/view-renders.js'
+
+const quoteNumber = phx.webhooks.prefetchBuilder
+  .withPrefetchHandler(data => ({ quoteNumber: \`Q-\${data.revisionId}\` }))
+  .build()
+
+export const quoteFinalization = phx.webhooks.finalizeHandlerBuilder
+  .withPrefetch(quoteNumber)
+  .withResources(viewRenderResources)
+  .withTask(shareLinkTask)
+  .withTask(studioRenderTask)
+  .withTask(viewRendersTask)
+  .withTask(quotePdfTask)
+  .withTask(quoteCsvTask)
+  .withTask(quoteEmailTask)
+  .withTask(crmQuoteTask)
+  .withTask(cartTask)
+  .withTask(quoteSheetTask)
+  .withCallback(quoteCallback)
+  .build()
+\`\`\`
+
+The quote number derives from the revision, so a retried request produces the same number. The view renders, the cart and the spreadsheet row skip themselves when their input or credentials are missing, so one handler serves every finalize action.`;export const generatePhoenixWebhookFinalizationFeature=()=>e({path:"features/webhooks/finalization.md",title:"Finalization",summary:"The finalize handler: how tasks are built and connected through resources, what each task receives, prefetch, the order the platform runs tasks in and what happens when one fails; read when implementing what happens after the configurator finalizes.",whenToUse:"Read when a finalize action has to produce something on the server — a link, a render, a PDF, an email, an order — or when a finalization fails.",capabilities:"### The pipeline\n\n- The configurator saves the configuration, uploads its configurator-rendered images and asks the platform to finalize the latest saved revision. Its handler then waits with `waitForFinalizationToComplete`, whose default timeout of 30 seconds is too short for a server render: pass a longer `pollingTimeout`. [Finalization actions](../custom-layout/finalization-actions.md) owns that side.\n- The webhook runs [backend data](backend-data.md) again, rebuilds the domain from the saved state and refuses to finalize while a `warning` violation remains. It then runs the prefetch, collects the tasks and resources and hands them to the platform, which runs them. Under `phoenix dev` this part has 60 seconds.\n- Build it with `phx.webhooks.finalizeHandlerBuilder`: `withPrefetch` once, `withTask` per task, `withResources` for resources known only at runtime, `withCallback` once, then `build()`. Register the result with `withConfiguratorFinalize` in the [entry](entry-and-environment.md).\n\n### Tasks\n\n- Build each task with `phx.webhooks.taskFactory.create<Type>Task((resources, data, ctx) => task)`, one factory per task type in [Finalization tasks](tasks/index.md). Return the task, several tasks, or `null` to skip it for this request.\n- `resources` holds the names declared under `resources:`, typed, so a misspelled name does not compile.\n- `data` holds `configurationId`, `revisionId`, `deploymentId`, `frontendUrl`, `state`, `finalizeData` (what the configurator sent, validated against the `finalizeData` schema), `sessionRole`, `sessionPayload`, `publishedData`, `frontendData`, `backendData` and `prefetchedData`.\n- `ctx` holds `domain` (`ctx.domain.getRoot$Entity(data.state)` reads the configured product), `resolveLocalizable` and `i18n` in the request's locale, `getPublicAssetUrl` for files under `assets/public/`, `blenderProjections`, the `pdfTaskBuilder` and `emailTaskBuilder`, and `logger`.\n- `phx.webhooks.prefetchBuilder.withPrefetchHandler((data, ctx) => values)` computes once what several tasks need, such as a quote number. The `prefetchedFinalizeData` schema types it, and tasks read it as `data.prefetchedData`.\n\n### Resources\n\n- Tasks connect through named resources: one task produces a resource under its name, others include it. Declare them under `resources:` as `ConfigurationLink`, `Pdf`, `Csv` or `Image`; an `Image` is rendered on the server (`s3Key`), rendered by the configurator (`clientGenerated: true` with `s3Key`) or an existing file (`exists: true` with `url`).\n- Finalization fails when a declared resource has no task producing it, a name repeats or a task includes an undeclared resource.\n- Images of `clientSideImage` components are declared automatically; tasks name them by entity id and instance name.\n\n### Order and failure\n\n- The platform runs tasks by type, not in `withTask` order: links and server renders first, then CSVs, PDFs, emails, HTTP requests, WooCommerce and Google Sheets, and the [callback](tasks/callback.md) last. Tasks of one type run in parallel, except server renders, which queue one at a time. A PDF or email can use the links and renders, and an email can attach the PDFs and CSVs.\n- A generated PDF or CSV is stored, and so reachable by a link, only when the same finalization has a callback or WooCommerce task.\n- Nothing is retried or rolled back. When a task fails the finalization fails, and what already ran stays done. The configurator learns only that it failed; the cause is in the platform's logs, out of the project's reach. Try each task with test data first.\n- Tasks run on the platform even under `phoenix dev`: emails are sent and requests made. Use test recipients and endpoints until the client authorizes real ones.\n- The configurator receives the callback's result; without a callback it receives nothing.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/finalization.mdx` — the finalization flow, its data schemas and the configurator side.\n- `docs/phoenix/webhooks.mdx` — the finalize payload, task context and every task type.\n\nThe [Finalization](../../processes/finalization.md) process covers agreeing the journey with the client.",phxMembers:["webhooks.finalizeHandlerBuilder","webhooks.prefetchBuilder","webhooks.taskFactory"]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/index.d.ts

@@ -0,0 +1 @@
+export * from './webhooks.js';

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/index.js

@@ -0,0 +1 @@
+export*from"./webhooks.js";

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/publishing.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Admin publishing: the SDK-built Admin finalization, the publish tasks and the project's mapping and validation handlers. */
+export declare const generatePhoenixPublishingFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/publishing.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";export const generatePhoenixPublishingFeature=()=>e({path:"features/webhooks/publishing.md",title:"Admin publishing",summary:"What publishing in Project Admin runs in the webhook: the `PublishRevision` tasks, mapping admin entities to published data and validating data rows and sheets; read when admin content has to reach the configurator.",whenToUse:"Read when the project has Project Admin content to publish, maps its own admin entities into published data, or validates manual or connected data before publishing.",capabilities:"### What publishing runs\n\n- Publishing in Project Admin runs the webhook's Admin finalization, which the SDK builds itself: `phx.webhooks` has no builder for it and the [entry](entry-and-environment.md) registers nothing.\n- Without published-data chunks it produces one `PublishRevision` task with the whole published data. With chunks it produces `PublishRevisionChunksStaged`, which uploads the chunks first and takes up to 100 MiB, or `PublishRevisionChunks` with the chunks inline where the platform offers no upload.\n- Presets, preset categories, recipes and swatch options are published without project code. A project maps its own admin entities with a handler.\n\n### Project handlers\n\nDefault-export each from a file in `src/handlers/`. These files join the webhook automatically, so they import only server-safe modules. Only the first handler of each kind counts.\n\n- `phx.domain.admin.createMapPublishedRevisionDataHandler(({ entities, adminEntity }) => data)` — the published data, without chunks.\n- `phx.domain.admin.createMapPublishedChunkedDataHandler(({ entities, adminEntity, connectedSheetData }) => chunks)` — per-chunk data spread over what the SDK generates; `connectedSheetData` holds the rows of connected spreadsheets during publishing.\n- `phx.domain.admin.createDataRowValidatorHandler` and `createSheetValidatorHandler` — business rules for manual and connected data, returning messages with `severity` `error` or `warning`. They run in Admin's verify dialog and again when publishing, where an `error` stops the publish and a `warning` does not. Keep them synchronous and pure.\n\n### Reaching the configurator\n\n- The configurator reads published data as `publishedData` in expressions and tasks. A session reads the `public` chunk and the scopes [authentication](authentication.md) grants with `withPublishedChunkScopes`.\n- Published data belongs to the environment and outlives deploys. Check the configurator against freshly published data after a deploy that changes the published-data schema.",example:'A catalogue maps its visible custom materials into the `catalog` chunk, and a row validator rejects a material without a price before it is published. The complete handler is the "Custom Mapping Handler" of `docs/phoenix/publishing.mdx`, and the validators are under "Custom Validation Handlers" in `docs/phoenix/connected-data-sources.mdx`; both depend on the project\'s admin model and data entries, so start from them rather than a copy.',documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/publishing.mdx` — chunks, scopes, the publish flow and the mapping handler.\n- `docs/phoenix/connected-data-sources.mdx` — connected spreadsheets and the validators.\n- `docs/phoenix/admin.mdx` — Project Admin and its model.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/callback.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** The finalization callback: the CallLambdaBack task and the result the configurator receives. */
+export declare const generatePhoenixCallbackFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/callback.js

@@ -0,0 +1,26 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let a=`The quote result gives the configurator the quote number, the PDF to download and the share link:
+
+\`\`\`ts
+// src/webhooks/tasks/callback.ts
+export const quoteCallback = phx.webhooks.callbackBuilder
+  .withCallbackData((resources, data) => ({
+    replayData: { quoteNumber: data.prefetchedData.quoteNumber },
+    resources: {
+      [resources.quotePdf]: { embeddingType: 'Link' },
+      [resources.shareLink]: { embeddingType: 'Link' },
+    },
+  }))
+  .withCallbackHandler(async ({ replayData, resources }) => {
+    const pdfUrl = resources.quotePdf?.link
+    const shareUrl = resources.shareLink?.link
+
+    if (pdfUrl === undefined || shareUrl === undefined) {
+      throw new Error(
+        \`Quote \${replayData.quoteNumber} finished without its PDF or share link. Check the PDF and link tasks of this finalization.\`
+      )
+    }
+
+    return { quoteNumber: replayData.quoteNumber, pdfUrl, shareUrl }
+  })
+  .build()
+\`\`\``;export const generatePhoenixCallbackFeature=()=>e({path:"features/webhooks/tasks/callback.md",title:"Callback and result",summary:"`callbackBuilder` and its `CallLambdaBack` task: links to the generated files and the result the configurator receives; read when the configurator shows, downloads or forwards what finalization produced.",whenToUse:"Read when the configurator needs something back from finalization — a download, a quote number, a link to redirect to — or when the produced files must reach another system.",capabilities:"### How it works\n\n- Build the callback with `phx.webhooks.callbackBuilder`: `withCallbackData` chooses what to carry over and which resources to receive, `withCallbackHandler` turns them into the result, then `build()`. Register it with `withCallback` on the [finalize handler](../finalization.md), once.\n- `withCallbackData((resources, data, ctx) => ({ replayData, resources }))` runs with the other tasks. `replayData` follows the `callbackData` schema; `resources` maps each resource to receive to `{ embeddingType: 'Link' }`. It adds a `CallLambdaBack` task, which the platform runs last.\n- The platform then calls the webhook again with `{ replayData, resources }`, where each resource is `{ type: 'Link', link }`. The handler's return value is the finalization result, typed by the `finalizeResult` schema but not checked at runtime.\n- The configurator receives that result from `waitForFinalizationToComplete`. Without a callback it receives nothing, so a download or a redirect needs one.\n\n### Links and limits\n\n- File links are signed and expire after 30 minutes: hand them to the configurator user to open now, not to keep. A configuration link stays valid for its own `expiration`.\n- Only resources stored by the platform can be passed: generated PDFs, CSVs and images with an `s3Key`, and configuration links. An `exists` image with a `url` cannot.\n- The callback runs after everything else, so a throw fails a finalization whose emails and requests already went out. Check what the handler needs and fail with a message saying which resource is missing.\n- The handler is the place to send the links to another system, for example posting the PDF link to a partner's endpoint with a credential from `phx.webhooksEnv`.\n- Under `phoenix dev` the callback returns through the development tunnel, so `phoenix dev` must still be running when the tasks finish.",example:a,documentation:"Read `docs/phoenix/finalization.mdx` with `pnpm phoenix docs -r docs/phoenix/finalization.mdx` for the callback and result schemas and the configurator side. `docs/phoenix/integration/finalization-internal.mdx` sends a partner the links from the callback.",phxMembers:["webhooks.callbackBuilder"]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/documents.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Generated PDF and CSV documents. */
+export declare const generatePhoenixDocumentsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/documents.js

@@ -0,0 +1,51 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`A quote PDF with the share link and the studio render, numbered pages and a draft watermark, and a one-row CSV for the sales team:
+
+\`\`\`tsx
+// src/webhooks/tasks/documents.tsx
+import { PdfHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+export const quotePdfTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return ctx.pdfTaskBuilder
+    .withResourceName(resources.quotePdf)
+    .withFormat('A4')
+    .withMargin({ top: '24mm', bottom: '20mm', left: '16mm', right: '16mm' })
+    .withIncludedResources({
+      other: [
+        { type: 'ConfigurationLink', name: resources.shareLink },
+        { type: 'Image', name: resources.studioRender, embeddingType: 'Link' },
+      ],
+    })
+    .withReactBody(
+      <main style={{ fontFamily: 'Georgia, serif' }}>
+        <img src={ctx.getPublicAssetUrl('pdf/logo.png')} alt="" width={96} />
+        <h1>Quote {data.prefetchedData.quoteNumber}</h1>
+        <ResourceHelpers.Image resource={resources.studioRender} alt={chair.label} style={{ width: '100%' }} />
+        <p>
+          {chair.label}, {chair.finish}, {chair.width} cm wide
+        </p>
+        <ResourceHelpers.Link resource={resources.shareLink}>Open your configuration</ResourceHelpers.Link>
+      </main>
+    )
+    .withReactFooter(
+      <div style={{ fontSize: '8pt', textAlign: 'center', width: '100%' }}>
+        <PdfHelpers.PageNumber /> / <PdfHelpers.TotalPages />
+      </div>,
+      { height: '12mm', startAt: 1 }
+    )
+    .withWatermarkText('DRAFT')
+    .build()
+})
+
+export const quoteCsvTask = phx.webhooks.taskFactory.createGenerateCsvTask((resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'GenerateCsv',
+    name: resources.quoteCsv,
+    columns: ['quote', 'model', 'finish', 'width'],
+    data: [{ quote: data.prefetchedData.quoteNumber, model: chair.label, finish: chair.finish, width: chair.width }],
+  }
+})
+\`\`\``;export const generatePhoenixDocumentsFeature=()=>e({path:"features/webhooks/tasks/documents.md",title:"PDF and CSV documents",summary:"`GenerateStaticPdf` through `ctx.pdfTaskBuilder` with React templates, headers, footers and watermarks, legacy `GeneratePdf`, and `GenerateCsv`; read when finalization produces a document.",whenToUse:"Read when finalization produces a summary, quote or specification PDF, or a CSV for a spreadsheet or another system.",capabilities:"### PDF\n\n- Build a PDF with `ctx.pdfTaskBuilder` inside `createGeneratePdfTask`, in this order: `withResourceName` with a declared `Pdf` resource, then optionally `withLocale`, `withFormat` (A4 by default), `withMargin` and `withIncludedResources`, an optional header, `withReactBody` or `withHtmlBody`, an optional footer and an optional watermark, then `build()`. It produces a `GenerateStaticPdf` task, rendered from the HTML by the platform's print engine.\n- Show included resources with `ResourceHelpers.Link`, `ResourceHelpers.Image` and `ResourceHelpers.ClientSideImage` from `@salsita-ai/sdk/webhook`. Declare each with `withIncludedResources` first, or rendering throws. An image declared with `embeddingType: 'Link'` loads from a signed URL valid for 30 minutes; `'Embedded'` inlines it.\n- `withReactHeader` and `withReactFooter` take the band's `height` and the page it `startAt`. `PdfHelpers.PageNumber`, `TotalPages`, `Date`, `Title` and `Url` work only there and throw in the body.\n- Load logos, fonts and other files under `assets/public/` with `ctx.getPublicAssetUrl(path)`.\n- `withWatermarkText`, `withWatermarkImage` and `withWatermarkResourceImage` mark every page, such as a draft whose prices are still provisional.\n- `GeneratePdf` is the legacy form: a Handlebars template with `{{resource-<name>}}` placeholders. New projects use the builder.\n\n### CSV\n\n- `GenerateCsv` writes `columns` and `data` rows, objects keyed by column, under a declared `Csv` resource. `header` defaults to true, `delimiter` to a comma and `bom` to true, so spreadsheet applications detect UTF-8.\n- Resolve localizable text with `ctx.resolveLocalizable` before it becomes a cell.\n\n### Using the files\n\n- An email attaches the PDFs and CSVs of the same finalization ([Email](email.md)). A link to one, in a callback result or another document, works only when the finalization has a callback or WooCommerce task ([Finalization](../finalization.md)).",example:t,documentation:"Read `docs/phoenix/webhooks.mdx` with `pnpm phoenix docs -r docs/phoenix/webhooks.mdx` for the complete PDF template and every builder method. `docs/phoenix/localization.mdx` covers translated PDF text.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/email.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Emails sent by finalization. */
+export declare const generatePhoenixEmailFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/email.js

@@ -0,0 +1,38 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`The quote email, sent only when the configurator user entered an address, with the PDF and the render attached:
+
+\`\`\`tsx
+// src/webhooks/tasks/email.tsx
+import { ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+const EMAIL_ADDRESS = /^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$/
+
+export const quoteEmailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data, ctx) => {
+  const { email } = data.finalizeData
+
+  if (email === undefined || !EMAIL_ADDRESS.test(email)) {
+    return null
+  }
+
+  const { quoteNumber } = data.prefetchedData
+
+  return ctx.emailTaskBuilder
+    .withSender({ from: phx.webhooksEnv.QUOTE_SENDER })
+    .withRecipients({ to: email })
+    .withSubject(\`Your quote \${quoteNumber}\`)
+    .withBodyResources({ other: [{ type: 'ConfigurationLink', name: resources.shareLink }] })
+    .withReactBody(
+      <div style={{ fontFamily: 'Arial, sans-serif', maxWidth: 600 }}>
+        <img src={ctx.getPublicAssetUrl('email/logo.png')} alt="" width={120} />
+        <p>Your quote {quoteNumber} and a picture of your chair are attached.</p>
+        <ResourceHelpers.Link resource={resources.shareLink}>Open your configuration</ResourceHelpers.Link>
+      </div>
+    )
+    .withAttachments({
+      other: [
+        { type: 'resource', filename: \`\${quoteNumber}.pdf\`, resource: resources.quotePdf },
+        { type: 'resource', filename: 'chair.png', resource: resources.studioRender },
+      ],
+    })
+    .build()
+})
+\`\`\``;export const generatePhoenixEmailFeature=()=>e({path:"features/webhooks/tasks/email.md",title:"Email",summary:"`SendStaticEmail` through `ctx.emailTaskBuilder` with React bodies, links and attachments, images that survive mail clients, and legacy `SendEmail`; read when finalization sends an email.",whenToUse:"Read when finalization sends the configurator user, the client or a sales team an email.",capabilities:"### Building an email\n\n- Build an email with `ctx.emailTaskBuilder` inside `createSendEmailTask`, in this order: `withSender({ from, replyTo? })`, `withRecipients({ to, cc?, bcc? })` with comma-separated addresses, an optional `withLocale`, `withSubject`, an optional `withBodyResources`, `withReactBody` or `withHtmlBody`, an optional `withPlainTextBody` and `withAttachments`, then `build()`. It produces a `SendStaticEmail` task; a React body also yields its plain-text part.\n- Return `null` when this request sends nothing, such as a download without an email address. Check an address from `data.finalizeData` before sending to it.\n- Links and images in the body use `ResourceHelpers` from `@salsita-ai/sdk/webhook` and must be declared with `withBodyResources` first. `EmailHelpers.HtmlOnly` and `EmailHelpers.TextOnly` show content in only one of the two parts.\n- `withAttachments` attaches the PDFs, CSVs and images of the same finalization by resource name, configurator-rendered images by entity id and instance name, and any file as base64.\n- `SendEmail` is the legacy form with a Handlebars template. New projects use the builder.\n\n### Images in the body\n\n- Mail clients drop `data:` images, and a configurator-rendered image in the body is inlined as one. A rendered resource shown by link loads from a signed URL that expires after 30 minutes.\n- So attach the product images and the PDF, and load the logo and other fixed images from `assets/public/` with `ctx.getPublicAssetUrl(path)`, in versions made for the email's background.\n\n### Sending\n\n- The platform's mail service sends from `from`. Agree the sender address with the client and confirm a test email arrives before relying on it.\n- Emails go out even under `phoenix dev`. Send to the client's own address, and to configurator users only once the client authorizes it.",example:t,documentation:"Read `docs/phoenix/webhooks.mdx` with `pnpm phoenix docs -r docs/phoenix/webhooks.mdx` for the complete email template and every builder method. `docs/phoenix/localization.mdx` covers translated subjects and bodies.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/index.d.ts

@@ -0,0 +1 @@
+export * from './tasks.js';

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/index.js

@@ -0,0 +1 @@
+export*from"./tasks.js";

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/integrations.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Finalization tasks that reach other systems: HTTP requests, WooCommerce carts and Google Sheets. */
+export declare const generatePhoenixIntegrationsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/integrations.js

@@ -0,0 +1,88 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`The quote goes to the CRM, a cart when the configurator runs in the shop, and a row in the sales spreadsheet, each skipped when it does not apply:
+
+\`\`\`ts
+// src/webhooks/tasks/integrations.ts
+export const crmQuoteTask = phx.webhooks.taskFactory.createSendHttpRequestTask((_resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'SendHttpRequest',
+    url: \`\${phx.webhooksEnv.CRM_API_URL}/quotes\`,
+    method: 'POST',
+    headers: { authorization: \`Bearer \${phx.webhooksEnv.CRM_API_TOKEN}\`, 'content-type': 'application/json' },
+    body: JSON.stringify({
+      quoteNumber: data.prefetchedData.quoteNumber,
+      configurationId: data.configurationId,
+      model: chair.label,
+      finish: chair.finish,
+    }),
+  }
+})
+
+export const cartTask = phx.webhooks.taskFactory.createWooCommerceAddToCartTask((resources, data, ctx) => {
+  const { cartSession, addToCartUrl } = data.finalizeData
+  const shopUrl = phx.webhooksEnv.WOOCOMMERCE_SHOP_URL
+  const apiKey = phx.webhooksEnv.WOOCOMMERCE_API_KEY
+
+  if (cartSession === undefined || addToCartUrl === undefined || shopUrl === undefined || apiKey === undefined) {
+    return null
+  }
+
+  // The platform sends the API key to this URL, so it may only point at the shop
+  const cartEndpoint = new URL(addToCartUrl, shopUrl)
+
+  if (cartEndpoint.origin !== new URL(shopUrl).origin) {
+    throw new Error(
+      \`The add-to-cart URL \${addToCartUrl} is not on the shop \${shopUrl}. Pass the plugin's add-to-cart-url unchanged.\`
+    )
+  }
+
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'WooCommerceAddToCart',
+    session: cartSession,
+    addToCartUrl: cartEndpoint.href,
+    apiKey,
+    items: [
+      {
+        product: 'custom-chair',
+        productName: chair.label,
+        productDescription: \`\${chair.finish}, \${chair.width} cm\`,
+        quantity: 1,
+        image: resources.studioRender,
+        resources: [{ type: 'Pdf', name: resources.quotePdf, label: 'Quote' }],
+      },
+    ],
+  }
+})
+
+export const quoteSheetTask = phx.webhooks.taskFactory.createEditGoogleSpreadsheetTask((resources, data, ctx) => {
+  const spreadsheetId = phx.webhooksEnv.QUOTES_SPREADSHEET_ID
+  const serviceAccount = phx.webhooksEnv.GOOGLE_SERVICE_ACCOUNT_JSON
+
+  if (spreadsheetId === undefined || serviceAccount === undefined) {
+    return null
+  }
+
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'EditGoogleSpreadsheet',
+    credentials: JSON.parse(serviceAccount),
+    spreadsheetId,
+    edits: [
+      {
+        mode: 'append',
+        ranges: {
+          'Quotes!A:D': [
+            [data.prefetchedData.quoteNumber, chair.label, chair.width, { type: 'ConfigurationLink', name: resources.shareLink }],
+          ],
+        },
+      },
+    ],
+  }
+})
+\`\`\`
+
+The [finalize handler](../finalization.md) registers each with \`.withTask\`.`;export const generatePhoenixIntegrationsFeature=()=>e({path:"features/webhooks/tasks/integrations.md",title:"HTTP, WooCommerce and Google Sheets",summary:"`SendHttpRequest`, `WooCommerceAddToCart`, `EditGoogleSpreadsheet` and the generic `createTask`; read when finalization sends the configuration to another system.",whenToUse:"Read when finalization posts to a CRM or ERP, adds the configuration to a WooCommerce cart or records it in a Google spreadsheet. Agree with the client before connecting a live system.",capabilities:"### HTTP request\n\n- `SendHttpRequest` sends `url` with `method` (`GET` by default), `headers` and a string `body` from the platform, after the emails. A body needs a method other than `GET`.\n- An answer outside 2xx fails the finalization. There is no timeout and no retry, and a request already sent is not undone, so make the receiving endpoint tolerate a repeated quote number.\n- The request carries no generated files. When the other system needs the PDF or a link, send it from the [callback](callback.md) handler, which receives their links, or let the other system fetch them.\n\n### WooCommerce cart\n\n- `WooCommerceAddToCart` adds `items` and optional `fees` to the shopper's cart through the Phoenix WordPress plugin. An item has a `product`, and optionally `productName`, `productDescription`, `price`, `quantity`, `customData`, an `image` given as the name of a declared `Image` resource, and `resources` listed in the order as `{ type, name, label }`.\n- The plugin gives the configurator tag an encrypted `session` and an `add-to-cart-url` relative to the shop; pass both unchanged in the finalize data. `apiKey` is the key configured in the plugin, kept in a webhook variable.\n- The platform sends the API key to `addToCartUrl`, and the finalize data comes from the browser. Build the absolute URL in the webhook from the shop's URL in a webhook variable, and refuse any other origin, or anyone could have the key sent to a server of their choosing.\n\n### Google Sheets\n\n- `EditGoogleSpreadsheet` appends rows to, or overwrites, ranges of a spreadsheet with a service account: `credentials` is the parsed service-account key, `spreadsheetId` the id from its URL, and each edit maps A1 ranges to rows with `mode` `append` or `overwrite`.\n- Share the spreadsheet with the service account's email. Cells take strings, numbers, booleans and `{ type: 'ConfigurationLink', name }`, and are written exactly as given.\n\n### Any task\n\n- `phx.webhooks.taskFactory.createTask` accepts a handler returning any task type the project can build, for one handler that returns different kinds of tasks.\n- Keep each credential in a webhook variable ([Webhook entry and environment](../entry-and-environment.md)). The platform keeps a task's fields with its job record, also after the job finishes, so prefer keys scoped to the one integration.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/webhooks.mdx` — the task fields of each integration.\n- `docs/integrations/woocommerce/overview.mdx` — the WordPress plugin, the attributes it passes and its API key.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/links-and-images.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Configuration links, server-rendered images and resources declared at runtime. */
+export declare const generatePhoenixLinksAndImagesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/links-and-images.js

@@ -0,0 +1,68 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`A share link frozen at the finalized revision, valid for 30 days, and a studio render of the configured chair:
+
+\`\`\`ts
+// src/webhooks/tasks/links-and-images.ts
+export const shareLinkTask = phx.webhooks.taskFactory.createGenerateConfigurationLinkTask((resources, data) => ({
+  type: 'GenerateConfigurationLink',
+  name: resources.shareLink,
+  frontendUrl: data.frontendUrl,
+  configurationId: data.configurationId,
+  revisionId: data.revisionId,
+  access: 'rr',
+  expiration: 30 * 24,
+}))
+
+export const studioRenderTask = phx.webhooks.taskFactory.createGenerateImagesTask((resources, data, ctx) => {
+  const view = ctx.blenderProjections.getBlenderImageConfig(data.state, 'Studio', data.state.rootEntityId, {
+    width: 1600,
+    height: 1200,
+  })
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'blender/studio.blend',
+    templateFiles: ['models/chair.glb'],
+    images: [{ name: resources.studioRender, fileFormat: 'PNG', ...view }],
+  }
+})
+\`\`\`
+
+One render per view ticked in the finalize form, each view an export state, declared at runtime and produced by one task:
+
+\`\`\`ts
+// src/webhooks/tasks/view-renders.ts
+// The views the finalize form offers, each an export state; finalize data comes from the browser, so keep only these
+const VIEWS = ['Front', 'Side', 'Top']
+const renderName = (view: string) => \`view-\${view}\`
+const selectedViews = (views: readonly string[] | undefined) => VIEWS.filter(view => views?.includes(view))
+
+export const viewRenderResources = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((_resources, data) =>
+  selectedViews(data.finalizeData.views).map(view => ({ type: 'Image', name: renderName(view), s3Key: \`\${renderName(view)}.jpg\` }))
+)
+
+export const viewRendersTask = phx.webhooks.taskFactory.createGenerateImagesTask((_resources, data, ctx) => {
+  const views = selectedViews(data.finalizeData.views)
+
+  if (views.length === 0) {
+    return null
+  }
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'blender/studio.blend',
+    templateFiles: ['models/chair.glb'],
+    images: views.map(view => ({
+      name: renderName(view),
+      fileFormat: 'JPEG',
+      ...ctx.blenderProjections.getBlenderImageConfig(data.state, view, data.state.rootEntityId, {
+        width: 800,
+        height: 800,
+      }),
+    })),
+  }
+})
+\`\`\`
+
+The [finalize handler](../finalization.md) registers them with \`.withResources(viewRenderResources)\` and \`.withTask(viewRendersTask)\`.`;export const generatePhoenixLinksAndImagesFeature=()=>e({path:"features/webhooks/tasks/links-and-images.md",title:"Links and images",summary:"`GenerateConfigurationLink`, `GenerateImages` with Blender, configurator-rendered images and resources declared at runtime; read when finalization shares the configuration or shows it in a picture.",whenToUse:"Read when finalization produces a link to the configuration or an image of it, or when the number of produced files depends on the configuration.",capabilities:"### Configuration links\n\n- `GenerateConfigurationLink` produces a link to the saved configuration under a declared `ConfigurationLink` resource, which PDFs, emails, spreadsheets and the callback include.\n- `access` decides what the link opens: `o` the configuration itself with edit rights, permanently; `rr` the finalized revision in read mode, unaffected by later edits; `r` the latest revision, refused on save but with the editing interface still shown. Pass `revisionId` for `rr` and `r`.\n- `expiration` is in hours; without it a link never expires, and an `o` link never does.\n\n### Server-rendered images\n\n- `GenerateImages` renders one or more images in Blender from the configured state, each under a declared `Image` resource with an `s3Key`. [Scene objects](../../scene-objects.md) and the 3D components decide what the scene holds.\n- `ctx.blenderProjections.getBlenderImageConfig(data.state, exportState, entityId, { width, height })` returns the camera, rendered entities and lights of an export state; spread it into the image.\n- `blenderSetupTemplate`, `templateFiles` and an optional `blenderPythonScriptName` are paths under `assets/private/`, uploaded with the deploy. The engine saved in the template renders the image, so choose it there: EEVEE renders faster, Cycles more realistically.\n- Renders queue one after another across the platform and can take minutes. The configurator waits with a `pollingTimeout` long enough for them ([Finalization](../finalization.md)).\n- Images the configurator renders itself, described in `docs/other-features/client-side-rendering/declarative.mdx`, need no server render and suit PDFs and email attachments that only show the current view.\n\n### Resources declared at runtime\n\n- When the number of resources depends on the configuration, return them from a `phx.webhooks.dynamicResourcesFactory` handler registered with `withResources`: `createGeneratedImage`, `createClientGeneratedImage`, `createExistingImage`, `createLink`, `createPdf`, `createCsv` or `createResource`. Their names are plain strings, unchecked until finalization runs.\n- `getClientSideImageResourceName(entityId, instanceName)` names the resource of a configurator-rendered image.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/sharing.mdx` — access levels and link generation.\n- `docs/phoenix/blender-rendering.mdx` — the Blender template, materials, lights, cameras, render settings and assets.\n- `docs/other-features/client-side-rendering/declarative.mdx` — configurator-rendered images in PDFs and emails.",phxMembers:["webhooks.dynamicResourcesFactory"]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/tasks.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** The finalization tasks index followed by its guides, grouped by what the tasks produce. */
+export declare const generatePhoenixTaskGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/tasks.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../../guide.js";import{generatePhoenixCallbackFeature as t}from"./callback.js";import{generatePhoenixDocumentsFeature as a}from"./documents.js";import{generatePhoenixEmailFeature as i}from"./email.js";import{generatePhoenixIntegrationsFeature as n}from"./integrations.js";import{generatePhoenixLinksAndImagesFeature as s}from"./links-and-images.js";export const generatePhoenixTaskGuides=()=>{let o=[s(),a(),i(),n(),t()];return[e({path:"features/webhooks/tasks/index.md",title:"Finalization tasks",summary:"Every task type finalization can run — links, images, PDFs, CSVs, emails, HTTP requests, WooCommerce, Google Sheets and the callback — grouped by what they produce; read when choosing or building a task.",intro:"A task is one thing the platform does after a finalization. The [finalize handler](../finalization.md) builds tasks with `phx.webhooks.taskFactory`, connects them through named resources and leaves their order to the platform, which runs them by type. Read only the guide for the task at hand.\n\n- Built by the project: `GenerateConfigurationLink` and `GenerateImages` (links and images), `GenerateStaticPdf`, `GeneratePdf` and `GenerateCsv` (documents), `SendStaticEmail` and `SendEmail` (email), `SendHttpRequest`, `WooCommerceAddToCart` and `EditGoogleSpreadsheet` (integrations), and `CallLambdaBack` (callback).\n- Built by the SDK when Project Admin publishes: `PublishRevision`, `PublishRevisionChunks` and `PublishRevisionChunksStaged` ([Admin publishing](../publishing.md)).",guides:o,notes:[]}),...o]};

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/webhooks.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The webhooks index followed by its guides: the entry, one guide per hook and the finalization tasks. */
+export declare const generatePhoenixWebhooksGuides: () => readonly PhoenixGuide[];