Statsig rollout template

apps/README.md

@@ -15,6 +15,7 @@ independent project that can be copied, built, and deployed on its own.
 | ----------------------------------------------- | ------------------------------------------------------------------------- |
 | [Default app](templates/apps-default/)          | A recurring workflow with a durable step and an interactive custom block. |
 | [Perfect Meetings](templates/perfect-meetings/) | Calendar connection, deterministic triggers and agentic research          |
+| [Statsig Rollout](templates/statsig-rollout/)   | Database-triggered workflow that calls an external API with retries       |
 
 ## Quick start
 

apps/templates/statsig-rollout/.agents/INSTRUCTIONS.md

@@ -0,0 +1,200 @@
+# Apps template guidance
+
+Apps are a private alpha. Check the installed `@notionhq/apps` exports and
+declarations before using a capability; SDK support does not establish that a
+provider is enabled on the server.
+
+## Design the App before implementation
+
+First establish what the complete App should do: its outcome, source data,
+triggers, external services, and every Notion resource it needs. Recommend a
+workflow for most automations; use a sync when the goal is to mirror an external
+collection into a Notion database. An App may contain both.
+
+Before proposing the design, read only enough of this guidance and the
+top-level descriptions of the relevant capability skills (workflow, sync,
+connections, and Notion as Code) to describe concrete options for open
+decisions. Do not read full skill instructions, generated declarations
+(`*.generated.d.ts`), full provider API surfaces, or other implementation
+details until the user agrees on a direction. Verify those details against the
+selected option during implementation.
+
+Present the proposed design concisely and get the user's agreement before
+implementing. Include `APP.md` as the App's home page and primary user
+interface. It should briefly explain the App, embed its most important views,
+and link to supporting Notion resources. The proposal should
+include:
+
+- `APP.md`, the primary views it will embed, and the resources it will link to.
+- Other Notion resources the App will create, including databases, pages, and
+  custom agents; state each resource's purpose and which capabilities use it.
+- Every sync, including its external source, destination database, and
+  synchronization behavior.
+- Every workflow, including its trigger, main actions, resources it reads or
+  changes, and external connections.
+- Open decisions and required access.
+
+Adapt the format to the App. For example:
+
+### Example App design
+
+**Outcome:** Bring support tickets into Notion and escalate urgent tickets to
+the support team.
+
+**Notion resources**
+
+| Kind         | Name              | Purpose                                             | Used by                          |
+| ------------ | ----------------- | --------------------------------------------------- | -------------------------------- |
+| `APP.md`     | Support App       | Explain the App and embed the ticket triage view    | Team members                     |
+| Database     | Support tickets   | Store synchronized tickets and triage status        | Ticket sync, escalation workflow |
+| Page         | Support dashboard | Give the team an operational home and database view | Team members                     |
+| Custom agent | Ticket triage     | Classify urgency and summarize a ticket             | Escalation workflow              |
+
+**Syncs and workflows**
+
+| Kind     | Name                   | Source or trigger                       | Behavior                                              | Dependencies                                                        |
+| -------- | ---------------------- | --------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
+| Sync     | Ticket sync            | Support-system tickets                  | Upsert by stable external ID                          | Support-system connection, Support tickets database                 |
+| Workflow | Escalate urgent ticket | Support tickets page created or updated | Run triage, update status, and notify support channel | Ticket triage agent, Support tickets database, messaging connection |
+
+**Open questions:** Which support system and messaging channel should the App use?
+
+Ask the user to confirm or revise the design. Do not begin implementation
+until they agree. If implementation reveals a material resource or capability
+not covered by the agreed design, update the proposal and confirm the change
+before adding it.
+
+## App home page (APP.md)
+
+The app root includes `APP.md`. This file is the App's home page and, as much
+as the App needs one, its user interface. Design it as the place people come
+to use the App. Update it when the App's behavior or resources change.
+The Apps SDK provisions the page in the
+installation workspace when the file exists. Its page title is the deployed
+App's name, not `APP.md`; do not put a second copy of the title in its body.
+
+Use the installed SDK's `skills/notion-as-code/markdown.md` reference for
+Notion Markdown in `APP.md`, page content, and custom-agent instructions.
+Use resource IDs in mentions and database tags. An optional YAML frontmatter
+`icon` sets the app page icon; the build removes frontmatter from the body.
+
+Use this basic structure, adapting the sections to the App:
+
+1. **Brief description:** Explain what the App does and who it helps in a few
+   sentences.
+2. **Primary views:** Embed the most important databases or specific views,
+   including custom views, in the order people need them. For a CRM, this
+   might be Contacts and a pipeline view; for a meeting App, a next-meeting
+   card and upcoming meetings. Give each view a clear heading and only the
+   explanation needed to use it.
+3. **Common actions:** Explain what to open, add, or change and what happens
+   next. Include views or controls for those actions when available, along
+   with useful status indicators and automatic update behavior.
+4. **Supporting resources:** Link to other pages and databases people may
+   need without embedding every resource on the home page.
+
+Embed linked database views with declared data source or view resource IDs,
+including custom view resource IDs. For example, after declaring the view:
+
+```text
+<database inline="true" data-source-url="{{contacts-view}}">Contacts</database>
+```
+
+Use a Notion as Code resource reference, such as
+`<mention url="resource-id">Resource name</mention>`, to link to
+another page declared by the App. Keep the resource ID in sync with the
+corresponding declaration. Use only declared resources in actual embeds and
+links; keep illustrative placeholders in code fences. Do not create a separate
+home page. Keep developer setup, deployment commands, and implementation
+details in the README.
+
+## SDK imports
+
+Import the creation helpers you use directly from the package root:
+
+```ts
+import { database, sync } from "@notionhq/apps"
+```
+
+The root exports `page`, `database`, `teamspace`, `customAgent`, `view`,
+`sync`, `workflow`, and `customBlock`. Workflow helpers `access`, `input`,
+and `events`, plus workflow types such as `WorkflowContext`, are also available
+from the root.
+`sync` takes a Notion as Code data source handle. There is no standalone
+`dataSource`; declare data sources inside `database`.
+
+Keep other imports on their existing subpaths: `Builder` from
+`@notionhq/apps/builder`, value helpers and types from their own modules,
+`connections` from `@notionhq/apps/workflow`, and `events` from
+`@notionhq/apps/events` (or use the workflow's typed trigger callback).
+Provider input and result types come from `@notionhq/apps/connections/<provider>`.
+Browser runtime and React APIs also keep their subpaths.
+
+Check that the installed SDK supports these exports before building.
+
+## Capability layout
+
+After the user agrees on the design, compare it with the complete scaffold.
+Remove template workflows, syncs, custom blocks, Notion resource declarations,
+sample assets, and supporting code that the App does not need. Do not leave
+example or placeholder capabilities in discovered capability directories: the
+build can include and deploy them. Preserve shared configuration and
+infrastructure required by the selected capabilities.
+
+Each direct TypeScript file in these directories default-exports a declaration.
+Its filename supplies the capability key. Put capability-specific helpers in
+`src/workflows/lib/` (or the matching capability directory's `lib/`) and shared
+helpers in `src/lib/`. Discovery only reads direct children, so these helpers
+are not treated as capabilities.
+
+The App template's `.agents/skills/` files point to the full SDK skills
+installed under `./node_modules/@notionhq/apps/skills/`. For every area you
+implement, follow the template pointer and read the corresponding installed
+SDK skill listed in this table. If the installed SDK skill is missing, install
+the App's dependencies; if it remains missing, update `@notionhq/apps` to a
+release that includes it. Do not continue without the full SDK guidance.
+
+| Area           | Where used                                                   | Template pointer                         | Full SDK skill                                               |
+| -------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ |
+| Workflow       | `src/workflows/`                                             | `.agents/skills/workflow/SKILL.md`       | `node_modules/@notionhq/apps/skills/workflow/SKILL.md`       |
+| Connections    | Workflow provider clients and triggers                       | `.agents/skills/connections/SKILL.md`    | `node_modules/@notionhq/apps/skills/connections/SKILL.md`    |
+| Database sync  | `src/syncs/`                                                 | `.agents/skills/sync/SKILL.md`           | `node_modules/@notionhq/apps/skills/sync/SKILL.md`           |
+| Custom blocks  | `src/customBlocks/`                                          | `.agents/skills/custom-blocks/SKILL.md`  | `node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md`  |
+| 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` |
+
+Notion as Code declarations are not a separate discovered capability
+directory. Syncs can use their declared data source handles.
+
+Prefer Notion as Code over other methods for equivalent supported resource
+setup. Use another method when the user explicitly requests it, an existing
+resource must be attached, or the required operation is not supported by Apps
+Notion as Code. Runtime operations on changing data still use the appropriate API.
+
+Apps do not expose Worker-style tool or webhook registration, Worker fetch
+interceptors, or Worker managed-database configuration. Do not translate those
+APIs by changing package names. Sync contexts have `notion`, but no workflow
+`step` or `connections` client.
+
+## Runtime and credentials
+
+Use Node.js 26 or newer and install from the app root. Use `context.notion`
+for Notion API access. Deployed apps receive Notion credentials automatically;
+local execution needs `NOTION_API_TOKEN` in `.env` before making API requests.
+Never commit tokens or generated `dist/` and `.notion/` state.
+
+## Verification and deployment
+
+Run `npm run check` and `npm run build` from the app root after changes.
+Add offline tests for pagination, transforms, and retry-sensitive behavior.
+Building does not verify server availability, published connection setup, or
+browser interactions. State separately which live checks actually ran.
+
+For a requested deployment, enable `ntn experiments enable apps`, authenticate,
+and use `ntn apps deploy --json` with any required arguments. On the first
+deployment, pass `--name <name>`; omit `--name` for updates. Use the JSON fields
+`worker_url`, `setup_url`, and `is_update` in the handoff. For a first
+deployment (`is_update` is false), show the `setup_url` and tell the user to
+open it to finish setup. For an update (`is_update` is true), show both URLs
+with clear labels: `worker_url` opens the deployed App and `setup_url` revisits
+onboarding. Use the URLs returned by the CLI; do not construct or guess them.
+Read the installed CLI help for other commands.

apps/templates/statsig-rollout/.agents/skills/connections/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: connections
+description: Configure and use typed provider connections and connection-bound triggers in Notion App workflows.
+user-invocable: false
+---
+
+# App connections
+
+Before creating, modifying, or troubleshooting connection code, read
+`node_modules/@notionhq/apps/skills/connections/SKILL.md`.
+Resolve this path relative to the App project root.
+Follow the instructions in that file.
+
+If the file is missing, install the project dependencies.
+If it remains missing, update `@notionhq/apps` to a release that includes the skill.
+Do not continue with connection changes until you can read the SDK skill.

apps/templates/statsig-rollout/.agents/skills/custom-blocks/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: custom-blocks
+description: Build interactive browser custom blocks declared by a Notion App.
+user-invocable: false
+---
+
+# App custom blocks
+
+Before creating, modifying, or troubleshooting custom block code, read
+`node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md`.
+Resolve this path relative to the App project root.
+Follow the instructions in that file.
+
+If the file is missing, install the project dependencies.
+If it remains missing, update `@notionhq/apps` to a release that includes the skill.
+Do not continue with custom block changes until you can read the SDK skill.

apps/templates/statsig-rollout/.agents/skills/notion-as-code/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: notion-as-code
+description: Declare Notion pages, databases, teamspaces, and custom agents in an App, including data sources used by syncs.
+user-invocable: false
+---
+
+# Apps Notion as Code
+
+Before creating, modifying, or troubleshooting Notion as Code code, read
+`node_modules/@notionhq/apps/skills/notion-as-code/SKILL.md`.
+Resolve this path relative to the App project root.
+Follow the instructions in that file.
+
+If the file is missing, install the project dependencies.
+If it remains missing, update `@notionhq/apps` to a release that includes the skill.
+Do not continue with Notion as Code changes until you can read the SDK skill.

apps/templates/statsig-rollout/.agents/skills/sync/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sync
+description: Build, debug, or review Notion App database syncs with stable keys and resumable pagination.
+user-invocable: false
+---
+
+# App database syncs
+
+Before creating, modifying, or troubleshooting sync code, read
+`node_modules/@notionhq/apps/skills/sync/SKILL.md`.
+Resolve this path relative to the App project root.
+Follow the instructions in that file.
+
+If the file is missing, install the project dependencies.
+If it remains missing, update `@notionhq/apps` to a release that includes the skill.
+Do not continue with sync changes until you can read the SDK skill.

apps/templates/statsig-rollout/.agents/skills/workflow/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: workflow
+description: Build or review Notion App workflows for typed triggers, durable replay-safe steps, and idempotent effects.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# App workflows
+
+Before creating, modifying, or troubleshooting workflow code, read
+`node_modules/@notionhq/apps/skills/workflow/SKILL.md`.
+Resolve this path relative to the App project root.
+Follow the instructions in that file.
+
+If the file is missing, install the project dependencies.
+If it remains missing, update `@notionhq/apps` to a release that includes the skill.
+Do not continue with workflow changes until you can read the SDK skill.

apps/templates/statsig-rollout/.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

apps/templates/statsig-rollout/.claudeignore

@@ -0,0 +1,2 @@
+.env
+.env.*

apps/templates/statsig-rollout/.codexignore

@@ -0,0 +1,2 @@
+.env
+.env.*

apps/templates/statsig-rollout/.env.example

@@ -0,0 +1,2 @@
+STATSIG_CONSOLE_API_KEY=console-xxxxxxxx
+STATSIG_SEGMENT_ID=my_rollout_segment

apps/templates/statsig-rollout/.gitignore

@@ -0,0 +1,12 @@
+.notion/
+app.json
+workers.json
+dist/
+node_modules/
+package-lock.json
+.env
+.env.*
+!.env.example
+
+# Local editor state; each installation creates its own.
+.claude/settings.local.json

apps/templates/statsig-rollout/AGENTS.md

@@ -0,0 +1 @@
+.agents/INSTRUCTIONS.md

apps/templates/statsig-rollout/APP.md

@@ -0,0 +1,10 @@
+---
+icon:
+  type: notion_icon
+  description: flag
+  color: green
+---
+
+Add a space, user, or other UUID below to add it to your Statsig ID List segment. **Status** shows whether it was added.
+
+<database inline="true" data-source-url="rollout-table">Rollout</database>

apps/templates/statsig-rollout/CLAUDE.md

@@ -0,0 +1 @@
+.agents/INSTRUCTIONS.md