@salsita-ai/sdk 0.50.0-develop.c28cfb7ded → 0.50.0-develop.ca72986c39

package/dist/client/phoenix-api.d.ts

@@ -55,6 +55,38 @@ export interface paths {
     readonly patch?: never
     readonly trace?: never
   }
+  readonly '/auth/callback': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly get: operations['completeBrowserLogin']
+    readonly put?: never
+    readonly post?: never
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
+  readonly '/auth/config': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly get: operations['getBrowserAuthConfig']
+    readonly put?: never
+    readonly post?: never
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
   readonly '/auth/identity': {
     readonly parameters: {
       readonly query?: never
@@ -72,6 +104,39 @@ export interface paths {
     readonly patch?: never
     readonly trace?: never
   }
+  readonly '/auth/login': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly get: operations['startBrowserLogin']
+    readonly put?: never
+    readonly post?: never
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
+  readonly '/auth/logout': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly get?: never
+    readonly put?: never
+    /** @description Destroy the local session and return the fixed Cognito hosted logout URL. Requires the exact shared Studio Origin. */
+    readonly post: operations['endBrowserSession']
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
   readonly '/auth/me': {
     readonly parameters: {
       readonly query?: never
@@ -89,6 +154,23 @@ export interface paths {
     readonly patch?: never
     readonly trace?: never
   }
+  readonly '/auth/session': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    /** @description Read the opaque browser session and current account status/memberships. Requires the exact shared Studio Origin. */
+    readonly get: operations['getBrowserSession']
+    readonly put?: never
+    readonly post?: never
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
   readonly '/auth/token': {
     readonly parameters: {
       readonly query?: never
@@ -1620,6 +1702,114 @@ export interface operations {
       }
     }
   }
+  readonly completeBrowserLogin: {
+    readonly parameters: {
+      readonly query: {
+        readonly code: string
+        readonly state: string
+      }
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description Redirect to the configured sign-in or Studio destination. */
+      readonly 302: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': Record<string, unknown>
+        }
+      }
+      /** @description Bad Request! */
+      readonly 400: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadRequestError']
+        }
+      }
+      /** @description Unauthorized! */
+      readonly 401: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['UnauthorizedError']
+        }
+      }
+      /** @description Forbidden! */
+      readonly 403: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ForbiddenError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description Service Unavailable! */
+      readonly 503: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ServiceUnavailableError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
+  readonly getBrowserAuthConfig: {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description Shared Studio origin when browser sign-in is configured; null otherwise. */
+      readonly 200: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': {
+            readonly studioOrigin: string | null
+          }
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
   readonly resolveIdentity: {
     readonly parameters: {
       readonly query?: never
@@ -1699,6 +1889,112 @@ export interface operations {
       }
     }
   }
+  readonly startBrowserLogin: {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description Redirect to the configured sign-in or Studio destination. */
+      readonly 302: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': Record<string, unknown>
+        }
+      }
+      /** @description Bad Request! */
+      readonly 400: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadRequestError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
+  readonly endBrowserSession: {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description Navigate to this URL to finish hosted logout. */
+      readonly 200: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': {
+            /** Format: uri */
+            readonly logoutUrl: string
+          }
+        }
+      }
+      /** @description Bad Request! */
+      readonly 400: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadRequestError']
+        }
+      }
+      /** @description Forbidden! */
+      readonly 403: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ForbiddenError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
   readonly getApiSession: {
     readonly parameters: {
       readonly query?: never
@@ -1748,6 +2044,77 @@ export interface operations {
       }
     }
   }
