API Reference

import { NotionORM } from "./notion";

const notion = new NotionORM({
  auth: process.env.NOTION_KEY,
});

// DatabaseClient — e.g. notion.databases.books
// AgentClient — e.g. notion.agents.helpBot

const page = await notion.booksDb.findUnique({
  where: { id: "page-id-here" },
  select: ["bookName", "status"],
});

const book = await notion.booksDb.findFirst({
  where: { bookName: { equals: "Creativity, Inc." } },
});

// Simple query — returns all rows
const allBooks = await notion.booksDb.findMany();

// Filtered + sorted + projected
const recent = await notion.booksDb.findMany({
  where: { publishDate: { on_or_after: "2025-01-01" } },
  sortBy: [{ property: "publishDate", direction: "descending" }],
  select: ["bookName", "publishDate"],
  size: 20,
});

// Cursor pagination
const firstPage = await notion.booksDb.findMany({ after: null, size: 10 });
const secondPage = await notion.booksDb.findMany({ after: firstPage.nextCursor, size: 10 });
// firstPage.data, firstPage.hasMore, firstPage.nextCursor

// Streaming large datasets
for await (const row of notion.booksDb.findMany({ stream: 100 })) {
  console.log(row.bookName);
}

// Walk every page: start with after: null, then pass nextCursor until it is null
let after: string | null = null;
do {
  const page = await notion.booksDb.findMany({ after, size: 10 });
  for (const row of page.data) {
    /* use row */
  }
  after = page.nextCursor;
} while (after !== null);

await notion.booksDb.findMany({
  where: { genre: { contains: "Sci-Fi" } },
});

await notion.booksDb.findMany({
  where: {
    and: [
      { genre: { contains: "Sci-Fi" } },
      { numberOfPages: { greater_than: 200 } },
      {
        or: [
          { status: { equals: "In progress" } },
          { status: { equals: "Not started" } },
        ],
      },
    ],
  },
});

const total = await notion.booksDb.count();
const filtered = await notion.booksDb.count({
  where: { status: { equals: "Done" } },
});

const result = await notion.booksDb.create({
  properties: {
    bookName: "The Dream Machine",
    genre: ["Non-fiction"],
    numberOfPages: 460,
  },
  icon: { type: "emoji", emoji: "📗" },
});
// result.id — the new page ID

await notion.booksDb.create({
  properties: {
    bookName: "Reading Notes",
  },
  markdown: "# Key Takeaways\n\n- **Creativity requires candor** — honest feedback loops matter\n- Protect the new — early ideas are fragile\n\n> \"Quality is the best business plan.\"",
});

const results = await notion.booksDb.createMany([
  { properties: { bookName: "Book A", genre: ["Sci-Fi"], numberOfPages: 300 } },
  { properties: { bookName: "Book B", genre: ["Biography"], numberOfPages: 250 } },
  {
    properties: { bookName: "Book C", genre: ["Fantasy"], numberOfPages: 420 },
    icon: { type: "emoji", emoji: "📘" },
  },
  {
    properties: { bookName: "Book D", genre: ["History"], numberOfPages: 380 },
    markdown: "# Notes\n\n- Imported from archive",
  },
]);

await notion.booksDb.update({
  where: { id: "page-id" },
  properties: { status: "Done", numberOfPages: 512 },
});

await notion.booksDb.updateMany({
  where: { status: { equals: "Draft" } },
  properties: { status: "In progress" },
});

await notion.booksDb.upsert({
  where: { bookName: { equals: "The Dream Machine" } },
  create: {
    bookName: "The Dream Machine",
    genre: ["Non-fiction"],
    numberOfPages: 460,
  },
  update: { numberOfPages: 500 },
});

await notion.booksDb.delete({ where: { id: "page-id" } });

await notion.booksDb.deleteMany({
  where: { status: { equals: "Archived" } },
});

const first = await notion.agents.helpBot.chat({
  message: "Give me a high-protein dinner idea under 30 minutes.",
});
// first.threadId, first.status, first.isNewChat

