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

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as t}from"../../guide.js";import{generatePhoenixStateSlicesFeature as e}from"./slices.js";import{generatePhoenixUpdatesFeature as o}from"./updates.js";import{generatePhoenixViolationsFeature as a}from"./violations.js";export const generatePhoenixStateGuides=()=>{let n=[e(),o(),a()];return[t({path:"features/state/index.md",title:"State",summary:"Reading and writing the configuration at runtime and how violations surface; read when UI or a handler reads or changes the configuration, or must reflect what a change breaks.",intro:"The configurator keeps the configuration in a store. The slices hold the states UI can read; updates stage and commit changes, and dry runs test them first; the violations of those states disable control options, become hints and block finalizing. Read only the guide for the task. Declaring invariants belongs to [Validation and repair](../domain-model/validation-and-repair.md), transformers to [Transformers](../domain-model/transformers.md), and the controls that write for you to [Domain controls](../domain-controls/index.md).",guides:n,notes:[]}),...n]};

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Writing the configuration: update kinds, the stage and commit cycle, dry runs, undo steps and update guards. */
+export declare const generatePhoenixUpdatesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/updates.js

@@ -0,0 +1,39 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A width scrubber no configured control covers: every position is previewed, the release commits once, and the drag is one undo step. A width that breaks an invariant is not previewed, so the cabinet stays at the last valid width; a rejected release reverts the preview and becomes a message.
+
+\`\`\`tsx
+// src/_shared/WidthScrubber.tsx
+import { Slider } from '@mui/material'
+
+export const WidthScrubber = ({ cabinetId }: { readonly cabinetId: Cabinet['id'] }) => {
+  const { storeSystem } = phx.frontend.useDomain()
+  const width = phx.frontend.useRenderedEntitySelector(cabinetId, cabinet => cabinet.width, [])
+
+  const preview = (value: number | number[]) => {
+    if (typeof value !== 'number') {
+      return
+    }
+
+    // Replaces the previous preview: the whole change from the committed state
+    storeSystem.stage([
+      phx.frontend.updates.DomainEntityModification({
+        entityId: cabinetId,
+        stateDelta: { width: value },
+        updateTag: 'cabinet.scrubWidth',
+      }),
+    ])
+  }
+
+  return (
+    <Slider
+      value={width}
+      min={400}
+      max={1200}
+      step={10}
+      onChange={(_event, value) => preview(value)}
+      onChangeCommitted={() => storeSystem.commit()}
+    />
+  )
+}
+\`\`\`
+
+A discrete action is one call, such as \`storeSystem.stageAndCommit([phx.frontend.updates.EntityDeletion({ entityId, updateTag: 'cabinet.remove' })])\`. When configurator users pick it among options, a control with a dry run is the better home.`;export const generatePhoenixUpdatesFeature=()=>e({path:"features/state/updates.md",title:"Updates and dry runs",summary:"Update kinds, the stage, commit and rollback cycle, dry runs and undo steps; read when code writes the configuration or a transformer must stay cheap.",whenToUse:"Read when code writes the configuration outside a configured control, previews a change during a gesture, dry-runs a change to decide whether to offer it, needs ids for new entities, or narrows updates in a transformer.",capabilities:"### Choose the write path\n\n- Write through the control hooks of [Custom controls](../domain-controls/custom-controls.md) first: they build updates, dry-run options, stage gestures and commit. `phx.frontend.useUpdateControl(fixableViolations)` returns `prepare(updates)`, which dry-runs any updates and returns `{ disabled, hints, update, stage, trace }`.\n- Use the store system only when no control hook fits: a gesture you drive yourself, a write from a toolbar action, dialog or handler, a confirmation before a commit, or work that waits for a gesture to end.\n- `phx.frontend.useDomain()` returns the stable domain systems (`storeSystem`, `domain`, `undoSystem`, `navigationSystem`, `componentReader`, the projections), safe in dependency arrays. Navigation and selection changes belong to [Application states](../application-states/index.md).\n- Transformers return update arrays and never write to the store ([Transformers](../domain-model/transformers.md)).\n\n### Build updates\n\nEach `phx.frontend.updates` factory takes one object with an `updateTag` naming the change, such as `'cabinet.scrubWidth'`; `withTag` filters, the guards below and analytics read it. An optional localizable `hint` reaches configurator users as a side-effect message on commit: set it when a transformer changes something they did not touch.\n\n- `DomainEntityModification({ entityId, stateDelta, updateTag })` — sets some of the entity's own fields, never `id` or `type`.\n- `DomainEntityCreation({ entity, parentId, updateTag })` — adds a complete entity, optionally to the reference component instance named by `collection`. Build it with `phx.domain.createRecipe({ type, … })`, which fills the spec defaults, and replace its placeholder id. For children from recipes, prefer `phx.frontend.useCookRecipes`, which assigns ids.\n- `DomainEntityReplacement({ entityId, replacementEntity, keepChildren, updateTag })` — swaps in a new entity with a new id; `keepChildren: false` deletes its composed children.\n- `EntityDeletion({ entityId, updateTag })` — removes an entity; built-in transformers delete its composed children and prune references to it.\n- `ComponentModification({ componentInstance, writableState, updateTag })` — writes a component's writable state, as built-in controls do; it throws for a state the component rejects.\n\n`phx.frontend.getIdSequence(entities, pendingUpdates)` returns `{ nextId(type) }`, above every existing id and every id created or replaced in `pendingUpdates`. Draw a batch's ids from one sequence: two sequences from one state return the same id. In a transformer, use the context's `getIdSequence()`.\n\n### Stage, commit and roll back\n\n- `storeSystem.stage(updates)` runs transformers and invariants against the committed state and previews a valid result in the rendered slice; an invalid stage previews nothing. Each call replaces the staged updates: stage the whole change from the committed state, never a delta.\n- `storeSystem.commit()` prepares the staged updates again, runs the `onBeforeCommit` hooks and commits a valid result. A rejected commit keeps the committed state, resets the preview and reaches configurator messages through the potentially invalid slice.\n- `storeSystem.rollback()` drops the staged updates and their preview.\n- `storeSystem.stageAndCommit(updates)` writes a discrete action in one step: a click, a toggle, an add.\n- `storeSystem.hasStagedUpdates` is `true` while a staged change is pending; a hover stages nothing. It is a getter, not a subscription: check it before snapshotting the committed state, such as for an export.\n- `storeSystem.onBeforeCommit((emission, emit) => …)` runs before every commit and returns its unregister function; register it in an effect. Returning `false` holds the commit, such as to confirm a destructive change: the preview rolls back, and `emit()` commits that emission later. The hooks run again then, so let it through.\n- Leave `storeSystem.commitPrepared` to the SDK's own operations.\n\n### Dry runs\n\n- `storeSystem.prepareStateEmission(updates, storeSystem.stateSlices.committed.value.state, 'committed')` returns the emission a commit would produce, `{ state, validity, updates, … }`, without emitting it. Controls dry-run every option this way ([Violations](violations.md)).\n- Transformers and invariants run in a dry run exactly as in a commit, with the kind `'committed'`, so a transformer cannot tell them apart: `onEmissionsOfKind(['committed'])` skips staged previews but not dry runs.\n- Every mounted control dry-runs each option after every commit: ten options run the transformer pipeline and every invariant ten times per change. Staging runs them on every frame of a gesture.\n- Keep transformers pure and cheap: no requests, storage, analytics or React state.\n\n### Undo steps\n\n- One commit that changes entities is one undo step, transformer updates included, so a transformer's repair undoes with the change that caused it.\n- A commit that changes only navigation, view, tool or selection state makes no step.\n- Staged frames make no steps, but `stageAndCommit` on every keystroke or slider tick makes one each: stage while the value changes and commit once, on release or blur. [Toolbar actions](../custom-layout/toolbar-actions.md) covers the undo and redo buttons.\n\n### Update guards\n\nNarrow updates in a transformer (`ctx.updates`, `overrideAllUpdates`) or in an `onBeforeCommit` emission:\n\n- `phx.frontend.isCreateEntityUpdate(update, types)`, `phx.frontend.isReplaceEntityUpdate(update, types)` and `phx.frontend.isDeleteEntityUpdate(update, types)` — an entity of `types` added or replaced from a recipe, or removed by a built-in delete control. They check the SDK's own tags, so your own `EntityDeletion` does not match.\n- `(update, types, instanceName)` guards — the write of one built-in control on one component instance: `phx.frontend.isAttributeSelectionUpdate`, `phx.frontend.isAttributeSwitchUpdate`, `phx.frontend.isTextValueUpdate`, `phx.frontend.isSwatchSelectionUpdate`, `phx.frontend.isGenericDimensionUpdate`, `phx.frontend.isDistanceDimensionUpdate`, `phx.frontend.isAngleDimensionUpdate`.\n- A built-in step at priority `Infinity` turns component writes into entity modifications. Transformers default to that priority and run after it, and `onBeforeCommit` sees its result, so the control guards never match there. Give such a transformer a finite `priority` in its `transformers:` entry, or filter with `when.entity([...]).modified({ atFields })`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/transformers.mdx` — the transformer guide, including a component trigger registered with a finite priority.\n- `docs/complex-use-cases/navigation-guard.mdx` — an `onBeforeCommit` hook that holds a commit until configurator users confirm.\n- `docs/phoenix/state-management.mdx` — the stage, commit and rollback cycle and the emission kinds.\n- `docs/phoenix/configurator-interface.mdx` — "Updates Factory" and "Update Type Guards": every factory member, a control that dry-runs its updates, and the guards.',phxMembers:["frontend.updates","frontend.getIdSequence","frontend.useDomain","frontend.isCreateEntityUpdate","frontend.isReplaceEntityUpdate","frontend.isDeleteEntityUpdate","frontend.isAngleDimensionUpdate","frontend.isDistanceDimensionUpdate","frontend.isGenericDimensionUpdate","frontend.isAttributeSelectionUpdate","frontend.isAttributeSwitchUpdate","frontend.isTextValueUpdate","frontend.isSwatchSelectionUpdate"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** How violations disable control options, become hint text and gate Next and Finalize at runtime. */
+export declare const generatePhoenixViolationsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/violations.js

@@ -0,0 +1,36 @@
+import{createPhoenixFeatureGuide as t}from"../../guide.js";let i=`A missing purpose is a \`warning\`: the change stays, the purpose step's Next waits for it, and finalizing waits for it like for every other warning. Its priority puts its text alone in the finalize hint while lower-ranked warnings also hold.
+
+\`\`\`yaml
+# spec/invariants.yaml
+invariants:
+  KitchenRange:
+    purposeRequired:
+      type: purpose-required
+      severity: warning
+      message:
+        $msg: Choose a purpose before continuing
+      controlViolationPriority: 10
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/PurposeNextButton.tsx
+import { Trans } from '@lingui/react/macro'
+import { Button, Tooltip } from '@mui/material'
+
+export const PurposeNextButton = () => {
+  const { canGoNext, next } = phx.frontend.useStepNavigation()
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const missing = violations?.find(({ violation }) => violation.type === 'purpose-required')
+
+  return (
+    <Tooltip title={missing ? resolve(missing.violation.message ?? missing.violation.type) : ''}>
+      <span>
+        <Button variant="contained" disabled={!canGoNext || missing !== undefined} onClick={() => next()}>
+          <Trans>Next</Trans>
+        </Button>
+      </span>
+    </Tooltip>
+  )
+}
+\`\`\``;export const generatePhoenixViolationsFeature=()=>t({path:"features/state/violations.md",title:"Violations",summary:"How violations disable control options, become hints and gate finalizing; read when a control or button must reflect what a change would break or what still blocks the configuration.",whenToUse:"Read when a control must show what an option would break, when hint text needs ranking or custom wording, or when Next or Finalize must wait for the configuration's problems. Declaring invariants, choosing a severity and repairing with transformers belong to [Validation and repair](../domain-model/validation-and-repair.md).",capabilities:"### Where violations surface\n\n- **Controls** — every option is dry-run ([Updates and dry runs](updates.md#dry-runs)). An option is `disabled` when its dry run, after transformers, still has a `fatal` or `fixable` violation or an invariant throws; its hint is the text of those violations. A `warning` or `notice` never disables an option.\n- **Messages** — a rejected commit reaches the potentially invalid slice, and its violations become configurator messages. They include every violation of that state, notices and warnings too, so check `violation.severity`. [Messages](../custom-layout/messages.md) owns showing them.\n- **Finalizing** — reads the committed state: a `warning` or a failed save blocks it, a `notice` only adds text.\n\n### Control violations\n\n`phx.frontend.useControlViolations(ignoredTypes)` returns a function from a prepared emission to `{ disabled, hints, violations }`:\n\n- no violation — enabled, no hint;\n- `notice` or `warning` — enabled, no hint, `violations` listed;\n- `fatal` or `fixable` — disabled, `hints` from those violations, `violations` all of them;\n- an invariant that throws — disabled, no hint. A transformer that throws is not caught: the control's render throws.\n\nPrefer `phx.frontend.useUpdateControl` from [Custom controls](../domain-controls/custom-controls.md), which prepares the emission and applies this mapping. Call `useControlViolations` yourself only for an emission you prepared, such as a dialog listing from `violations` what an option would break.\n\n`fixableViolations`, an argument of every control hook and of both update hooks, only removes those violation types from the hint text: the option stays disabled. List a type when another part of the UI explains it. To keep an option enabled, repair the violation in a transformer, so its dry run ends valid.\n\n### Hint text\n\n- Hints keep only the violations with the highest `controlViolationPriority` (default 0), drop duplicates and join several as sentences. Rank a root cause above its consequences, such as size above color.\n- Ignored types are removed before the highest priority is found, so ignoring the top-ranked violation shows the next one.\n- Set `controlViolationPriority` on a YAML invariant or on a violation returned from TypeScript. The finalize hint applies the same ranking.\n- A TypeScript violation may add `formatControlViolationMessage(emission, { i18n })`: a hint naming the attempted value, or `null` to drop this hint, such as for all but one of identical violations. Messages keep using `message`.\n- `message` is optional on a TypeScript violation, and messages fall back to its type. In YAML it is a string or `$msg`; [Localization](../localization.md) covers the catalogs.\n- `phx.frontend.useMapViolationHints(ignoreTypes?)` returns `(violations, emission) => string`, the hint text these rules make from any violations. For the committed state, take the emission from `phx.frontend.useCommittedSlice()`.\n\n### Finalize and step gating\n\n`phx.frontend.useFinalizeViolations()` returns `{ disabled, hints, violations }` for the committed state:\n\n- `disabled` while a `warning` holds or the last save failed; `hints` then says why, and `violations` is `undefined` for a failed save;\n- a `notice` leaves it enabled, with its text in `hints`;\n- `violations` lists the committed state's violations, `undefined` when there are none.\n\n`phx.frontend.useStateValidity()` returns the validity of the last committed emission: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'warning' | 'notice', entityViolations }`. A `fatal` or `fixable` violation is never committed, so a `warning` is the problem the committed state can still have. Its type also lists the rejected results: narrow on `severity` before reading `entityViolations`.\n\n- Gate Finalize with `disabled` and show `hints` beside it; `useFinalizeActions` already returns both ([Finalization actions](../custom-layout/finalization-actions.md)).\n- Next enforces nothing by itself ([Tabs and steps](../custom-layout/tabs-and-steps.md)). Gate it with `disabled` and show `hints`. `useStateValidity().severity === 'warning'` holds it for the configuration alone, ignoring a failed save, and gives no text.\n- When a step waits only for its own problems, filter `violations` by their types and word them with `useMapViolationHints`.",example:i,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/violation-messages.mdx` — `controlViolationPriority` and `formatControlViolationMessage` worked through four ranked violations, with localized hint text.\n- `docs/other-features/violation-severity.mdx` — what each severity does to controls and finalizing; [Validation and repair](../domain-model/validation-and-repair.md) owns choosing one.\n- `docs/complex-use-cases/filtered-controls-with-fix-dialog.mdx` — controls ordered so transformers repair lower choices, with `fixableViolations` shortening each hint.\n- `docs/phoenix/configurator-interface.mdx` — "Violations" lists the violation hooks with what each returns.',phxMembers:["frontend.useControlViolations","frontend.useFinalizeViolations","frontend.useStateValidity","frontend.useMapViolationHints"]});

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

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixVariantsFeature: () => PhoenixGuide;

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

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";export const generatePhoenixVariantsFeature=()=>e({path:"features/variants.md",title:"Variants",summary:"Supported alternative types, preview constraints and usage; read when preparing a comparison in the live preview and applying the choice.",whenToUse:"Read when preparing a visual or interaction comparison in the running preview. The [workflow](../core/workflow.md#visual-choices) owns whether alternatives would help; this guide covers the supported options and how to collect and apply a choice.",capabilities:'### Option types\n\n- Use `<id>.variant.js` to edit real frontend project files on top of one captured baseline. Use `<id>.html` for a standalone branding, layout or flow proposal rendered in an iframe.\n- Use the same mechanism for controls, layout, brand, lights, visuals, materials, positions, components, elements and transformers.\n- Keep the model, schemas, data, assistant server settings, webhooks and code shared with them, dependencies, environment and uploaded assets unchanged. The preview rejects changes needing server preparation.\n- Options reuse the already loaded configurator, one at a time. Variant transactions bypass the file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.\n\n### Design the comparison\n\n- One decision per set, one set open at a time. Vary the decision being compared and keep unrelated details identical.\n- Make the difference visible in the UI or the scene; similar materials in flat light may not distinguish the alternatives.\n- Choose the number of options that clarifies the decision; no fixed count is required.\n- Name options in the client\'s product language and explain what changes in one line.\n\n### Write the options\n\n- One folder per set: `.phoenix/variants/<name>/`, one script or HTML file per option. HTML and scripts can share a set, but option ids must be unique. Keep HTML self-contained. This folder survives rebuilds and is never committed.\n- For HTML, set `<title>` and `<meta name="description" content="...">`; choosing a page changes no source files.\n- For scripts, export `title` and `description` as plain string literals, and a default function `({ read, write, remove }) => {}`; it may be async.\n- `read(path)` returns the original baseline file contents. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Paths are relative to the project root.\n- Scripts run once per selection in the browser and collect edits. Phoenix validates and writes the whole batch locally and owns backups and undo. Do not perform your own filesystem or network operations.\n- Supported edits are YAML in `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions and invariants run on the server too; those folders and action files are outside the supported edit surface.\n- Every option starts from the same baseline. Original restores it; switching restores the files only the previous option changed.\n- Keep the working tree untouched while comparing. Phoenix never overwrites an edit made outside the preview: it refuses to switch options over one, and when the comparison ends it leaves that file as it is and warns in the dev log.\n\n### Run it and wait\n\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the client the options are open there.\n- Put the title and the description in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside them as `\'\\\'\'`; in PowerShell, double it instead.\n- The command waits for the answer, 540 seconds unless `--timeout <seconds>` says otherwise, so give it a command timeout longer than that. It prints JSON:\n  - `"status": "chosen"` with `choice` (the option id, or `null` for Original) and `label`;\n  - `"status": "waiting"` when the wait ran out. The options stay open: run the same command again, or end the turn and run it when the client is back. An answer given in between is returned by the next run;\n  - `"status": "closed"` when the preview was closed without an answer.\n- `pnpm phoenix variants --close` closes the open set when the comparison is abandoned.\n- `--port <port>` names the editor WebSocket port when `phoenix dev` does not use 3020.\n- The live configurator keeps its current configuration. Interactions still change it; restoring source files does not undo configuration changes.\n\n### Use the answer\n\n- **Chosen** — a script\'s exact file edits remain in the project. For an HTML choice, implement the selected proposal using the SDK and compare the result with the page. With `choice: null`, the client chose Original and the baseline remains. Verify the result with `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the client anything that came out differently.\n- Record the decision and its reason in the [project record](../core/workflow.md#records).\n- The client confirms Original or another option; Escape and the backdrop do not close the comparison. `--close` restores the baseline source files without an answer. The folder is removed once the client answers; pass `--keep` while its files are still needed to build from, and remove the folder afterwards.',example:"Compare warm and neutral lighting with two variant scripts while keeping the product and camera unchanged. Use HTML proposals instead when comparing standalone pages, such as branding sheets, then implement the selected proposal in the project. Original remains available as the captured baseline.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for the CLI contract. Use the [review index](../processes/review/index.md) to select evidence for the applied result.",phxMembers:[]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The assistant setup handler that narrows the assistant per session. */
+export declare const generatePhoenixAssistantSetupFeature: () => PhoenixGuide;

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

@@ -0,0 +1,32 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let s=`A configurator user who opens a shared configuration may ask about it but not change it:
+
+\`\`\`yaml
+# spec/assistant.yaml
+assistant:
+  instructions: Help the visitor choose a chair and explain the finishes.
+  ai:
+    provider: openai
+    model: balanced
+    reasoning: low
+  entities:
+    Chair:
+      label:
+      finish:
+  writable:
+    Chair:
+      finish:
+\`\`\`
+
+\`\`\`ts
+// src/handlers/assistant-setup.ts
+export default phx.domain.createAssistantSetupHandler((manifest, { access }) =>
+  access === 'o'
+    ? manifest
+    : {
+        ...manifest,
+        writable: {},
+        deletable: {},
+        instructions: 'The visitor is viewing a shared configuration. Describe it and answer questions; never offer to change it.',
+      }
+)
+\`\`\``;export const generatePhoenixAssistantSetupFeature=()=>e({path:"features/webhooks/assistant-setup.md",title:"Assistant setup",summary:"`phx.domain.createAssistantSetupHandler`, which narrows what the assistant may see and change per session or switches it off; read when the assistant must behave differently by role, session data or access.",whenToUse:"Read when the assistant must offer less to some sessions — viewers of a shared configuration, anonymous users, a customer group — or none at all.",capabilities:"### The handler\n\n- `phx.webhooks` has no builder for it: default-export `phx.domain.createAssistantSetupHandler((manifest, { role, sessionData, access }) => manifest)` from a file in `src/handlers/`, at most one per project. The file joins the webhook automatically, so it imports only server-safe modules ([Webhook entry and environment](entry-and-environment.md)).\n- The SDK calls it for every assistant session with the manifest the `assistant` spec declares, and uses what it returns. Return `null` to switch the assistant off for the session.\n- `role` and `sessionData` come from [authentication](authentication.md); `access` is how the configuration was opened, such as `o` for its owner.\n\n### What it may change\n\n- Narrow, never widen: leave out entries of `entities`, `writable`, `deletable`, `actions` and the recipe maps to hide them. Entries keep the entity and alias split of the YAML; narrow those original declarations and the SDK expands them to member types afterwards.\n- Writable options accept only `validate: true` and `allowDryRuns: false`; recipe groups accept a `description` and `allowDryRuns: false`; screenshot views accept a `description`; deletable entries are `{}`. Names, component bindings, hints and types are fixed by the spec.\n- `instructions` and `ai` change the server's prompt and model. An empty `instructions` string clears the spec's instructions; an omitted one keeps them. `ai.voice` turns voice messages and the replies read aloud on or off for the session; the panel follows the server, so it shows the mic, the play buttons and the mute control exactly when the server takes them.\n- The assistant's buttons and panel follow the spec, not the handler; hide them per session in the layout, for example with `$filter`.\n\n### Constraints\n\n- Keep it synchronous, pure and deterministic: it runs in the browser and in the webhook, and both must reach the same manifest.\n- In the browser the manifest has no `instructions` or `ai`, and what the handler returns for them is ignored. Never decide the other entries from `manifest.ai`, or the browser's schema would differ from the server's.\n- A handler that throws or returns an invalid manifest leaves the assistant unavailable for the session. Deployed environments reuse a session's setup for up to 15 minutes; under `phoenix dev` it runs on every request, within 15 seconds.",example:s,documentation:"The shipped SDK docs do not cover the assistant setup handler yet; [Webhook entry and environment](entry-and-environment.md) covers how its file joins the webhook.",phxMembers:["domain.createAssistantSetupHandler"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The auth hook: its flows, what a handler returns and how the session reaches the rest of the project. */
+export declare const generatePhoenixWebhookAuthenticationFeature: () => PhoenixGuide;

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;