@kody/notion

/**
 * Package overview for Notion helpers: API version, reconnect URL, and export map.
 * Use domain exports for reads/writes and `./request` as the generic API escape hatch.
 *
 * @returns `{ integration, apiBaseUrl, notionVersion, reconnectUrl, exports, safety, notes }`.
 *
 * @example
 * import notionOverview from 'kody:@kody/notion'
 * const overview = await notionOverview()
 * // => { integration: 'notion', notionVersion: '2026-03-11', safety: { mutationsRequireConfirmation: true, … } }
 */
export default async function notionOverview() {
  return {
    integration: 'notion',
    apiBaseUrl: 'https://api.notion.com/v1',
    notionVersion: '2026-03-11',
    reconnectUrl: 'https://kody.codes/connect/oauth?provider=notion',
    exports: [
      'smoke-test',
      'request',
      'search',
      'get-page',
      'get-block-children',
      'get-database',
      'get-data-source',
      'query-database',
      'create-page',
      'append-block-children',
    ],
    safety: {
      mutationsRequireConfirmation: true,
      dryRunAvailable: true,
    },
    notes: [
      'Access is limited to pages and databases shared with the connected Notion integration.',
      'Use the search export first to discover page and data source ids (databases surface as data_source objects).',
      'Databases are containers: get-database lists data sources; get-data-source reads the schema; query-database queries rows (accepts databaseId with auto-resolve, or dataSourceId).',
      'Database-row pages need a data source parent; create-page auto-resolves parent.database_id to the single data source.',
      'append-block-children positions blocks via position { type: after_block | start | end }.',
      'Trash status is the in_trash field (the archived field no longer exists).',
      'To create an inline child database on a page, POST /databases via request with parent { type: "page_id" }, is_inline: true, and initial_data_source: { properties }.',
    ],
  }
}