@notionhq/apps 0.0.13 → 0.0.15

package/README.md

@@ -3,6 +3,66 @@
 [![CI](https://github.com/makenotion/apps-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/makenotion/apps-sdk/actions/workflows/ci.yml?query=branch%3Amain)
 [![Publish](https://github.com/makenotion/apps-sdk/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/makenotion/apps-sdk/actions/workflows/publish.yml?query=branch%3Amain)
 
+## Imports
+
+The package root exports only resource and capability creation helpers:
+
+```ts
+import {
+	page,
+	database,
+	teamspace,
+	customAgent,
+	sync,
+	workflow,
+	customBlock,
+} from "@notionhq/apps";
+```
+
+Import the helpers your app uses:
+
+```ts
+import { page, workflow } from "@notionhq/apps";
+
+const home = page({ resourceId: "home" });
+
+export default workflow({
+	name: "Follow up",
+	description: "Runs when a page is created",
+	triggers: ({ triggers }) => [triggers.notionPageCreated()],
+	handler: async () => {},
+});
+```
+
+Namespace imports (`import * as Notion from "@notionhq/apps"`) are also supported
+for autocomplete and API exploration.
+
+`sync` accepts a Notion-as-Code data-source handle. `customBlock` creates a custom-block
+capability; it is not the browser runtime object. The capability factories use these
+short names on both the root and their subpaths. Their behavior is unchanged.
+
+The old capability factory names are no longer exported. Update existing imports and calls:
+
+| Removed name           | Use instead   | Subpath                       |
+| ---------------------- | ------------- | ----------------------------- |
+| `createWorkflow`       | `workflow`    | `@notionhq/apps/workflow`     |
+| `createDataSourceSync` | `sync`        | `@notionhq/apps/sync`         |
+| `createCustomBlock`    | `customBlock` | `@notionhq/apps/custom-block` |
+
+Everything else keeps its subpath import, including builders, value helpers, types,
+connections, triggers, pacers, and the custom-block browser runtime:
+
+```ts
+import { Builder } from "@notionhq/apps/builder";
+import { notion } from "@notionhq/apps/notion-as-code";
+import type { DataSourceSyncConfiguration } from "@notionhq/apps/sync";
+```
+
+Existing subpaths remain available, with the capability factory renames above. The root
+uses explicit exports and does not re-export utility types or the custom-block browser runtime. Browser code should
+keep using `@notionhq/apps/custom-blocks` and `@notionhq/apps/react`; the root includes
+Node-only workflow code. Styles stay in `@notionhq/apps/nds.css`.
+
 ## Development
 
 1. Install [mise](https://mise.jdx.dev/getting-started.html)
@@ -14,13 +74,14 @@ The SDK requires Node 26 or newer. It supports workflows and database syncs.
 
 ```ts
 import { triggers } from "@notionhq/apps/triggers";
-import { connections, createWorkflow } from "@notionhq/apps/workflow";
+import { workflow } from "@notionhq/apps";
+import { connections } from "@notionhq/apps/workflow";
 ```
 
 Add a connection requirement to a workflow when it needs Calendar:
 
 ```ts
-export default createWorkflow({
+export default workflow({
 	name: "Schedule follow-up",
 	description: "Schedules a follow-up after a page is created",
 	triggers: [triggers.notionPageCreated()],
@@ -37,26 +98,30 @@ Use `context.notion` for Notion API calls. Deployed apps receive Notion API
 credentials automatically, so do not configure or push `NOTION_API_TOKEN`.
 Local execution needs the token in `.env` before making a Notion API request.
 
-## Database syncs
+## Data-source syncs
 
-Apps declare a database schema, and users attach a real Notion database to it. Apps SDK
-databases are always attached; there is no managed-database option.
+Declare a database with Notion as Code, then pass one of its data-source handles to `sync`:
 
 ```ts
+import { database, sync } from "@notionhq/apps";
 import { Builder } from "@notionhq/apps/builder";
-import { createDatabase } from "@notionhq/apps/database";
-import { Schema } from "@notionhq/apps/schema";
-import { createSync } from "@notionhq/apps/sync";
-
-const issues = createDatabase("issues", {
-	schema: {
-		Name: Schema.title(),
-		"GitHub ID": Schema.richText(),
-	},
+
+const issues = database({
+	resourceId: "issues-db",
+	dataSources: [
+		{
+			resourceId: "issues-source",
+			name: "GitHub Issues",
+			properties: [
+				{ resourceId: "name", name: "Name", type: "title" },
+				{ resourceId: "github-id", name: "GitHub ID", type: "text" },
+			],
+		},
+	],
 });
 
-export default createSync({
-	database: issues,
+export default sync({
+	dataSource: issues.dataSources["issues-source"],
 	primaryKey: "GitHub ID",
 	handler: async () => ({
 		changes: [
@@ -71,52 +136,48 @@ export default createSync({
 ```
 
 Put each default-exported sync directly in `src/syncs/`. A primary key must be a title
-or rich-text property. Do not include that property in an upsert: the SDK fills it from
+or text property. Do not include that property in an upsert: the SDK fills it from
 the change's `key`.
 
-### Moving from the Workers alpha SDK
-
-- Remove `type` and `primaryKey` from `createDatabase`.
-- Move the property map from `schema.properties` directly into `schema`.
-- Add `primaryKey` to each `createSync`.
-- Remove the primary-key property from each upsert's `properties` object.
-- Change imports from `@notionhq/workers/alpha/*` to `@notionhq/apps/*`.
-
-## Publishing New Versions
-
-Publishing is initiated only from the GitHub Actions UI:
-
-1. Open the [Publish workflow](https://github.com/makenotion/sdk/actions/workflows/publish.yml).
-2. Select **Run workflow** on the `main` branch.
-
-The workflow always increments the patch version. It builds, checks, and tests the
-SDK before committing the new version, creating a `v*` GitHub release,
-and publishing `@notionhq/apps` to npm.
-
 ## Custom blocks
 
 Declare browser blocks in `src/customBlocks/<key>.ts`:
 
 ```ts
-import { createCustomBlock } from "@notionhq/apps/custom-block";
+import { customBlock } from "@notionhq/apps";
 
-export default createCustomBlock({
+export default customBlock({
 	path: "./blocks/hello",
 	slashCommand: "hello",
 	dataSources: {},
 });
 ```
 
-The filename supplies the block key. `path` is required and relative to the app
-root. Browser source belongs in the directory it names, with `index.html` and a
-Vite config. The project root supplies React, React DOM, Vite, and the React Vite
-plugin. `command` defaults to `npx vite build`, and `output` defaults to `dist`.
-Use `static: true` for an already-built directory. `slashCommand` accepts one
-optional leading `/`, then 1–64 lowercase letters, numbers, hyphens or underscores,
-starting with a letter or number. `dataSources` describes the block's schemas.
+`path` is relative to the project root. Keep frontend project code out of `src/` to avoid hitting upload caps.
+`notion-apps build-blocks` and `notion-apps upload-blocks` are used for local builds.
+
+See [the build and deployment guide](docs/BUILD.md) for provisioning artifacts,
+cloud builds with server coordination, and local builds with CLI coordination.
+
+## Local / Boxy end to end testing
+
+To build and deploy the app template against a running local Notion server:
+
+```sh
+# Installed ntn and the notion-cookbook template from main
+scripts/smoketest.sh
+
+# CLI binary and template from sibling checkouts
+CLI=local TEMPLATE=local scripts/smoketest.sh
+```
+
+## Publishing New Versions
 
-`notion-apps build` reads declarations in a separate temporary bundle and emits
-`custom_block` capabilities into the manifest. Blocks never enter `worker.js`.
+Publishing is initiated only from the GitHub Actions UI:
 
-`notion-apps build-blocks` and `notion-apps upload-blocks` are invoked by the CLI
-during `ntn apps deploy` for local builds.
+1. Open the [Publish workflow](https://github.com/makenotion/sdk/actions/workflows/publish.yml).
+2. Select **Run workflow** on the `main` branch.
+
+The workflow always increments the patch version. It builds, checks, and tests the
+SDK before committing the new version, creating a `v*` GitHub release,
+and publishing `@notionhq/apps` to npm.

package/dist/box.generated.d.ts

@@ -0,0 +1,164 @@
+import type { ConnectionActionInvoker } from "./connection-actions.js";
+/**
+ * Script input for the "Find shared Box item" effect (`box.findSharedItem`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Resolve a Box shared link to an item ID and type.
+ */
+export type FindSharedItemScriptInput = {
+    /**
+     * The full Box shared link URL.
+     */
+    sharedLink: string;
+};
+/**
+ * Canonical Tool Core output for the "Find shared Box item" effect (`box.findSharedItem`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type FindSharedItemScriptOutput = {
+    itemId: string;
+    /**
+     * One of: `file`, `folder`
+     */
+    itemType: "file" | "folder";
+    name: string;
+    size: number;
+    modifiedAt: string;
+    owner: string;
+};
+/**
+ * Script input for the "Load Box file" effect (`box.loadFile`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Load a Box file by its file ID.
+ */
+export type LoadFileScriptInput = {
+    /**
+     * The Box file ID.
+     */
+    fileId: string;
+};
+/**
+ * Canonical Tool Core output for the "Load Box file" effect (`box.loadFile`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type LoadFileScriptOutput = {
+    /**
+     * Always `box-file`
+     */
+    type: "box-file";
+    title: string;
+    blocks: Array<string>;
+    fileId: string;
+};
+/**
+ * Script input for the "List Box folder" effect (`box.lsFolder`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List files and subfolders in a Box folder.
+ */
+export type LsFolderScriptInput = {
+    /**
+     * The Box folder ID to list contents of.
+     */
+    folderId: string;
+};
+/**
+ * Canonical Tool Core output for the "List Box folder" effect (`box.lsFolder`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type LsFolderScriptOutput = {
+    items: Array<{
+        id: string;
+        /**
+         * One of: `file`, `folder`
+         */
+        type: "file" | "folder";
+        name: string;
+        size: number;
+        modifiedAt: string;
+    }>;
+};
+/**
+ * Script input for the "Search Box" effect (`box.search`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search Box via the configured connector.
+ */
+export type SearchScriptInput = {
+    /**
+     * A single, focused question to search for.
+     */
+    question: string;
+    /**
+     * Brief keywords capturing the core entities.
+     */
+    keywords?: string;
+    /**
+     * Optional time window. Use only "default", "all_time", a duration matching /^\d+[dwmy]$/ (for example, "7d", "2w", "3m", or "1y"), or a date in "YYYY-MM-DD" format. Do not use natural-language durations or combine units.
+     */
+    lookback?: string;
+    /**
+     * Optional list of Box folder IDs to scope the search to. Use findSharedItem or searchFolders to get folder IDs.
+     */
+    folderIds?: Array<string>;
+};
+/**
+ * Canonical Tool Core output for the "Search Box" effect (`box.search`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SearchScriptOutput = {
+    results: Array<{
+        id: string;
+        title: string;
+        path: string;
+        text: string;
+        lastEdited: string;
+        isPrivate: boolean;
+        pageId: string;
+        fileType: string;
+        fileId: string;
+    }>;
+};
+/**
+ * Script input for the "Search Box folders" effect (`box.searchFolders`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search Box folders by name.
+ */
+export type SearchFoldersScriptInput = {
+    /**
+     * The search query for finding folders.
+     */
+    question: string;
+    /**
+     * Optional additional keywords to refine the folder search.
+     */
+    keywords?: string;
+};
+/**
+ * Canonical Tool Core output for the "Search Box folders" effect (`box.searchFolders`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SearchFoldersScriptOutput = {
+    results: Array<{
+        id: string;
+        name: string;
+        folderId: string;
+    }>;
+};
+export declare class BoxConnectionClient {
+    private readonly invoke;
+    constructor(invoke: ConnectionActionInvoker);
+    findSharedItem(args: FindSharedItemScriptInput): Promise<FindSharedItemScriptOutput>;
+    loadFile(args: LoadFileScriptInput): Promise<LoadFileScriptOutput>;
+    lsFolder(args: LsFolderScriptInput): Promise<LsFolderScriptOutput>;
+    search(args: SearchScriptInput): Promise<SearchScriptOutput>;
+    searchFolders(args: SearchFoldersScriptInput): Promise<SearchFoldersScriptOutput>;
+}
+//# sourceMappingURL=box.generated.d.ts.map

package/dist/box.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.generated.d.ts","sourceRoot":"","sources":["../src/box.generated.ts"],"names":[],"mappings":"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"}

package/dist/box.generated.js

@@ -0,0 +1,24 @@
+class BoxConnectionClient {
+  constructor(invoke) {
+    this.invoke = invoke;
+  }
+  invoke;
+  findSharedItem(args) {
+    return this.invoke("findSharedItem", args);
+  }
+  loadFile(args) {
+    return this.invoke("loadFile", args);
+  }
+  lsFolder(args) {
+    return this.invoke("lsFolder", args);
+  }
+  search(args) {
+    return this.invoke("search", args);
+  }
+  searchFolders(args) {
+    return this.invoke("searchFolders", args);
+  }
+}
+export {
+  BoxConnectionClient
+};