@project-ajax/sdk 0.0.69 → 0.0.71

package/dist/capabilities/sync.d.ts

@@ -9,41 +9,79 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
     type: "place";
 } ? PlaceValue : TextValue;
 /**
- * An object representing a third-party record to be synced.
+ * Sync mode determines how the sync handles data lifecycle.
  */
-export type SyncedObject<PK extends string, S extends PropertySchema<PK>> = {
+export type SyncMode = "replace" | "incremental";
+/**
+ * A change representing a record to be created or updated.
+ */
+export type SyncChangeUpsert<PK extends string, S extends PropertySchema<PK>> = {
+    /**
+     * The type of change. Use `"upsert"` to create or update a record.
+     */
+    type: "upsert";
+    /**
+     * A unique identifier for this record, used to match against existing pages.
+     * This value will be stored in the property specified by `primaryKeyProperty`.
+     */
     key: string;
+    /**
+     * The property values for this record.
+     * Keys must match the property names defined in the schema.
+     * Use the Builder helpers (e.g., `Builder.title()`, `Builder.richText()`) to create values.
+     */
     properties: {
         [Property in keyof S]: PropertyValueType<S[Property]>;
     };
     /**
      * Optional icon to use as the icon for this row's page.
-     * Use the `icon()` builder to create an icon value.
+     * Use the `Builder.emojiIcon()`, `Builder.notionIcon()`, or `Builder.imageIcon()` helpers.
      */
     icon?: Icon;
     /**
-     * Optional markdown content to add to the page.
-     * This will be converted to blocks and added as page content.
+     * Optional markdown content to add to the page body.
+     * This will be converted to Notion blocks and added as page content.
      */
     pageContentMarkdown?: string;
 };
+/**
+ * A change representing a record to be deleted.
+ * Only applicable when using `mode: "incremental"`.
+ */
+export type SyncChangeDelete = {
+    /**
+     * The type of change. Use `"delete"` to remove a record.
+     */
+    type: "delete";
+    /**
+     * The unique identifier of the record to delete.
+     * Must match the `key` of a previously upserted record.
+     */
+    key: string;
+};
+/**
+ * A change to be applied to the synced database.
+ * Can be either an upsert (create/update) or a delete.
+ */
+export type SyncChange<PK extends string, S extends PropertySchema<PK>> = SyncChangeUpsert<PK, S> | SyncChangeDelete;
 /**
  * Result returned from the sync execute function.
  */
 export type SyncExecutionResult<PK extends string, Context = unknown> = {
     /**
-     * The batch of objects fetched in this execution.
+     * The batch of changes to apply in this execution.
+     * Can include upserts (create/update) and deletes.
      */
-    objects: SyncedObject<PK, PropertySchema<PK>>[];
+    changes: SyncChange<PK, PropertySchema<PK>>[];
     /**
-     * Indicates whether the sync is complete.
-     * - `true`: No more data to fetch, sync is complete
-     * - `false`: More data available, will trigger another execution with nextContext
+     * Indicates whether there is more data to fetch.
+     * - `true`: More data available, will trigger another execution with nextContext
+     * - `false`: No more data to fetch, sync is complete
      */
-    done: boolean;
+    hasMore: boolean;
     /**
      * Optional context data to pass to the next execution.
-     * Required if `done` is `false`, ignored if `done` is `true`.
+     * Required if `hasMore` is `true`, ignored if `hasMore` is `false`.
      * This can be any type of data (cursor, page number, timestamp, etc.).
      * The same data will be provided in the context parameter of the next execution.
      */
@@ -65,15 +103,16 @@ export type SyncConfiguration<PK extends string, S extends Schema<PK>, Context =
      */
     schema: S;
     /**
-     * Whether to delete pages from the collection that are not returned
-     * from any of the sync executions (mark-and-sweep deletion).
-     *
-     * - `true`: Pages not seen in any execution batch will be deleted
-     * - `false` (default): Only upsert pages, never delete
+     * How the sync handles data lifecycle:
+     * - "replace": Each sync returns the complete dataset. After hasMore:false,
+     *              pages not seen in this sync run are deleted.
+     * - "incremental": Sync returns changes only. After hasMore:false, sync
+     *                  continues from saved cursor. Use delete markers
+     *                  to explicitly remove pages.
      *
-     * @default false
+     * @default "replace"
      */
-    deleteUnreturnedPages?: boolean;
+    mode?: SyncMode;
     /**
      * How often the sync should run.
      * - "continuous": Run as frequently as the system allows (default)
@@ -89,24 +128,24 @@ export type SyncConfiguration<PK extends string, S extends Schema<PK>, Context =
      * A function that fetches the data to sync from the third-party service.
      *
      * This function can return all data at once, or implement pagination by:
-     * 1. Returning a batch of objects with `done: false` and a `nextContext`
+     * 1. Returning a batch of changes with `hasMore: true` and a `nextContext`
      * 2. The runtime will call execute again with that context data
-     * 3. Continue until `done: true` is returned
+     * 3. Continue until `hasMore: false` is returned
      *
      * The runtime will handle diffing against the data source and creating,
      * updating, and deleting pages as necessary.
      *
      * @param context - Optional context data from previous execution (undefined on first call)
-     * @returns A result containing objects, done status, and optional nextContext
+     * @returns A result containing changes, hasMore status, and optional nextContext
      */
     execute: (context?: Context) => Promise<SyncExecutionResult<PK, Context>>;
 };
 export type SyncHandlerResult<PK extends string, Context = unknown> = {
     primaryKeyProperty: PK;
-    objects: SyncedObject<PK, PropertySchema<PK>>[];
-    done: boolean;
+    changes: SyncChange<PK, PropertySchema<PK>>[];
+    hasMore: boolean;
     nextContext?: Context;
-    deleteUnreturnedPages?: boolean;
+    mode?: SyncMode;
 };
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
 /**
@@ -122,12 +161,12 @@ export declare function createSyncCapability<PK extends string, S extends Schema
     config: {
         primaryKeyProperty: PK;
         schema: S;
-        deleteUnreturnedPages: boolean | undefined;
+        mode: SyncMode | undefined;
         schedule: SyncSchedule;
     };
     handler(context?: Context): Promise<{
-        objects: SyncedObject<PK, PropertySchema<PK>>[];
-        done: boolean;
+        changes: SyncChange<PK, PropertySchema<PK>>[];
+        hasMore: boolean;
         nextContext: Context | undefined;
     }>;
 };

package/dist/capabilities/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,qBAAqB,EACrB,cAAc,EACd,MAAM,EACN,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACX,IAAI,EACJ,WAAW,EACX,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EAET,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,qBAAqB,IAAI,CAAC,SAAS;IACnE,IAAI,EAAE,QAAQ,CAAC;CACf,GACE,WAAW,GACX,CAAC,SAAS;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B,UAAU,GACV,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,SAAS,cAAc,CAAC,EAAE,CAAC,IAAI;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE;SACV,QAAQ,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KACrD,CAAC;IACF;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,OAAO,GAAG,OAAO,IAAI;IACvE;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAEhD;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAC5B,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,OAAO,GAAG,OAAO,IACd;IACH;;;;OAIG;IACH,kBAAkB,EAAE,EAAE,CAAC;IAEvB;;OAEG;IACH,MAAM,EAAE,CAAC,CAAC;IAEV;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1E,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,OAAO,GAAG,OAAO,IAAI;IACrE,kBAAkB,EAAE,EAAE,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,OAAO,GAAG,OAAO,EAChB,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC;;;;;;;;;sBAUzC,OAAO;;;;;EAkBhC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/sync.js

@@ -6,7 +6,7 @@ function createSyncCapability(key, syncConfiguration) {
     config: {
       primaryKeyProperty: syncConfiguration.primaryKeyProperty,
       schema: syncConfiguration.schema,
-      deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages,
+      mode: syncConfiguration.mode,
       schedule: parseSchedule(syncConfiguration.schedule)
     },
     async handler(context) {
@@ -14,8 +14,8 @@ function createSyncCapability(key, syncConfiguration) {
         throw new ExecutionError(err);
       });
       const result = {
-        objects: executionResult.objects,
-        done: executionResult.done,
+        changes: executionResult.changes,
+        hasMore: executionResult.hasMore,
         nextContext: executionResult.nextContext
       };
       process.stdout.write(`

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
 export type { AutomationCapability, AutomationConfiguration, AutomationContext, PageObjectResponse, } from "./capabilities/automation.js";
 export type { NotionManagedOAuthConfiguration, OAuthCapability, OAuthConfiguration, UserManagedOAuthConfiguration, } from "./capabilities/oauth.js";
-export type { SyncCapability, SyncConfiguration, SyncExecutionResult, SyncedObject, } from "./capabilities/sync.js";
+export type { SyncCapability, SyncChange, SyncChangeDelete, SyncChangeUpsert, SyncConfiguration, SyncExecutionResult, SyncMode, } from "./capabilities/sync.js";
 export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
 export type { Icon, ImageIcon, NoticonColor, NoticonName, PlaceValue, Schedule, } from "./types.js";
 export { Worker } from "./worker.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACZ,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/worker.d.ts

@@ -35,7 +35,7 @@ export declare class Worker {
      *     },
      *   },
      *   execute: async () => {
-     *     const objects = [
+     *     const changes = [
      *       {
      *         key: "task-1",
      *         properties: {
@@ -46,7 +46,7 @@ export declare class Worker {
      *       },
      *     ];
      *
-     *     return { objects, done: true };
+     *     return { changes, hasMore: false };
      *   },
      * });
      * ```

package/dist/worker.js

@@ -31,7 +31,7 @@ class Worker {
    *     },
    *   },
    *   execute: async () => {
-   *     const objects = [
+   *     const changes = [
    *       {
    *         key: "task-1",
    *         properties: {
@@ -42,7 +42,7 @@ class Worker {
    *       },
    *     ];
    *
-   *     return { objects, done: true };
+   *     return { changes, hasMore: false };
    *   },
    * });
    * ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.69",
+	"version": "0.0.71",
 	"description": "An SDK for building workers for the Project Ajax platform",
 	"license": "UNLICENSED",
 	"type": "module",

package/src/capabilities/sync.ts

@@ -26,44 +26,90 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
 		: TextValue;
 
 /**
- * An object representing a third-party record to be synced.
+ * Sync mode determines how the sync handles data lifecycle.
  */
-export type SyncedObject<PK extends string, S extends PropertySchema<PK>> = {
+export type SyncMode = "replace" | "incremental";
+
+/**
+ * A change representing a record to be created or updated.
+ */
+export type SyncChangeUpsert<
+	PK extends string,
+	S extends PropertySchema<PK>,
+> = {
+	/**
+	 * The type of change. Use `"upsert"` to create or update a record.
+	 */
+	type: "upsert";
+	/**
+	 * A unique identifier for this record, used to match against existing pages.
+	 * This value will be stored in the property specified by `primaryKeyProperty`.
+	 */
 	key: string;
+	/**
+	 * The property values for this record.
+	 * Keys must match the property names defined in the schema.
+	 * Use the Builder helpers (e.g., `Builder.title()`, `Builder.richText()`) to create values.
+	 */
 	properties: {
 		[Property in keyof S]: PropertyValueType<S[Property]>;
 	};
 	/**
 	 * Optional icon to use as the icon for this row's page.
-	 * Use the `icon()` builder to create an icon value.
+	 * Use the `Builder.emojiIcon()`, `Builder.notionIcon()`, or `Builder.imageIcon()` helpers.
 	 */
 	icon?: Icon;
 	/**
-	 * Optional markdown content to add to the page.
-	 * This will be converted to blocks and added as page content.
+	 * Optional markdown content to add to the page body.
+	 * This will be converted to Notion blocks and added as page content.
 	 */
 	pageContentMarkdown?: string;
 };
 
+/**
+ * A change representing a record to be deleted.
+ * Only applicable when using `mode: "incremental"`.
+ */
+export type SyncChangeDelete = {
+	/**
+	 * The type of change. Use `"delete"` to remove a record.
+	 */
+	type: "delete";
+	/**
+	 * The unique identifier of the record to delete.
+	 * Must match the `key` of a previously upserted record.
+	 */
+	key: string;
+};
+
+/**
+ * A change to be applied to the synced database.
+ * Can be either an upsert (create/update) or a delete.
+ */
+export type SyncChange<PK extends string, S extends PropertySchema<PK>> =
+	| SyncChangeUpsert<PK, S>
+	| SyncChangeDelete;
+
 /**
  * Result returned from the sync execute function.
  */
 export type SyncExecutionResult<PK extends string, Context = unknown> = {
 	/**
-	 * The batch of objects fetched in this execution.
+	 * The batch of changes to apply in this execution.
+	 * Can include upserts (create/update) and deletes.
 	 */
-	objects: SyncedObject<PK, PropertySchema<PK>>[];
+	changes: SyncChange<PK, PropertySchema<PK>>[];
 
 	/**
-	 * Indicates whether the sync is complete.
-	 * - `true`: No more data to fetch, sync is complete
-	 * - `false`: More data available, will trigger another execution with nextContext
+	 * Indicates whether there is more data to fetch.
+	 * - `true`: More data available, will trigger another execution with nextContext
+	 * - `false`: No more data to fetch, sync is complete
 	 */
-	done: boolean;
+	hasMore: boolean;
 
 	/**
 	 * Optional context data to pass to the next execution.
-	 * Required if `done` is `false`, ignored if `done` is `true`.
+	 * Required if `hasMore` is `true`, ignored if `hasMore` is `false`.
 	 * This can be any type of data (cursor, page number, timestamp, etc.).
 	 * The same data will be provided in the context parameter of the next execution.
 	 */
@@ -92,15 +138,16 @@ export type SyncConfiguration<
 	schema: S;
 
 	/**
-	 * Whether to delete pages from the collection that are not returned
-	 * from any of the sync executions (mark-and-sweep deletion).
-	 *
-	 * - `true`: Pages not seen in any execution batch will be deleted
-	 * - `false` (default): Only upsert pages, never delete
+	 * How the sync handles data lifecycle:
+	 * - "replace": Each sync returns the complete dataset. After hasMore:false,
+	 *              pages not seen in this sync run are deleted.
+	 * - "incremental": Sync returns changes only. After hasMore:false, sync
+	 *                  continues from saved cursor. Use delete markers
+	 *                  to explicitly remove pages.
 	 *
-	 * @default false
+	 * @default "replace"
 	 */
-	deleteUnreturnedPages?: boolean;
+	mode?: SyncMode;
 
 	/**
 	 * How often the sync should run.
@@ -118,25 +165,25 @@ export type SyncConfiguration<
 	 * A function that fetches the data to sync from the third-party service.
 	 *
 	 * This function can return all data at once, or implement pagination by:
-	 * 1. Returning a batch of objects with `done: false` and a `nextContext`
+	 * 1. Returning a batch of changes with `hasMore: true` and a `nextContext`
 	 * 2. The runtime will call execute again with that context data
-	 * 3. Continue until `done: true` is returned
+	 * 3. Continue until `hasMore: false` is returned
 	 *
 	 * The runtime will handle diffing against the data source and creating,
 	 * updating, and deleting pages as necessary.
 	 *
 	 * @param context - Optional context data from previous execution (undefined on first call)
-	 * @returns A result containing objects, done status, and optional nextContext
+	 * @returns A result containing changes, hasMore status, and optional nextContext
 	 */
 	execute: (context?: Context) => Promise<SyncExecutionResult<PK, Context>>;
 };
 
 export type SyncHandlerResult<PK extends string, Context = unknown> = {
 	primaryKeyProperty: PK;
-	objects: SyncedObject<PK, PropertySchema<PK>>[];
-	done: boolean;
+	changes: SyncChange<PK, PropertySchema<PK>>[];
+	hasMore: boolean;
 	nextContext?: Context;
-	deleteUnreturnedPages?: boolean;
+	mode?: SyncMode;
 };
 
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
@@ -159,7 +206,7 @@ export function createSyncCapability<
 		config: {
 			primaryKeyProperty: syncConfiguration.primaryKeyProperty,
 			schema: syncConfiguration.schema,
-			deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages,
+			mode: syncConfiguration.mode,
 			schedule: parseSchedule(syncConfiguration.schedule),
 		},
 		async handler(context?: Context) {
@@ -170,8 +217,8 @@ export function createSyncCapability<
 				});
 
 			const result = {
-				objects: executionResult.objects,
-				done: executionResult.done,
+				changes: executionResult.changes,
+				hasMore: executionResult.hasMore,
 				nextContext: executionResult.nextContext,
 			};
 

package/src/index.ts

@@ -13,9 +13,12 @@ export type {
 } from "./capabilities/oauth.js";
 export type {
 	SyncCapability,
+	SyncChange,
+	SyncChangeDelete,
+	SyncChangeUpsert,
 	SyncConfiguration,
 	SyncExecutionResult,
-	SyncedObject,
+	SyncMode,
 } from "./capabilities/sync.js";
 export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
 export type {

package/src/worker.ts

@@ -74,7 +74,7 @@ export class Worker {
 	 *     },
 	 *   },
 	 *   execute: async () => {
-	 *     const objects = [
+	 *     const changes = [
 	 *       {
 	 *         key: "task-1",
 	 *         properties: {
@@ -85,7 +85,7 @@ export class Worker {
 	 *       },
 	 *     ];
 	 *
-	 *     return { objects, done: true };
+	 *     return { changes, hasMore: false };
 	 *   },
 	 * });
 	 * ```