@mestra-dev/contract 0.0.37 → 0.0.38

package/dist/index.d.ts

@@ -98,7 +98,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 					},
 					{
 						readonly name: "Files";
-						readonly description: "S3 file upload (presigned POST to a temporary `.tmp` key), confirm (magic-byte validation then promote to final key), profile and workspace picture upload/confirm/delete, comment attachment upload/confirm, list task comment files with download URLs, folder create/delete, list (includes pin metadata; excludes `.tmp` objects), pin/unpin, download, and file delete. General uploads accept JPEG/PNG/WebP/PDF; profile/workspace pictures accept JPEG/PNG only (0.5 MB). Workspace file routes require active collaborator status and crm::files access; comment attachments require crm::tasks write/read.";
+						readonly description: "S3 file upload (presigned POST to a temporary `.tmp` key), confirm (magic-byte validation then promote to final key), optional nested folder destination under `{workspace}/folders/{path}/`, profile and workspace picture upload/confirm/delete, comment attachment upload/confirm, list task comment files with download URLs, folder create/delete (nested paths), list (includes pin metadata; excludes `.tmp` objects), pin/unpin, download by relative path, move, and file delete. General uploads accept JPEG/PNG/WebP/PDF; profile/workspace pictures accept JPEG/PNG only (0.5 MB). Workspace file routes require active collaborator status and crm::files access; comment attachments require crm::tasks write/read.";
 					},
 					{
 						readonly name: "Chat";
@@ -1451,7 +1451,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly type: "string";
 									readonly minLength: 1;
 									readonly maxLength: 200;
-									readonly description: "Safe file name (no path separators, not `.tmp`).";
+									readonly description: "Safe leaf file name (no path separators, not `.tmp`).";
 									readonly example: "invoice-2026.pdf";
 								};
 								readonly contentType: {
@@ -1468,6 +1468,13 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly format: "uuid";
 									readonly description: "Workspace identifier.";
 								};
+								readonly folder: {
+									readonly type: "string";
+									readonly minLength: 1;
+									readonly maxLength: 800;
+									readonly description: "Optional nested folder path under `{workspace}/folders/` (e.g. `a/b`). Each segment is a safe name; max depth 10. The folder marker must already exist via `/files/create-folder`. Omitting uploads to the workspace root.";
+									readonly example: "contracts/2026";
+								};
 							};
 						};
 						readonly ConfirmFileRequest: {
@@ -1481,7 +1488,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly type: "string";
 									readonly minLength: 1;
 									readonly maxLength: 200;
-									readonly description: "Original file name used for `/files/upload` (without the `.tmp` suffix).";
+									readonly description: "Original leaf file name used for `/files/upload` (without the `.tmp` suffix).";
 									readonly example: "invoice-2026.pdf";
 								};
 								readonly workspace: {
@@ -1489,6 +1496,13 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly format: "uuid";
 									readonly description: "Workspace identifier.";
 								};
+								readonly folder: {
+									readonly type: "string";
+									readonly minLength: 1;
+									readonly maxLength: 800;
+									readonly description: "Same optional nested folder path passed to `/files/upload`.";
+									readonly example: "contracts/2026";
+								};
 							};
 						};
 						readonly ConfirmFileSuccess: {
@@ -1504,8 +1518,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 								readonly key: {
 									readonly type: "string";
-									readonly description: "Final S3 object key after promotion (`{workspace}/{filename}`).";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
+									readonly description: "Final S3 object key after promotion (`{workspace}/{filename}` or `{workspace}/folders/{folder}/{filename}`).";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000/folders/contracts/2026/invoice-2026.pdf";
 								};
 							};
 						};
@@ -1531,8 +1545,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 								readonly key: {
 									readonly type: "string";
-									readonly description: "Temporary S3 object key (`{workspace}/{filename}.tmp`). Call `/files/confirm` after upload.";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf.tmp";
+									readonly description: "Temporary S3 object key (`.tmp` suffix). Call `/files/confirm` after upload. Root: `{workspace}/{filename}.tmp`. Folder: `{workspace}/folders/{folder}/{filename}.tmp`.";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000/folders/contracts/2026/invoice-2026.pdf.tmp";
 								};
 								readonly maxSize: {
 									readonly type: "integer";
@@ -1876,16 +1890,25 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 								readonly name: {
 									readonly type: "string";
-									readonly description: "Folder name (trimmed).";
-									readonly example: "contracts";
+									readonly minLength: 1;
+									readonly maxLength: 800;
+									readonly description: "Nested folder path under `{workspace}/folders/` (e.g. `contracts` or `contracts/2026`). Each segment is a safe name; max depth 10.";
+									readonly example: "contracts/2026";
 								};
 							};
 						};
