@notionhq/apps 0.0.23 → 0.0.25

package/dist/notion-as-code/custom-agent.d.ts

@@ -72,6 +72,27 @@ export type CustomAgentPropertyUpdatedTrigger = CustomAgentTriggerBase & Propert
     dataSourceResourceId: ResourceId;
 };
 export type CustomAgentTrigger = CustomAgentRecurrenceTrigger | CustomAgentPageAddedTrigger | CustomAgentPropertyUpdatedTrigger;
+/**
+ * Defines access levels for resources that a custom agent can use.
+ *
+ * These values map to Notion module permissions: full access, content editing,
+ * commenting, and read-only.
+ */
+export type CustomAgentAccessRole = "full_access" | "can_edit_content" | "can_comment" | "can_view";
+/** Grants a custom agent access to a page or database resource. */
+export type CustomAgentAccess = {
+    resourceId: ResourceId;
+    role: CustomAgentAccessRole;
+};
+/**
+ * URL trust settings for a custom agent.
+ *
+ * URL trust is independent from web access: an agent can trust URLs without
+ * being granted web search access.
+ */
+export type CustomAgentTrustedUrls = {
+    type: "all";
+};
 export type CustomAgentArgs = {
     resourceId: ResourceId;
     name: string;
@@ -80,14 +101,34 @@ export type CustomAgentArgs = {
     }>;
     instructions?: string;
     model?: "ambrosia-tart-high" | "opal-quince-medium" | "almond-croissant-low";
-    sharedResources?: readonly ResourceId[];
+    /**
+     * Whether the agent can use web search. Defaults to `false` when omitted for
+     * a new agent. When updating an existing agent, omitting this field preserves
+     * its current web access and domain restrictions.
+     */
+    webAccess?: boolean;
+    /**
+     * URL trust policy for this agent. `{ type: "all" }` allows every HTTP and
+     * HTTPS URL. For a new agent, omitting this field leaves URL trust disabled;
+     * for an existing agent, omission preserves the current URL trust policy.
+     */
+    trustedUrls?: CustomAgentTrustedUrls;
+    /**
+     * Grants the agent access to pages and databases.
+     *
+     * For an existing custom agent, omit this field or provide an empty list to
+     * preserve current page and database grants. Each listed resource adds a
+     * grant or replaces its existing grant with the listed role. Grants for
+     * unlisted resources remain unchanged.
+     */
+    access?: readonly CustomAgentAccess[];
     triggers?: readonly CustomAgentTrigger[];
 };
 export type CustomAgentHandle = {
     readonly resourceType: "customAgent";
     readonly resourceId: string;
 };
-/** Declare a custom agent and validate every shared resource reference. */
+/** Declare a custom agent and validate every resource reference. */
 export declare function customAgent(args: CustomAgentArgs): CustomAgentHandle;
 export {};
 //# sourceMappingURL=custom-agent.d.ts.map

package/dist/notion-as-code/custom-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-agent.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/custom-agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"custom-agent.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/custom-agent.ts"],"names":[],"mappings":"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"}

package/dist/notion-as-code/custom-agent.js

