@mestra-dev/contract 0.0.24 → 0.0.25

package/dist/index.d.ts

@@ -94,7 +94,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 					},
 					{
 						readonly name: "Files";
-						readonly description: "S3 file upload (presigned POST), profile and workspace picture upload/confirm/delete, comment attachment upload, list task comment files with download URLs, folder create/delete, list (includes pin metadata), pin/unpin, download, and file delete. General uploads accept JPEG/PNG/WebP/PDF; profile/workspace pictures accept JPEG/PNG only (0.5 MB).";
+						readonly description: "Context-based S3 file upload and confirmation using presigned POSTs, with storage, profile, workspace, and comment contexts. Includes folder create/delete, workspace listing, pin/unpin, download, and delete.";
 					},
 					{
 						readonly name: "Chat";
@@ -1404,21 +1404,104 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							readonly required: readonly [
 								"filename",
 								"contentType",
-								"workspace"
+								"context"
 							];
 							readonly properties: {
 								readonly filename: {
 									readonly type: "string";
-									readonly description: "Original file name (trimmed).";
+									readonly description: "Original file name (trimmed). Must not contain path separators or `..`.";
 									readonly example: "invoice-2026.pdf";
 								};
 								readonly contentType: {
 									readonly $ref: "#/components/schemas/FileContentType";
 								};
+								readonly context: {
+									readonly type: "string";
+									readonly enum: readonly [
+										"storage",
+										"profile",
+										"workspace",
+										"comment"
+									];
+									readonly description: "Determines the S3 key prefix.";
+								};
 								readonly workspace: {
 									readonly type: "string";
 									readonly format: "uuid";
-									readonly description: "Workspace identifier.";
+									readonly description: "Required for storage, workspace, and comment contexts.";
+								};
+								readonly taskId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Required for comment context.";
+								};
+								readonly commentId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Required for comment context.";
+								};
+							};
+						};
+						readonly ConfirmFileRequest: {
+							readonly type: "object";
+							readonly required: readonly [
+								"filename",
+								"context",
+								"uploadId"
+							];
+							readonly properties: {
+								readonly filename: {
+									readonly type: "string";
+									readonly description: "Original file name used in `/files/upload` (without `.tmp`). Must not contain path separators or `..`.";
+									readonly example: "invoice-2026.pdf";
+								};
+								readonly context: {
+									readonly type: "string";
+									readonly enum: readonly [
+										"storage",
+										"profile",
+										"workspace",
+										"comment"
+									];
+									readonly description: "Must match the context used for `/files/upload`.";
+								};
+								readonly uploadId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Upload session identifier returned by `/files/upload`.";
+								};
+								readonly workspace: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Required for storage, workspace, and comment contexts.";
+								};
+								readonly taskId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Required for comment context.";
+								};
+								readonly commentId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Required for comment context.";
+								};
+							};
+						};
+						readonly ConfirmFileSuccess: {
+							readonly type: "object";
+							readonly required: readonly [
+								"success",
+								"key"
+							];
+							readonly properties: {
+								readonly success: {
+									readonly type: "boolean";
+									readonly const: true;
+								};
+								readonly key: {
+									readonly type: "string";
+									readonly description: "Final S3 object key after confirmation, derived from context.";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
 								};
 							};
 						};
@@ -1428,6 +1511,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"url",
 								"fields",
 								"key",
+								"fileKey",
+								"uploadId",
 								"maxSize"
 							];
 							readonly properties: {
@@ -1444,14 +1529,23 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 								readonly key: {
 									readonly type: "string";
-									readonly description: "S3 object key where the file will be stored (`{workspace}/{filename}`).";
-									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
+									readonly description: "Context-derived temporary S3 object key. Call `/files/confirm` after upload.";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf.tmp/7b7c3c8b-2d17-4d5f-9f2b-1e7b3b4c5d6e";
 								};
 								readonly maxSize: {
 									readonly type: "integer";
 									readonly description: "Maximum allowed upload size in bytes (15 MB).";
 									readonly example: 15728640;
 								};
+								readonly fileKey: {
+									readonly type: "string";
+									readonly description: "Final S3 object key to use with generic file operations.";
+								};
+								readonly uploadId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Upload session identifier required by `/files/confirm`.";
+								};
 							};
 						};
 						readonly UploadToCommentRequest: {
@@ -1730,11 +1824,11 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								readonly workspace: {
 									readonly type: "string";
 									readonly format: "uuid";
-									readonly description: "Workspace identifier (used for access check).";
+									readonly description: "Workspace identifier. `fileKey` must be under `{workspace}/`.";
 								};
 								readonly fileKey: {
 									readonly type: "string";
-									readonly description: "Full S3 object key to pin or unpin (as returned by list or upload).";
+									readonly description: "Full S3 object key to pin or unpin. Must start with `{workspace}/` (as returned by list or confirm).";
 									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
 								};
 								readonly pin: {
@@ -1862,15 +1956,34 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								readonly workspace: {
 									readonly type: "string";
 									readonly format: "uuid";
-									readonly description: "Workspace identifier (used for access check).";
+									readonly description: "Workspace identifier. `fileKey` must be under `{workspace}/`.";
 								};
 								readonly fileKey: {
 									readonly type: "string";
-									readonly description: "Full S3 object key to delete (as returned by list or upload).";
+									readonly description: "Full S3 object key to delete. Must start with `{workspace}/` (as returned by list or confirm).";
 									readonly example: "550e8400-e29b-41d4-a716-446655440000/invoice-2026.pdf";
 								};
 							};
 						};
