@notionhq/apps 0.0.19 → 0.0.20

package/README.md

@@ -23,8 +23,12 @@ Import the helpers your app uses:
 
 ```ts
 import { page, workflow } from "@notionhq/apps";
+import { notion } from "@notionhq/apps/notion-as-code";
 
-const home = page({ resourceId: "home" });
+const home = page({
+	resourceId: "home",
+	properties: { title: notion.text("App home") },
+});
 
 export default workflow({
 	name: "Follow up",

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

@@ -1,9 +1,10 @@
+import type { TextValue } from "./page.js";
 /** Serialize Notion-as-Code date values for Apps property payloads. */
-export declare function date(startDate: string, endDate?: string): unknown[][];
+export declare function date(startDate: string, endDate?: string): TextValue;
 /** Serialize Notion-as-Code datetime values for Apps property payloads. */
 export declare function datetime(value: {
     start: string;
     end?: string;
     timeZone?: string;
-}): unknown[][];
+}): TextValue;
 //# sourceMappingURL=date.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/date.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE,CAWrE;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,EAAE,CA6B/F"}
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/date.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,uEAAuE;AACvE,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAWnE;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA6B7F"}

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

@@ -1,7 +1,7 @@
 import { customAgent } from "./custom-agent.js";
 import { database } from "./database.js";
 import { date, datetime } from "./date.js";
-import { page } from "./page.js";
+import { page, type TextValue, type VerificationInput, type VerificationPropertyValue } from "./page.js";
 import { teamspace } from "./teamspace.js";
 import { view } from "./view.js";
 declare const notionAsCodeFacade: {
@@ -10,22 +10,19 @@ declare const notionAsCodeFacade: {
     page: typeof page;
     customAgent: typeof customAgent;
     view: typeof view;
-    text: (value: string) => string[][];
-    number: (value: number) => string[][];
+    text: (value: string) => TextValue;
+    number: (value: number) => TextValue;
     date: typeof date;
     datetime: typeof datetime;
+    verification: (value: VerificationInput) => VerificationPropertyValue;
     select: (value: string) => string;
     status: (value: string) => string;
     multiSelect: (values: readonly string[]) => string;
-    checkbox: (value: boolean) => string[][];
-    url: (value: string) => (string | string[][])[][];
-    email: (value: string) => (string | string[][])[][];
-    phone: (value: string) => string[][];
+    checkbox: (value: boolean) => TextValue;
+    url: (value: string) => TextValue;
+    email: (value: string) => TextValue;
+    phone: (value: string) => TextValue;
     relation: (value: string | readonly string[]) => string | any[] | readonly string[];
-    file: (resourceId: string) => {
-        type: "file";
-        resourceId: string;
-    };
 };
 export type NotionAsCodeFacade = typeof notionAsCodeFacade;
 /** Create the runtime facade used to declare Notion-as-Code project metadata. */

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

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,QAAA,MAAM,kBAAkB;;;;;;kBAMT,MAAM;oBACJ,MAAM;;;oBAGN,MAAM;oBACN,MAAM;0BACA,SAAS,MAAM,EAAE;sBACrB,OAAO;iBACZ,MAAM;mBACJ,MAAM;mBACN,MAAM;sBACH,MAAM,GAAG,SAAS,MAAM,EAAE;uBACzB,MAAM;;;;CAIzB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAE3D,iFAAiF;AACjF,wBAAgB,YAAY,IAAI,kBAAkB,CAEjD"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACN,IAAI,EACJ,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,QAAA,MAAM,kBAAkB;;;;;;kBAMT,MAAM,KAAG,SAAS;oBAChB,MAAM,KAAG,SAAS;;;0BAGZ,iBAAiB,KAAG,yBAAyB;oBAInD,MAAM;oBACN,MAAM;0BACA,SAAS,MAAM,EAAE;sBACrB,OAAO,KAAG,SAAS;iBACxB,MAAM,KAAG,SAAS;mBAChB,MAAM,KAAG,SAAS;mBAClB,MAAM,KAAG,SAAS;sBACf,MAAM,GAAG,SAAS,MAAM,EAAE;CAC5C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAE3D,iFAAiF;AACjF,wBAAgB,YAAY,IAAI,kBAAkB,CAEjD"}

package/dist/notion-as-code/handles.js

@@ -1,8 +1,9 @@
 import { customAgent } from "./custom-agent.js";
 import { database } from "./database.js";
 import { date, datetime } from "./date.js";
-import { page } from "./page.js";
-import { assertUserResourceId } from "./resource.js";
+import {
+  page
+} from "./page.js";
 import { teamspace } from "./teamspace.js";
 import { view } from "./view.js";
 const notionAsCodeFacade = {
@@ -15,6 +16,10 @@ const notionAsCodeFacade = {
   number: (value) => [[String(value)]],
   date,
   datetime,
+  verification: (value) => ({
+    ...value,
+    type: "verification"
+  }),
   select: (value) => value,
   status: (value) => value,
   multiSelect: (values) => values.join(","),
@@ -22,11 +27,7 @@ const notionAsCodeFacade = {
   url: (value) => [[value, [["a", value]]]],
   email: (value) => [[value, [["a", `mailto:${value}`]]]],
   phone: (value) => [[value]],
-  relation: (value) => Array.isArray(value) ? [...value] : value,
-  file: (resourceId) => {
-    assertUserResourceId(resourceId);
-    return { type: "file", resourceId };
-  }
+  relation: (value) => Array.isArray(value) ? [...value] : value
 };
 function createNotion() {
   return notionAsCodeFacade;

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

@@ -2,7 +2,7 @@ export { APPS_RESERVED_RESOURCE_ID_PREFIX, APPS_WORKSPACE_RESOURCE_ID } from "./
 export type { DatabaseIntent, DataSourceDefinition, NotionAsCodeIcon, NotionAsCodeProperty, NotionAsCodePropertyConfig, NotionAsCodeSchema, NotionAsCodeSelectOption, NotionAsCodeStatusOption, Parent, ResourceId, } from "./intents.js";
 export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
 export type { ChildDatabaseArgs, ChildDatabaseFactory, ChildMultiSourceDatabaseArgs, ChildSingleSourceDatabaseArgs, DataSourceArgs, DataSourceHandle, DataSourceMap, DatabaseArgs, DatabaseHandle, MultiSourceDatabaseArgs, SingleSourceDatabaseArgs, SingleSourceDatabaseHandle, } from "./database.js";
-export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
+export type { ChildPageArgs, PageArgs, PageHandle, PropertyValue, SimpleTextToken, TextValue, VerificationInput, VerificationPropertyValue, } from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";
 export type { ViewArgs, ViewHandle } from "./view.js";
 export type { AdvancedFilterSchema, BasePropertyFilter, BaseViewSchema, BoardViewSchema, CalendarViewSchema, CheckboxGroupByFormat, CheckboxPropertyFilter, CoverAspectFormat, CoverFormat, CoverSizeFormat, DatabaseViewSortDirection, DateFilterMode, DateGroupByFormat, DatePropertyFilter, DatePropertyFilterValue, DatePropertyTypes, ExactDatePropertyFilterValue, ExactRangeDatePropertyFilterValue, FeedViewSchema, FilterSchema, FormulaGroupByFormat, GalleryViewSchema, GroupByFormat, GroupByFormatBase, GroupFormat, ListViewSchema, LocationGroupByFormat, MultiSelectPropertyFilter, NumberGroupByFormat, NumberPropertyFilter, PersonGroupByFormat, PersonPropertyFilter, PropertyFilterSchema, PropertyFormat, PropertyViewSortSchema, PropertyVisibility, RelationGroupByFormat, RelationPropertyFilter, RelativeDatePreset, RelativeDatePropertyFilterValue, RelativeDateRangeUnit, RelativeToTodayDatePropertyFilterValue, SelectGroupByFormat, SelectPropertyFilter, StatusGroupByFormat, StatusPropertyFilter, TableViewSchema, TextGroupByFormat, TextPropertyFilter, TimelineViewSchema, ViewSchema, ViewType, } from "./views.js";
@@ -13,21 +13,18 @@ export declare const notion: {
     page: typeof import("./page.js").page;
     customAgent: typeof import("./custom-agent.js").customAgent;
     view: typeof import("./view.js").view;
-    text: (value: string) => string[][];
-    number: (value: number) => string[][];
+    text: (value: string) => import("./page.js").TextValue;
+    number: (value: number) => import("./page.js").TextValue;
     date: typeof import("./date.js").date;
     datetime: typeof import("./date.js").datetime;
+    verification: (value: import("./page.js").VerificationInput) => import("./page.js").VerificationPropertyValue;
     select: (value: string) => string;
     status: (value: string) => string;
     multiSelect: (values: readonly string[]) => string;
-    checkbox: (value: boolean) => string[][];
-    url: (value: string) => (string | string[][])[][];
-    email: (value: string) => (string | string[][])[][];
-    phone: (value: string) => string[][];
+    checkbox: (value: boolean) => import("./page.js").TextValue;
+    url: (value: string) => import("./page.js").TextValue;
+    email: (value: string) => import("./page.js").TextValue;
+    phone: (value: string) => import("./page.js").TextValue;
     relation: (value: string | readonly string[]) => string | any[] | readonly string[];
-    file: (resourceId: string) => {
-        type: "file";
-        resourceId: string;
-    };
 };
 //# sourceMappingURL=index.d.ts.map

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,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,EACN,UAAU,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,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,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACrE,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,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,EACN,UAAU,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,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,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/dist/notion-as-code/page.d.ts

@@ -1,11 +1,59 @@
 import { type Parent, type ResourceId } from "./intents.js";
 import { type ChildDatabaseFactory } from "./database.js";
+/**
+ * A single text token: plain text as `[string]`, or text with annotations as
+ * `[string, ...annotations]`.
+ */
+export type SimpleTextToken = [string] | [string, ...unknown[]];
+/**
+ * The JSON-serializable text format returned by Notion-as-Code text helpers.
+ */
+export type TextValue = SimpleTextToken[];
+export type VerificationInput = {
+    state: "verified";
+    /** Set an expiration with `notion.datetime(...)`; omit it for indefinite verification. */
+    datetime?: TextValue;
+} | {
+    state: "unverified";
+};
+export type VerificationPropertyValue = VerificationInput & {
+    type: "verification";
+};
+/**
+ * A page property value accepted by Notion as Code.
+ *
+ * Use helpers from `@notionhq/apps/notion-as-code` to construct rich values
+ * such as text, dates, checkboxes, and URLs.
+ */
+export type PropertyValue = string | number | TextValue | string[] | VerificationPropertyValue | undefined;
+/**
+ * Arguments for declaring a page.
+ *
+ * For a regular page, set its title through
+ * `properties.title: notion.text("My Page Title")`. For a database page, use
+ * the title property's schema name instead of `title`.
+ */
 export type PageArgs = {
     resourceId: ResourceId;
     /** Omit to create a private top-level page in the Apps workspace. */
     parent?: Parent;
     cover?: unknown;
-    properties?: Record<string, unknown>;
+    /**
+     * Page properties, including the page title.
+     *
+     * @example Regular page
+     * properties: { title: notion.text("My Page Title") }
+     *
+     * @example Database page
+     * properties: { Name: notion.text("Task Name"), Status: "In Progress" }
+     */
+    properties?: Record<string, PropertyValue | undefined>;
+    /**
+     * Page body in Notion-flavored Markdown.
+     *
+     * Markdown headings create child blocks. They do not set the page title;
+     * set a regular page's title with `properties.title`.
+     */
     content?: string;
     fullWidth?: boolean;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/page.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI/E,MAAM,MAAM,QAAQ,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAS/C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAgBrF"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/page.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI/E;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;AAE1C,MAAM,MAAM,iBAAiB,GAC1B;IACA,KAAK,EAAE,UAAU,CAAC;IAClB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,SAAS,CAAC;CACpB,GACD;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,GAAG;IAC3D,IAAI,EAAE,cAAc,CAAC;CACrB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,MAAM,EAAE,GACR,yBAAyB,GACzB,SAAS,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC;IACvD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAS/C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAgBrF"}

package/dist/notion-as-code/page.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=page.test.d.ts.map

package/dist/notion-as-code/page.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.test.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/page.test.ts"],"names":[],"mappings":""}

package/package.json

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

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

@@ -75,7 +75,8 @@ root exports support:
 
 - `teamspace({ resourceId, name, accessLevel })`, with `addPage` and
   `teamspace.addDatabase(id, args)` on the returned handle.
-- `page({ resourceId, parent?, properties?, content? })`, with
+- `page({ resourceId, parent?, properties?, content? })`; regular page titles use
+  `properties: { title: notion.text("My Page Title") }`. It also has
   `addPage` and `page.addDatabase(id, args)` for children.
 - `database(resourceId, { dataSourceResourceId, name, schema, parent?, views? })`,
   returning a single source as `handle.dataSource`, or
@@ -90,6 +91,11 @@ root exports support:
   Use property resource IDs in view filters, sorts, and layout options; calendar
   views require `calendarBy`, and timeline views require `timelineBy`.
 
+For a regular page, set the title with
+`properties: { title: notion.text("My Page Title") }`. A Markdown heading in
+`content` creates a child heading block; it does not set the page title. For a
+database page, use the title property's schema name instead of `title`.
+
 A database declaration must include at least one data source or at least one
 view. A linked-only database may omit `datasources`, or use `datasources: {}`,
 only when `views` is nonempty. `{}`, `{ datasources: {} }`, and
@@ -131,8 +137,7 @@ The Apps SDK exposes a subset of Notion as Code. Data sources are nested inside
 Apps deployment rejects workspace creation or changes and supplies the App's
 workspace binding itself. Value helpers and types stay on their existing
 subpaths. For example, import `{ notion }` from `@notionhq/apps/notion-as-code`
-for `notion.text(...)` or `notion.file(resourceId)`. The latter creates a file
-reference, not an upload or file declaration. These helpers are not root exports.
+for `notion.text(...)`. These helpers are not root exports.
 CLI acceptance of a serialized intent envelope alone does not establish server
 support for its contents.
 

package/skills/workflow/SKILL.md

@@ -120,10 +120,12 @@ guide page in `src/workflows/sayHello/lib/notion.ts`:
 
 ```ts
 import { page } from "@notionhq/apps";