+						readonly WorkspaceRelativeFilePath: {
+							readonly type: "string";
+							readonly minLength: 1;
+							readonly maxLength: 800;
+							readonly description: "Path after `{workspace}/`. Root file: `invoice.pdf`. Folder file: `folders/contracts/2026/invoice.pdf`. Not a full S3 key; no leading slash; not `.tmp`.";
+							readonly example: "folders/contracts/2026/invoice-2026.pdf";
+						};
 						readonly PinFileRequest: {
 							readonly type: "object";
 							readonly required: readonly [
 								"workspace",
-								"fileKey",
+								"path",
 								"pin"
 							];
 							readonly properties: {
@@ -1894,10 +1917,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly format: "uuid";
 									readonly description: "Workspace identifier (used for access check).";
 								};
-								readonly fileKey: {
-									readonly type: "string";
-									readonly description: "Full S3 object key to pin or unpin (as returned by list or upload).";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
+								readonly path: {
+									readonly $ref: "#/components/schemas/WorkspaceRelativeFilePath";
 								};
 								readonly pin: {
 									readonly type: "boolean";
@@ -1945,7 +1966,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								readonly key: {
 									readonly type: "string";
 									readonly description: "S3 prefix key for the empty folder (`{workspace}/folders/{name}/`).";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/folders/contracts/";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000/folders/contracts/2026/";
 								};
 							};
 						};
@@ -2018,7 +2039,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							readonly type: "object";
 							readonly required: readonly [
 								"workspace",
-								"fileKey"
+								"path"
 							];
 							readonly properties: {
 								readonly workspace: {
@@ -2026,10 +2047,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly format: "uuid";
 									readonly description: "Workspace identifier (used for access check).";
 								};
-								readonly fileKey: {
-									readonly type: "string";
-									readonly description: "Full S3 object key to delete (as returned by list or upload).";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
+								readonly path: {
+									readonly $ref: "#/components/schemas/WorkspaceRelativeFilePath";
 								};
 							};
 						};
@@ -2080,6 +2099,49 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 							};
 						};
