streamby-core 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 0.43.0
+
+### Added
+
+- **License metadata of assets**, for crediting the ones taken from others: `sourceUrl`,
+  `creatorName`, `creatorUrl`, `licenseType` and `comments`, all optional, in `asset_rights`.
+  The license is one of a closed list (`LICENSE_TYPES`: CC BY, CC BY-SA, CC BY-ND, CC BY-NC,
+  CC BY-NC-SA, CC BY-NC-ND, CC0, Free Standard, Standard, Editorial), checked by the server; the
+  links are http(s) URLs. It can be given with an upload (query params of `GET .../upload-url`;
+  an API token needs `rights:write` too). An `assetRightsEvent` to the project's active members
+  on each change, and when an asset is deleted.
+- **Credits sheets**: project documents of a new kind, `credits`, that a workflow's Credits sheet
+  node makes (`CREDITS_SHEET_NODE`). One keeps only its sources (assets and Storage folders picked,
+  and the Ingest nodes connected to its node); its rows are made when it's read, from each asset's
+  metadata, with its status: complete when it has an asset and each has its creator, source and
+  license. Routes `GET /projects/:projectId/credits-sheets` and `.../credits-sheets/:docId`
+  (`rights:read`). Types `CreditsSheet`, `SheetRow`, `SheetSources` and `SheetStatus`.
+- MCP: `get_credits_sheet`; `request_asset_upload` takes the license metadata.
+- **The workflow defines the project.** Each resource is a node of it, bound by the resource's
+  id in its data. A resource added or removed from its section (`POST`/`DELETE` of a connection,
+  an API, an export, a pipeline, a project integration) adds or removes its node; saving the
+  workflow connects what its nodes were set to (`"__connect__:<integrationId>"`), makes the APIs
+  drafted on them (`data.connectionDraft`) and removes the resources whose nodes are gone,
+  answering `{ data, project, errors }`. A save needs `baseUpdatedAt` (a 409 over a newer version)
+  and a `nodeSchema` with `nodes` and `edges` lists (a 400 otherwise); an app connected with OAuth
+  can't remove resources through it (a 403 listing them). Pipelines and exports drafted on nodes
+  are made on save too. A node with a configuration of its own (a data source's table, an
+  Ingest's file) consumes its resource and is never merged into its node.
+  A workflow made before this is brought to it once, when it's read (`resourceNodesAt`).
+- **What depends on a resource**, asked before removing it: `GET /projects/:id/dependents/:kind/:resourceId`
+  (connections, exports, pipelines): the workflow's, exports' and pipelines' nodes that use it,
+  and the files, folders, deliverables and shots kept for it. `GET /user/integrations/:id/dependents`:
+  the project connections that use an account's integration.
+- **A change to a project's resources answers its list as it is then**, for the client to show
+  without asking again: connecting or disconnecting a database (`dbConnections`), a storage
+  (`storageConnections`, with built-ins' `available`) or an API (`connections`), deleting an
+  export (`exports`) or a pipeline (`pipelines`); `POST`/`DELETE /projects/:id/integrations`
+  answer the `project`; deleting an account's integration, each project it was disconnected
+  from (`affected`).
+- **A built-in connected again keeps the id it had** (`disconnectedBuiltins` on the project; a
+  new `disconnectedBuiltins` column in a PostgreSQL projects table, added at startup), so its
+  files and records are its own again.
+
+### Changed
+
+- **`asset_rights` holds the license metadata only.** `rightsHolder`, `licenseUrl`, `territory`,
+  `expiresAt`, `usageRestrictions` and `notes` are gone: not read, and dropped from a record when
+  it's next saved; a `licenseType` off the list reads as none. `set_asset_rights` and
+  `get_asset_rights` take and give the new fields.
+
+### Fixed
+
+- Deleting an asset or a project deletes its license metadata (it was left behind).
+- A built-in database or storage can be disconnected from a project (it was refused with a 403,
+  though the backfill already left a disconnected one alone): what the project keeps in it stays.
+- Deleting an account's integration disconnects the project connections that use it (they were
+  left pointing at nothing).
+- `POST .../connections/db` and `.../connections/storage` with an `integrationId` connect a
+  built-in too (they refused it as an unknown integration, and checked the pool's `sql`/`nosql`
+  as the type): with an integration, its name and type are the integration's.
+
+## 0.42.0
+
+### Added
+
+- **Project documents**: markdown a project's team reads and edits in the UI, and agents read and
+  keep up to date through the MCP server, with every save a version (who saved it, and when). The
+  README's Documents section documents them.
+  - **New tables: `documents` and `document_versions`.** They're created at startup in the main
+    database (collections in MongoDB; in memory without one).
+  - Routes under `/projects/:projectId/documents`: the tree, a document, creating, a new version
+    (`PATCH` with `baseVersion`; 409 with the document as it is now when it changed since), a
+    section's (`PATCH .../sections`), moving and marking exportable, the history
+    (`.../versions[/:version]`), publishing a version (`POST .../publish`) and deleting (a folder
+    with everything in it). Deleting a project deletes its documents.
+  - Permissions `docs:read`, `docs:write`, `docs:publish` and `docs:delete`. Publishing (a
+    version for the exports, or whether they deliver it: `POST .../publish`, `PATCH` with
+    `exportable`) needs `docs:publish`, not `docs:write`. The OAuth scopes grant reading
+    (`streamby:read`) and writing (`streamby:write`); an app publishes and deletes none, whatever
+    its scopes: what it edits stays a draft.
+  - In MongoDB, a save writes the document and its version in a transaction when the server has
+    them (a replica set or a sharded cluster); on a standalone server, two writes.
+  - MCP tools `list_documents`, `get_document`, `list_document_versions`, `create_document`,
+    `update_document` and `update_document_section`.
+  - An export's `documentsNode` delivers the published version of the project's exportable
+    documents (all, one folder's, or some), never a draft.
+  - A `documentEvent` to the project's active members on each change.
+  - Types `ProjectDocument`, `DocumentVersion`, `DocumentAuthor` and `DocumentKind`.
+
 ## 0.41.0
 
 ### Added

package/README.md

@@ -132,8 +132,9 @@ hash is stored, with a short prefix to tell it apart.
 | Production | `production:read`, `production:write`, `production:delete` | Sequences, shots and tasks. |
 | Workflow | `workflow:read`, `workflow:write` | The workflow and its pipelines. |
 | Exports | `exports:read`, `exports:write` | The project's exports. |
-| Rights | `rights:read`, `rights:write` | Assets' rights. |
+| Rights | `rights:read`, `rights:write` | Assets' license metadata, and reading credits sheets. |
 | Jobs | `jobs:read`, `jobs:run` | Following jobs; starting them (transcoding, rendering, AI, publishing a deliverable). |
+| Documents | `docs:read`, `docs:write`, `docs:publish`, `docs:delete` | The project's documents: reading them and their history; creating, editing and moving them; publishing them (the version its exports deliver, and whether they deliver it); deleting them. |
 | Account | `projects:create` | Creating projects. A user's token only; the token reaches what it creates. |
 
 `PROJECT_PERMISSIONS` and `ACCOUNT_PERMISSIONS` are exported. A route no permission covers
@@ -185,15 +186,16 @@ approved, and never more than the user can: their role in each project still app
 
 | Scope | Permissions |
 |---|---|
-| `streamby:read` | Every `:read` permission: `project:read`, `members:read`, `assets:read`, `production:read`, `workflow:read`, `exports:read`, `rights:read`, `jobs:read`. |
-| `streamby:write` | Those, and making and changing: `project:update`, `assets:write`, `production:write`, `workflow:write`, `exports:write`, `rights:write`, `jobs:run`, `projects:create`. |
+| `streamby:read` | Every `:read` permission: `project:read`, `members:read`, `assets:read`, `production:read`, `workflow:read`, `exports:read`, `rights:read`, `jobs:read`, `docs:read`. |
+| `streamby:write` | Those, and making and changing: `project:update`, `assets:write`, `production:write`, `workflow:write`, `exports:write`, `rights:write`, `jobs:run`, `projects:create`, `docs:write`. |
 
 No scope grants deleting (`*:delete`, `project:delete`) nor managing members. And since some
 write permissions also reach routes that delete (`project:update` a connection, a worker or an
 integration; `workflow:write` a pipeline; `exports:write` an export), **an app's `DELETE` is
 refused (403) whatever its route**, but taking a deliverable's mark off, which only forgets the
-mark (the asset stays). API tokens aren't affected. Other scopes (`profile`, `email`) grant
-nothing in StreamBy. `OAUTH_SCOPE_PERMISSIONS` is exported.
+mark (the asset stays). Nor does an app publish a document (`POST .../publish`, or a `PATCH`
+changing `exportable`), whatever its scopes: what it edits stays a draft until someone publishes
+it. API tokens aren't affected. Other scopes (`profile`, `email`) grant nothing in StreamBy. `OAUTH_SCOPE_PERMISSIONS` is exported.
 
 **Telling clients where to sign in**
 
@@ -283,7 +285,7 @@ A token sees only the tools whose permissions it has (an app: those its scopes g
 | `list_assets` (by category, optionally in one storage connection, and filtered by name), `get_asset_metadata` | `assets:read` |
 | `update_asset_metadata` | `assets:write` |
 | `delete_asset` | `assets:delete` |
-| `get_asset_rights` / `set_asset_rights` | `rights:read` / `rights:write` |
+| `get_asset_rights`, `get_credits_sheet` / `set_asset_rights` | `rights:read` / `rights:write` |
 | `get_workflow`, `list_pipelines`, `get_pipeline` | `workflow:read` |
 | `create_pipeline`, `update_pipeline` | `workflow:write` |
 | `list_exports` | `project:read` and `exports:read` |
@@ -296,7 +298,9 @@ A token sees only the tools whose permissions it has (an app: those its scopes g
 | `create_sequence`, `create_shot`, `create_task` | `production:write` and `workflow:write` |
 | `delete_sequence`, `delete_shot`, `delete_task` | `production:delete` |
 | `list_asset_versions`, `get_asset_download_url`, `list_deliverables` | `assets:read` |
-| `request_asset_upload`, `mark_deliverable`, `remove_deliverable` | `assets:write` |
+| `request_asset_upload` (with license metadata, also `rights:write`), `mark_deliverable`, `remove_deliverable` | `assets:write` |
+| `list_documents`, `get_document`, `list_document_versions` | `docs:read` |
+| `create_document`, `update_document`, `update_document_section` | `docs:write` |
 
 The tools take the path a user does in the UI, and each one's description says where its
 result shows there. Production data lives under a production node of the project's workflow:
@@ -446,6 +450,87 @@ person removes it in their account's connected apps (in Nhexa, accounts.nhexa.cl
 
 ---
 
+## 📄 Documents
+
+Each project keeps its documents: markdown its team reads and edits (its concept, its
+architecture, its decisions), and agents read and keep up to date through the MCP server. They're
+kept in the main database (the `documents` and `document_versions` tables, created at startup,
+or collections), each one in a single project, in folders.
+
+- **Every save is a version**, with who saved it and when: a user, an API token, or an app on a
+  user's behalf (`{ userId, username, via: 'session' | 'apiToken' | 'oauth', tokenId?, clientId?, clientName? }`).
+- **Nothing is overwritten without notice.** A change says the version it was made on
+  (`baseVersion`); if someone saved another one since, it's refused with a 409 and the document
+  as it is now, to read again.
+- **A section** is what's under a heading (`## Architecture`), up to the next one of the same
+  level or above: it can be replaced alone, the rest untouched.
+- **Drafts and published versions.** A document marked exportable delivers, through the project's
+  exports, only the version published from its history; editing it changes nothing exported until
+  another version is published. An export's `documentsNode` (on the StreamBy node's data input)
+  delivers them, `[{ id, title, parentId, position, version, content, publishedAt }]`: all the
+  project's, those in one folder (`data.folderId`), or some (`data.documentIds`).
+- **In real time**, a `documentEvent` reaches the project's active members on each change:
+  `{ projectId, action: 'created' | 'saved' | 'changed' | 'deleted', documentIds, version?, title?, author }`
+  (`saved` is a new version; `changed`, a move or a publication).
+
+| Route | Permission |
+|---|---|
+| `GET /projects/:projectId/documents`: the tree, without contents | `docs:read` |
+| `POST /projects/:projectId/documents` `{ title, content?, kind?: 'document' \| 'folder' \| 'credits', parentId?, position? }` | `docs:write` |
+| `GET /projects/:projectId/documents/:docId` | `docs:read` |
+| `PATCH /projects/:projectId/documents/:docId` `{ baseVersion, title?, content? }` (a new version) and/or `{ parentId?, position? }` | `docs:write` |
+| `PATCH /projects/:projectId/documents/:docId` `{ exportable }` | `docs:write` and `docs:publish` |
+| `PATCH /projects/:projectId/documents/:docId/sections` `{ baseVersion, heading, content }` | `docs:write` |
+| `GET /projects/:projectId/documents/:docId/versions` and `/versions/:version` | `docs:read` |
+| `POST /projects/:projectId/documents/:docId/publish` `{ version }` (`null`: none) | `docs:publish` |
+| `DELETE /projects/:projectId/documents/:docId` (a folder, with everything in it) | `docs:delete` |
+
+Editors and admins create, edit, publish and delete them; viewers read them. An app connected
+with OAuth reads and edits them, but publishes and deletes none: what it edits stays a draft.
+
+In MongoDB, a save writes the document and its version in a transaction when the server has them
+(a replica set or a sharded cluster). A standalone server doesn't: there they're two writes.
+
+---
+
+## ©️ License metadata and credits sheets
+
+Each asset can carry its **license metadata**, for all its versions: where it was taken from
+(`sourceUrl`), who made it (`creatorName`, `creatorUrl`), its license (`licenseType`) and
+`comments`. All are optional; the links are http(s) URLs, and the license is one of
+`CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC`, `CC BY-NC-SA`, `CC BY-NC-ND`, `CC0`, `Free Standard`,
+`Standard` and `Editorial` (`LICENSE_TYPES`, exported). It's kept in the `asset_rights`
+collection, the only place it lives, and goes with its asset or its project when they're deleted.
+It can be given with the upload: `licenseType`, `sourceUrl`, `creatorName`, `creatorUrl` and
+`comments` as query params of `GET .../upload-url` (an API token needs `rights:write` too).
+
+A **credits sheet** is a project document of kind `credits`, made by a Credits sheet node of the
+workflow (its `data.documentId`). It keeps only what feeds it, as its content:
+`{ "assetIds": [...], "folderIds": [...] }` (assets and Storage folders picked, with everything
+inside them); the Ingest nodes connected to its node feed it too, with the asset each imports
+(`data.fileId`). Its rows are made each time it's read, from each asset's metadata, so two sheets
+with the same asset show the same, and editing a row is setting its asset's metadata. Deleting
+the node leaves the document; an asset deleted leaves the sheet.
+
+A sheet is **complete** when it has an asset and each one has its creator, source and license;
+**incomplete** otherwise, each row listing what it lacks (`missing`).
+
+- **In real time**, an `assetRightsEvent` reaches the project's active members on each change:
+  `{ projectId, action: 'saved' | 'deleted', assetIds, rights? }` (`deleted`: the asset is gone).
+
+| Route | Permission |
+|---|---|
+| `GET /projects/:projectId/assets/:assetId/rights` | `rights:read` |
+| `PUT /projects/:projectId/assets/:assetId/rights` `{ sourceUrl?, creatorName?, creatorUrl?, licenseType?, comments? }` (the fields given; empty or `null` clears one) | `rights:write` |
+| `GET /projects/:projectId/credits-sheets`: each with `{ id, title, status, rows, incomplete }` | `rights:read` |
+| `GET /projects/:projectId/credits-sheets/:docId`: `{ document, sources, rows, status }` | `rights:read` |
+
+Each row: `{ assetId, name, category, sourceUrl, creatorName, creatorUrl, licenseType, comments, missing, from }`,
+`from` saying how it got there (`asset`, `folder`, `ingest`). Editors and admins set the metadata
+(as they edit the asset); every member reads it.
+
+---
+
 ## ⚙️ Processing workers
 
 StreamBy doesn't process assets itself (optimizing a glTF, making LODs, transcoding...): it
@@ -551,6 +636,56 @@ A job its worker doesn't complete before its deadline is sent again, up to
 
 ---
 
+## 🧭 The workflow defines the project
+
+Each of a project's resources (a database, an API, a storage, a service, an export, a pipeline)
+is a node of its workflow, bound to it by the resource's id in its data (`connectionId`,
+`storageConnectionId`, `integrationConnectionId`, `exportId`, `pipelineId`). One node per
+resource; a data source reading one of a database's tables is a node of its own.
+
+- **From a section** (or an agent): adding a resource adds its node to the saved workflow, and
+  removing it removes its nodes.
+- **Saving the workflow** (`PATCH /projects/:id/workflow` `{ nodeSchema, baseUpdatedAt }`) makes
+  the project what it defines, then answers `{ data, project, errors }`: the workflow, the
+  project's lists as they are then, and what couldn't be done. A node set to an integration the
+  project doesn't have (`"__connect__:<integrationId>"`) connects it; an API, a pipeline or an
+  export drafted on a node (`data.connectionDraft`, `data.pipelineDraft`, `data.exportDraft`) is
+  made; a resource whose nodes are all gone is removed.
+  - `baseUpdatedAt` (the workflow's `updatedAt` as it was read) is required with a `nodeSchema`,
+    and `nodeSchema` must be `{ nodes: [...], edges: [...] }`: a 400 otherwise. Saved over a newer
+    version, it's a 409 with the workflow as it is now.
+  - An app connected with OAuth removes nothing through it, as it deletes nothing: a save that
+    would remove resources is a 403 listing them (`removing`).
+  - A node holding a configuration of its own beside its resource's id (a data source reading one
+    table, an Ingest importing one file) consumes the resource: never merged into its node.
+- **Reading it** (`GET`) never rewrites it, except once, for a workflow made before this: the
+  nodes once drawn from the project's lists are bound by their ids, a resource without a node gets
+  one, and two nodes of the same resource are merged.
+
+---
+
+## 🔌 Removing a project's resources
+
+Before a connection (database, API, storage, service), an export or a pipeline is removed, the
+UI asks what depends on it: `GET /projects/:id/dependents/:kind/:resourceId` (`kind`: `db`,
+`api`, `storage`, `service`, `export`, `pipeline`; `project:read`) answers
+`{ dependents: [{ type, name, id?, count? }] }`: the nodes that use it in the workflow, the
+exports and the pipelines (`workflow`, `export`, `pipeline`: they stop working without it), and
+what's kept for it (`files` and `folders` of a storage, `deliverables` and `shots` of an
+export). Removing it changes none of them.
+
+**Built-ins** (the host's database and storage) are disconnected like any connection, and what
+the project keeps in them stays. They're connected again as any integration is, by its id in
+the pool (`GET /user/integrations`): `POST /projects/:id/integrations` `{ integrationId }`, or
+`POST .../connections/db` and `.../connections/storage` with `integrationId` (its name and type
+come from the integration). One connected again keeps the id it had (`disconnectedBuiltins`
+on the project), so its files and records are its own again.
+
+Deleting an account's integration disconnects the project connections that use it;
+`GET /user/integrations/:id/dependents` lists them first.
+
+---
+
 ## 👥 Project roles
 
 What a user can do in a project depends on their role in that project, as an active member
@@ -560,7 +695,7 @@ What a user can do in a project depends on their role in that project, as an act
 | Role | Can |
 |---|---|
 | `viewer` | See the project and its content, and archive the project in their own list. |
-| `editor` | Everything a viewer can, plus change the project: its details, connections, exports, files and folders, workflow, pipelines, production, reviews, rights, and start jobs. |
+| `editor` | Everything a viewer can, plus change the project: its details, connections, exports, files and folders, workflow, pipelines, production, reviews, rights, documents, and start jobs. |
 | `admin` | Everything an editor can, plus manage the project's members and delete the project. |
 
 A project's public exports (`GET /streamby/:projectId/export/:exportName`) are read without a

package/dist/adapters/database/connectionManager.js

@@ -101,6 +101,7 @@ const createTables = async (pool) => {
       ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS workflow            JSONB;
       ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS pipelines           JSONB DEFAULT '[]';
       ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "builtinBackfilledAt" TIMESTAMP WITH TIME ZONE;
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "disconnectedBuiltins" JSONB DEFAULT '[]';
       -- Written when a project is made (routes/project) and by its connection routes.
       ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS public              BOOLEAN DEFAULT TRUE;
       ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS category            TEXT;
@@ -254,6 +255,38 @@ const createTables = async (pool) => {
       ALTER TABLE streamby.mcp_audit ALTER COLUMN "tokenId" DROP NOT NULL;
     `);
         console.log('✅ "mcp_audit" table ensured to exist.');
+        // Projects' documents and their versions (see services/documents). Main db only.
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.documents (
+        id                  TEXT PRIMARY KEY,
+        "projectId"         VARCHAR(255) NOT NULL,
+        kind                VARCHAR(20) NOT NULL DEFAULT 'document',
+        title               TEXT NOT NULL,
+        "parentId"          TEXT,
+        position            INTEGER NOT NULL DEFAULT 0,
+        content             TEXT NOT NULL DEFAULT '',
+        version             INTEGER NOT NULL,
+        exportable          BOOLEAN NOT NULL DEFAULT FALSE,
+        "publishedVersion"  INTEGER,
+        "createdAt"         TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        "createdBy"         JSONB NOT NULL,
+        "updatedAt"         TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        "updatedBy"         JSONB NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS documents_project_idx ON streamby.documents ("projectId");
+      CREATE TABLE IF NOT EXISTS streamby.document_versions (
+        "documentId"  TEXT NOT NULL,
+        "projectId"   VARCHAR(255) NOT NULL,
+        version       INTEGER NOT NULL,
+        title         TEXT NOT NULL,
+        content       TEXT NOT NULL,
+        author        JSONB NOT NULL,
+        "createdAt"   TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        PRIMARY KEY ("documentId", version)
+      );
+      CREATE INDEX IF NOT EXISTS document_versions_project_idx ON streamby.document_versions ("projectId");
+    `);
+        console.log('✅ "documents" and "document_versions" tables ensured to exist.');
     }
     catch (error) {
         console.error('❌ Error ensuring tables exist:', error);

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 export { createStreamByRouter } from './middleware/createRouter';
 export { emitToUser } from './services/wsHub';
 export { createNotification } from './services/notification';
-export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenKind, ApiTokenPermission, ProjectPermission, AccountPermission, OAuthClientInfo, OAuthResourceConfig } from './types';
+export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenKind, ApiTokenPermission, ProjectPermission, AccountPermission, OAuthClientInfo, OAuthResourceConfig, ProjectDocument, DocumentVersion, DocumentAuthor, DocumentKind } from './types';
 export { resolveApiToken, API_TOKEN_PREFIX } from './services/apiTokens';
 export { PROJECT_PERMISSIONS, ACCOUNT_PERMISSIONS } from './services/apiTokenPermissions';
+export { LICENSE_TYPES } from './services/rights';
+export type { AssetRights, LicenseType } from './services/rights';
+export { CREDITS_SHEET_NODE } from './services/creditsSheets';
+export type { CreditsSheet, SheetRow, SheetSources, SheetStatus } from './services/creditsSheets';
 export type { ResolvedApiToken } from './services/apiTokens';
 export { createOAuthTokenVerifier, looksLikeOAuthAccessToken, protectedResourceMetadata, defaultResourceMetadataUrl, permissionsForOAuthScopes, OAUTH_SCOPES, OAUTH_SCOPE_PERMISSIONS, } from './services/oauthTokens';
 export type { VerifiedOAuthToken, OAuthTokenVerifierOptions, Jwks, Jwk, OAuthScope } from './services/oauthTokens';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAUTH_SCOPE_PERMISSIONS = exports.OAUTH_SCOPES = exports.permissionsForOAuthScopes = exports.defaultResourceMetadataUrl = exports.protectedResourceMetadata = exports.looksLikeOAuthAccessToken = exports.createOAuthTokenVerifier = exports.ACCOUNT_PERMISSIONS = exports.PROJECT_PERMISSIONS = exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
+exports.OAUTH_SCOPE_PERMISSIONS = exports.OAUTH_SCOPES = exports.permissionsForOAuthScopes = exports.defaultResourceMetadataUrl = exports.protectedResourceMetadata = exports.looksLikeOAuthAccessToken = exports.createOAuthTokenVerifier = exports.CREDITS_SHEET_NODE = exports.LICENSE_TYPES = exports.ACCOUNT_PERMISSIONS = exports.PROJECT_PERMISSIONS = exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
 var createRouter_1 = require("./middleware/createRouter");
 Object.defineProperty(exports, "createStreamByRouter", { enumerable: true, get: function () { return createRouter_1.createStreamByRouter; } });
 var wsHub_1 = require("./services/wsHub");
@@ -13,6 +13,10 @@ Object.defineProperty(exports, "API_TOKEN_PREFIX", { enumerable: true, get: func
 var apiTokenPermissions_1 = require("./services/apiTokenPermissions");
 Object.defineProperty(exports, "PROJECT_PERMISSIONS", { enumerable: true, get: function () { return apiTokenPermissions_1.PROJECT_PERMISSIONS; } });
 Object.defineProperty(exports, "ACCOUNT_PERMISSIONS", { enumerable: true, get: function () { return apiTokenPermissions_1.ACCOUNT_PERMISSIONS; } });
+var rights_1 = require("./services/rights");
+Object.defineProperty(exports, "LICENSE_TYPES", { enumerable: true, get: function () { return rights_1.LICENSE_TYPES; } });
+var creditsSheets_1 = require("./services/creditsSheets");
+Object.defineProperty(exports, "CREDITS_SHEET_NODE", { enumerable: true, get: function () { return creditsSheets_1.CREDITS_SHEET_NODE; } });
 var oauthTokens_1 = require("./services/oauthTokens");
 Object.defineProperty(exports, "createOAuthTokenVerifier", { enumerable: true, get: function () { return oauthTokens_1.createOAuthTokenVerifier; } });
 Object.defineProperty(exports, "looksLikeOAuthAccessToken", { enumerable: true, get: function () { return oauthTokens_1.looksLikeOAuthAccessToken; } });

package/dist/mcp/tools.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOLS = void 0;
 const zod_1 = require("zod");
+const rights_1 = require("../services/rights");
 const tool = (definition) => definition;
 const id = (what) => zod_1.z.string().min(1).describe(`The ${what}'s id`);
 const projectId = id('project');
@@ -25,14 +26,13 @@ const taskFields = {
     dueDate: zod_1.z.string().optional().describe('An ISO 8601 date'),
     notes: zod_1.z.string().optional(),
 };
+// An asset's license metadata: what crediting it takes. Each is optional; an empty one clears it.
 const rightsFields = {
-    rightsHolder: zod_1.z.string().optional(),
-    licenseType: zod_1.z.string().optional().describe('e.g. CC0, CC BY 4.0, proprietary'),
-    licenseUrl: zod_1.z.string().optional(),
-    territory: zod_1.z.string().optional(),
-    expiresAt: zod_1.z.string().optional().describe('An ISO 8601 date'),
-    usageRestrictions: zod_1.z.string().optional(),
-    notes: zod_1.z.string().optional(),
+    sourceUrl: zod_1.z.string().optional().describe('Where the asset was taken from (an http(s) URL)'),
+    creatorName: zod_1.z.string().optional().describe('Who made it'),
+    creatorUrl: zod_1.z.string().optional().describe("The creator's page (an http(s) URL)"),
+    licenseType: zod_1.z.enum(rights_1.LICENSE_TYPES).or(zod_1.z.literal('')).optional().describe('Its license'),
+    comments: zod_1.z.string().optional(),
 };
 // Only the fields given (an unset optional field isn't sent as undefined).
 const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
@@ -86,7 +86,7 @@ exports.TOOLS = [
     }),
     tool({
         name: 'get_asset_rights', title: "Get an asset's rights", permissions: ['rights:read'],
-        description: "An asset's rights: holder, license, territory, expiry and restrictions.",
+        description: "An asset's license metadata: where it was taken from, its creator (name and link), its license and comments; null if it has none.",
         input: { projectId, assetId: id('asset') },
         projectOf: byProject,
         call: ({ projectId, assetId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights` }),
@@ -164,7 +164,7 @@ exports.TOOLS = [
     }),
     tool({
         name: 'set_asset_rights', title: "Set an asset's rights", permissions: ['rights:write'], write: true,
-        description: "Sets an asset's rights: holder, license, territory, expiry, restrictions and notes. They show in the file's Rights tab, in Storage.",
+        description: `Sets an asset's license metadata (the fields given; an empty one clears it): where it was taken from, its creator (name and link), its license (one of: ${rights_1.LICENSE_TYPES.join(', ')}) and comments. It shows in the file's Rights tab, in Storage, and in every credits sheet the asset is in.`,
         input: { projectId, assetId: id('asset'), ...rightsFields },
         projectOf: byProject,
         call: ({ projectId, assetId, ...rights }) => ({ method: 'PUT', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights`, body: defined(rights) }),
@@ -245,6 +245,7 @@ exports.TOOLS = [
             "It doesn't upload anything: the file is sent by the tool that has it (for example Blender's MCP, running Python), with an HTTP PUT of its bytes to `upload.url` and the `upload.headers` given, before `expiresAt`.",
             "The URL works for that file only. A new version keeps the asset's URL (it replaces what it serves); the earlier ones are archived and can still be downloaded.",
             "Categories: images, audios, videos, 3d-models (.glb, .gltf, .obj, .fbx, .stl, .ply); contentType must match it.",
+            "For a new asset taken from someone else (a CC model, a stock image), give its license metadata too, so it's credited (it needs the rights:write permission); for a new version, set_asset_rights changes it.",
         ].join(' '),
         input: {
             projectId,
@@ -253,10 +254,14 @@ exports.TOOLS = [
             contentType: zod_1.z.string().min(1).describe('Its MIME type (e.g. model/gltf-binary, image/png, video/mp4)'),
             assetId: zod_1.z.string().optional().describe('An existing asset to upload a new version of; a new asset if not given'),
             connectionId: zod_1.z.string().optional().describe("A storage connection to store it in; the project's built-in storage if not given"),
+            ...rightsFields,
         },
         projectOf: byProject,
-        call: ({ projectId, category, fileName, contentType, assetId, connectionId }) => {
-            const query = new URLSearchParams({ fileName, contentType, ...(connectionId && !assetId ? { category } : {}) });
+        call: ({ projectId, category, fileName, contentType, assetId, connectionId, ...rights }) => {
+            const query = new URLSearchParams({
+                fileName, contentType, ...(connectionId && !assetId ? { category } : {}),
+                ...(assetId ? {} : defined(rights)),
+            });
             const files = connectionId ? `/projects/${enc(projectId)}/connections/storage/${enc(connectionId)}` : `/projects/${enc(projectId)}/storage`;
             const path = assetId
                 ? `${files}/files/${enc(assetId)}/replace-url`
@@ -358,6 +363,83 @@ exports.TOOLS = [
         call: ({ projectId, jobId }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/jobs/${enc(jobId)}/retry` }),
         pick: (data) => data?.job,
     }),
+    // ── Credits sheets ──
+    tool({
+        name: 'get_credits_sheet', title: 'Read a credits sheet', permissions: ['rights:read'],
+        description: "A credits sheet (a document of kind 'credits', made by a Credits sheet node of the workflow; list_documents lists them): a row per asset fed to it (picked on it, in a Storage folder picked, or imported by an Ingest node connected to it) with that asset's license metadata as it is now, and its status: 'complete' when it has an asset and each has its creator, source and license; 'incomplete' otherwise, each row listing what it lacks (`missing`). To fill a row in, set_asset_rights on its asset.",
+        input: { projectId, documentId: id('credits sheet') },
+        projectOf: byProject,
+        call: ({ projectId, documentId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/credits-sheets/${enc(documentId)}` }),
+        pick: (data) => data && { id: data.document?.id, title: data.document?.title, status: data.status, rows: data.rows },
+    }),
+    // ── Documents ──
+    tool({
+        name: 'list_documents', title: 'List documents', permissions: ['docs:read'],
+        description: "A project's documents (its concept, architecture, decisions...), as the tree of its Documents section shows them: each one's id, title, folder (parentId; a folder's kind is 'folder'), position, current version and the version published through its exports, without their content (read one with get_document).",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/documents` }),
+        pick: (data) => data?.documents ?? [],
+    }),
+    tool({
+        name: 'get_document', title: 'Read a document', permissions: ['docs:read'],
+        description: "A document's markdown and its current version, the one an update is made on. With `version`, that past version instead (see list_document_versions).",
+        input: { projectId, documentId: id('document'), version: zod_1.z.number().int().min(1).optional().describe('A past version to read; the current one if not given') },
+        projectOf: byProject,
+        call: ({ projectId, documentId, version }) => ({
+            method: 'GET',
+            path: `/projects/${enc(projectId)}/documents/${enc(documentId)}${version ? `/versions/${version}` : ''}`,
+        }),
+        pick: (data) => data?.document ?? data?.version,
+    }),
+    tool({
+        name: 'list_document_versions', title: "List a document's versions", permissions: ['docs:read'],
+        description: "A document's history, the latest first: each version's number, title, who saved it (a user, an API token, or an app on a user's behalf) and when.",
+        input: { projectId, documentId: id('document') },
+        projectOf: byProject,
+        call: ({ projectId, documentId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}/versions` }),
+        pick: (data) => data?.versions ?? [],
+    }),
+    tool({
+        name: 'create_document', title: 'Create a document', permissions: ['docs:write'], write: true,
+        description: "Creates a markdown document (or, with kind 'folder', a folder to group them) in a project's Documents section, at the end of its folder. It's a draft: nothing is exported until someone publishes a version of it in the UI.",
+        input: {
+            projectId,
+            title: zod_1.z.string().min(1),
+            content: zod_1.z.string().optional().describe('Its markdown'),
+            kind: zod_1.z.enum(['document', 'folder']).optional(),
+            parentId: zod_1.z.string().optional().describe("The folder it goes in (a folder's id); at the top if not given"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/documents`, body: defined(fields) }),
+        pick: (data) => data?.document,
+    }),
+    tool({
+        name: 'update_document', title: 'Update a document', permissions: ['docs:write'], write: true,
+        description: "Saves a new version of a document: its whole markdown, its title, or both. `baseVersion` is the version it was read at (get_document): if someone saved another one since, nothing is saved and the answer says so; read it again and make the change on the new version. To change one part, update_document_section rewrites less.",
+        input: {
+            projectId, documentId: id('document'),
+            baseVersion: zod_1.z.number().int().min(1).describe('The version the change was made on'),
+            title: zod_1.z.string().min(1).optional(),
+            content: zod_1.z.string().optional().describe('The whole new markdown'),
+        },
+        projectOf: byProject,
+        call: ({ projectId, documentId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}`, body: defined(fields) }),
+        pick: (data) => data?.document,
+    }),
+    tool({
+        name: 'update_document_section', title: "Update a document's section", permissions: ['docs:write'], write: true,
+        description: "Saves a new version of a document with only what's under one of its headings replaced (up to the next heading of the same level or above), the rest untouched. `heading` is the heading as written (\"## Architecture\") or its title alone. `baseVersion` is the version it was read at: if the document changed since, nothing is saved; read it again.",
+        input: {
+            projectId, documentId: id('document'),
+            baseVersion: zod_1.z.number().int().min(1).describe('The version the change was made on'),
+            heading: zod_1.z.string().min(1).describe('The section\'s heading, e.g. "## Architecture"'),
+            content: zod_1.z.string().describe("The section's new markdown, without its heading"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, documentId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}/sections`, body: fields }),
+        pick: (data) => data?.document,
+    }),
     // ── Projects ──
     tool({
         name: 'create_project', title: 'Create a project', permissions: ['projects:create'], write: true,

package/dist/mcp/workflowNodes.js

@@ -9,6 +9,7 @@ const crypto_1 = __importDefault(require("crypto"));
 const manager_1 = require("../models/manager");
 const auth_1 = require("../utils/auth");
 const auth_2 = require("../services/auth");
+const workflowResources_1 = require("../services/workflowResources");
 // The node types that make a workflow's production section (as the UI groups them).
 const PRODUCTION_NODE_TYPES = new Set(['shotNode', 'assemblyNode', 'masterNode']);
 /** A Shot node, as the UI makes one dropped on the canvas without a position. */
@@ -32,14 +33,19 @@ async function ensureWorkflowNode(requirement, projectId, auth, api) {
     const project = await (0, manager_1.getModel)('projects').findOne({ _id: projectId });
     if (!project || !(0, auth_1.activeMemberOf)(project, auth.userId))
         return null;
-    const schema = project.workflow?.nodeSchema ?? null;
-    const nodes = Array.isArray(schema?.nodes) ? schema.nodes : [];
+    // The workflow as it's answered (brought to define the project, if it wasn't yet), and saved
+    // on that version: what changed since isn't undone.
+    const workflow = await (0, workflowResources_1.readWorkflow)(project);
+    const nodes = Array.isArray(workflow?.nodeSchema?.nodes) ? workflow.nodeSchema.nodes : [];
     if (nodes.some(node => PRODUCTION_NODE_TYPES.has(node?.type)))
         return null;
     const answer = await api({
         method: 'PATCH',
         path: `/projects/${encodeURIComponent(projectId)}/workflow`,
-        body: { nodeSchema: { ...(schema ?? {}), nodes: [...nodes, (0, exports.newShotNode)()], edges: Array.isArray(schema?.edges) ? schema.edges : [] } },
+        body: {
+            nodeSchema: { nodes: [...nodes, (0, exports.newShotNode)()], edges: Array.isArray(workflow?.nodeSchema?.edges) ? workflow.nodeSchema.edges : [] },
+            baseUpdatedAt: new Date(workflow.updatedAt).toISOString(),
+        },
     });
     if (answer.status >= 200 && answer.status < 300)
         return null;

package/dist/middleware/createRouter.js

@@ -44,11 +44,15 @@ const worker_1 = require("./routes/worker");
 const workerCallback_1 = require("./routes/workerCallback");
 const workerJobs_1 = require("../services/workerJobs");
 const deliverable_1 = require("./routes/deliverable");
+const document_1 = require("./routes/document");
+const projectResources_1 = require("./routes/projectResources");
+const documents_1 = require("../services/documents");
 function createStreamByRouter(config) {
     const router = express_1.default.Router();
     if (config.encrypt)
         (0, encryption_1.setEncryptionKey)(config.encrypt, config.encryptPreviousKeys);
     (0, jobStore_1.setJobStoreDatabase)(config);
+    (0, documents_1.setDocumentStoreDatabase)(config);
     // Establish DB connections asynchronously (Postgres/Mongo + schema migrations).
     // Until they're ready, HOLD incoming requests instead of letting them through —
     // route handlers resolve projects/exports (e.g. the /menu-list export) against a
@@ -149,5 +153,7 @@ function createStreamByRouter(config) {
     router.use((0, pipeline_1.pipelineRouter)(config));
     router.use((0, worker_1.workerRouter)({ ...config, adapter }));
     router.use((0, deliverable_1.deliverableRouter)({ ...config, adapter }));
+    router.use((0, document_1.documentRouter)(config));
+    router.use((0, projectResources_1.projectResourcesRouter)(config));
     return router;
 }

package/dist/middleware/routes/connection.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.connectionRouter = connectionRouter;
 const express_1 = require("express");
+const workflowResources_1 = require("../../services/workflowResources");
 const manager_1 = require("../../models/manager");
 const auth_1 = require("../../utils/auth");
 const connection_1 = require("../../services/connection");
@@ -88,7 +89,8 @@ function connectionRouter(config) {
                 ...(description !== undefined && { description }),
                 ...(token !== undefined && { token }),
             });
-            return res.status(201).json({ data: (0, sanitize_1.sanitizeConnection)(connection) });
+            await (0, workflowResources_1.addToWorkflow)(projectId, 'api', connection);
+            return res.status(201).json({ data: (0, sanitize_1.sanitizeConnection)(connection), connections: (0, sanitize_1.sanitizeConnections)((await Project.findOne({ _id: projectId }))?.connections) });
         }
         catch (err) {
             res.status(500).json({ message: 'Failed to add connection', details: err.message });
@@ -178,7 +180,8 @@ function connectionRouter(config) {
                 return res.status(404).json({ message: 'Connection not found' });
             }
             await (0, connection_1.deleteConnection)(config, projectId, connectionId);
-            return res.status(200).json({ message: 'Connection deleted successfully.' });
+            await (0, workflowResources_1.removeFromWorkflow)(projectId, 'api', connectionId);
+            return res.status(200).json({ message: 'Connection deleted successfully.', connections: (0, sanitize_1.sanitizeConnections)((await Project.findOne({ _id: projectId }))?.connections) });
         }
         catch (err) {
             res.status(500).json({ message: 'Failed to delete connection', details: err.message });