@salsita-ai/contracts 0.0.0-stage → 0.49.0-develop.0247831f20

package/CHANGELOG.md

@@ -0,0 +1,419 @@
+# Change Log
+
+All notable changes to the @salsita-ai/contracts package will be documented in this file.
+
+## [0.48.0]
+
+change!: remove the process-local `ClerkBackendApiClient.fetchUserCached()` method (CON-2556, CON-2685)
+
+**Migration:** replace `fetchUserCached(userId, tenantId)` with `fetchUser(userId)`. Applications that need caching should provide a shared, caller-owned cache appropriate for their runtime.
+
+feat: add deployment source metadata
+
+Deployment contracts now expose the readable project ref and resolved commit SHA, with null defaults for legacy creation paths.
+
+change!: add explicit normal, transient, and development environment types
+
+Migration:
+
+- Replace the `transient` argument to `Environment.create()` with `type: EnvironmentType.Normal` or
+  `type: EnvironmentType.Transient`. Keep passing `localConfig` for both types.
+- To create a development environment, pass `type: EnvironmentType.Development` and
+  `developmentConfig` with its public and private buckets instead of `localConfig`.
+- Add `type` to manually constructed `Environment` and `NewEnvironment` values, keeping the legacy
+  `transient` field consistent with it.
+
+feat: add the `DevelopmentKey` branded type and `createDevelopmentKey` factory to the environment domain
+
+The development-environment key format `dev_<project-slug>_<environment-slug>_<random>` is owned by the domain; the server supplies the random part.
+
+feat: bind webhook base URLs in the HTTP transport
+
+WebhookClient accepts a transport that consumes relative operation routes. Use createUrlWebhookHttpClient to bind a destination URL; the existing URL constructor remains available as a deprecated compatibility overload.
+
+feat: add webhook tunnel wire contracts and support relative webhook routes
+
+Webhook contracts now describe tunneled request polling and responses, while webhook clients can use relative operation routes when development deployments have no stored webhook URL.
+
+fix: allow explicit `null` Blender material texture-map overrides so render workers can distinguish removal from omission
+
+fix: carry the optional `transparent` flag in Blender material overrides so workers can match Three.js opacity behavior
+
+feat: add JWKS-based Clerk session-token verification for auth webhooks, including issuer, expiry, required session claims, and authorized deployment-origin checks
+
+chore: build and type-check with the TypeScript 7 native compiler
+
+chore: resolve all pnpm audit findings (CON-2655)
+
+Bump the vite devDependency to 6.4.3 as part of bringing `pnpm audit` to zero findings workspace-wide.
+
+fix: allow custom environment variables to override system and generated active values
+
+fix: export the shared `PdfUnitValue` type and `PdfUnitValueSchema`
+
+Finalize worker job contracts can now reuse the same unit-bearing PDF values accepted by `GeneratePdfTask` and `GenerateStaticPdfTask`.
+
+fix: add backward-compatible staged revision-chunk webhook contracts
+
+Servers can offer a private staging upload URL, and current SDK webhooks can return a lightweight publication task while older inline chunk tasks remain supported.
+
+feat: support protected project Lambda webhooks
+
+Webhook calls can now use authenticated access without changing existing project integrations or local development.
+
+## [0.47.0]
+
+### 2026-07-22 commit f58f411f3 PR #1602
+
+feat: `GeneratePdfTask`/`GenerateStaticPdfTask` margin and header/footer height accept strings with unit suffix (`px`/`cm`/`mm`/`in`/`pt`) in addition to numbers (px)
+
+## [0.46.0]
+
+### 2026-06-09 commit 1f03b862b PR #1635
+
+fix: add SharePoint tenant domain to site config
+
+### 2026-06-09 commit 48bfcfe65 PR #1636
+
+fix: stop preserving stale active environment variables
+
+### 2026-06-08 commit be12ba53d PR #1633
+
+fix: skip unsupported Microsoft Excel data validation API
+
+## [0.45.0]
+
+### 2026-06-02 commit 525a87f9b PR #1609
+
+chore: bump vitest 3.2.4 → 4.1.7 to clear critical advisory
+
+Clears critical advisory GHSA-5xrq-8626-4rwp (vitest <4.1.0: arbitrary file read/exec when Vitest UI server listening).
+
+### 2026-06-02 commit 78215678b PR #1596
+
+chore: add `vite` 5.4.21 as direct devDep
+
+Promotes vitest's transitive vite to a pinned devDep so it uses the patched version.
+
+### 2026-06-02 commit c1a67bb99 PR #1593
+
+chore: align vitest 3.2.1 → 3.2.4
+
+### 2026-06-01 commit 75664ca05 PR #1583
+
+chore: bump ajv 8.17.1 → 8.20.0 (ReDoS in <8.18.0)
+
+### 2026-06-01 commit dd378335f PR #1582
+
+chore: bump @lingui/core 4.11.3 → 5.9.5
+
+See `@salsita-ai/platform-project-sdk` changelog for the lingui 4 → 5 migration guide.
+
+### 2026-06-01 commit eba73549e PR #1581
+
+chore: bump @swc/core 1.4.2 → 1.7.28, @swc/cli 0.3.10 → 0.7.10
+
+### 2026-06-01 commit fabe5ce58 PR #1580
+
+chore: bump typescript 5.7.2 → 5.9.3
+
+### 2026-06-01 commit 868ced09c PR #1572
+
+chore: drop unused chokidar dep; bump prettier 3.2.5 → 3.8.3
+
+### 2026-06-01 commit 868ced09c PR #1572
+
+chore: bump openai 4.53.0 → 6.38.0; dropped `openai/core.mjs` Response import (use SDK return type); relocated `openai/uploads.mjs` → `openai/core/uploads`; narrowed `createCompletionTool` return + `ChatToolCalls.tool_calls` + `processToolCalls`/`createAssistantMessage` to function-tool variant (v6 split tool calls into function + custom union); switched `createTranscription` param type to the non-streaming overload
+
+### 2026-06-01 commit fdd0ae84c PR #1570
+
+chore: dep updates
+
+- `http-errors` 2.0.0 → 2.0.1, `@types/http-errors` 2.0.0 → 2.0.5
+- `ts-pattern` 5.1.2 → 5.9.0
+- `jose` 5.2.1 → 6.2.3
+- `lodash-es` 4.17.21 → 4.18.1 (CVE-2026-4800, CVE-2026-2950, CVE-2025-13465)
+- `uuid` 9.0.1 → 14.0.0, dropped `@types/uuid` (types ship with uuid since v11)
+
+### 2026-05-27 commit 10b52f456 PR #1532
+
+- feat: Excel SpreadsheetAdapter implementation
+
+  Full Microsoft Excel adapter with parity to Google: create workbook,
+  list files, fetch / reset data. Powers the connected-data flow for
+  SharePoint-hosted workbooks.
+
+  Excel and Google adapters also behave identically on error reporting,
+  cell-value coercion on write, and in-sheet data validation (dropdowns
+  / list locks). Connected-data UX is provider-agnostic.
+
+### 2026-05-18 commit 53f48433c PR #1546
+
+feat: optional `replyTo` on `SendEmailTask` — recipients see it in the Reply-To header; falls back to `from` when unset
+
+## [0.44.0]
+
+### 2026-04-13 commit df99c3334 PR #1486
+
+change!: `GenerateImagesTask.images[].camera` is now optional — omit it to use the Blender template's own camera instead of a programmatic look-at camera
+
+**Migration:** existing webhook handlers that always provide `camera` are unaffected. If you relied on the type requiring `camera`, add an explicit `camera` field or update your type expectations.
+
+feat: extend `GenerateImagesTask` with `renderSettings` (task-level and per-image), `lights`, extended `camera` fields (`dof`, `sensorWidth`, `clipStart`, `clipEnd`, `fov`), and `scale` on `DefaultRenderedEntity`
+
+feat: add `BlenderRenderSettings`, `BlenderLight`, `BlenderCameraDof`, `BlenderMaterialOverride` types and `BlenderMaterialOverrideSchema` Zod schema — material overrides expanded from color+baseMaterial to full PBR (textures, opacity, clearcoat, sheen, transmission, anisotropy, etc.)
+
+## [0.43.0]
+
+### 2026-03-27 commit adf02f34c PR #1395
+
+feat: add image render tracking domain with configurable per-environment limits
+
+feat: add `imageRenderLimitEnabled` customer feature flag
+
+## [0.42.0]
+
+- Empty
+
+## [0.41.0]
+
+- feat: add `connectedProvidersEnabled` to `Customer` interface and `updateBasicInfo`
+
+- feat: add `OAuthConnection` domain types (`OAuthConnectionId`, `OAuthConnectionProvider`, `OAuthRefreshToken`, `OAuthGrantedScopes`)
+
+- feat: add `connectedProviderAccessTokens` optional field to `FinalizeWebhookPayload`
+
+- feat: add Google Sheets client utilities (`fetchSpreadsheetMeta`, `fetchTabHeaders`, `fetchSheetData`)
+
+- feat: add `releaseToProductionEnabled` to `Customer` interface and `updateBasicInfo`
+
+- feat: add `applicationVersion` and `publishedDataHash` to `Deployment`, `NewDeployment`, `CreateDeploymentData`
+
+- feat: export `PRODUCTION_ENVIRONMENT_SLUG` constant
+
+- feat: add `publishedDataHash` field to `ChunkedPublishedDataRevision` and `PublishRevisionChunksTask`
+
+- feat: add configurable `serverKey` and `baseDomain` params to environment domain functions (`getPublicS3Bucket`, `getPrivateS3Bucket`, `getServiceName`, `getActiveVariables`, `getLocalActiveVariables`)
+
+- feat: store `publicS3Bucket`, `privateS3Bucket`, `serviceName` on `Environment` and `NewEnvironment` interfaces
+
+- change!: `Environment.create()` now requires `serverKey` param to compute resource names at creation time
+
+- change!: `getActiveVariables` no longer accepts `serverKey` — reads stored values from environment
+
+- change!: `getLocalActiveVariables` no longer accepts `serverKey` — reads `serviceName` from environment
+
+- change!: rename `getPublicS3Bucket` → `computePublicS3Bucket`, `getPrivateS3Bucket` → `computePrivateS3Bucket`, `getServiceName` → `computeServiceName`
+
+## [0.40.0]
+
+- feat: add support for order/email attachments in WooCommerceAddToCartTask. It is now possible to include images, PDFs and CSVs with the cart item. These resources are copied to WordPress instance's media library and referenced by the cart, order and order email.
+- fix: rendering of WooCommerce cart item custom description.
+
+## [0.39.0]
+
+- feat: add chunked published data revision domain types (`ChunkedPublishedDataRevision`, `PublishedDataRevisionKind`, `ChunkKey`, `ChunkScope`)
+
+- feat: add `PublishRevisionChunks` task type and `PublishRevisionChunksTask` webhook task
+
+- feat: add `scopes` field to session token contract
+
+- feat: add `configurationPreviewEnabled` to `Customer` interface for controlling configuration preview in Studio
+
+- feat: add `integratedAdminEnabled` to `Customer` interface for controlling admin panel visibility in Studio
+
+- feat: add `configurationPreviewEnabled` to `Customer` interface for controlling configuration preview in Studio
+
+## [0.38.0]
+
+- feat: add `configurationListEnabled` field to `Customer` domain
+
+- feat: add `activityAnalyticsEnabled` field to `Customer` domain
+
+- feat: add `activityAnalyticsEnabled` field to `Customer` domain
+
+## [0.38.0]
+
+- feat: add support for custom fees to WooCommerceAddToCartTask
+
+## [0.37.0]
+
+- feat: add customData field to WooCommerceAddToCartItem for passing custom data (e.g., shipping info, dimensions) stored in WooCommerce cart with 'salsita\_' prefix
+
+## [0.36.0]
+
+- Empty
+
+## [0.35.0]
+
+- Empty
+
+## [0.34.0]
+
+- Empty
+
+## [0.33.0]
+
+- Empty
+
+## [0.32.0]
+
+- feat: add support for "base64"" attachment type in webhook email task - can be used for sending custom attachments
+
+## [0.31.0]
+
+- Empty
+
+## [0.30.0]
+
+- Empty
+
+## [0.29.0]
+
+- feat: Introduce `BackendData` for data collected on... wait for it... backend, which is fed to the domain both in FE and webhooks
+
+## [0.28.0]
+
+- change!: `SessionTokenPayload`'s data are now required field
+
+- feat: `SessionRole`, `SessionTokenPayload` and `AccessTokenPayload` are now provided from contracts
+
+## [0.27.0]
+
+- feat: add Clerk backend API client and Clerk authorization webhook
+
+## [0.26.0]
+
+- Empty
+
+## [0.25.0]
+
+- Empty
+
+## [0.24.0]
+
+- Empty
+
+## [0.23.0]
+
+- Empty
+
+## [0.22.0] (2025-1-29)
+
+- feat: all webhook types (resource, tasks, payload, etc...) and validation functions are now available for consumption by project-sdk and possibly projects
+
+- feat: `AccessLevel`, `SessionRole` and all domain types are now available for consumption
+
+## [0.21.0] (2025-1-22)
+
+- Empty
+
+## [0.20.0] (2025-1-15)
+
+- Empty
+
+## [0.19.0] (2025-1-8)
+
+- Empty
+
+## [0.18.2] (2025-1-7)
+
+- Empty
+
+## [0.18.1] (2025-1-7)
+
+- Empty
+
+## [0.18.0] (2025-1-7)
+
+- change!: original chat-sdk package is now available under /chat import path
+
+## [0.17.0] (2024-12-18)
+
+- Empty
+
+## [0.16.0] (2024-11-26)
+
+- Empty
+
+## [0.15.0] (2024-11-19)
+
+- Empty
+
+## [0.14.0] (2024-11-15)
+
+- Empty
+
+## [0.13.0] (2024-11-7)
+
+- Empty
+
+## [0.12.0] (2024-11-5)
+
+- Empty
+
+## [0.11.0] (2024-10-25)
+
+- Empty
+
+## [0.10.0] (2024-10-22)
+
+- Empty
+
+## [0.9.0] (2024-10-16)
+
+- Empty
+
+## [0.8.0] (2024-10-10)
+
+- Empty
+
+## [0.7.0] (2024-10-9)
+
+- Empty
+
+## [0.6.0] (2024-10-2)
+
+- Empty
+
+## [0.5.0] (2024-9-27)
+
+### Bug Fixes
+
+- None
+
+### Features
+
+- None
+
+## [0.4.0] (2024-9-23)
+
+### Bug Fixes
+
+- None
+
+### Features
+
+- Providing .d.ts files for the published build
+
+## [0.3.0] (2024-9-20)
+
+### Bug Fixes
+
+- None
+
+### Features
+
+- None
+
+## 0.2.0 (2024-9-4)
+
+Initial testing release
+
+## 0.1.0 (2024-9-3)
+
+Initial testing release
+
+## 0.0.1 (2024-8-12)
+
+Initial testing release

