@notionhq/apps 0.0.27 → 0.0.28

package/docs/CONNECTIONS.md

@@ -47,7 +47,7 @@ The callback runs once when `workflow` is called. Its result is serialized as th
 
 Deployment creates a disabled trigger attached to that connection. Configure the account, channel or calendar, and enable the trigger through workflow setup before publishing. Redeploying preserves its configuration. The server checks the binding at publication and execution, so a trigger on another connection cannot invoke this declaration.
 
-Calendar, Slack, Google Drive OAuth, and Discord currently have generated connection trigger helpers. Providers without registered public trigger events do not gain helpers merely by supporting actions. Existing helper calls without `connectionKey` keep their existing behavior. For `connections: { calendar: connections.calendar() }`, use `triggers.calendarEventCreated({ connectionKey: "calendar" })`.
+Calendar, Mail, Slack, Google Drive OAuth, and Discord currently have generated connection trigger helpers. Providers without registered public trigger events do not gain helpers merely by supporting actions. Existing helper calls without `connectionKey` keep their existing behavior. For `connections: { calendar: connections.calendar() }`, use `triggers.calendarEventCreated({ connectionKey: "calendar" })`.
 
 Removing a declaration retains the configured trigger, but it can no longer invoke the capability unless another declaration allows it. Renaming a key creates a new connection and disabled trigger. Two keys can declare the same event type independently; repeating the same type and key is rejected.
 
@@ -88,12 +88,47 @@ The SDK serializes the object to the existing manifest array of `{ key, type }`
 
 ## Supported providers and setup
 
-The registry currently generates 73 methods across 12 providers: Calendar, Slack, Google Drive OAuth, Discord, Cursor, Box, Confluence, Gmail, Google Calendar, Google Drive, Outlook, and Salesforce. Only eligible Tool Core methods are generated; this does not expose every operation in those services.
+The registry generates clients for Calendar, Mail, Slack, Google Drive OAuth, Discord, Cursor, Box, Confluence, Gmail, Google Calendar, Google Drive, Outlook, and Salesforce. Only eligible Tool Core methods are generated; this does not expose every operation in those services.
 
 Each connection must be authenticated and granted access through the workflow’s setup flow before use. The server handles provider-specific authentication and checks that setup is complete. App code declares a provider under a binding key; declaring a connection never grants permissions.
 
 Providers outside the supported list are not currently available as workflow connections. Unsupported declarations receive an unavailable-provider error.
 
+### Mail
+
+`connections.mail()` uses the personal Mail connection and selected accounts configured in workflow setup. It is separate from the admin-enabled `connections.gmail()` and `connections.outlook()` search connectors.
+
+```ts
+import { workflow } from "@notionhq/apps";
+import { connections } from "@notionhq/apps/workflow";
+
+export default workflow({
+	name: "Read unread mail",
+	description: "Search the configured mailbox when an email arrives",
+	connections: { inbox: connections.mail() },
+	triggers: ({ triggers }) => [triggers.mailEmailReceived({ connectionKey: "inbox" })],
+	handler: async (_event, context) => {
+		await context.step("Search unread mail", async () => {
+			const result = await context.connections.inbox.searchEmails({
+				userEmailAddress: "me@example.com",
+				query: "is:unread",
+				count: 20,
+			});
+			if (result.isError) throw new Error("Mailbox search failed");
+			return result;
+		});
+	},
+});
+```
+
+Mail exposes reads such as `searchEmails`, `viewThreadContent`, `readAttachment`, and `listLabels`, plus writes such as `sendNewEmail`, draft creation, and label updates. Search accepts `pageToken` for pagination. Results preserve the Mail tool response, including `content`, optional `structuredContent`, and `isError`; inspect the provider's response before using its contents. The server enforces selected accounts and action permissions on every call.
+
+### Mail and Calendar write approval
+
+Mail and Calendar write methods are available in configured workflows, including sending email and creating, updating, or canceling calendar events. Configuring and publishing the workflow authorizes unattended execution within the connection's permissions. The server automatically approves ordinary action confirmations for the workflow's granted Mail and Calendar connections; app code does not need to approve individual calls.
+
+Account and calendar permissions still apply. Auto-approval does not grant access to an unselected mailbox, enable disallowed sending, or make a read-only calendar writable. Other confirmation requirements are not automatically approved. Direct agent calls retain their existing confirmation behavior.
+
 ## Regenerate provider clients
 
 From `apps-sdk`, with a compatible sibling `notion-next` checkout and its mise toolchain installed:
@@ -113,7 +148,7 @@ notion tool-core codegen-script-types --connections --path ../apps-sdk/src --che
 ### How generation works
 
 1. The generator reads `src/shared/workflows/connectionProviders.ts` in `notion-next`. Each entry selects a provider; the server owns its authentication and readiness checks.
-2. For each provider, it reads the corresponding workflow module's effects. It keeps effects backed by a Tool Core definition, exposed to script agents, not excluded from the connection API, and without an explicit confirmation requirement. Workflows do not yet support human confirmation steps.
+2. For each provider, it reads the corresponding workflow module's effects. It keeps effects backed by a Tool Core definition, exposed to script agents, and not excluded from the connection API. Mail and Calendar include writes because the workflow runtime can approve their action confirmations. Other providers include only read-only methods or methods without a confirmation policy. Server permission checks still apply; workflows do not yet support human confirmation steps.
 3. It reads the exact Tool Core definition stored on each workflow effect projection, so providers with multiple tool versions use the contract selected by their module.
 4. The existing script-type emitter renders the method's wire input and result types. It honors input field mappings and declared output projections, so the types describe the workflow endpoint contract.
 5. It also reads each provider module’s trigger definitions and emits `connection-trigger-definitions.generated.ts`. The SDK trigger generator intersects these with the public `TriggerEventMap` to generate supported `connectionKey` options, descriptions, event types, and provider-scoped trigger creators. Internal events are not exposed.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.27",
+	"version": "0.0.28",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {