@notionhq/apps 0.0.24 → 0.0.25

package/package.json

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

package/skills/notion-as-code/SKILL.md

@@ -86,9 +86,9 @@ root exports support:
   `database(resourceId, { datasources: { Key: { resourceId, schema } }, views?, parent? })`,
   returning sources as `handle.datasources.Key`. A source's `addPage` declares a row;
   the database handle also exposes `addView`.
-- `customAgent({ resourceId, name, instructions?, access?, webAccess?, trustedUrls? })`.
-  Access grants pair declared page or database resource IDs with a role. Inspect
-  the installed types before specifying models, triggers, or URL trust.
+- `customAgent({ resourceId, name, ... })`; only `resourceId` and `name` are
+  required. Choose optional fields individually as described below, and inspect
+  the installed types before using them.
 - `view({ databaseResourceId, resourceId, type, dataSourceResourceId, ... })`,
   returning a handle with `resourceId`. This is also available as `notion.view`.
   Use property resource IDs in view filters, sorts, and layout options; calendar
@@ -127,11 +127,72 @@ use `{ type: "resourceId", resourceId: parent.resourceId }`; child helpers set
 this reference for you. Pages and databases without a parent default to private
 top-level resources in the Apps workspace.
 
-Page and database covers accept `{ type: "url", url, position? }`. Custom-agent
-triggers are discriminated unions for recurrence, page-added, and
-property-updated triggers. Weekly recurrences require at least one weekday, and
-property-updated triggers require property conditions or
-`triggerWhenPageContentEdited: true`.
+Page and database covers accept `{ type: "url", url, position? }`.
+
+## Configure a custom agent
+
+Start with the smallest declaration that describes the requested agent:
+
+```ts
+import { customAgent } from "@notionhq/apps";
+
+const analyst = customAgent({
+	resourceId: "project-analyst",
+	name: "Project analyst",
+	instructions: "Summarize project status and identify blocked work.",
+});
+```
+
+Do not add every optional field by default. Decide on each field separately:
+
+- `instructions`: set when the App should define the agent's purpose or
+  behavior. Omit rather than inventing placeholder instructions.
+- `icon`: set only when the agent needs a specified visual identity. Custom
+  agents accept an emoji or Notion icon, but not a file-backed icon.
+- `model`: set only when the user or product requirement calls for one of the
+  exact model values in the installed declarations. Otherwise omit it and let
+  Notion choose the model.
+- `access`: set only for declared pages or databases the agent must use. Grant
+  the least-capable suitable role: `can_view` for reading, `can_comment` for
+  comments, `can_edit_content` for editing content, or `full_access` only when
+  broader access is required. Use the target handle's `resourceId`; this is
+  separate from a workflow's `access.call(agent)` binding.
+- `webAccess`: set `true` only when the agent must search the web. Set `false`
+  when the declaration must explicitly disable web search. For a new agent,
+  omission defaults to `false`; for an existing agent, omission preserves its
+  current web access and domain restrictions.
+- `trustedUrls`: set `{ type: "all" }` only when the agent must trust every HTTP
+  and HTTPS URL. URL trust is independent of web search, so do not add it merely
+  because `webAccess` is enabled. Omission disables URL trust for a new agent
+  and preserves the current policy for an existing agent. The current type has
+  no value that clears an existing trust policy.
+- `triggers`: set only when the agent should run automatically. Use
+  `recurrence` for a schedule, `page_added` for new rows in a data source, and
+  `property_updated` for selected property edits and/or page-content edits.
+  Do not add a trigger merely because its data source also appears in `access`.
+
+For an existing agent, `access` is additive: each entry adds a grant or updates
+that resource's role, while unlisted grants remain unchanged. Omitting `access`
+and passing `access: []` both preserve existing grants. Reuse declared resource
+IDs and choose roles deliberately:
+
+```ts
+customAgent({
+	resourceId: "project-analyst",
+	name: "Project analyst",
+	instructions: "Summarize project status and identify blocked work.",
+	access: [{ resourceId: projects.resourceId, role: "can_view" }],
+	webAccess: true,
+});
+```
+
+For a recurrence trigger, always set `interval`, `start`, and `timeZone`; add
+`end` only for a finite schedule. Weekly triggers also require a nonempty
+`weekdays` object, and monthly triggers require `monthlyRestriction`. Page-added
+and property-updated triggers reference a declared data source by
+`dataSourceResourceId`. Property-updated triggers require property conditions
+or `triggerWhenPageContentEdited: true`. Give every trigger its own stable
+`resourceId`.
 
 Database page layouts are typed against their keyed data-source schema. Reference
 property resource IDs, not schema keys. The SDK restricts relation groups to