+						readonly DeleteCommentFileRequest: {
+							readonly type: "object";
+							readonly required: readonly [
+								"workspace",
+								"fileKey"
+							];
+							readonly properties: {
+								readonly workspace: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Workspace identifier. `fileKey` must be under `{workspace}_comments/`.";
+								};
+								readonly fileKey: {
+									readonly type: "string";
+									readonly description: "Full S3 object key to delete (as returned by upload-to-comment or download-from-task).";
+									readonly example: "550e8400-e29b-41d4-a716-446655440000_comments/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/ffffffff-1111-2222-3333-444444444444/receipt.pdf";
+								};
+							};
+						};
 						readonly DeleteFileSuccess: {
 							readonly type: "object";
 							readonly required: readonly [
@@ -1893,6 +2006,28 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 							};
 						};
+						readonly DeleteCommentFileSuccess: {
+							readonly type: "object";
+							readonly required: readonly [
+								"success",
+								"message",
+								"key"
+							];
+							readonly properties: {
+								readonly success: {
+									readonly type: "boolean";
+									readonly const: true;
+								};
+								readonly message: {
+									readonly type: "string";
+									readonly example: "Comment file deleted successfully";
+								};
+								readonly key: {
+									readonly type: "string";
+									readonly description: "S3 object key that was deleted.";
+								};
+							};
+						};
 						readonly DeleteFileFailure: {
 							readonly type: "object";
 							readonly required: readonly [
@@ -9660,7 +9795,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}`. Only JPEG, PNG, WebP, and PDF content types are accepted. Requires workspace access.";
+							readonly description: "Returns a presigned POST URL for a context-based temporary upload (max 15 MB, 5-minute expiry). The context may be `storage`, `profile`, `workspace`, or `comment`; related identifiers are required for each context. The response includes a server-generated `uploadId`, which must be sent to `/files/confirm` to prevent temporary-upload substitution. Workspace, comment, and workspace-profile contexts require the corresponding workspace permissions.";
 							readonly security: readonly [
 								never
 							];
@@ -9686,7 +9821,81 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 400: {
-									readonly description: "Invalid request payload or unsupported content type.";
+									readonly description: "Invalid request payload, unsupported content type, or unsafe filename.";
+									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: "Workspace not found.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+							};
+						};
+					};
+					readonly "/files/confirm": {
+						readonly post: {
+							readonly tags: readonly [
+								"Files"
+							];
+							readonly summary: "Confirm and persist an uploaded workspace file";
+							readonly description: "Reads the context-specific temporary object identified by `uploadId`, verifies size (<= 15 MB) and real file type via magic bytes (JPEG, PNG, WebP, or PDF), writes it to the context-derived final key, and deletes the temporary object. On failure, the temporary object is deleted. The same context identifiers and uploadId returned by `/files/upload` are required.";
+							readonly security: readonly [
+								never
+							];
+							readonly requestBody: {
+								readonly required: true;
+								readonly content: {
+									readonly "application/json": {
+										readonly schema: {
+											readonly $ref: "#/components/schemas/ConfirmFileRequest";
+										};
+									};
+								};
+							};
+							readonly responses: {
+								readonly 200: {
+									readonly description: "File confirmed and stored at the final key.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ConfirmFileSuccess";
+											};
+										};
+									};
+								};
+								readonly 400: {
+									readonly description: "Invalid payload, missing temp object, file too large, or invalid file type.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -9882,7 +10091,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Files"
 							];
 							readonly summary: "List workspace files";
-							readonly description: "Lists up to 50 S3 objects under the workspace prefix. Each item includes `pin` from S3 object user metadata. Requires workspace access.";
+							readonly description: "Lists up to 50 S3 objects under the workspace prefix (excludes keys ending in `.tmp`). Each item includes `pin` from S3 object user metadata. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -10043,7 +10252,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 the given full `fileKey` via copy-in-place with MetadataDirective REPLACE. `fileKey` must start with `{workspace}/`. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -10117,7 +10326,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"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 description: "Deletes an S3 object by full `fileKey`. Rejects keys that are not under `{workspace}/`. Verifies the object exists before deletion and confirms removal afterward. Requires workspace access.";
 							readonly security: readonly [
 								never
 							];
@@ -10163,11 +10372,11 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 403: {
-									readonly description: "Forbidden - Token issuer is not 'access' or user lacks workspace access.";
+									readonly description: "Forbidden - Token issuer is not 'access', user lacks workspace access, or fileKey is outside the workspace prefix.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
-												readonly $ref: "#/components/schemas/ErrorResponse";
+												readonly $ref: "#/components/schemas/DeleteFileFailure";
 											};
 										};
 									};
@@ -10269,6 +10478,80 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							};
 						};
 					};
+					readonly "/files/delete-from-comment": {
+						readonly post: {
+							readonly tags: readonly [
+								"Files"
+							];
+							readonly summary: "Delete a comment attachment by S3 key";
+							readonly description: "Deletes a comment attachment S3 object by full `fileKey`. Rejects keys that are not under `{workspace}_comments/`. Requires workspace access and write access to crm::tasks.";
+							readonly security: readonly [
+								never
+							];
+							readonly requestBody: {
+								readonly required: true;
+								readonly content: {
+									readonly "application/json": {
+										readonly schema: {
+											readonly $ref: "#/components/schemas/DeleteCommentFileRequest";
+										};
+									};
+								};
+							};
+							readonly responses: {
+								readonly 200: {
+									readonly description: "Comment file deleted successfully.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/DeleteCommentFileSuccess";
+											};
+										};
+									};
+								};
+								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', user lacks workspace access, user lacks write access to crm::tasks, or fileKey is outside the comment attachments prefix.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/DeleteFileFailure";
+											};
+										};
+									};
+								};
+								readonly 404: {
+									readonly description: "File not found at the given key.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/DeleteFileFailure";
+											};
+										};
+									};
+								};
+							};
+						};
+					};
 					readonly "/files/download-from-task/{workspace}/{taskId}": {
 						readonly get: {
 							readonly tags: readonly [
@@ -16438,18 +16721,21 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			input: {};
 			output: {
 				success: false;
-				error: never;
+				error: string;
 			};
 			outputFormat: "json";
 			status: 400;
 		} | {
 			input: {};
 			output: {
+				success: true;
 				url: string;
 				fields: {
 					[x: string]: string;
 				};
 				key: string;
+				fileKey: string;
+				uploadId: `${string}-${string}-${string}-${string}-${string}`;
 				maxSize: number;
 			};
 			outputFormat: "json";
@@ -16457,12 +16743,12 @@ declare const routes: import("hono/hono-base").HonoBase<{
 		};
 	};
 } & {
-	"/create-folder": {
+	"/confirm": {
 		$post: {
 			input: {};
 			output: {
 				success: false;
-				error: never;
+				error: string;
 			};
 			outputFormat: "json";
 			status: 400;
@@ -16470,53 +16756,11 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			input: {};
 			output: {
 				success: true;
-				message: string;
 				key: string;
+				fileKey: string;
 			};
 			outputFormat: "json";
-			status: 201;
-		};
-	};
-} & {
-	"/delete-folder": {
-		$post: {
-			input: {};
-			output: {
-				success: false;
-				error: never;
-			};
-			outputFormat: "json";
-			status: 400;
-		} | {
-			input: {};
-			output: {
-				success: true;
-				message: string;
-			};
-			outputFormat: "json";
-			status: 200;
-		};
-	};
-} & {
-	"/list/:workspace": {
-		$get: {
-			input: {
-				param: {
-					workspace: string;
-				};
-			};
-			output: {
-				success: true;
-				files: {
-					key: string | undefined;
-					size: number | undefined;
-					lastModified: string | undefined;
-					pin: boolean;
-				}[];
-				nextToken: string | undefined;
-			};
-			outputFormat: "json";
-			status: 200;
+			status: import("hono/utils/http-status").ContentfulStatusCode;
 		};
 	};
 } & {
@@ -16577,15 +16821,6 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			};
 			outputFormat: "json";
 			status: 404;
-		} | {
-			input: {};
-			output: {
-				success: false;
-				message: string;
-				key: string;
-			};
-			outputFormat: "json";
-			status: 500;
 		} | {
 			input: {};
 			output: {
@@ -16598,7 +16833,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 		};
 	};
 } & {
-	"/upload-to-comment": {
+	"/create-folder": {
 		$post: {
 			input: {};
 			output: {
@@ -16611,44 +16846,15 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			input: {};
 			output: {
 				success: true;
-				url: string;
-				fields: {
-					[x: string]: string;
-				};
+				message: string;
 				key: string;
-				maxSize: number;
 			};
 			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
-		};
-	};
-} & {
-	"/download-from-task/:workspace/:taskId": {
-		$get: {
-			input: {
-				param: {
-					workspace: string;
-				} & {
-					taskId: string;
-				};
-			};
-			output: {
-				success: true;
-				files: {
-					key: string;
-					filename: string;
-					commentId: string;
-					size: number;
-					lastModified: string | null;
-					downloadUrl: string;
-				}[];
-			};
-			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
+			status: 201;
 		};
 	};
 } & {
-	"/upload-profile-picture": {
+	"/delete-folder": {
 		$post: {
 			input: {};
 			output: {
@@ -16658,42 +16864,6 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			outputFormat: "json";
 			status: 400;
 		} | {
-			input: {};
-			output: {
-				url: string;
-				fields: {
-					[x: string]: string;
-				};
-				key: string;
-				maxSize: number;
-			};
-			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
-		};
-	};
-} & {
-	"/confirm-profile-picture": {
-		$post: {
-			input: {};
-			output: {
-				success: true;
-				url: string;
-			};
-			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
-		} | {
-			input: {};
-			output: {
-				success: false;
-				error: string;
-			};
-			outputFormat: "json";
-			status: 400;
-		};
-	};
-} & {
-	"/delete-profile-picture": {
-		$post: {
 			input: {};
 			output: {
 				success: true;
@@ -16701,86 +16871,28 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			};
 			outputFormat: "json";
 			status: import("hono/utils/http-status").ContentfulStatusCode;
-		} | {
-			input: {};
-			output: {
-				success: false;
-				error: string;
-			};
-			outputFormat: "json";
-			status: 500;
 		};
 	};
 } & {
-	"/upload-workspace-picture": {
-		$post: {
-			input: {};
-			output: {
-				success: false;
-				error: never;
-			};
-			outputFormat: "json";
-			status: 400;
-		} | {
-			input: {};
-			output: {
-				url: string;
-				fields: {
-					[x: string]: string;
+	"/list/:workspace": {
+		$get: {
+			input: {
+				param: {
+					workspace: string;
 				};
-				key: string;
-				maxSize: number;
 			};
-			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
-		};
-	};
-} & {
-	"/confirm-workspace-picture": {
-		$post: {
-			input: {};
 			output: {
 				success: true;
-				url: string;
-			};
-			outputFormat: "json";
-			status: import("hono/utils/http-status").ContentfulStatusCode;
-		} | {
-			input: {};
-			output: {
-				success: false;
-				error: string;
-			};
-			outputFormat: "json";
-			status: 400;
-		};
-	};
-} & {
-	"/delete-workspace-picture": {
-		$post: {
-			input: {};
-			output: {
-				success: false;
-				error: never;
-			};
-			outputFormat: "json";
-			status: 400;
-		} | {
-			input: {};
-			output: {
-				success: true;
-				message: string;
+				files: {
+					key: string | undefined;
+					size: number | undefined;
+					lastModified: string | undefined;
+					pin: boolean;
+				}[];
+				nextToken: string | undefined;
 			};
 			outputFormat: "json";
 			status: import("hono/utils/http-status").ContentfulStatusCode;
-		} | {
-			input: {};
-			output: {
-				success: false;
-				error: string;
-			};
-			outputFormat: "json";
-			status: 500;
 		};
 	};
 }, "/files"> | import("hono/types").MergeSchemaPath<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mestra-dev/contract",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "Types-only Hono AppType contract for the Mestra auth API",
   "type": "module",
   "sideEffects": false,