Notion

interface NotionInternalConfig {
  token:                  string;   // Notion internal integration secret (secret_...)
  deliverablesDatabaseId: string;   // Notion database ID for deliverable period entries
  strategyParentPageId?:  string;   // Page under which strategy pages are created
  reportParentPageId?:    string;   // Page under which monthly report pages are created
}

scope: Notion scopes are workspace-level — the OAuth token grants access to
       any pages/databases the user shares with the integration.

Stored in integrations:
  provider:   'notion'
  api_key:    encrypt(token)
  metadata:   {
    connectionType:         'internal' | 'oauth',
    workspaceId:            string,
    workspaceName:          string,
    deliverablesDatabaseId: string,
    strategyParentPageId:   string | null,
    reportParentPageId:     string | null,
  }

import { Client } from '@notionhq/client';
 
class NotionTool {
  private client: Client;
 
  constructor(private token: string) {
    this.client = new Client({ auth: token });
  }
 
  /**
   * Create a new page under a parent page.
   * Used for strategy documents and monthly reports.
   */
  async createPage(options: {
    parentPageId: string;
    title:        string;
    markdownBody: string;   // Converted to Notion blocks via markdown-to-blocks
  }): Promise<{ pageId: string; url: string }> {
    const blocks = markdownToNotionBlocks(options.markdownBody);
 
    const response = await this.client.pages.create({
      parent: { type: 'page_id', page_id: options.parentPageId },
      properties: {
        title: {
          title: [{ type: 'text', text: { content: options.title } }],
        },
      },
      children: blocks.slice(0, 100),   // Notion API: max 100 blocks per request
    });
 
    // Append remaining blocks in batches if content > 100 blocks
    if (blocks.length > 100) {
      await this.appendBlocks({ pageId: response.id, blocks: blocks.slice(100) });
    }
 
    return {
      pageId: response.id,
      url:    (response as any).url,
    };
  }
 
  /**
   * Append additional blocks to an existing page.
   * Used when content exceeds 100 blocks.
   */
  async appendBlocks(options: {
    pageId: string;
    blocks: object[];
  }): Promise<void> {
    const CHUNK_SIZE = 100;
    for (let i = 0; i < options.blocks.length; i += CHUNK_SIZE) {
      await this.client.blocks.children.append({
        block_id: options.pageId,
        children: options.blocks.slice(i, i + CHUNK_SIZE) as any,
      });
    }
  }
 
  /**
   * Create a row in a Notion database.
   * Used for deliverable period tracking.
   */
  async createDatabaseEntry(options: {
    databaseId: string;
    properties: {
      name:         string;            // "April 2026 — Acme Corp"
      status:       'In Progress' | 'Ready for Review' | 'Approved' | 'Delivered';
      periodStart:  string;            // ISO date
      periodEnd:    string;            // ISO date
      blogCount:    number;
      socialCount:  number;
      portalUrl:    string;
    };
  }): Promise<{ pageId: string; url: string }> {
    const response = await this.client.pages.create({
      parent: { type: 'database_id', database_id: options.databaseId },
      properties: {
        Name: {
          title: [{ type: 'text', text: { content: options.properties.name } }],
        },
        Status: {
          select: { name: options.properties.status },
        },
        'Period Start': {
          date: { start: options.properties.periodStart },
        },
        'Period End': {
          date: { start: options.properties.periodEnd },
        },
        'Blog Posts': {
          number: options.properties.blogCount,
        },
        'Social Posts': {
          number: options.properties.socialCount,
        },
        'Review Link': {
          url: options.properties.portalUrl,
        },
      },
    });
 
    return {
      pageId: response.id,
      url:    (response as any).url,
    };
  }
 
  /**
   * Update the Status property of an existing database entry.
   * Called when a deliverable period is approved by the client.
   */
  async updateDatabaseEntryStatus(options: {
    pageId: string;
    status: 'In Progress' | 'Ready for Review' | 'Approved' | 'Delivered';
  }): Promise<void> {
    await this.client.pages.update({
      page_id:    options.pageId,
      properties: {
        Status: { select: { name: options.status } },
      },
    });
  }
 
  async verify(): Promise<void> {
    await this.client.users.me({});
  }
}

import { markdownToBlocks } from '@tryfabric/martian';
 
function markdownToNotionBlocks(markdown: string): object[] {
  return markdownToBlocks(markdown);
}

Strategy Writer agent generates strategy document (Markdown)
        │
        ▼ (HITL review by DM team + client approval)
Strategy Publisher worker
  ├── Resolve tenant's Notion integration
  ├── Convert Markdown to Notion blocks
  ├── Call createPage() under strategyParentPageId
  └── Store notion_page_id + url in strategy_versions table
        │
        ▼
Client can view/comment directly in Notion

Deliverable period marked "Ready for Review"
        │
        ▼
Deliverable Publisher worker
  ├── Resolve tenant's Notion integration
  ├── Call createDatabaseEntry() with period stats and portal URL
  └── Store notion_page_id in deliverable_periods table
        │
        ▼
When client approves in platform → updateDatabaseEntryStatus('Approved')