+						readonly MoveFileRequest: {
+							readonly type: "object";
+							readonly required: readonly [
+								"workspace",
+								"from",
+								"to"
+							];
+							readonly properties: {
+								readonly workspace: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Workspace identifier.";
+								};
+								readonly from: {
+									readonly $ref: "#/components/schemas/WorkspaceRelativeFilePath";
+								};
+								readonly to: {
+									readonly $ref: "#/components/schemas/WorkspaceRelativeFilePath";
+								};
+							};
+						};
+						readonly MoveFileSuccess: {
+							readonly type: "object";
+							readonly required: readonly [
+								"success",
+								"from",
+								"to"
+							];
+							readonly properties: {
+								readonly success: {
+									readonly type: "boolean";
+									readonly const: true;
+								};
+								readonly from: {
+									readonly type: "string";
+									readonly description: "Source full S3 object key.";
+								};
+								readonly to: {
+									readonly type: "string";
+									readonly description: "Destination full S3 object key.";
+								};
+							};
+						};
 						readonly MatrixLoginResponse: {
 							readonly type: "object";
 							readonly description: "Raw Matrix login payload returned directly (not wrapped). Existing tenants are looked up by JWT `userId` + workspace. On first login, Synapse `/login` response is returned and the access token is persisted on the tenant. On subsequent calls, a cached payload is synthesized from the stored token with `device_id` `MESTRA_{tenantId}` and `well_known.m.homeserver.base_url`. Workspace owners use Matrix localpart `owner_{emailLocalPart}-{workspaceId}`; other collaborators use `{emailLocalPart}-{workspaceId}`.";
@@ -10655,7 +10717,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "Create presigned S3 upload";
-							readonly description: "Returns a presigned POST URL and form fields for uploading a file to S3 (max 15 MB, 5-minute expiry). Object key is `{workspace}/{filename}.tmp`. Only JPEG, PNG, WebP, and PDF content types are accepted. After the multipart upload succeeds, call `/files/confirm` to validate magic bytes and promote the object to `{workspace}/{filename}`. Temporary objects are excluded from list results. Requires active workspace access and write access to crm::files.";
+							readonly description: "Returns a presigned POST URL and form fields for uploading a file to S3 (max 15 MB, 5-minute expiry). Root object key is `{workspace}/{filename}.tmp`. With optional `folder`, key is `{workspace}/folders/{folder}/{filename}.tmp` and the folder marker must already exist. Only JPEG, PNG, WebP, and PDF content types are accepted. After the multipart upload succeeds, call `/files/confirm` with the same `filename` and `folder` to validate magic bytes and promote the object. Temporary objects are excluded from list results. Requires active workspace access and write access to crm::files.";
 							readonly security: readonly [
 								never
 							];
@@ -10711,7 +10773,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 404: {
-									readonly description: "Workspace not found.";
+									readonly description: "Workspace or destination folder not found.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -10729,7 +10791,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "Confirm and promote a temporary upload";
-							readonly description: "Reads the temporary object at `{workspace}/{filename}.tmp`, verifies size (<= 15 MB) and real file type (JPEG, PNG, WebP, or PDF), copies it to `{workspace}/{filename}`, and deletes the temporary object. On failure, the temporary object is deleted. Requires workspace access.";
+							readonly description: "Reads the temporary object (root or under `folders/{folder}/`), verifies size (<= 15 MB) and real file type (JPEG, PNG, WebP, or PDF), promotes it to the final key, and deletes the temporary object. On failure, the temporary object is deleted. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -10785,7 +10847,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 404: {
-									readonly description: "Workspace not found.";
+									readonly description: "Workspace or destination folder not found.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -10803,7 +10865,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "Create an empty S3 folder";
-							readonly description: "Creates an empty folder marker in S3 at `{workspace}/folders/{name}/`. Requires workspace access.";
+							readonly description: "Creates an empty folder marker in S3 at `{workspace}/folders/{name}/`. `name` may be nested (e.g. `contracts/2026`). Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -10877,7 +10939,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "Delete an S3 folder and its contents";
-							readonly description: "Deletes all objects under `{workspace}/folders/{name}/` in paginated batches. Requires workspace access.";
+							readonly description: "Deletes all objects under `{workspace}/folders/{name}/` in paginated batches. `name` may be nested. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -11021,13 +11083,13 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							};
 						};
 					};
-					readonly "/files/download/{workspace}/{fileKey}": {
+					readonly "/files/download/{workspace}": {
 						readonly get: {
 							readonly tags: readonly [
 								"Files"
 							];
 							readonly summary: "Get presigned download URL";
-							readonly description: "Returns a presigned GET URL for `{workspace}/{fileKey}` (5-minute expiry). Requires workspace access.";
+							readonly description: "Returns a presigned GET URL for `{workspace}/{path}` (5-minute expiry). Pass the workspace-relative path as the `path` query parameter (root leaf or `folders/...`). Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -11043,13 +11105,13 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly description: "Workspace identifier.";
 								},
 								{
-									readonly name: "fileKey";
-									readonly in: "path";
+									readonly name: "path";
+									readonly in: "query";
 									readonly required: true;
 									readonly schema: {
-										readonly type: "string";
+										readonly $ref: "#/components/schemas/WorkspaceRelativeFilePath";
 									};
-									readonly description: "Object key segment after the workspace prefix (may include slashes if encoded).";
+									readonly description: "Workspace-relative file path after the workspace prefix.";
 								}
 							];
 							readonly responses: {
@@ -11064,7 +11126,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 400: {
-									readonly description: "Invalid workspace id.";
+									readonly description: "Invalid workspace id or file path.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -11112,7 +11174,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "Pin or unpin a file";
-							readonly description: "Sets S3 object user metadata `pin` to `true` or `false` on the given full `fileKey` via copy-in-place with MetadataDirective REPLACE. Requires workspace access.";
+							readonly description: "Sets S3 object user metadata `pin` to `true` or `false` on `{workspace}/{path}` via copy-in-place with MetadataDirective REPLACE. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -11185,8 +11247,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							readonly tags: readonly [
 								"Files"
 							];
-							readonly summary: "Delete a file by S3 key";
-							readonly description: "Deletes an S3 object by full `fileKey`. Verifies the object exists before deletion and confirms removal afterward. Requires workspace access.";
+							readonly summary: "Delete a file by workspace-relative path";
+							readonly description: "Deletes the S3 object at `{workspace}/{path}`. Verifies the object exists before deletion and confirms removal afterward. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -11242,7 +11304,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 404: {
-									readonly description: "File not found at the given key.";
+									readonly description: "File or workspace not found.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -11252,7 +11314,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 500: {
-									readonly description: "Delete command ran but the object still exists.";
+									readonly description: "Delete failed (object still present after delete).";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -11264,6 +11326,90 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							};
 						};
 					};
