API Reference

import NotionORM from "@haustle/notion-orm";

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

// DatabaseClient
const db = notion.databases.yourDatabaseName;
// AgentClient
const agent = notion.agents.yourAgentName;

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

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

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

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

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

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

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

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

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

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

await db.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 db.createMany({
  properties: [
    { bookName: "Book A", genre: ["Sci-Fi"], numberOfPages: 300 },
    { bookName: "Book B", genre: ["Biography"], numberOfPages: 250 },
  ],
});

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

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

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

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

await db.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");