const followUp = await notion.agents.helpBot.chat({
  threadId: first.threadId,
  message: "Now make it vegetarian.",
});

import { AgentClient } from "@haustle/notion-orm";

const thread = await notion.agents.helpBot.chatStream({
  message: "How do I reset my password?",
  onMessage: (msg) => {
    if (msg.role === "agent") process.stdout.write(msg.content);
  },
});

const plainText = AgentClient.getAgentResponse(thread);

const continued = await notion.agents.helpBot.chatStream({
  threadId: thread.threadId,
  message: "Shorter version, bullet points only.",
  onMessage: (msg) => {
    /* … */
  },
});

import { AgentClient } from "@haustle/notion-orm";

const thread = await notion.agents.helpBot.chatStream({
  message: "One paragraph about our refund policy.",
});
const answer = AgentClient.getAgentResponse(thread);

const chat = await notion.agents.helpBot.chat({
  message: "Summarize yesterday’s standup notes.",
});
await notion.agents.helpBot.pollThread(chat.threadId);

// Optional: tune polling (defaults: maxAttempts 60, baseDelayMs 1000, …)
await notion.agents.helpBot.pollThread(chat.threadId, {
  maxAttempts: 30,
  initialDelayMs: 500,
});

await notion.agents.helpBot.pollThread(threadId);

const all = await notion.agents.helpBot.getMessages(threadId);
const agentOnly = await notion.agents.helpBot.getMessages(threadId, {
  role: "agent",
});

const threads = await notion.agents.helpBot.listThreads();
for (const t of threads) {
  console.log(t.id, t.title, t.status);
}

const info = await notion.agents.helpBot.getThreadInfo("thread-id-here");
// info.id, info.title, info.status, …

const title = await notion.agents.helpBot.getThreadTitle("thread-id-here");

// Generated by @haustle/notion-orm — do not edit manually.
// Regenerate with `notion sync` (or your package script).

import type {
  DatabaseColumns,
  DatabaseDefinition,
  InferCreateSchema,
  InferDatabaseSchema,
  Query,
} from "@haustle/notion-orm";
import { DatabaseClient } from "@haustle/notion-orm";

// Option literals for select / status / multi_select columns
export const CategoryPropertyValues = ["Electronics", "Clothing", "Food"] as const;

export const AvailabilityPropertyValues = [
  "In Stock",
  "Out of Stock",
  "Backordered",
] as const;

export const TagsPropertyValues = ["New", "Sale", "Featured"] as const;

const columns = {
  "itemName": { columnName: "Item Name", type: "title" },
  "category": {
    columnName: "Category",
    type: "select",
    options: CategoryPropertyValues,
  },
  "availability": {
    columnName: "Availability",
    type: "status",
    options: AvailabilityPropertyValues,
  },
  "tags": {
    columnName: "Tags",
    type: "multi_select",
    options: TagsPropertyValues,
  },
  "price": { columnName: "Price", type: "number" },
  // …plus every other supported column type (e.g. relations, rich_text, files, …)
} as const satisfies DatabaseColumns;

export type PageSchema = InferDatabaseSchema<typeof columns>;
export type CreateSchema = InferCreateSchema<typeof columns>;
export type QuerySchema = Query<DatabaseDefinition<typeof columns>>;

export const InventoryItems = (auth: string) => {
  return new DatabaseClient<DatabaseDefinition<typeof columns>>({
    id: "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
    columns,
    name: "Inventory Items",
    auth,
  });
};

notion/
├── index.ts                 # NotionORM entry + re-exports
├── databases/
│   ├── index.ts             # `databases` registry barrel (all DB factories)
│   ├── <Database>.ts        # one file per tracked database (e.g. CustomerOrders.ts)
│   └── metadata.json        # sync cache: ids + display names for incremental runs
└── agents/
    ├── index.ts             # `agents` registry barrel (all agent factories)
    ├── <Agent>.ts           # one file per agent (e.g. MealAgent.ts)
    └── metadata.json        # sync cache for agents