import { APIErrorCode, Client, isNotionClientError, type CreateDatabaseParameters, type DatabaseObjectResponse, type DataSourceObjectResponse, type PageObjectResponse, type UpdateDataSourceParameters, } from "@notionhq/client"; import type { ExportSchema, ExportSchemaProperty, ExportableItem, ExportRecordResult } from "../types"; import type { NotionDataSource, NotionExportConfig, NotionPage, NotionPropertyType } from "./types"; /** Notion writes one page per request and throttles around 3 requests/second. */ export const NOTION_MAX_ITEMS_PER_RUN = 100; /** Notion caps a search at 100 results per call; stop after this many pages of results. */ const MAX_SEARCH_CALLS = 10; type PropertyConfig = CreateDatabaseParameters extends { initial_data_source?: { properties?: infer P } } ? P extends Record ? V : never : never; type PageProperties = NonNullable[0]["properties"]>; type PageProperty = PageProperties[string]; const sleep = (ms: number): Promise => new Promise((resolve) => setTimeout(resolve, ms)); function getClient(token: string) { if (!token) { throw new Error("Missing Notion API token"); } return new Client({ auth: token }); } /** * Notion rate-limits aggressively (HTTP 429 with a Retry-After header). Every write * goes through here so a busy workspace slows the sync down instead of failing it. */ async function withRateLimitRetry(fn: () => Promise, maxRetries = 3): Promise { for (let attempt = 1; ; attempt++) { try { return await fn(); } catch (error) { const rateLimited = isNotionClientError(error) && error.code === APIErrorCode.RateLimited; if (!rateLimited || attempt > maxRetries) throw error; const retryAfter = Number((error as { headers?: Record }).headers?.["retry-after"]); await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : attempt * 1000); } } } function describeError(error: unknown): string { if (isNotionClientError(error)) return `${error.code}: ${error.message}`; return error instanceof Error ? error.message : String(error); } function plainTitle(title: { plain_text: string }[] | undefined, fallback: string) { return title?.map((part) => part.plain_text).join("") || fallback; } /** * Pick the property backing the Notion title column. Notion requires exactly one, and * it cannot be added later, so we always end up with one: the datasource `labelBy` * when it points at a usable property, else the first string property, else `$id`. */ function pickTitleProperty(schema: ExportSchema): string { const properties = schema.properties ?? {}; const names = Object.keys(properties); if (schema.labelBy && names.includes(schema.labelBy)) return schema.labelBy; const firstString = names.find((name) => properties[name]?.type === "string" && !name.startsWith("$")); return firstString ?? names.find((name) => name === "$id") ?? names[0]; } function buildPropertyConfig(property: ExportSchemaProperty): PropertyConfig { if (property.type === "boolean") return { checkbox: {} } as PropertyConfig; if (property.type === "number" || property.type === "integer") return { number: {} } as PropertyConfig; if (property.format === "email") return { email: {} } as PropertyConfig; if (property.format === "uri") return { url: {} } as PropertyConfig; if (property.format === "date" || property.format === "date-time") { return { date: {} } as PropertyConfig; } if (property.enum) { const options = property.enum.map((name) => ({ name })); return ( property.metadata?.["ui:widget"] === "checkbox" ? { multi_select: { options } } : { select: { options } } ) as PropertyConfig; } return { rich_text: {} } as PropertyConfig; } /** Build the Notion property configuration of a datasource schema. */ export function buildNotionProperties(schema: ExportSchema): Record { const titleProperty = pickTitleProperty(schema); const properties: Record = {}; for (const [name, property] of Object.entries(schema.properties ?? {})) { properties[name] = name === titleProperty ? ({ title: {} } as PropertyConfig) : buildPropertyConfig(property); } // A data source without a title property is rejected by Notion. if (!Object.keys(properties).length) { properties.Name = { title: {} } as PropertyConfig; } return properties; } function propertyTypes(dataSource: { properties: Record }) { return Object.fromEntries(Object.entries(dataSource.properties).map(([name, prop]) => [name, prop.type])); } /** Convert one item value to the Notion payload matching the remote property type. */ export function toNotionValue(value: unknown, type: NotionPropertyType | string): PageProperty | null { if (value === null || value === undefined || value === "") { // Notion clears a property when it is given an empty value. switch (type) { case "title": return { title: [] } as PageProperty; case "rich_text": return { rich_text: [] } as PageProperty; case "number": return { number: null } as PageProperty; case "url": return { url: null } as PageProperty; case "email": return { email: null } as PageProperty; case "date": return { date: null } as PageProperty; case "checkbox": return { checkbox: false } as PageProperty; default: return null; } } const asText = typeof value === "string" ? value : JSON.stringify(value); switch (type) { case "title": return { title: [{ text: { content: asText.slice(0, 2000) } }] } as PageProperty; case "rich_text": return { rich_text: [{ text: { content: asText.slice(0, 2000) } }] } as PageProperty; case "number": { const num = typeof value === "number" ? value : Number(value); return { number: Number.isNaN(num) ? null : num } as PageProperty; } case "checkbox": return { checkbox: typeof value === "boolean" ? value : ["true", "1", "on", "yes"].includes(asText.toLowerCase()), } as PageProperty; case "date": return { date: { start: value instanceof Date ? value.toISOString() : asText } } as PageProperty; case "email": return { email: asText } as PageProperty; case "url": return { url: asText } as PageProperty; case "phone_number": return { phone_number: asText } as PageProperty; case "select": return { select: { name: asText } } as PageProperty; case "multi_select": { const values = Array.isArray(value) ? value.map(String) : asText .split(",") .map((entry) => entry.trim()) .filter(Boolean); return { multi_select: values.map((name) => ({ name })) } as PageProperty; } default: // Formulas, rollups and the like are computed by Notion: never written to. return null; } } /** * Build the page properties for one item: apply the configured mapping, then coerce * each value to its remote property type. Properties absent from the remote data * source are skipped rather than failing the whole page. */ export function mapItemToNotionProperties( data: Record, config: Pick, ): PageProperties { const properties: PageProperties = {}; for (const [property, value] of Object.entries(data)) { if (value === undefined) continue; const name = config.fieldMapping?.[property] ?? property; const type = config.properties?.[name]; if (!type) continue; const payload = toNotionValue(value, type); if (payload) properties[name] = payload; } return properties; } /** Pages the integration can use as a parent for a new database. */ export async function fetchNotionParentPages(accessToken: string): Promise { const client = getClient(accessToken); const pages: NotionPage[] = []; let cursor: string | undefined; for (let call = 0; call < MAX_SEARCH_CALLS; call++) { const response = await withRateLimitRetry(() => client.search({ filter: { property: "object", value: "page" }, start_cursor: cursor, page_size: 100 }), ); for (const result of response.results) { if (result.object !== "page" || !("parent" in result)) continue; const page = result as PageObjectResponse; // Rows of a data source are pages too; only standalone pages can host a database. if (page.parent.type === "data_source_id" || page.parent.type === "database_id") continue; const titleProperty = Object.values(page.properties).find((property) => property.type === "title"); pages.push({ id: page.id, name: plainTitle(titleProperty?.type === "title" ? titleProperty.title : undefined, "Untitled"), }); } if (!response.has_more || !response.next_cursor) break; cursor = response.next_cursor; } return pages; } /** Existing data sources the items could be written to. */ export async function fetchNotionDataSources(accessToken: string): Promise { const client = getClient(accessToken); const dataSources: NotionDataSource[] = []; let cursor: string | undefined; for (let call = 0; call < MAX_SEARCH_CALLS; call++) { const response = await withRateLimitRetry(() => client.search({ filter: { property: "object", value: "data_source" }, start_cursor: cursor, page_size: 100, }), ); for (const result of response.results) { if (result.object !== "data_source" || !("title" in result)) continue; const dataSource = result as DataSourceObjectResponse; dataSources.push({ id: dataSource.id, name: plainTitle(dataSource.title, "Untitled"), databaseId: dataSource.database_parent?.type === "database_id" ? dataSource.database_parent.database_id : "", fields: Object.entries(dataSource.properties).map(([name, property]) => ({ id: property.id, name, type: property.type, })), }); } if (!response.has_more || !response.next_cursor) break; cursor = response.next_cursor; } return dataSources; } async function retrieveDataSource(client: Client, dataSourceId: string): Promise { const dataSource = await withRateLimitRetry(() => client.dataSources.retrieve({ data_source_id: dataSourceId }), ); // Notion may answer with a partial object; `title` only exists on the full one. if (!("title" in dataSource)) { throw new Error(`Notion returned an incomplete data source ${dataSourceId}`); } return dataSource; } /** Create a Notion database (and its data source) under `parentPageId`. */ export async function createNotionDatabase({ accessToken, parentPageId, name, schema, }: { accessToken: string; parentPageId: string; name: string; schema: ExportSchema; }): Promise { const client = getClient(accessToken); const created = await withRateLimitRetry(() => client.databases.create({ parent: { type: "page_id", page_id: parentPageId }, title: [{ type: "text", text: { content: name } }], initial_data_source: { properties: buildNotionProperties(schema) }, }), ); // The create response can be partial: re-read the database to get its data source. const database = (await withRateLimitRetry(() => client.databases.retrieve({ database_id: created.id }), )) as DatabaseObjectResponse; const dataSourceId = database.data_sources?.[0]?.id; if (!dataSourceId) { throw new Error("Notion database was created without a data source"); } const dataSource = await retrieveDataSource(client, dataSourceId); return { parentPageId, databaseId: database.id, dataSourceId, databaseName: plainTitle(database.title, name), externalUrl: database.url, properties: propertyTypes(dataSource), fieldMapping: {}, createdByUpstart: true, }; } /** * Add to an existing data source the properties missing on the Notion side, and * return the configuration to store. Properties removed from the datasource are left * in place on Notion. */ export async function attachNotionDataSource({ accessToken, dataSourceId, schema, fieldMapping = {}, }: { accessToken: string; dataSourceId: string; schema: ExportSchema; fieldMapping?: Record; }): Promise { const client = getClient(accessToken); const dataSource = await retrieveDataSource(client, dataSourceId); const existing = new Set(Object.keys(dataSource.properties)); const wanted = buildNotionProperties(schema); const missing: UpdateDataSourceParameters["properties"] = {}; for (const [name, config] of Object.entries(wanted)) { const remoteName = fieldMapping[name] ?? name; // Only one title property may exist, and the remote one already has it. if (existing.has(remoteName) || "title" in (config as Record)) continue; (missing as Record)[remoteName] = config; } const updated = Object.keys(missing ?? {}).length ? await withRateLimitRetry(() => client.dataSources.update({ data_source_id: dataSourceId, properties: missing }), ) : dataSource; const properties = "properties" in updated ? updated.properties : dataSource.properties; const databaseId = dataSource.database_parent?.type === "database_id" ? dataSource.database_parent.database_id : ""; return { databaseId, dataSourceId, databaseName: plainTitle(dataSource.title, "Untitled"), externalUrl: dataSource.url, properties: propertyTypes({ properties }), fieldMapping, createdByUpstart: false, }; } /** * Create or update one Notion page per item. Notion has no batch endpoint, so items * are pushed sequentially and a failing item never stops the others. */ export async function upsertNotionRecords({ accessToken, config, items, }: { accessToken: string; config: NotionExportConfig; items: ExportableItem[]; }): Promise { const client = getClient(accessToken); const results: ExportRecordResult[] = []; for (const item of items) { const properties = mapItemToNotionProperties(item.data, config); const createPage = () => withRateLimitRetry(() => client.pages.create({ parent: { type: "data_source_id", data_source_id: config.dataSourceId }, properties, }), ); // A page deleted in Notion is only moved to the trash, and Notion refuses to edit // an archived page ("Can't edit block that is archived"). Since the Upstart item is // the source of truth, every update also restores the page: that revives the // original one — keeping its id, its content and its comments — instead of leaving // a duplicate behind the day the user empties the trash. On a page that is not // archived, `in_trash: false` is a no-op. const updatePage = () => withRateLimitRetry(() => client.pages.update({ page_id: item.externalRecordId as string, properties, in_trash: false }), ); let pageWasPurged = false; try { if (item.externalRecordId) { try { await updatePage(); results.push({ itemId: item.itemId, externalRecordId: item.externalRecordId }); } catch (error) { // Permanently deleted (trash emptied): the id is dead, create a page now // rather than failing this run and recreating on the next one. if (!isNotionClientError(error) || error.code !== APIErrorCode.ObjectNotFound) throw error; pageWasPurged = true; const page = await createPage(); results.push({ itemId: item.itemId, externalRecordId: page.id }); } } else { const page = await createPage(); results.push({ itemId: item.itemId, externalRecordId: page.id }); } } catch (error) { // The stored id is only forgotten when the page was purged AND recreating it // just failed too, so the next run starts from a create. Every other failure // keeps the link: a validation error means the payload no longer matches the // remote schema (a renamed property, say), and dropping the id there would // create a duplicate page as soon as the schema is fixed. results.push({ itemId: item.itemId, error: describeError(error), resetExternalRecordId: pageWasPurged, }); } } return results; } /** Notion has no hard delete: a removed item archives its page (moves it to trash). */ export async function deleteNotionRecords({ accessToken, recordIds, }: { accessToken: string; recordIds: string[]; }): Promise { const client = getClient(accessToken); for (const pageId of recordIds) { try { await withRateLimitRetry(() => client.pages.update({ page_id: pageId, in_trash: true })); } catch (error) { // Already gone on the Notion side: nothing to do. if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) continue; throw new Error(`Failed to archive Notion page ${pageId}: ${describeError(error)}`); } } }