@project-ajax/sdk 0.0.28

package/src/block.ts

@@ -0,0 +1,529 @@
+// ============================================================================
+// Block Type Definitions
+// ============================================================================
+
+// Color types
+type ApiColor =
+	| "default"
+	| "gray"
+	| "brown"
+	| "orange"
+	| "yellow"
+	| "green"
+	| "blue"
+	| "purple"
+	| "pink"
+	| "red"
+	| "gray_background"
+	| "brown_background"
+	| "orange_background"
+	| "yellow_background"
+	| "green_background"
+	| "blue_background"
+	| "purple_background"
+	| "pink_background"
+	| "red_background";
+
+// Rich text annotations
+type RichTextAnnotations = {
+	bold: boolean;
+	italic: boolean;
+	strikethrough: boolean;
+	underline: boolean;
+	code: boolean;
+	color: ApiColor;
+};
+
+// Base rich text structure
+type RichTextBase = {
+	plain_text: string;
+	href: string | null;
+	annotations: RichTextAnnotations;
+};
+
+// Text content
+type TextContent = {
+	content: string;
+	link: { url: string } | null;
+};
+
+// Equation content
+type EquationContent = {
+	expression: string;
+};
+
+// Date mention
+type DateMention = {
+	type: "date";
+	date: {
+		start: string;
+		end?: string | null;
+		time_zone?: string | null;
+	};
+};
+
+// Custom emoji mention
+type CustomEmojiMention = {
+	type: "custom_emoji";
+	custom_emoji: {
+		id: string;
+		name?: string;
+		url?: string;
+	};
+};
+
+// Link preview mention
+type LinkPreviewMention = {
+	type: "link_preview";
+	link_preview: {
+		url: string;
+	};
+};
+
+// Link mention
+type LinkMention = {
+	type: "link_mention";
+	link_mention: {
+		href: string;
+	};
+};
+
+// All mention types
+type MentionContent =
+	| DateMention
+	| CustomEmojiMention
+	| LinkPreviewMention
+	| LinkMention;
+
+// Rich text item
+type RichTextItem = RichTextBase &
+	(
+		| { type: "text"; text: TextContent }
+		| { type: "mention"; mention: MentionContent }
+		| { type: "equation"; equation: EquationContent }
+	);
+
+// Rich text array
+type RichText = RichTextItem[];
+
+// Icon types
+type EmojiIcon = {
+	type: "emoji";
+	emoji: string;
+};
+
+type ExternalIcon = {
+	type: "external";
+	external: { url: string };
+};
+
+type FileIcon = {
+	type: "file";
+	file: {
+		url: string;
+		expiry_time: string;
+	};
+};
+
+type Icon = EmojiIcon | ExternalIcon | FileIcon;
+
+// File object types
+type ExternalFile = {
+	type: "external";
+	external: {
+		url: string;
+	};
+};
+
+type HostedFile = {
+	type: "file";
+	file: {
+		url: string;
+		expiry_time: string;
+	};
+	name?: string;
+};
+
+type FileObject = ExternalFile | HostedFile;
+
+// Base block structure
+type BlockBase = {
+	object: "block";
+};
+
+// Text blocks
+type ParagraphBlock = BlockBase & {
+	type: "paragraph";
+	paragraph: {
+		rich_text: RichText;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type Heading1Block = BlockBase & {
+	type: "heading_1";
+	heading_1: {
+		rich_text: RichText;
+		color?: ApiColor;
+		is_toggleable?: boolean;
+		children?: Block[];
+	};
+};
+
+type Heading2Block = BlockBase & {
+	type: "heading_2";
+	heading_2: {
+		rich_text: RichText;
+		color?: ApiColor;
+		is_toggleable?: boolean;
+		children?: Block[];
+	};
+};
+
+type Heading3Block = BlockBase & {
+	type: "heading_3";
+	heading_3: {
+		rich_text: RichText;
+		color?: ApiColor;
+		is_toggleable?: boolean;
+		children?: Block[];
+	};
+};
+
+type BulletedListItemBlock = BlockBase & {
+	type: "bulleted_list_item";
+	bulleted_list_item: {
+		rich_text: RichText;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type NumberedListItemBlock = BlockBase & {
+	type: "numbered_list_item";
+	numbered_list_item: {
+		rich_text: RichText;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type ToDoBlock = BlockBase & {
+	type: "to_do";
+	to_do: {
+		rich_text: RichText;
+		checked: boolean;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type ToggleBlock = BlockBase & {
+	type: "toggle";
+	toggle: {
+		rich_text: RichText;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type QuoteBlock = BlockBase & {
+	type: "quote";
+	quote: {
+		rich_text: RichText;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+type CalloutBlock = BlockBase & {
+	type: "callout";
+	callout: {
+		rich_text: RichText;
+		icon?: Icon | null;
+		color?: ApiColor;
+		children?: Block[];
+	};
+};
+
+// Code block
+type CodeBlock = BlockBase & {
+	type: "code";
+	code: {
+		rich_text: RichText;
+		caption?: RichText;
+		language: string;
+	};
+};
+
+// Equation block
+type EquationBlock = BlockBase & {
+	type: "equation";
+	equation: {
+		expression: string;
+	};
+};
+
+// Divider block
+type DividerBlock = BlockBase & {
+	type: "divider";
+	divider: Record<string, never>;
+};
+
+// Breadcrumb block
+type BreadcrumbBlock = BlockBase & {
+	type: "breadcrumb";
+	breadcrumb: Record<string, never>;
+};
+
+// Table of contents block
+type TableOfContentsBlock = BlockBase & {
+	type: "table_of_contents";
+	table_of_contents: {
+		color?: ApiColor;
+	};
+};
+
+// Column layout blocks
+type ColumnListBlock = BlockBase & {
+	type: "column_list";
+	column_list: {
+		children: ColumnBlock[];
+	};
+};
+
+type ColumnBlock = BlockBase & {
+	type: "column";
+	column: {
+		children?: Block[];
+	};
+};
+
+// Media blocks
+type ImageBlock = BlockBase & {
+	type: "image";
+	image: FileObject & {
+		caption?: RichText;
+	};
+};
+
+type VideoBlock = BlockBase & {
+	type: "video";
+	video: FileObject & {
+		caption?: RichText;
+	};
+};
+
+type AudioBlock = BlockBase & {
+	type: "audio";
+	audio: FileObject & {
+		caption?: RichText;
+	};
+};
+
+type PDFBlock = BlockBase & {
+	type: "pdf";
+	pdf: FileObject & {
+		caption?: RichText;
+	};
+};
+
+type FileBlock = BlockBase & {
+	type: "file";
+	file: FileObject & {
+		caption?: RichText;
+	};
+};
+
+// Embed and bookmark blocks
+type EmbedBlock = BlockBase & {
+	type: "embed";
+	embed: {
+		url: string;
+		caption?: RichText;
+	};
+};
+
+type BookmarkBlock = BlockBase & {
+	type: "bookmark";
+	bookmark: {
+		url: string;
+		caption?: RichText;
+	};
+};
+
+// Link preview block
+type LinkPreviewBlock = BlockBase & {
+	type: "link_preview";
+	link_preview: {
+		url: string;
+	};
+};
+
+// Reference blocks
+type ChildPageBlock = BlockBase & {
+	type: "child_page";
+	child_page: {
+		title: string;
+	};
+};
+
+type ChildDatabaseBlock = BlockBase & {
+	type: "child_database";
+	child_database: {
+		title: string;
+	};
+};
+
+// type LinkToPageBlock = BlockBase & {
+// 	type: "link_to_page"
+// 	link_to_page:
+// 		| { type: "page_id"; page_id: string }
+// 		| { type: "database_id"; database_id: string }
+// }
+
+// // Synced block
+// type SyncedBlock = BlockBase & {
+// 	type: "synced_block"
+// 	synced_block: {
+// 		synced_from: {
+// 			type: "block_id"
+// 			block_id: string
+// 		} | null
+// 		children?: Block[]
+// 	}
+// }
+
+// Template block
+type TemplateBlock = BlockBase & {
+	type: "template";
+	template: {
+		rich_text: RichText;
+		children?: Block[];
+	};
+};
+
+// Table blocks
+type TableBlock = BlockBase & {
+	type: "table";
+	table: {
+		table_width: number;
+		has_column_header: boolean;
+		has_row_header: boolean;
+		children: TableRowBlock[];
+	};
+};
+
+type TableRowBlock = BlockBase & {
+	type: "table_row";
+	table_row: {
+		cells: RichText[];
+	};
+};
+
+// AI block
+type AIBlock = BlockBase & {
+	type: "ai_block";
+	ai_block: {
+		prompt?: string;
+	};
+};
+
+// Unsupported block
+type UnsupportedBlock = BlockBase & {
+	type: "unsupported";
+	unsupported: Record<string, never>;
+};
+
+// All block types union
+type Block =
+	| ParagraphBlock
+	| Heading1Block
+	| Heading2Block
+	| Heading3Block
+	| BulletedListItemBlock
+	| NumberedListItemBlock
+	| ToDoBlock
+	| ToggleBlock
+	| QuoteBlock
+	| CalloutBlock
+	| CodeBlock
+	| EquationBlock
+	| DividerBlock
+	| BreadcrumbBlock
+	| TableOfContentsBlock
+	| ColumnListBlock
+	| ColumnBlock
+	| ImageBlock
+	| VideoBlock
+	| AudioBlock
+	| PDFBlock
+	| FileBlock
+	| EmbedBlock
+	| BookmarkBlock
+	| LinkPreviewBlock
+	| ChildPageBlock
+	| ChildDatabaseBlock
+	| TemplateBlock
+	| TableBlock
+	| TableRowBlock
+	| AIBlock
+	| UnsupportedBlock;
+
+// Export all types
+export type {
+	RichText,
+	RichTextItem,
+	RichTextBase,
+	RichTextAnnotations,
+	TextContent,
+	EquationContent,
+	MentionContent,
+	DateMention,
+	CustomEmojiMention,
+	LinkPreviewMention,
+	LinkMention,
+	ApiColor,
+	Icon,
+	EmojiIcon,
+	ExternalIcon,
+	FileIcon,
+	FileObject,
+	ExternalFile,
+	HostedFile,
+	BlockBase,
+	ParagraphBlock,
+	Heading1Block,
+	Heading2Block,
+	Heading3Block,
+	BulletedListItemBlock,
+	NumberedListItemBlock,
+	ToDoBlock,
+	ToggleBlock,
+	QuoteBlock,
+	CalloutBlock,
+	CodeBlock,
+	EquationBlock,
+	DividerBlock,
+	BreadcrumbBlock,
+	TableOfContentsBlock,
+	ColumnListBlock,
+	ColumnBlock,
+	ImageBlock,
+	VideoBlock,
+	AudioBlock,
+	PDFBlock,
+	FileBlock,
+	EmbedBlock,
+	BookmarkBlock,
+	LinkPreviewBlock,
+	ChildPageBlock,
+	ChildDatabaseBlock,
+	TemplateBlock,
+	TableBlock,
+	TableRowBlock,
+	AIBlock,
+	UnsupportedBlock,
+	Block,
+};

package/src/builder.ts

@@ -0,0 +1,26 @@
+import type { TextValue } from "./types.js";
+
+export function richText(content: string): TextValue {
+	return [[content]];
+}
+
+export function url(url: string): TextValue {
+	return [[url]];
+}
+
+export function title(content: string): TextValue {
+	return [[content]];
+}
+
+export function text(content: string): TextValue {
+	return [[content]];
+}
+
+/**
+ * Creates a link with custom display text
+ * @param displayText - The text to display
+ * @param url - The URL to link to
+ */
+export function link(displayText: string, url: string): TextValue {
+	return [[displayText, [["a", url]]]];
+}

package/src/capabilities/slashCommand.ts

@@ -0,0 +1,71 @@
+import type { Block } from "../block.js";
+import { ExecutionError } from "../error.js";
+
+export type SlashCommandConfiguration = {
+	menuTitle: string;
+	menuDescription: string;
+	search: {
+		placeholder: string;
+		debounce: number;
+	};
+
+	/**
+	 * A function that returns a list of items to display in the search results
+	 * as well as the corresponding blocks to insert for each item should it be selected.
+	 */
+	executeSearch: (searchQuery: string) => Promise<{
+		items: { title: string; description: string; id: string }[];
+	}>;
+	executeSelect: (selectedItemId: string) => Promise<Block[]>;
+};
+
+export type SlashCommandHandlerResult = {
+	menuTitle: string;
+	menuDescription: string;
+	search: {
+		placeholder: string;
+		debounce: number;
+	};
+};
+
+/**
+ * Creates a special handler for handling slash commands.
+ *
+ * @param slashCommandConfiguration - The configuration for the slash command.
+ * @returns A handler function that executes the slash command function, and passes data
+ * needed to complete the operation back to the platform.
+ */
+export function slashCommand(
+	slashCommandConfiguration: SlashCommandConfiguration,
+) {
+	return {
+		_tag: "slashCommand",
+		config: {
+			menuTitle: slashCommandConfiguration.menuTitle,
+			menuDescription: slashCommandConfiguration.menuDescription,
+			search: slashCommandConfiguration.search,
+		},
+		async handleSearch(searchQuery: string) {
+			const result = await slashCommandConfiguration
+				.executeSearch(searchQuery)
+				.catch((err) => {
+					throw new ExecutionError(err);
+				});
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return result;
+		},
+		async handleSelect(selectedItemId: string) {
+			const result = await slashCommandConfiguration
+				.executeSelect(selectedItemId)
+				.catch((err) => {
+					throw new ExecutionError(err);
+				});
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return result;
+		},
+	};
+}

package/src/capabilities/sync.ts

@@ -0,0 +1,76 @@
+import { ExecutionError } from "../error.js";
+import type { PropertySchema, Schema } from "../schema.js";
+import type { TextValue } from "../types.js";
+
+/**
+ * An object representing a third-party record to be synced.
+ */
+export type SyncedObject<PK extends string, S extends PropertySchema<PK>> = {
+	key: string;
+	properties: { [Property in keyof S]: TextValue };
+};
+
+/**
+ * A configuration object that enables synchronization between a data
+ * source and a third-party source.
+ */
+export type SyncConfiguration<PK extends string, S extends Schema<PK>> = {
+	/**
+	 * The property of the data source that maps to a "primary key" in the
+	 * third-party data. This is used to match existing pages to
+	 * records in the third-party service. Must be a property defined in the schema.
+	 */
+	primaryKeyProperty: PK;
+
+	/**
+	 * The schema defining the structure of properties in the collection.
+	 */
+	schema: S;
+
+	/**
+	 * A function that fetches the data to sync from the third-party service.
+	 *
+	 * For now, this function must return all of the data to be synced each time
+	 * it's called. The runtime will handle diffing this against the data source
+	 * and creating, updating, and deleting pages as necessary.
+	 */
+	execute: () => Promise<SyncedObject<PK, PropertySchema<PK>>[]>;
+};
+
+export type SyncHandlerResult<PK extends string> = {
+	primaryKeyProperty: PK;
+	objects: SyncedObject<PK, PropertySchema<PK>>[];
+};
+
+/**
+ * Creates a special handler for syncing third-party data to a collection.
+ *
+ * @param syncConfiguration - The configuration for the sync.
+ * @returns A handler function that executes the sync function, and passes data
+ * needed to complete the sync back to the platform.
+ */
+export function sync<PK extends string, S extends Schema<PK>>(
+	syncConfiguration: SyncConfiguration<PK, S>,
+) {
+	return {
+		_tag: "sync",
+		config: {
+			schema: syncConfiguration.schema,
+		},
+		async handler() {
+			const objects = await syncConfiguration.execute().catch((err) => {
+				throw new ExecutionError(err);
+			});
+
+			const result = {
+				schema: syncConfiguration.schema,
+				primaryKeyProperty: syncConfiguration.primaryKeyProperty,
+				objects,
+			};
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return result;
+		},
+	};
+}