+  readonly getBrowserSession: {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description Current account and fixed session expiry, in Unix milliseconds. */
+      readonly 200: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': {
+            readonly expiresAt: number
+            /** Format: uuid */
+            readonly userId: string
+            readonly workspaces: readonly {
+              /** Format: uuid */
+              readonly customerId: string
+              readonly name: string
+              /** @enum {string} */
+              readonly role: 'user' | 'admin' | 'superadmin'
+              readonly slug: string
+              readonly tags: readonly string[]
+              /** @enum {string} */
+              readonly type: 'standard' | 'sdk_builder'
+            }[]
+          }
+        }
+      }
+      /** @description Unauthorized! */
+      readonly 401: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['UnauthorizedError']
+        }
+      }
+      /** @description Forbidden! */
+      readonly 403: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ForbiddenError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
   readonly exchangeAuthCode: {
     readonly parameters: {
       readonly query?: never

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-14T19:37:05.683Z",
+  "generatedAt": "2026-10-15T09:04:15.149Z",
   "categories": [
     {
       "name": "Phoenix",

package/dist/docs/phoenix/deployments.mdx

@@ -281,9 +281,7 @@ Phoenix provides two helper functions for reading environment variables with val
 **`createEnvReader`** - General purpose environment reader used in frontend and deployment contexts:
 
 ```typescript
-import { bool, str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { bool, createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 // Create a reader function
 const readEnv = createEnvReader({
@@ -301,9 +299,7 @@ console.log(env.SERVER_URL) // Typed and validated
 
 ```typescript
 // webhooks/webhooks.config.ts
-import { str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 export const readRuntimeConfig = createEnvReader({
   AWS_S3_PUBLIC_RESOURCES_BUCKET: str(),

package/dist/docs/phoenix/getting-started.mdx

@@ -26,6 +26,7 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 - `phoenix dev` - Start the development server with hot reload
 - `phoenix build` - Build the configurator for production
 - `phoenix sync` - Synchronize dependencies and generated code
+- `phoenix deps` - Add the SDK's missing peer dependencies to `package.json` and move out-of-range ones into range
 - `phoenix check` - Validate domain configuration and code
 - `phoenix fix` - Auto-fix common issues in domain files
 

package/dist/docs/phoenix/localization.mdx

@@ -408,7 +408,7 @@ function EntityList({ entities }) {
 When you need to do more complex text formatting with placeholders or embedded elements, you can reach for Lingui's `Trans` macro directly:
 
 ```tsx
-import { Trans, msg } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 function WelcomeMessage({ userName, itemCount }) {
   return (
@@ -423,14 +423,14 @@ function WelcomeMessage({ userName, itemCount }) {
 
 ## Server-Side Translations for Webhooks
 
-The localization system isn't just for the frontend — it works in server-side webhook handlers too. PDF and email tasks render React templates with the same `@lingui/macro` toolchain (`<Trans>`, `msg`) you already use in UI components. The task context exposes `ctx.resolveLocalizable` already bound to the request locale and domain fallback chain, and the React builders use it for localizable subjects, attachment filenames, bodies, headers, footers, and watermark text.
+The localization system isn't just for the frontend — it works in server-side webhook handlers too. PDF and email tasks render React templates with the same Lingui macros (`<Trans>` from `@lingui/react/macro`, `msg` from `@lingui/core/macro`) you already use in UI components. The task context exposes `ctx.resolveLocalizable` already bound to the request locale and domain fallback chain, and the React builders use it for localizable subjects, attachment filenames, bodies, headers, footers, and watermark text.
 
 ### In the handler
 
 Use the `msg` template tag for one-off strings you pass into builder methods:
 
 ```tsx
-import { msg } from '@lingui/macro'
+import { msg } from '@lingui/core/macro'
 
 export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data, ctx) => {
   return ctx.emailTaskBuilder
@@ -450,7 +450,7 @@ export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources
 Use `<Trans>` for inline strings — exactly as in the frontend — and `<HtmlHelpers.Localized>` to render localizable values pulled from the domain (e.g. `$root.$summary[].title`, which are typed as `MessageDescriptor` or `MultilingualString`):
 
 ```tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers } from '@salsita-ai/sdk/webhook'
 

package/dist/docs/phoenix/migration-guide.mdx

@@ -251,8 +251,19 @@ rm src/frontend/frontend.tsx
 # Remove empty domain/frontend folders after moving all files
 rmdir src/domain/implementation src/domain/data src/domain
 rmdir src/frontend/systems/transformers src/frontend/systems src/frontend/ui src/frontend/admin-pages src/frontend
+
+# Remove the root TypeScript settings (sync writes the file again)
+rm tsconfig.json
 ```
 
+With the application-spec pipeline (`phoenix.applicationFlow` in `package.json`; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the project's TypeScript settings are generated into `.phoenix/tsconfig.json`. Sync writes the root `tsconfig.json` only into a project that has none, as a single line that extends them:
+
+```json
+{ "extends": "./.phoenix/tsconfig.json" }
+```
+
+A root `tsconfig.json` from the old multi-folder template, or one written by hand, stays as it is and does not pick up the generated settings or the global `phx` types in `.phoenix/globals.d.ts`, so `pnpm ts:check` fails. Delete it, or replace its content with the line above, before the first sync.
+
 ### 10. Create Mocks (Optional)
 
 If you have mock files, move them to `mocks/`:
@@ -390,7 +401,7 @@ pnpm install
 
 1. Run type check: `pnpm ts:check`
 2. Update any broken type imports
-3. Ensure `tsconfig.json` paths are correct (auto-generated by Phoenix)
+3. With the application-spec pipeline (`phoenix.applicationFlow`; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), check that the root `tsconfig.json` is the one-line file that extends `.phoenix/tsconfig.json` (see [step 9](#9-remove-auto-generated-files))
 
 ## Checklist
 
@@ -433,13 +444,13 @@ Use this checklist to verify migration completeness:
 
 The following files are no longer needed - they are auto-generated by the CLI:
 
-| File                        | Replacement                                  |
-| --------------------------- | -------------------------------------------- |
-| `src/domain/domain.ts`      | Auto-generated in `.phoenix/domain.ts`       |
-| `src/frontend/frontend.tsx` | Auto-generated in `.phoenix/configurator.ts` |
-| `tsconfig.json`             | Auto-generated by CLI                        |
-| `eslint.config.js`          | Auto-generated by CLI                        |
-| `prettier.config.js`        | Auto-generated by CLI                        |
+| File                        | Replacement                                                                                                                         |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `src/domain/domain.ts`      | Auto-generated in `.phoenix/domain.ts`                                                                                              |
+| `src/frontend/frontend.tsx` | Auto-generated in `.phoenix/configurator.ts`                                                                                        |
+| `tsconfig.json`             | Delete before the first sync; with the application-spec pipeline, sync writes a one-line file that extends `.phoenix/tsconfig.json` |
+| `eslint.config.js`          | Auto-generated by CLI                                                                                                               |
+| `prettier.config.js`        | Auto-generated by CLI                                                                                                               |
 
 ## Builder Options Moved to YAML
 

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -137,7 +137,7 @@ The same streams are available in the editor's **Logs** sidebar panel with per-s
 
 Runs all code quality checks in sequence:
 
-1. **TypeScript** — Type checking with `tsc`
+1. **TypeScript** — Type checking with `tsc`, with the project's root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none (see [Project Structure](?path=/docs/phoenix-project-structure--docs#root-level-files))
 2. **ESLint** — Linting rules, over `src/`; a project with no files there passes
 3. **Prettier** — Code formatting
 
@@ -147,12 +147,23 @@ Auto-fixes ESLint and Prettier issues. Equivalent to running `eslint --fix` and
 
 ## Environment Variables
 
-When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`.
+When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`. `phoenix dev` does the same for its development deployment when it starts.
+
+### The generated env file
+
+A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoenix/.env.generated`, unless the project has a `.env.generated` in its root, which then is the one that counts.
+
+- `phoenix dev` reads and writes `.phoenix/.env.generated` in a project without a root `.env.generated`, and creates no file in the project root. In a project that has a root `.env.generated`, it reads and writes that file and `.phoenix/.env.generated` is not used.
+- The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
+- Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
+- `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
 ### Data Flow
 
 ```
-spec/application.yaml → Server prepares environment → CLI writes .env.generated → Frontend/Webhooks read it
+spec/application.yaml → Server prepares environment → CLI writes the generated env file → Frontend/Webhooks read it
 ```
 
 ### Project Scripts
@@ -173,7 +184,7 @@ A project may have other scripts than these five, such as `sync`, `test` or `ver
 
 ### Server-Generated Variables
 
-These are automatically computed by the server and written to `.env.generated`:
+These are automatically computed by the server and written to the generated env file:
 
 | Variable                         | Purpose                                                 |
 | -------------------------------- | ------------------------------------------------------- |
@@ -261,7 +272,7 @@ A development environment keeps the AI assistant's conversation when the assista
 Environment variables are resolved in this order (highest to lowest priority):
 
 1. Process environment variables (shell)
-2. `.env.generated` (created by deployment commands)
+2. [The generated env file](#the-generated-env-file): `.env.generated` in the project root when the project has one, otherwise `.phoenix/.env.generated`
 3. `.env` (manual overrides)
 
 ### Generated Config Files
@@ -300,7 +311,8 @@ The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
-- `.env`, `.env.generated` — Environment files (triggers full Vite restart)
+- `.env` — Environment file; a change restarts the Vite dev server
+- `.env.generated`, `.phoenix/.env.generated` — Generated env files; a change rebuilds the project files. Only a file that exists when `phoenix dev` starts is watched: a root `.env.generated` that a deployment command creates while dev runs is not watched; restart `phoenix dev` to use it.
 
 When linked SDK packages are detected (`phoenix link`), changes to SDK dist files are also watched.
 
@@ -398,6 +410,24 @@ With the application-spec pipeline (see [Current and legacy project tooling](#cu
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
 
+### `phoenix deps`
+
+Brings `package.json` in line with the SDK's peer dependencies: the packages the SDK's code imports and the project installs next to it, so the project and the SDK share one copy. The `peerDependencies` of the installed `@salsita-ai/sdk` decide which packages and which versions. `@clerk/clerk-react` is needed only when the spec sets `useClerk`.
+
+```bash
+pnpm phoenix deps
+pnpm install
+```
+
+- A missing peer is added at the lowest version of the SDK's range, as an exact version, in alphabetical order: type packages (`@types/*`) to `devDependencies`, the others to `dependencies`.
+- A peer declared with a version range whose lowest version falls outside the SDK's range is set to the lowest version of the SDK's range, in the field that declares it. The output says when that is a downgrade.
+- A peer declared with a specifier that is not a version range, such as `workspace:`, `npm:`, `catalog:`, `file:`, `link:` or a git URL, stays as it is.
+- `@salsita-ai/common`, `@salsita-ai/contracts`, `@salsita-ai/platform-project-sdk`, `@salsita-ai/platform-common` and `@salsita-ai/platform-contracts` are removed, because `@salsita-ai/sdk` replaces them. No other entry is removed.
+
+Every other part of `package.json` keeps its order and formatting. `phoenix deps` installs nothing: it lists each change and names `pnpm install` as the next step, or says that nothing needed to change. Running it again changes nothing. It reads the spec to learn whether the project uses Clerk, so it stops with the spec's errors when the spec does not parse.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix deps` changes nothing and says that `phoenix sync` manages the dependencies.
+
 ### Current and legacy project tooling
 
 Use the `phoenix` binary for projects that still use domain-spec generation. The CLI selects a