@mestra-dev/contract 0.0.11 → 0.0.12

package/README.md

@@ -34,10 +34,10 @@ Always use `import type` so the bundler never pulls server code.
 
 ## Build (maintainers)
 
-Requires local `services/auth` and `services/utils` sources plus auth `node_modules` for type resolution. Those packages are **not** published with this contract.
+Requires local `services/core` and `services/utils` sources plus core `node_modules` for type resolution. Those packages are **not** published with this contract.
 
 ```bash
-cd services/contract
+cd services/hc
 bun install
 bun run build
 ```
@@ -47,7 +47,7 @@ Output: `dist/index.d.ts` (self-contained; depends on `hono` types only).
 ## Publish to npmjs
 
 ```bash
-cd services/contract
+cd services/hc
 bun run build
 bun pm version patch   # or: minor / major
 bun publish --access public

package/dist/index.d.ts

@@ -20,8 +20,8 @@ declare const routes: import("hono/hono-base").HonoBase<{
 				readonly openapi: "3.0.3";
 				readonly info: {
 					readonly title: "Auth Service API";
-					readonly version: "1.5.1";
-					readonly description: "OpenAPI specification for the Auth, Integrations, Workspace, Tasks, Templates, Tags, Comments, Assignees, Chat, Events, Billings, and Files endpoints exposed by the k3-core platform.";
+					readonly version: "1.5.2";
+					readonly description: "OpenAPI specification for the Auth, Integrations, Workspace, Tasks, Templates, Tags, Comments, Assignees, Chat, Events, Billings, Files, and Notifications endpoints exposed by the k3-core platform.";
 				};
 				readonly servers: readonly [
 					{
@@ -96,7 +96,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 					},
 					{
 						readonly name: "Notifications";
-						readonly description: "Cursor-based incremental notification sync for the authenticated user. Clients store the returned cursor and pass it on the next call to receive only notifications created or updated since.";
+						readonly description: "Cursor-based incremental notification sync, plus mark-read and archive. Clients store the sync cursor and pass it on the next call; read/archive bump updated_at so changes propagate via sync.";
 					}
 				];
 				readonly components: {
@@ -223,6 +223,17 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								};
 							};
 						};
+						readonly NotificationType: {
+							readonly type: "string";
+							readonly enum: readonly [
+								"info",
+								"warning",
+								"success",
+								"failure"
+							];
+							readonly default: "info";
+							readonly description: "Notification severity (`notification_type` Postgres enum).";
+						};
 						readonly Notification: {
 							readonly type: "object";
 							readonly required: readonly [
@@ -258,9 +269,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly maxLength: 256;
 								};
 								readonly type: {
-									readonly type: "string";
-									readonly maxLength: 50;
-									readonly description: "Notification category (application-defined).";
+									readonly $ref: "#/components/schemas/NotificationType";
 								};
 								readonly read: {
 									readonly type: "boolean";
@@ -364,10 +373,30 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly description: "Human readable error message.";
 								};
 								readonly error: {
-									readonly type: "object";
 									readonly nullable: true;
-									readonly description: "Validation error details.";
-									readonly additionalProperties: true;
+									readonly description: "String message or Zod validation details, depending on the failure.";
+									readonly oneOf: readonly [
+										{
+											readonly type: "string";
+										},
+										{
+											readonly type: "object";
+											readonly additionalProperties: true;
+										}
+									];
+								};
+							};
+						};
+						readonly NotificationIdRequest: {
+							readonly type: "object";
+							readonly required: readonly [
+								"notificationId"
+							];
+							readonly properties: {
+								readonly notificationId: {
+									readonly type: "string";
+									readonly format: "uuid";
+									readonly description: "Notification identifier belonging to the authenticated user.";
 								};
 							};
 						};
@@ -3072,7 +3101,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 400: {
-									readonly description: "Missing code or token verification failure.";
+									readonly description: "Missing `code`, or Google token exchange failed. `error` is a string such as Google's `error_description` (e.g. missing client_secret / invalid_request).";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -3082,7 +3111,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 500: {
-									readonly description: "Failed to issue tokens.";
+									readonly description: "`GOOGLE_CLIENT_SECRET is not configured`, or failed to issue session tokens after a successful Google exchange.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -3186,7 +3215,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 400: {
-									readonly description: "Missing query parameters, invalid state, or expired verifier.";
+									readonly description: "`Missing code or state`, `Invalid state`, `Invalid or expired state`, or Google token exchange failure (`error` string from Google / OAuth helper).";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -3212,7 +3241,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 500: {
-									readonly description: "Calendar creation, watch registration, or persistence failed (e.g. invalid watch response).";
+									readonly description: "`GOOGLE_CLIENT_SECRET is not configured`, or calendar creation / watch registration / persistence failed (e.g. invalid watch response).";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -4574,7 +4603,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 								"Workspace"
 							];
 							readonly summary: "Create workspace invitation";
-							readonly description: "Creates an invitation for a user to join a workspace with specified resources and role. Requires write access to crm::general resource.";
+							readonly description: "Creates an invitation for an email to join a workspace with specified resources and role. Works for emails that are not yet registered: a pending `invitations` row is stored and a collaborator is materialized when that email creates an account (OTP signup or OAuth). If the user already exists, a pending collaborator with policies is created immediately (same accept flow as before). Always returns the invite `token` for the frontend to share. Requires write access to crm::general. Pending invitations for unknown emails count toward the workspace collaborator seat limit.";
 							readonly security: readonly [
 								never
 							];
@@ -4594,7 +4623,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 												readonly email: {
 													readonly type: "string";
 													readonly format: "email";
-													readonly description: "Email of the user to invite.";
+													readonly description: "Email to invite (registered or not).";
 												};
 												readonly workspace: {
 													readonly type: "string";
@@ -4624,13 +4653,29 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
-												readonly $ref: "#/components/schemas/SimpleSuccess";
+												readonly type: "object";
+												readonly required: readonly [
+													"success",
+													"token"
+												];
+												readonly properties: {
+													readonly success: {
+														readonly type: "boolean";
+														readonly const: true;
+													};
+													readonly token: {
+														readonly type: "string";
+														readonly minLength: 64;
+														readonly maxLength: 64;
+														readonly description: "Invite token for GET /workspace/invite/{workspace}/{token} after the invitee authenticates.";
+													};
+												};
 											};
 										};
 									};
 								};
 								readonly 400: {
-									readonly description: "Invalid request payload, max collaborators reached, user not found, user is already a collaborator, or resource not found.";
+									readonly description: "Invalid request payload, max collaborators reached, invitation already pending, user is already a collaborator, or resource not found.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -5128,13 +5173,13 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							};
 						};
 					};
-					readonly "/workspace/leave/{workspace}/{collaboratorId}": {
+					readonly "/workspace/leave/{workspace}": {
 						readonly get: {
 							readonly tags: readonly [
 								"Workspace"
 							];
-							readonly summary: "Remove a collaborator from a workspace";
-							readonly description: "Removes the specified collaborator from the workspace. The authenticated workspace owner cannot use this endpoint; they must delete the workspace instead.";
+							readonly summary: "Leave a workspace";
+							readonly description: "Removes the authenticated user from the workspace. Workspace owners cannot leave; they must delete the workspace instead (`Owner cannot leave the workspace, Delete the workspace instead`).";
 							readonly security: readonly [
 								never
 							];
@@ -5148,21 +5193,11 @@ declare const routes: import("hono/hono-base").HonoBase<{
 										readonly type: "string";
 										readonly format: "uuid";
 									};
-								},
-								{
-									readonly name: "collaboratorId";
-									readonly in: "path";
-									readonly required: true;
-									readonly description: "Collaborator identifier to remove.";
-									readonly schema: {
-										readonly type: "string";
-										readonly format: "uuid";
-									};
 								}
 							];
 							readonly responses: {
 								readonly 200: {
-									readonly description: "Collaborator removed successfully.";
+									readonly description: "Left the workspace successfully.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -5172,7 +5207,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 									};
 								};
 								readonly 400: {
-									readonly description: "Invalid workspace id, user is not a collaborator, or user is the workspace owner.";
+									readonly description: "Invalid workspace id, caller is not a collaborator, or caller is the workspace owner.";
 									readonly content: {
 										readonly "application/json": {
 											readonly schema: {
@@ -10083,6 +10118,126 @@ declare const routes: import("hono/hono-base").HonoBase<{
 							};
 						};
 					};
+					readonly "/notifications/read": {
+						readonly post: {
+							readonly tags: readonly [
+								"Notifications"
+							];
+							readonly summary: "Mark a notification as read";
+							readonly description: "Sets `read=true` and bumps `updated_at` for a notification owned by the authenticated user so the change is picked up by `/notifications/sync`. Requires a valid access token (no workspace policy check).";
+							readonly security: readonly [
+								never
+							];
+							readonly requestBody: {
+								readonly required: true;
+								readonly content: {
+									readonly "application/json": {
+										readonly schema: {
+											readonly $ref: "#/components/schemas/NotificationIdRequest";
+										};
+									};
+								};
+							};
+							readonly responses: {
+								readonly 200: {
+									readonly description: "Notification marked as read.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/SimpleSuccess";
+											};
+										};
+									};
+								};
+								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 403: {
+									readonly description: "Forbidden - Token issuer is not 'access'.";
+								};
+								readonly 404: {
+									readonly description: "Notification not found for this user.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+							};
+						};
+					};
+					readonly "/notifications/archive": {
+						readonly post: {
+							readonly tags: readonly [
+								"Notifications"
+							];
+							readonly summary: "Archive a notification";
+							readonly description: "Sets `archive=true` and bumps `updated_at` for a notification owned by the authenticated user so the change is picked up by `/notifications/sync`. Requires a valid access token (no workspace policy check).";
+							readonly security: readonly [
+								never
+							];
+							readonly requestBody: {
+								readonly required: true;
+								readonly content: {
+									readonly "application/json": {
+										readonly schema: {
+											readonly $ref: "#/components/schemas/NotificationIdRequest";
+										};
+									};
+								};
+							};
+							readonly responses: {
+								readonly 200: {
+									readonly description: "Notification archived.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/SimpleSuccess";
+											};
+										};
+									};
+								};
+								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 403: {
+									readonly description: "Forbidden - Token issuer is not 'access'.";
+								};
+								readonly 404: {
+									readonly description: "Notification not found for this user.";
+									readonly content: {
+										readonly "application/json": {
+											readonly schema: {
+												readonly $ref: "#/components/schemas/ErrorResponse";
+											};
+										};
+									};
+								};
+							};
+						};
+					};
 					readonly "/chat/start": {
 						readonly post: {
 							readonly tags: readonly [
@@ -10622,6 +10777,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			input: {};
 			output: {
 				success: true;
+				token: string;
 			};
 			outputFormat: "json";
 			status: 201;
@@ -12271,6 +12427,14 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			};
 			outputFormat: "json";
 			status: 400;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 500;
 		} | {
 			input: {};
 			output: {
@@ -15763,7 +15927,6 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			output: {
 				success: false;
 				error: string;
-				details: string;
 			};
 			outputFormat: "json";
 			status: 500;
@@ -15845,7 +16008,7 @@ declare const routes: import("hono/hono-base").HonoBase<{
 					workspaceId: string;
 					title: string;
 					message: string;
-					type: string;
+					type: "success" | "info" | "warning" | "failure";
 					read: boolean;
 					archive: boolean;
 				}[];
@@ -15856,5 +16019,59 @@ declare const routes: import("hono/hono-base").HonoBase<{
 			status: 200;
 		};
 	};
+} & {
+	"/read": {
+		$post: {
+			input: {};
+			output: {
+				success: false;
+				error: never;
+			};
+			outputFormat: "json";
+			status: 400;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 404;
+		} | {
+			input: {};
+			output: {
+				success: true;
+			};
+			outputFormat: "json";
+			status: 200;
+		};
+	};
+} & {
+	"/archive": {
+		$post: {
+			input: {};
+			output: {
+				success: false;
+				error: never;
+			};
+			outputFormat: "json";
+			status: 400;
+		} | {
+			input: {};
+			output: {
+				success: false;
+				error: string;
+			};
+			outputFormat: "json";
+			status: 404;
+		} | {
+			input: {};
+			output: {
+				success: true;
+			};
+			outputFormat: "json";
+			status: 200;
+		};
+	};
 }, "/notifications">, "/", "/">;
 export type AppType = typeof routes;

package/package.json

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