+					readonly "/files/move": {
+						readonly post: {
+							readonly tags: readonly [
+								"Files"
+							];
+							readonly summary: "Move a file within a workspace";
+							readonly description: "Copies `{workspace}/{from}` to `{workspace}/{to}` (preserving content type and metadata including pin), then deletes the source. Destination must not already exist (409). If `to` is under `folders/`, the parent folder marker must exist. Requires workspace access and write access to crm::files.";
+							readonly security: readonly [
+								never
+							];
+							readonly requestBody: {
+								readonly required: true;
+								readonly content: {
+									readonly "application/json": {
+										readonly schema: {
+											readonly $ref: "#/components/schemas/MoveFileRequest";
+										};
+									};
+								};
+							};
+							readonly responses: {
+								readonly 200: {
+									readonly description: "File moved successfully.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/MoveFileSuccess";
+											};
+										};
+									};
+								};
+								readonly 400: {
+									readonly description: "Invalid request payload.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+								readonly 401: {
+									readonly description: "Unauthorized - Missing or invalid access token.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+								readonly 403: {
+									readonly description: "Forbidden - Token issuer is not 'access' or user lacks workspace access.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+								readonly 404: {
+									readonly description: "Source file, destination folder, or workspace not found.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+								readonly 409: {
+									readonly description: "Destination already exists.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+							};
+						};
+					};
 					readonly "/files/upload-to-comment": {
 						readonly post: {
 							readonly tags: readonly [
@@ -17861,6 +18007,14 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			};
 			outputFormat: "json";
 			status: 400;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 404;
 		} | {
 			input: {};
 			output: {
@@ -17878,6 +18032,14 @@ declare const routes: import("hono/hono-base").HonoBase<{
 } & {
 	"/confirm": {
 		$post: {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 404;
+		} | {
 			input: {};
 			output: {
 				success: true;
@@ -17959,13 +18121,11 @@ declare const routes: import("hono/hono-base").HonoBase<{
 		};
 	};
 } & {
-	"/download/:workspace/:fileKey": {
+	"/download/:workspace": {
 		$get: {
 			input: {
 				param: {
 					workspace: string;
-				} & {
-					fileKey: string;
 				};
 			};
 			output: {
@@ -17978,8 +18138,6 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			input: {
 				param: {
 					workspace: string;
-				} & {
-					fileKey: string;
 				};
 			};
 			output: {
@@ -18050,6 +18208,43 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			status: import("hono/utils/http-status").ContentfulStatusCode;
 		};
 	};
+} & {
+	"/move": {
+		$post: {
+			input: {};
+			output: {
+				success: false;
+				error: never;
+			};
+			outputFormat: "json";
+			status: 400;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 404;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 409;
+		} | {
+			input: {};
+			output: {
+				success: true;
+				from: string;
+				to: string;
+			};
+			outputFormat: "json";
+			status: import("hono/utils/http-status").ContentfulStatusCode;
+		};
+	};
 } & {
 	"/upload-to-comment": {
 		$post: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mestra-dev/contract",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "Types-only Hono AppType contract for the Mestra auth API",
   "type": "module",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "dts-bundle-generator": "^9.5.1",
-    "hono": "^4.12.32",
-    "typescript": "^5.8.0"
+    "hono": "^4.13.1",
+    "typescript": "^5.9.3"
   }
 }