package/LICENSE

@@ -0,0 +1,61 @@
+Salsita SDK License
+
+Copyright (c) 2026 Salsita s.r.o. All rights reserved.
+
+This software and its associated documentation (the "Software") are
+proprietary to Salsita s.r.o., Štefánikova 18/25, 150 00 Prague 5,
+Czech Republic, Company ID 272 04 201 ("Salsita"). The Software is
+licensed, not sold. By installing, copying or using the Software you
+agree to this license and to the Salsita SDK Terms at
+https://salsita.ai/terms (the "Terms"). If you do not agree,
+do not use the Software.
+
+1. License grant
+Subject to this license and the Terms, Salsita grants you a limited,
+non-exclusive, non-transferable, non-sublicensable, revocable license to:
+  (a) install and use the Software to develop, test and evaluate
+      applications built for the Salsita platform; and
+  (b) use the Software in production, and distribute it in compiled form
+      as part of such applications, only while you hold an active
+      Salsita account in good standing.
+
+2. Restrictions
+Except as expressly permitted above or by applicable law, you may not:
+  (a) redistribute, sublicense, sell, rent or lease the Software, or make
+      it available to third parties as a standalone product;
+  (b) modify, translate or create derivative works of the Software;
+  (c) reverse engineer, decompile or disassemble the Software, or attempt
+      to derive its source code;
+  (d) use the Software with, or to build, a product or service that
+      competes with or replaces the Salsita platform;
+  (e) remove or alter any copyright, trademark or licence notice.
+
+3. Ownership
+Salsita and its licensors retain all right, title and interest in the
+Software, including all intellectual property rights. No rights are
+granted except those expressly stated in this license.
+
+4. Third-party components
+The Software may include third-party components distributed under their
+own licences. Those licences govern your use of those components.
+
+5. Termination
+This license ends automatically if you breach it or if your account is
+closed. On termination you must stop using the Software and delete all
+copies in your possession. Sections 2, 3, 6 and 7 survive termination.
+
+6. Disclaimer of warranty
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+7. Limitation of liability
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, SALSITA SHALL NOT BE LIABLE FOR
+ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR
+FOR ANY LOSS OF PROFITS, REVENUE OR DATA, ARISING OUT OF OR RELATED TO
+THE SOFTWARE, WHETHER IN CONTRACT, TORT OR OTHERWISE.
+
+8. Terms
+The Terms supplement this license. If the Terms and this license
+conflict, the Terms prevail. If you have a separate signed agreement
+with Salsita covering the Software, that agreement prevails over both.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @salsita-ai/contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared TypeScript types and runtime schemas of the Salsita platform: the data that crosses the boundary between a configurator project, its webhooks, the API server and Studio.
+
+A project on the application-spec pipeline does not install this package itself: `@salsita-ai/sdk` depends on it and re-exports every entry point, so the project imports it through the SDK. Projects in the legacy format still declare it directly and import it by its own name; both paths resolve to the same code.
+
+```ts
+import { DeploymentId, ProjectSlug } from '@salsita-ai/sdk/contracts/domain'
+import type { CallbackPayload } from '@salsita-ai/sdk/contracts/webhook'
+```
+
+## Entry points
+
+There is no package-root export. Import from the path that owns the boundary; the exact paths are declared in `package.json`.
+
+| Entry point | Boundary it defines                                                                                                                                               |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`       | API access levels, session roles, and access and session token payloads.                                                                                          |
+| `clerk`     | Clerk backend client and services and the shared user, invitation, role, and token schemas.                                                                       |
+| `domain`    | Branded deployment, customer, project, environment, configuration, and revision data: types, schemas, constructors, and the state values clients compare against. |
+| `chat`      | Chat completion and stream chunks, tool definitions, validation, speech, and embeddings.                                                                          |
+| `assistant` | Experimental assistant: shared client-tool definitions and user-message metadata.                                                                                 |
+| `webhook`   | Webhook clients and building blocks, finalization tasks and resources, spreadsheet adapters.                                                                      |
+
+Runtime schemas and TypeScript types are kept aligned, so a value that passes the schema has the declared type.
+
+## Licence
+
+Proprietary software of Salsita s.r.o., published under the Salsita SDK License (the `LICENSE` file in this package) and the terms at https://salsita.ai/terms. The published package contains minified code without source maps.

package/dist/api/access-level.d.ts

@@ -0,0 +1,7 @@
+import type { ValueOf } from '@salsita-ai/common/utils';
+export declare const AccessLevel: {
+    readonly Owner: 'o';
+    readonly ReadRevision: 'rr';
+    readonly Read: 'r';
+};
+export type AccessLevel = ValueOf<typeof AccessLevel>;

package/dist/api/access-level.js

@@ -0,0 +1 @@
+export const AccessLevel={Owner:"o",ReadRevision:"rr",Read:"r"};

package/dist/api/access-token.d.ts

@@ -0,0 +1,6 @@
+import type { AccessLevel } from './access-level.js';
+export interface AccessTokenPayload {
+    configurationId: string;
+    revisionId?: string;
+    access: AccessLevel;
+}

package/dist/api/access-token.js

@@ -0,0 +1 @@
+export{};

package/dist/api/index.d.ts

@@ -0,0 +1,4 @@
+export { AccessLevel } from './access-level.js';
+export { SessionRole } from './session-role.js';
+export { type SessionTokenPayload } from './session-token.js';
+export { type AccessTokenPayload } from './access-token.js';

package/dist/api/index.js

@@ -0,0 +1 @@
+export{AccessLevel}from"./access-level.js";export{SessionRole}from"./session-role.js";

package/dist/api/session-role.d.ts

@@ -0,0 +1,8 @@
+import type { ValueOf } from '@salsita-ai/common/utils';
+export declare const SessionRole: {
+    readonly Anonymous: 'anonymous';
+    readonly User: 'user';
+    readonly Admin: 'admin';
+    readonly SuperAdmin: 'superadmin';
+};
+export type SessionRole = ValueOf<typeof SessionRole>;

package/dist/api/session-role.js

@@ -0,0 +1 @@
+export const SessionRole={Anonymous:"anonymous",User:"user",Admin:"admin",SuperAdmin:"superadmin"};

package/dist/api/session-token.d.ts

@@ -0,0 +1,22 @@
+import type { AllowedOrigin, ApplicationType, ChunkScope, ConfigurationSchemaId, DeploymentId, EnvironmentId } from '../domain/index.js';
+import type { SessionRole } from './session-role.js';
+export interface SessionTokenPayload<T extends Record<string, unknown>> {
+    readonly deploymentId: DeploymentId;
+    readonly applicationType: ApplicationType;
+    readonly publishedAdminRevisionPath?: string;
+    readonly environmentId: EnvironmentId;
+    readonly configurationSchemaId: ConfigurationSchemaId;
+    readonly role: SessionRole;
+    readonly chunkScopes?: readonly ChunkScope[];
+    /**
+     * The user the session belongs to, namespaced by the server with its source: `clerk-<id>`, `custom-<id>`,
+     * `anonymous-<browser uuid>` or `studio-<id>`. Per-user data (assistant threads) is keyed on it. The prefix
+     * is applied only on the server, so a browser-supplied id can never pass as a signed-in user. Absent when
+     * neither the auth handler nor the frontend supplied an id (old SDKs without an auth hook user id).
+     */
+    readonly sub?: string;
+    readonly origins: readonly AllowedOrigin[];
+    readonly data: T;
+    iat: number;
+    exp: number;
+}

package/dist/api/session-token.js

@@ -0,0 +1 @@
+export{};

package/dist/assistant/browser-details-tool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Client-side tool of the assistant chat: the browser draws its own details (user agent, viewport,
+ * pixel ratio, language) onto a canvas and returns the capture as an image content part. It carries
+ * no domain meaning; it proves that a client tool result reaches the model as an image.
+ *
+ * The server passes the definition to the model without an implementation, so every call becomes a
+ * client-tool interrupt; the SDK registers the browser implementation via `.client()`.
+ *
+ * The input schema is plain JSON Schema because `@tanstack/ai` converts only schemas that expose
+ * `~standard.jsonSchema` (Zod 4.2+), which the workspace's Zod 3 does not.
+ */
+export declare const browserDetailsTool: import("@tanstack/ai").ToolDefinition<{
+    type: string;
+    properties: {};
+    required: never[];
+}, undefined, "getBrowserDetails", false, undefined>;

package/dist/assistant/browser-details-tool.js

@@ -0,0 +1 @@
+import{toolDefinition as e}from"@tanstack/ai";export const browserDetailsTool=e({name:"getBrowserDetails",description:"Captures the user's browser details (user agent, viewport size, device pixel ratio, language) as an image.",inputSchema:{type:"object",properties:{},required:[]}});