+import { notion } from "@notionhq/apps/notion-as-code";
 
 export const guide = page({
 	resourceId: "workflow-guide",
-	content: "# Workflow guide\nThis App runs a scheduled workflow.",
+	properties: { title: notion.text("Workflow guide") },
+	content: "This App runs a scheduled workflow.",
 });
 ```
 

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

@@ -1,5 +1,7 @@
+import type { TextValue } from "./page.js";
+
 /** Serialize Notion-as-Code date values for Apps property payloads. */
-export function date(startDate: string, endDate?: string): unknown[][] {
+export function date(startDate: string, endDate?: string): TextValue {
 	const start_date = parseIsoDate(startDate);
 	const end_date = endDate === undefined ? undefined : parseIsoDate(endDate);
 	if (end_date !== undefined && end_date < start_date) {
@@ -13,7 +15,7 @@ export function date(startDate: string, endDate?: string): unknown[][] {
 }
 
 /** Serialize Notion-as-Code datetime values for Apps property payloads. */
-export function datetime(value: { start: string; end?: string; timeZone?: string }): unknown[][] {
+export function datetime(value: { start: string; end?: string; timeZone?: string }): TextValue {
 	const timeZone = value.timeZone ?? "UTC";
 	try {
 		new Intl.DateTimeFormat("en-US", { timeZone }).format();

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

@@ -1,8 +1,12 @@
 import { customAgent } from "./custom-agent.js";
 import { database } from "./database.js";
 import { date, datetime } from "./date.js";
-import { page } from "./page.js";
-import { assertUserResourceId } from "./resource.js";
+import {
+	page,
+	type TextValue,
+	type VerificationInput,
+	type VerificationPropertyValue,
+} from "./page.js";
 import { teamspace } from "./teamspace.js";
 import { view } from "./view.js";
 
@@ -12,22 +16,22 @@ const notionAsCodeFacade = {
 	page,
 	customAgent,
 	view,
-	text: (value: string) => [[value]],
-	number: (value: number) => [[String(value)]],
+	text: (value: string): TextValue => [[value]],
+	number: (value: number): TextValue => [[String(value)]],
 	date,
 	datetime,
+	verification: (value: VerificationInput): VerificationPropertyValue => ({
+		...value,
+		type: "verification",
+	}),
 	select: (value: string) => value,
 	status: (value: string) => value,
 	multiSelect: (values: readonly string[]) => values.join(","),
-	checkbox: (value: boolean) => [[value ? "Yes" : "No"]],
-	url: (value: string) => [[value, [["a", value]]]],
-	email: (value: string) => [[value, [["a", `mailto:${value}`]]]],
-	phone: (value: string) => [[value]],
+	checkbox: (value: boolean): TextValue => [[value ? "Yes" : "No"]],
+	url: (value: string): TextValue => [[value, [["a", value]]]],
+	email: (value: string): TextValue => [[value, [["a", `mailto:${value}`]]]],
+	phone: (value: string): TextValue => [[value]],
 	relation: (value: string | readonly string[]) => (Array.isArray(value) ? [...value] : value),
-	file: (resourceId: string) => {
-		assertUserResourceId(resourceId);
-		return { type: "file" as const, resourceId };
-	},
 };
 
 export type NotionAsCodeFacade = typeof notionAsCodeFacade;

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

@@ -28,7 +28,16 @@ export type {
 	SingleSourceDatabaseArgs,
 	SingleSourceDatabaseHandle,
 } from "./database.js";
-export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
+export type {
+	ChildPageArgs,
+	PageArgs,
+	PageHandle,
+	PropertyValue,
+	SimpleTextToken,
+	TextValue,
+	VerificationInput,
+	VerificationPropertyValue,
+} from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";
 export type { ViewArgs, ViewHandle } from "./view.js";
 export type {

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

@@ -0,0 +1,35 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { notion, type PageArgs, type PropertyValue } from "./index.js";
+import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
+
+describe("Notion-as-Code page declarations", () => {
+	it("records a regular page title separately from Markdown content", () => {
+		const properties = {
+			title: notion.text("Workflow guide"),
+		} satisfies Record<string, PropertyValue | undefined>;
+		const recorder = startMetadataRecording();
+
+		notion.page({
+			resourceId: "workflow-guide",
+			properties,
+			content: "# Body heading",
+		});
+
+		expectTypeOf<PageArgs["properties"]>().toEqualTypeOf<
+			Record<string, PropertyValue | undefined> | undefined
+		>();
+		expect(finishMetadataRecording(recorder).intents).toEqual([
+			{
+				type: "page",
+				resourceId: "workflow-guide",
+				parent: {
+					type: "resourceId",
+					resourceId: "__notion_apps_workspace__",
+				},
+				properties: { title: [["Workflow guide"]] },
+				content: "# Body heading",
+			},
+		]);
+	});
+});

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

@@ -8,14 +8,72 @@ import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 
+/**
+ * A single text token: plain text as `[string]`, or text with annotations as
+ * `[string, ...annotations]`.
+ */
+export type SimpleTextToken = [string] | [string, ...unknown[]];
+
+/**
+ * The JSON-serializable text format returned by Notion-as-Code text helpers.
+ */
+export type TextValue = SimpleTextToken[];
+
+export type VerificationInput =
+	| {
+			state: "verified";
+			/** Set an expiration with `notion.datetime(...)`; omit it for indefinite verification. */
+			datetime?: TextValue;
+	  }
+	| { state: "unverified" };
+
+export type VerificationPropertyValue = VerificationInput & {
+	type: "verification";
+};
+
+/**
+ * A page property value accepted by Notion as Code.
+ *
+ * Use helpers from `@notionhq/apps/notion-as-code` to construct rich values
+ * such as text, dates, checkboxes, and URLs.
+ */
+export type PropertyValue =
+	| string
+	| number
+	| TextValue
+	| string[]
+	| VerificationPropertyValue
+	| undefined;
+
+/**
+ * Arguments for declaring a page.
+ *
+ * For a regular page, set its title through
+ * `properties.title: notion.text("My Page Title")`. For a database page, use
+ * the title property's schema name instead of `title`.
+ */
 export type PageArgs = {
 	resourceId: ResourceId;
 	/** Omit to create a private top-level page in the Apps workspace. */
 	parent?: Parent;
 	// TODO: Port cover types.
 	cover?: unknown;
-	// TODO: Port page property types.
-	properties?: Record<string, unknown>;
+	/**
+	 * Page properties, including the page title.
+	 *
+	 * @example Regular page
+	 * properties: { title: notion.text("My Page Title") }
+	 *
+	 * @example Database page
+	 * properties: { Name: notion.text("Task Name"), Status: "In Progress" }
+	 */
+	properties?: Record<string, PropertyValue | undefined>;
+	/**
+	 * Page body in Notion-flavored Markdown.
+	 *
+	 * Markdown headings create child blocks. They do not set the page title;
+	 * set a regular page's title with `properties.title`.
+	 */
 	content?: string;
 	fullWidth?: boolean;
 };