Skip to content

Commit 32b9526

Browse files
emmaguo13emmaguo13
committed
Move App connections into shared declarations and separate skill folders
1 parent b321e9e commit 32b9526

16 files changed

Lines changed: 125 additions & 100 deletions

File tree

‎apps/README.md‎

Lines changed: 14 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -33,24 +33,17 @@ must be enabled before deployment.
3333

3434
Apps are a private alpha and are not currently open for general contribution.
3535

36-
## Calendar targets
37-
38-
Declare one Calendar connection per workflow. Give each purpose a named target
39-
with a description, needed permissions, and an explicit `multiple` setting.
40-
Connect accounts during setup, then choose calendars under each target.
41-
Connecting an account alone does not approve access to its calendars.
42-
43-
Calendar event triggers require a target from the trigger callback's
44-
`connections`. Reads require a target from `context.connections`. Reuse the same
45-
target when the trigger and the read should use the same calendars; setup shows
46-
one picker and lists the triggers that use it.
47-
48-
See [Perfect Meetings' Calendar workflow](templates/perfect-meetings/src/workflows/calendarIngest.ts)
49-
for all three Calendar event triggers sharing a read target. This example needs
50-
the target-aware Calendar trigger SDK and matching server/setup UI; older SDKs
51-
that accept only `connectionKey` for Calendar triggers cannot build it.
52-
53-
The SDK supports workflows, database syncs, and custom blocks. The full coding
54-
guidance ships with `@notionhq/apps`. Template skill loaders live in
55-
[agents/](agents/); run `npm run agents:sync` from the repository root after
56-
changing them.
36+
## Shared connections
37+
38+
Declare connections once in `src/connections/*.ts`, then import them in each
39+
workflow. Use `connection({ type: "calendar", ... })` or
40+
`connection({ type: "mail" })` instead of workflow-local connection declarations.
41+
Calendar targets are flat properties, such as `calendar.meetings`.
42+
43+
An installation configures each connection and its targets once. Every workflow
44+
in that App uses that saved setup. Accounts are not shared between installations.
45+
46+
See [Perfect Meetings' shared Calendar connection](templates/perfect-meetings/src/connections/calendar.ts)
47+
and its [Calendar workflow](templates/perfect-meetings/src/workflows/calendarIngest.ts).
48+
This example requires the app-level connections SDK and matching server/setup UI.
49+
Older SDKs with workflow-local connections cannot build it.

‎apps/agents/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,15 @@ skill for declarations, typed data source handles, and deployment behavior.
3232
| Skill | SDK surface |
3333
| ---------------------------------------------- | ---------------------------------------------------------------------- |
3434
| [Workflow](skills/workflow/SKILL.md) | Typed triggers and durable steps |
35-
| [Connections](skills/connections/SKILL.md) | Workflow provider clients, Calendar targets, trigger keys, and retries |
35+
| [Connections](skills/connections/SKILL.md) | Shared app provider declarations, flat Calendar targets, and trigger keys |
3636
| [Sync](skills/sync/SKILL.md) | Notion as Code data source syncs and pagination |
3737
| [Custom blocks](skills/custom-blocks/SKILL.md) | Browser project declarations and host integration |
3838

3939
Use the latest Apps SDK for the current Calendar targets and Notion Markdown
4040
guidance. Examples import the helpers they use, such as
4141
`import { access, workflow } from "@notionhq/apps"`.
4242
The root also exports resource and capability creators, `view`, `input`,
43-
`events`, and workflow types. Connections, provider types, builders, and browser
43+
`events`, `connection`, and workflow types. Provider types, builders, and browser
4444
APIs keep their own subpaths. The instructions replace
4545
Worker registration, auth interception, and database assumptions with Apps APIs.
4646
Worker tools and webhooks are not registered by the Apps capability discovery

‎apps/agents/instructions/default/INSTRUCTIONS.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,15 +117,15 @@ import { database, sync } from "@notionhq/apps"
117117
```
118118

119119
The root exports `page`, `database`, `teamspace`, `customAgent`, `view`,
120-
`sync`, `workflow`, and `customBlock`. Workflow helpers `access`, `input`,
120+
`sync`, `workflow`, `connection`, and `customBlock`. Workflow helpers `access`, `input`,
121121
and `events`, plus workflow types such as `WorkflowContext`, are also available
122122
from the root.
123123
`sync` takes a Notion as Code data source handle. There is no standalone
124124
`dataSource`; declare data sources inside `database`.
125125

126126
Keep other imports on their existing subpaths: `Builder` from
127127
`@notionhq/apps/builder`, value helpers and types from their own modules,
128-
`connections` from `@notionhq/apps/workflow`, and `events` from
128+
`connection` from the package root, and `events` from
129129
`@notionhq/apps/events` (or use the workflow's typed trigger callback).
130130
Provider input and result types come from `@notionhq/apps/connections/<provider>`.
131131
Browser runtime and React APIs also keep their subpaths.
@@ -141,8 +141,13 @@ example or placeholder capabilities in discovered capability directories: the
141141
build can include and deploy them. Preserve shared configuration and
142142
infrastructure required by the selected capabilities.
143143

144-
Each direct TypeScript file in these directories default-exports a declaration.
145-
Its filename supplies the capability key. Put capability-specific helpers in
144+
A default export in a direct TypeScript capability file uses its filename as
145+
the capability key. Named SDK factory exports use their variable names.
146+
`src/app.ts` can define several named workflows, connections, and other
147+
capabilities together. Keep connection declarations in `src/connections/*.ts`
148+
when using separate files. Import and call connections directly in handlers;
149+
do not declare workflow-local `connections` or use `context.connections`.
150+
Calendar targets are flat properties, such as `calendar.meetings`. Put capability-specific helpers in
146151
`src/workflows/lib/` (or the matching capability directory's `lib/`) and shared
147152
helpers in `src/lib/`. Discovery only reads direct children, so these helpers
148153
are not treated as capabilities.
@@ -157,7 +162,7 @@ release that includes it. Do not continue without the full SDK guidance.
157162
| Area | Where used | Template pointer | Full SDK skill |
158163
| -------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ |
159164
| Workflow | `src/workflows/` | `.agents/skills/workflow/SKILL.md` | `node_modules/@notionhq/apps/skills/workflow/SKILL.md` |
160-
| Connections | Workflow provider clients and triggers | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
165+
| Connections | `src/connections/` shared provider declarations and targets | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
161166
| Database sync | `src/syncs/` | `.agents/skills/sync/SKILL.md` | `node_modules/@notionhq/apps/skills/sync/SKILL.md` |
162167
| Custom blocks | `src/customBlocks/` | `.agents/skills/custom-blocks/SKILL.md` | `node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md` |
163168
| Notion as Code | Resources declared in modules imported by workflows or syncs | `.agents/skills/notion-as-code/SKILL.md` | `node_modules/@notionhq/apps/skills/notion-as-code/SKILL.md` |

‎apps/agents/skills/connections/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
---
22
name: connections
3-
description: Configure and use typed provider connections and connection-bound triggers in Notion App workflows.
3+
description: Declare and use shared app-level Calendar, Mail, Slack, and OAuth connections in Notion Apps.
44
user-invocable: false
55
---
66

77
# App connections
88

9+
Keep named declarations in `src/connections/`, separate from workflows.
10+
Use `connection({ type: ... })`, flat Calendar targets, and direct provider calls.
11+
The SDK also supports a continuous `src/app.ts` with several named workflows.
12+
913
Before creating, modifying, or troubleshooting connection code, read
1014
`node_modules/@notionhq/apps/skills/connections/SKILL.md`.
1115
Resolve this path relative to the App project root.

‎apps/templates/apps-default/.agents/INSTRUCTIONS.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,15 +117,15 @@ import { database, sync } from "@notionhq/apps"
117117
```
118118

119119
The root exports `page`, `database`, `teamspace`, `customAgent`, `view`,
120-
`sync`, `workflow`, and `customBlock`. Workflow helpers `access`, `input`,
120+
`sync`, `workflow`, `connection`, and `customBlock`. Workflow helpers `access`, `input`,
121121
and `events`, plus workflow types such as `WorkflowContext`, are also available
122122
from the root.
123123
`sync` takes a Notion as Code data source handle. There is no standalone
124124
`dataSource`; declare data sources inside `database`.
125125

126126
Keep other imports on their existing subpaths: `Builder` from
127127
`@notionhq/apps/builder`, value helpers and types from their own modules,
128-
`connections` from `@notionhq/apps/workflow`, and `events` from
128+
`connection` from the package root, and `events` from
129129
`@notionhq/apps/events` (or use the workflow's typed trigger callback).
130130
Provider input and result types come from `@notionhq/apps/connections/<provider>`.
131131
Browser runtime and React APIs also keep their subpaths.
@@ -141,8 +141,13 @@ example or placeholder capabilities in discovered capability directories: the
141141
build can include and deploy them. Preserve shared configuration and
142142
infrastructure required by the selected capabilities.
143143

144-
Each direct TypeScript file in these directories default-exports a declaration.
145-
Its filename supplies the capability key. Put capability-specific helpers in
144+
A default export in a direct TypeScript capability file uses its filename as
145+
the capability key. Named SDK factory exports use their variable names.
146+
`src/app.ts` can define several named workflows, connections, and other
147+
capabilities together. Keep connection declarations in `src/connections/*.ts`
148+
when using separate files. Import and call connections directly in handlers;
149+
do not declare workflow-local `connections` or use `context.connections`.
150+
Calendar targets are flat properties, such as `calendar.meetings`. Put capability-specific helpers in
146151
`src/workflows/lib/` (or the matching capability directory's `lib/`) and shared
147152
helpers in `src/lib/`. Discovery only reads direct children, so these helpers
148153
are not treated as capabilities.
@@ -157,7 +162,7 @@ release that includes it. Do not continue without the full SDK guidance.
157162
| Area | Where used | Template pointer | Full SDK skill |
158163
| -------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ |
159164
| Workflow | `src/workflows/` | `.agents/skills/workflow/SKILL.md` | `node_modules/@notionhq/apps/skills/workflow/SKILL.md` |
160-
| Connections | Workflow provider clients and triggers | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
165+
| Connections | `src/connections/` shared provider declarations and targets | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
161166
| Database sync | `src/syncs/` | `.agents/skills/sync/SKILL.md` | `node_modules/@notionhq/apps/skills/sync/SKILL.md` |
162167
| Custom blocks | `src/customBlocks/` | `.agents/skills/custom-blocks/SKILL.md` | `node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md` |
163168
| Notion as Code | Resources declared in modules imported by workflows or syncs | `.agents/skills/notion-as-code/SKILL.md` | `node_modules/@notionhq/apps/skills/notion-as-code/SKILL.md` |

‎apps/templates/apps-default/.agents/skills/connections/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
---
22
name: connections
3-
description: Configure and use typed provider connections and connection-bound triggers in Notion App workflows.
3+
description: Declare and use shared app-level Calendar, Mail, Slack, and OAuth connections in Notion Apps.
44
user-invocable: false
55
---
66

77
# App connections
88

9+
Keep named declarations in `src/connections/`, separate from workflows.
10+
Use `connection({ type: ... })`, flat Calendar targets, and direct provider calls.
11+
The SDK also supports a continuous `src/app.ts` with several named workflows.
12+
913
Before creating, modifying, or troubleshooting connection code, read
1014
`node_modules/@notionhq/apps/skills/connections/SKILL.md`.
1115
Resolve this path relative to the App project root.

‎apps/templates/apps-default/src/connections/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Shared app connections
2+
3+
Add named `connection({ type: ... })` exports in TypeScript files here when the
4+
app needs an external service. Import them into workflows and call them directly
5+
inside handlers. All workflows in one installation share setup.
6+
7+
Read the separate `.agents/skills/connections/SKILL.md` loader from the app root.
8+
No external connection is required by the default scaffold.

‎apps/templates/perfect-meetings/.agents/INSTRUCTIONS.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,15 +117,15 @@ import { database, sync } from "@notionhq/apps"
117117
```
118118

119119
The root exports `page`, `database`, `teamspace`, `customAgent`, `view`,
120-
`sync`, `workflow`, and `customBlock`. Workflow helpers `access`, `input`,
120+
`sync`, `workflow`, `connection`, and `customBlock`. Workflow helpers `access`, `input`,
121121
and `events`, plus workflow types such as `WorkflowContext`, are also available
122122
from the root.
123123
`sync` takes a Notion as Code data source handle. There is no standalone
124124
`dataSource`; declare data sources inside `database`.
125125

126126
Keep other imports on their existing subpaths: `Builder` from
127127
`@notionhq/apps/builder`, value helpers and types from their own modules,
128-
`connections` from `@notionhq/apps/workflow`, and `events` from
128+
`connection` from the package root, and `events` from
129129
`@notionhq/apps/events` (or use the workflow's typed trigger callback).
130130
Provider input and result types come from `@notionhq/apps/connections/<provider>`.
131131
Browser runtime and React APIs also keep their subpaths.
@@ -141,8 +141,13 @@ example or placeholder capabilities in discovered capability directories: the
141141
build can include and deploy them. Preserve shared configuration and
142142
infrastructure required by the selected capabilities.
143143

144-
Each direct TypeScript file in these directories default-exports a declaration.
145-
Its filename supplies the capability key. Put capability-specific helpers in
144+
A default export in a direct TypeScript capability file uses its filename as
145+
the capability key. Named SDK factory exports use their variable names.
146+
`src/app.ts` can define several named workflows, connections, and other
147+
capabilities together. Keep connection declarations in `src/connections/*.ts`
148+
when using separate files. Import and call connections directly in handlers;
149+
do not declare workflow-local `connections` or use `context.connections`.
150+
Calendar targets are flat properties, such as `calendar.meetings`. Put capability-specific helpers in
146151
`src/workflows/lib/` (or the matching capability directory's `lib/`) and shared
147152
helpers in `src/lib/`. Discovery only reads direct children, so these helpers
148153
are not treated as capabilities.
@@ -157,7 +162,7 @@ release that includes it. Do not continue without the full SDK guidance.
157162
| Area | Where used | Template pointer | Full SDK skill |
158163
| -------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ |
159164
| Workflow | `src/workflows/` | `.agents/skills/workflow/SKILL.md` | `node_modules/@notionhq/apps/skills/workflow/SKILL.md` |
160-
| Connections | Workflow provider clients and triggers | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
165+
| Connections | `src/connections/` shared provider declarations and targets | `.agents/skills/connections/SKILL.md` | `node_modules/@notionhq/apps/skills/connections/SKILL.md` |
161166
| Database sync | `src/syncs/` | `.agents/skills/sync/SKILL.md` | `node_modules/@notionhq/apps/skills/sync/SKILL.md` |
162167
| Custom blocks | `src/customBlocks/` | `.agents/skills/custom-blocks/SKILL.md` | `node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md` |
163168
| Notion as Code | Resources declared in modules imported by workflows or syncs | `.agents/skills/notion-as-code/SKILL.md` | `node_modules/@notionhq/apps/skills/notion-as-code/SKILL.md` |

‎apps/templates/perfect-meetings/.agents/skills/connections/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
---
22
name: connections
3-
description: Configure and use typed provider connections and connection-bound triggers in Notion App workflows.
3+
description: Declare and use shared app-level Calendar, Mail, Slack, and OAuth connections in Notion Apps.
44
user-invocable: false
55
---
66

77
# App connections
88

9+
Keep named declarations in `src/connections/`, separate from workflows.
10+
Use `connection({ type: ... })`, flat Calendar targets, and direct provider calls.
11+
The SDK also supports a continuous `src/app.ts` with several named workflows.
12+
913
Before creating, modifying, or troubleshooting connection code, read
1014
`node_modules/@notionhq/apps/skills/connections/SKILL.md`.
1115
Resolve this path relative to the App project root.

‎apps/templates/perfect-meetings/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -282,3 +282,11 @@ Notes:
282282
past meeting. Confirm profiles and Researched at are written, Done edits
283283
cause no further research, and Notes survive a retry. Build and offline
284284
tests cannot verify native trigger delivery or agent behavior.
285+
286+
## Shared Calendar setup
287+
288+
`src/connections/calendar.ts` declares Calendar once for all workflows. The
289+
`meetings` target selects calendars to sync; the `history` target selects past
290+
meetings for prep. All workflows share the connected accounts. Targets may have
291+
different selected calendars. Configure these targets in the app setup page
292+
once, not separately for each workflow.

0 commit comments

Comments
 (0)