@@ -2,8 +2,8 @@ import { recordIntent } from "./recorder.js";
 import { assertUserResourceId } from "./resource.js";
 function customAgent(args) {
   assertUserResourceId(args.resourceId);
-  for (const resourceId of args.sharedResources ?? []) {
-    assertUserResourceId(resourceId);
+  for (const grant of args.access ?? []) {
+    assertUserResourceId(grant.resourceId);
   }
   for (const trigger of args.triggers ?? []) {
     assertUserResourceId(trigger.resourceId);

package/dist/notion-as-code/index.d.ts

@@ -1,6 +1,6 @@
 export { APPS_RESERVED_RESOURCE_ID_PREFIX, APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
 export type { ContentPageLayoutTab, DatabasePageLayout, DatabasePageLayoutTab, DatabaseIntent, DataSourceDefinition, NotionAsCodeIcon, NotionAsCodeProperty, NotionAsCodePropertyConfig, NotionAsCodeSchema, NotionAsCodeSelectOption, NotionAsCodeStatusOption, PageCoverReference, PageLayoutMainModule, PageLayoutNumberAndFormulaStyle, PageLayoutPersonStyle, PageLayoutPropertiesModule, PageLayoutPropertyConfig, PageLayoutPropertyModule, PageLayoutPropertySection, PageLayoutRelationConfig, PageLayoutRelationsGroupModule, PageLayoutSidebarModule, Parent, ResourceId, RollupBaseAggregationType, RollupDateAggregationType, RollupNumberAggregationType, RollupTargetPropertyType, ViewPageLayoutTab, } from "./intents.js";
-export type { CustomAgentArgs, CustomAgentHandle, CustomAgentPageAddedTrigger, CustomAgentPropertyUpdatedTrigger, CustomAgentRecurrenceSchedule, CustomAgentRecurrenceTrigger, CustomAgentTrigger, CustomAgentTriggerBase, DailyRecurrenceSchedule, HourlyRecurrenceSchedule, MonthlyRecurrenceRestriction, MonthlyRecurrenceSchedule, MonthlyWeekdayOccurrence, PropertyTriggerCondition, RecurrenceScheduleEnd, RecurrenceWeekdays, WeeklyRecurrenceSchedule, YearlyRecurrenceSchedule, } from "./custom-agent.js";
+export type { CustomAgentAccess, CustomAgentAccessRole, CustomAgentArgs, CustomAgentHandle, CustomAgentPageAddedTrigger, CustomAgentPropertyUpdatedTrigger, CustomAgentRecurrenceSchedule, CustomAgentRecurrenceTrigger, CustomAgentTrustedUrls, CustomAgentTrigger, CustomAgentTriggerBase, DailyRecurrenceSchedule, HourlyRecurrenceSchedule, MonthlyRecurrenceRestriction, MonthlyRecurrenceSchedule, MonthlyWeekdayOccurrence, PropertyTriggerCondition, RecurrenceScheduleEnd, RecurrenceWeekdays, WeeklyRecurrenceSchedule, YearlyRecurrenceSchedule, } from "./custom-agent.js";
 export type { ChildDatabaseArgs, ChildDatabaseFactory, ChildMultiSourceDatabaseArgs, ChildSingleSourceDatabaseArgs, DataSourceArgs, DataSourceHandle, DataSourceMap, DatabaseArgs, DatabaseHandle, MultiSourceDatabaseArgs, SingleSourceDatabaseArgs, SingleSourceDatabaseHandle, } from "./database.js";
 export { toCustomBlockDefaultBinding, toCustomBlockDataSource } from "../translate.js";
 export type { ChildPageArgs, PageArgs, PageHandle, PropertyValue, SimpleTextToken, TextValue, VerificationInput, VerificationPropertyValue, } from "./page.js";

package/dist/notion-as-code/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gCAAgC,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EACX,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,EACN,UAAU,EACV,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,4BAA4B,EAC5B,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACvF,YAAY,EACX,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,yBAAyB,GACzB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EACX,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,4BAA4B,EAC5B,iCAAiC,EACjC,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,+BAA+B,EAC/B,qBAAqB,EACrB,sCAAsC,EACtC,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AAEpB,wEAAwE;AACxE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;CAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gCAAgC,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EACX,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,EACN,UAAU,EACV,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EACX,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACvF,YAAY,EACX,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,yBAAyB,GACzB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EACX,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,4BAA4B,EAC5B,iCAAiC,EACjC,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,+BAA+B,EAC/B,qBAAqB,EACrB,sCAAsC,EACtC,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AAEpB,wEAAwE;AACxE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;CAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.23",
+	"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?, sharedResources? })`.
-  Shared resources are declared resource IDs; inspect the installed types
-  before specifying models or triggers.
+- `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

package/src/notion-as-code/custom-agent.test.ts

@@ -4,12 +4,15 @@ import { notion } from "./index.js";
 import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
 
 describe("Notion-as-Code custom agent declarations", () => {
-	it("records typed recurrence and database triggers", () => {
+	it("records access, web, URL trust, and triggers", () => {
 		const recorder = startMetadataRecording();
 
 		notion.customAgent({
 			resourceId: "triage-agent",
 			name: "Triage agent",
+			webAccess: true,
+			trustedUrls: { type: "all" },
+			access: [{ resourceId: "tasks", role: "can_edit_content" }],
 			triggers: [
 				{
 					type: "recurrence",
@@ -37,6 +40,9 @@ describe("Notion-as-Code custom agent declarations", () => {
 				type: "custom_agent",
 				resourceId: "triage-agent",
 				name: "Triage agent",
+				webAccess: true,
+				trustedUrls: { type: "all" },
+				access: [{ resourceId: "tasks", role: "can_edit_content" }],
 				triggers: [
 					{
 						type: "recurrence",
@@ -76,4 +82,14 @@ describe("Notion-as-Code custom agent declarations", () => {
 			}),
 		).toThrow("reserved");
 	});
+
+	it("rejects reserved resource IDs inside access grants", () => {
+		expect(() =>
+			notion.customAgent({
+				resourceId: "triage-agent",
+				name: "Triage agent",
+				access: [{ resourceId: "__notion_apps_tasks", role: "can_view" }],
+			}),
+		).toThrow("reserved");
+	});
 });

package/src/notion-as-code/custom-agent.ts

@@ -101,13 +101,57 @@ export type CustomAgentTrigger =
 	| CustomAgentPageAddedTrigger
 	| CustomAgentPropertyUpdatedTrigger;
 
+/**
+ * Defines access levels for resources that a custom agent can use.
+ *
+ * These values map to Notion module permissions: full access, content editing,
+ * commenting, and read-only.
+ */
+export type CustomAgentAccessRole = "full_access" | "can_edit_content" | "can_comment" | "can_view";
+
+/** Grants a custom agent access to a page or database resource. */
+export type CustomAgentAccess = {
+	resourceId: ResourceId;
+	role: CustomAgentAccessRole;
+};
+
+/**
+ * URL trust settings for a custom agent.
+ *
+ * URL trust is independent from web access: an agent can trust URLs without
+ * being granted web search access.
+ */
+export type CustomAgentTrustedUrls = {
+	type: "all";
+};
+
 export type CustomAgentArgs = {
 	resourceId: ResourceId;
 	name: string;
 	icon?: Exclude<NotionAsCodeIcon, { type: "file" }>;
 	instructions?: string;
 	model?: "ambrosia-tart-high" | "opal-quince-medium" | "almond-croissant-low";
-	sharedResources?: readonly ResourceId[];
+	/**
+	 * Whether the agent can use web search. Defaults to `false` when omitted for
+	 * a new agent. When updating an existing agent, omitting this field preserves
+	 * its current web access and domain restrictions.
+	 */
+	webAccess?: boolean;
+	/**
+	 * URL trust policy for this agent. `{ type: "all" }` allows every HTTP and
+	 * HTTPS URL. For a new agent, omitting this field leaves URL trust disabled;
+	 * for an existing agent, omission preserves the current URL trust policy.
+	 */
+	trustedUrls?: CustomAgentTrustedUrls;
+	/**
+	 * Grants the agent access to pages and databases.
+	 *
+	 * For an existing custom agent, omit this field or provide an empty list to
+	 * preserve current page and database grants. Each listed resource adds a
+	 * grant or replaces its existing grant with the listed role. Grants for
+	 * unlisted resources remain unchanged.
+	 */
+	access?: readonly CustomAgentAccess[];
 	triggers?: readonly CustomAgentTrigger[];
 };
 
@@ -116,11 +160,11 @@ export type CustomAgentHandle = {
 	readonly resourceId: string;
 };
 
-/** Declare a custom agent and validate every shared resource reference. */
+/** Declare a custom agent and validate every resource reference. */
 export function customAgent(args: CustomAgentArgs): CustomAgentHandle {
 	assertUserResourceId(args.resourceId);
-	for (const resourceId of args.sharedResources ?? []) {
-		assertUserResourceId(resourceId);
+	for (const grant of args.access ?? []) {
+		assertUserResourceId(grant.resourceId);
 	}
 	for (const trigger of args.triggers ?? []) {
 		assertUserResourceId(trigger.resourceId);

package/src/notion-as-code/index.ts

@@ -33,12 +33,15 @@ export type {
 	ViewPageLayoutTab,
 } from "./intents.js";
 export type {
+	CustomAgentAccess,
+	CustomAgentAccessRole,
 	CustomAgentArgs,
 	CustomAgentHandle,
 	CustomAgentPageAddedTrigger,
 	CustomAgentPropertyUpdatedTrigger,
 	CustomAgentRecurrenceSchedule,
 	CustomAgentRecurrenceTrigger,
+	CustomAgentTrustedUrls,
 	CustomAgentTrigger,
 	CustomAgentTriggerBase,
 	DailyRecurrenceSchedule,

package/src/notion-as-code/notion-as-code-types.test.ts

@@ -1,8 +1,11 @@
 import { expectTypeOf, it } from "vitest";
 
 import type {
+	CustomAgentAccess,
+	CustomAgentAccessRole,
 	CustomAgentArgs,
 	CustomAgentPropertyUpdatedTrigger,
+	CustomAgentTrustedUrls,
 	CustomAgentTrigger,
 	DatabasePageLayout,
 	NotionAsCodePropertyConfig,
@@ -12,6 +15,28 @@ import type {
 	SingleSourceDatabaseArgs,
 } from "./index.js";
 
+it("types custom agent resource access and URL trust", () => {
+	expectTypeOf<
+		"full_access" | "can_edit_content" | "can_comment" | "can_view"
+	>().toEqualTypeOf<CustomAgentAccessRole>();
+	expectTypeOf<{
+		resourceId: "tasks";
+		role: "can_view";
+	}>().toExtend<CustomAgentAccess>();
+	expectTypeOf<{
+		resourceId: "tasks";
+		role: "read_and_write";
+	}>().not.toExtend<CustomAgentAccess>();
+	expectTypeOf<{ type: "all" }>().toEqualTypeOf<CustomAgentTrustedUrls>();
+	expectTypeOf<CustomAgentArgs["webAccess"]>().toEqualTypeOf<boolean | undefined>();
+	expectTypeOf<CustomAgentArgs["trustedUrls"]>().toEqualTypeOf<
+		CustomAgentTrustedUrls | undefined
+	>();
+	expectTypeOf<CustomAgentArgs["access"]>().toEqualTypeOf<
+		readonly CustomAgentAccess[] | undefined
+	>();
+});
+
 it("types page and database covers as URL references", () => {
 	expectTypeOf<{
 		type: "url";