@project-ajax/sdk 0.0.64 → 0.0.67

package/dist/capabilities/oauth.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Configuration for a Notion-managed OAuth provider.
+ *
+ * Notion owns the OAuth app credentials (client ID/secret) and the backend has
+ * pre-configured provider settings.
+ */
+export interface NotionManagedOAuthConfiguration {
+    /**
+     * The unique identifier for this OAuth provider instance.
+     */
+    name: string;
+    /**
+     * The pre-configured provider to use (e.g., "google", "github", "salesforce").
+     * The backend will use this to look up the OAuth configuration.
+     */
+    provider: string;
+    /**
+     * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+     * does not return `expires_in` in token responses.
+     *
+     * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+     */
+    accessTokenExpireMs?: number;
+}
+/**
+ * Configuration for a user-managed OAuth provider.
+ *
+ * You own the OAuth app credentials and must explicitly provide endpoints and
+ * other OAuth parameters.
+ */
+export interface UserManagedOAuthConfiguration {
+    /**
+     * The unique identifier for this OAuth provider instance.
+     */
+    name: string;
+    /**
+     * The client ID for the OAuth app.
+     */
+    clientId: string;
+    /**
+     * The client secret for the OAuth app.
+     */
+    clientSecret: string;
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     */
+    authorizationEndpoint: string;
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     */
+    tokenEndpoint: string;
+    /**
+     * The OAuth scope(s) to request.
+     */
+    scope: string;
+    /**
+     * Optional additional authorization parameters to include in the authorization request.
+     */
+    authorizationParams?: Record<string, string>;
+    /**
+     * Optional callback URL for OAuth redirect.
+     */
+    callbackUrl?: string;
+    /**
+     * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+     * does not return `expires_in` in token responses.
+     *
+     * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+     */
+    accessTokenExpireMs?: number;
+}
+/**
+ * Union type representing either Notion-managed or user-managed OAuth configuration.
+ */
+export type OAuthConfiguration = NotionManagedOAuthConfiguration | UserManagedOAuthConfiguration;
+/**
+ * Creates an OAuth provider configuration for authenticating with third-party services.
+ *
+ * There are two ways to configure OAuth:
+ *
+ * 1. Notion-managed providers:
+ * ```ts
+ * oauth({
+ *   type: "notion_managed",
+ *   name: "my-google-auth",
+ *   provider: "google"
+ * })
+ * ```
+ *
+ * 2. User-managed OAuth configuration:
+ * ```ts
+ * oauth({
+ *   type: "user_managed",
+ *   name: "my-custom-oauth",
+ *   authorizationEndpoint: "https://provider.com/oauth/authorize",
+ *   tokenEndpoint: "https://provider.com/oauth/token",
+ *   scope: "read write",
+ *   clientId: process.env.CLIENT_ID,
+ *   clientSecret: process.env.CLIENT_SECRET,
+ *   authorizationParams: {
+ *     access_type: "offline",
+ *     prompt: "consent"
+ *   }
+ * })
+ * ```
+ *
+ * @param config - The OAuth configuration (Notion-managed or user-managed).
+ * @returns An OAuth provider definition.
+ */
+export declare function oauth(config: OAuthConfiguration): {
+    _tag: string;
+    envKey: string;
+    accessToken(): Promise<string>;
+    config: {
+        type: "notion_managed";
+        name: string;
+        provider: string;
+        accessTokenExpireMs: number | undefined;
+        authorizationEndpoint?: never;
+        tokenEndpoint?: never;
+        scope?: never;
+        clientId?: never;
+        clientSecret?: never;
+        authorizationParams?: never;
+        callbackUrl?: never;
+    };
+} | {
+    _tag: string;
+    envKey: string;
+    accessToken(): Promise<string>;
+    config: {
+        type: "user_managed";
+        name: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        scope: string;
+        clientId: string;
+        clientSecret: string;
+        authorizationParams: Record<string, string> | undefined;
+        callbackUrl: string | undefined;
+        accessTokenExpireMs: number | undefined;
+        provider?: never;
+    };
+};
+//# sourceMappingURL=oauth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/capabilities/oauth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC/C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC7C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC3B,+BAA+B,GAC/B,6BAA6B,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,kBAAkB;;;mBAOxB,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;mBAehB,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;EAgBrC"}

package/dist/capabilities/oauth.js

@@ -0,0 +1,53 @@
+function oauth(config) {
+  const envKey = oauthNameToEnvKey(config.name);
+  if ("provider" in config) {
+    return {
+      _tag: "oauth",
+      envKey,
+      async accessToken() {
+        return readRequiredEnvVar(envKey, { name: config.name });
+      },
+      config: {
+        type: "notion_managed",
+        name: config.name,
+        provider: config.provider,
+        accessTokenExpireMs: config.accessTokenExpireMs
+      }
+    };
+  }
+  return {
+    _tag: "oauth",
+    envKey,
+    async accessToken() {
+      return readRequiredEnvVar(envKey, { name: config.name });
+    },
+    config: {
+      type: "user_managed",
+      name: config.name,
+      authorizationEndpoint: config.authorizationEndpoint,
+      tokenEndpoint: config.tokenEndpoint,
+      scope: config.scope,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      authorizationParams: config.authorizationParams,
+      callbackUrl: config.callbackUrl,
+      accessTokenExpireMs: config.accessTokenExpireMs
+    }
+  };
+}
+function oauthNameToEnvKey(identifier) {
+  const encoded = Buffer.from(identifier).toString("hex").toUpperCase();
+  return `OAUTH_${encoded}_ACCESS_TOKEN`;
+}
+function readRequiredEnvVar(key, context) {
+  const value = process.env[key];
+  if (value) {
+    return value;
+  }
+  throw new Error(
+    `Missing OAuth access token env var "${key}" (name: "${context.name}"). Make sure you've completed OAuth for this capability and are running inside the worker runtime.`
+  );
+}
+export {
+  oauth
+};

package/dist/capabilities/oauth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth.test.d.ts.map

package/dist/capabilities/oauth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.test.d.ts","sourceRoot":"","sources":["../../src/capabilities/oauth.test.ts"],"names":[],"mappings":""}

package/dist/capabilities/sync.d.ts

@@ -1,5 +1,5 @@
 import type { PropertyConfiguration, PropertySchema, Schema } from "../schema.js";
-import type { Icon, PeopleValue, TextValue } from "../types.js";
+import type { Icon, PeopleValue, Schedule, SyncSchedule, TextValue } from "../types.js";
 /**
  * Maps a property configuration to its corresponding value type.
  */
@@ -72,6 +72,17 @@ export type SyncConfiguration<PK extends string, S extends Schema<PK>, Context =
      * @default false
      */
     deleteUnreturnedPages?: boolean;
+    /**
+     * How often the sync should run.
+     * - "continuous": Run as frequently as the system allows (default)
+     * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
+     *
+     * Minimum interval: 1 minute ("1m")
+     * Maximum interval: 7 days ("7d")
+     *
+     * @default "continuous"
+     */
+    schedule?: Schedule;
     /**
      * A function that fetches the data to sync from the third-party service.
      *
@@ -108,6 +119,7 @@ export declare function sync<PK extends string, S extends Schema<PK>, Context =
         primaryKeyProperty: PK;
         schema: S;
         deleteUnreturnedPages: boolean | undefined;
+        schedule: SyncSchedule;
     };
     handler(context?: Context): Promise<{
         objects: SyncedObject<PK, PropertySchema<PK>>[];

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,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEhE;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,qBAAqB,IAAI,CAAC,SAAS;IACnE,IAAI,EAAE,QAAQ,CAAC;CACf,GACE,WAAW,GACX,SAAS,CAAC;AAEb;;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;;;;;;;;;;;;;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;;;;;;GAMG;AACH,wBAAgB,IAAI,CACnB,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,OAAO,GAAG,OAAO,EAChB,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC;;;;;;;sBAQ5B,OAAO;;;;;EAkBhC"}
+{"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,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,SAAS,CAAC;AAEb;;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;;;;;;GAMG;AACH,wBAAgB,IAAI,CACnB,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,OAAO,GAAG,OAAO,EAChB,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC;;;;;;;;sBAS5B,OAAO;;;;;EAkBhC"}

package/dist/capabilities/sync.js

@@ -1,11 +1,12 @@
-import { ExecutionError } from "../error.js";
+import { ExecutionError, unreachable } from "../error.js";
 function sync(syncConfiguration) {
   return {
     _tag: "sync",
     config: {
       primaryKeyProperty: syncConfiguration.primaryKeyProperty,
       schema: syncConfiguration.schema,
-      deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages
+      deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages,
+      schedule: parseSchedule(syncConfiguration.schedule)
     },
     async handler(context) {
       const executionResult = await syncConfiguration.execute(context).catch((err) => {
@@ -23,6 +24,49 @@ function sync(syncConfiguration) {
     }
   };
 }
+const MS_PER_MINUTE = 60 * 1e3;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const MIN_INTERVAL_MS = MS_PER_MINUTE;
+const MAX_INTERVAL_MS = 7 * MS_PER_DAY;
+function parseSchedule(schedule) {
+  if (!schedule || schedule === "continuous") {
+    return { type: "continuous" };
+  }
+  const match = schedule.match(/^(\d+)(m|h|d)$/);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(
+      `Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`
+    );
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  let intervalMs;
+  switch (unit) {
+    case "m":
+      intervalMs = value * MS_PER_MINUTE;
+      break;
+    case "h":
+      intervalMs = value * MS_PER_HOUR;
+      break;
+    case "d":
+      intervalMs = value * MS_PER_DAY;
+      break;
+    default:
+      unreachable(unit);
+  }
+  if (intervalMs < MIN_INTERVAL_MS) {
+    throw new Error(
+      `Schedule interval must be at least 1 minute. Got: "${schedule}"`
+    );
+  }
+  if (intervalMs > MAX_INTERVAL_MS) {
+    throw new Error(
+      `Schedule interval must be at most 7 days. Got: "${schedule}"`
+    );
+  }
+  return { type: "interval", intervalMs };
+}
 export {
   sync
 };

package/dist/error.d.ts

@@ -5,4 +5,8 @@ export declare class ExecutionError extends Error {
     readonly cause: unknown;
     constructor(cause: unknown);
 }
+/**
+ * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
+ */
+export declare function unreachable(value: never): never;
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,KAAK,EAAE,OAAO;CAK1B"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,KAAK,EAAE,OAAO;CAK1B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}

package/dist/error.js

@@ -6,6 +6,10 @@ class ExecutionError extends Error {
     this.cause = cause;
   }
 }
+function unreachable(value) {
+  throw new Error(`Unreachable: ${value}`);
+}
 export {
-  ExecutionError
+  ExecutionError,
+  unreachable
 };

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { emojiIcon, imageIcon, notionIcon } from "./builder.js";
 export type { AutomationConfiguration, AutomationContext, PageObjectResponse, } from "./capabilities/automation.js";
 export { automation } from "./capabilities/automation.js";
+export type { NotionManagedOAuthConfiguration, OAuthConfiguration, UserManagedOAuthConfiguration, } from "./capabilities/oauth.js";
+export { oauth } from "./capabilities/oauth.js";
 export type { SyncConfiguration, SyncExecutionResult, SyncedObject, } from "./capabilities/sync.js";
 export { sync } from "./capabilities/sync.js";
 export { tool } from "./capabilities/tool.js";
-export type { Icon, ImageIcon, NoticonColor, NoticonName } from "./types.js";
+export type { Icon, ImageIcon, NoticonColor, NoticonName, Schedule, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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,MAAM,cAAc,CAAC;AAChE,YAAY,EACX,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EACX,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EACX,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EACX,+BAA+B,EAC/B,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,YAAY,EACX,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,GACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 import { emojiIcon, imageIcon, notionIcon } from "./builder.js";
 import { automation } from "./capabilities/automation.js";
+import { oauth } from "./capabilities/oauth.js";
 import { sync } from "./capabilities/sync.js";
 import { tool } from "./capabilities/tool.js";
 export {
@@ -7,6 +8,7 @@ export {
   emojiIcon,
   imageIcon,
   notionIcon,
+  oauth,
   sync,
   tool
 };

package/dist/types.d.ts

@@ -130,4 +130,30 @@ export interface PersonReference {
  */
 export type PeopleValue = PersonReference[];
 export type { NoticonName } from "./icon-names.js";
+/**
+ * Time units for schedule intervals.
+ * - "m": minutes
+ * - "h": hours
+ * - "d": days
+ */
+export type TimeUnit = "m" | "h" | "d";
+/**
+ * A string representing an interval, e.g. "30m", "1h", "7d".
+ */
+export type IntervalString = `${number}${TimeUnit}`;
+/**
+ * Schedule configuration for sync capabilities.
+ * - "continuous": Run as frequently as the system allows
+ * - IntervalString: Run at specified intervals, e.g. "30m", "1h", "1d"
+ */
+export type Schedule = "continuous" | IntervalString;
+/**
+ * Normalized schedule representation stored in the backend.
+ */
+export type SyncSchedule = {
+    type: "continuous";
+} | {
+    type: "interval";
+    intervalMs: number;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/capabilities/oauth.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { oauth } from "./oauth.js";
+
+describe("oauth", () => {
+	afterEach(() => {
+		// Clean up env changes between tests
+		delete process.env.OAUTH_676F6F676C6541757468_ACCESS_TOKEN;
+		delete process.env.OAUTH_676F6F676C652D63616C656E646172_ACCESS_TOKEN;
+	});
+
+	it("creates notion-managed oauth capability with accessToken helper", async () => {
+		const myOauth = oauth({
+			name: "googleAuth",
+			provider: "google",
+			accessTokenExpireMs: 60_000,
+		});
+
+		expect(myOauth._tag).toBe("oauth");
+		expect(myOauth.config.type).toBe("notion_managed");
+		expect(myOauth.config.accessTokenExpireMs).toBe(60_000);
+		expect(myOauth.envKey).toBe("OAUTH_676F6F676C6541757468_ACCESS_TOKEN");
+		expect(typeof myOauth.accessToken).toBe("function");
+
+		process.env.OAUTH_676F6F676C6541757468_ACCESS_TOKEN = "token-123";
+		await expect(myOauth.accessToken()).resolves.toBe("token-123");
+	});
+
+	it("normalizes non-alphanumeric characters in the identifier", () => {
+		const myOauth = oauth({
+			name: "google-calendar",
+			provider: "google",
+			accessTokenExpireMs: 3600_000,
+		});
+
+		expect(myOauth.envKey).toBe(
+			"OAUTH_676F6F676C652D63616C656E646172_ACCESS_TOKEN",
+		);
+		expect(myOauth.config.accessTokenExpireMs).toBe(3600_000);
+	});
+
+	it("throws a helpful error when the token env var is missing", async () => {
+		const myOauth = oauth({
+			name: "googleAuth",
+			provider: "google",
+		});
+
+		await expect(myOauth.accessToken()).rejects.toThrow(
+			/Missing OAuth access token env var "OAUTH_676F6F676C6541757468_ACCESS_TOKEN"/,
+		);
+	});
+});

package/src/capabilities/oauth.ts

@@ -0,0 +1,181 @@
+/**
+ * Configuration for a Notion-managed OAuth provider.
+ *
+ * Notion owns the OAuth app credentials (client ID/secret) and the backend has
+ * pre-configured provider settings.
+ */
+export interface NotionManagedOAuthConfiguration {
+	/**
+	 * The unique identifier for this OAuth provider instance.
+	 */
+	name: string;
+
+	/**
+	 * The pre-configured provider to use (e.g., "google", "github", "salesforce").
+	 * The backend will use this to look up the OAuth configuration.
+	 */
+	provider: string;
+
+	/**
+	 * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+	 * does not return `expires_in` in token responses.
+	 *
+	 * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+	 */
+	accessTokenExpireMs?: number;
+}
+
+/**
+ * Configuration for a user-managed OAuth provider.
+ *
+ * You own the OAuth app credentials and must explicitly provide endpoints and
+ * other OAuth parameters.
+ */
+export interface UserManagedOAuthConfiguration {
+	/**
+	 * The unique identifier for this OAuth provider instance.
+	 */
+	name: string;
+
+	/**
+	 * The client ID for the OAuth app.
+	 */
+	clientId: string;
+
+	/**
+	 * The client secret for the OAuth app.
+	 */
+	clientSecret: string;
+
+	/**
+	 * The OAuth 2.0 authorization endpoint URL.
+	 */
+	authorizationEndpoint: string;
+
+	/**
+	 * The OAuth 2.0 token endpoint URL.
+	 */
+	tokenEndpoint: string;
+
+	/**
+	 * The OAuth scope(s) to request.
+	 */
+	scope: string;
+
+	/**
+	 * Optional additional authorization parameters to include in the authorization request.
+	 */
+	authorizationParams?: Record<string, string>;
+
+	/**
+	 * Optional callback URL for OAuth redirect.
+	 */
+	callbackUrl?: string;
+
+	/**
+	 * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+	 * does not return `expires_in` in token responses.
+	 *
+	 * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+	 */
+	accessTokenExpireMs?: number;
+}
+
+/**
+ * Union type representing either Notion-managed or user-managed OAuth configuration.
+ */
+export type OAuthConfiguration =
+	| NotionManagedOAuthConfiguration
+	| UserManagedOAuthConfiguration;
+
+/**
+ * Creates an OAuth provider configuration for authenticating with third-party services.
+ *
+ * There are two ways to configure OAuth:
+ *
+ * 1. Notion-managed providers:
+ * ```ts
+ * oauth({
+ *   type: "notion_managed",
+ *   name: "my-google-auth",
+ *   provider: "google"
+ * })
+ * ```
+ *
+ * 2. User-managed OAuth configuration:
+ * ```ts
+ * oauth({
+ *   type: "user_managed",
+ *   name: "my-custom-oauth",
+ *   authorizationEndpoint: "https://provider.com/oauth/authorize",
+ *   tokenEndpoint: "https://provider.com/oauth/token",
+ *   scope: "read write",
+ *   clientId: process.env.CLIENT_ID,
+ *   clientSecret: process.env.CLIENT_SECRET,
+ *   authorizationParams: {
+ *     access_type: "offline",
+ *     prompt: "consent"
+ *   }
+ * })
+ * ```
+ *
+ * @param config - The OAuth configuration (Notion-managed or user-managed).
+ * @returns An OAuth provider definition.
+ */
+export function oauth(config: OAuthConfiguration) {
+	const envKey = oauthNameToEnvKey(config.name);
+
+	if ("provider" in config) {
+		return {
+			_tag: "oauth",
+			envKey,
+			async accessToken(): Promise<string> {
+				return readRequiredEnvVar(envKey, { name: config.name });
+			},
+			config: {
+				type: "notion_managed" as const,
+				name: config.name,
+				provider: config.provider,
+				accessTokenExpireMs: config.accessTokenExpireMs,
+			},
+		};
+	}
+
+	return {
+		_tag: "oauth",
+		envKey,
+		async accessToken(): Promise<string> {
+			return readRequiredEnvVar(envKey, { name: config.name });
+		},
+		config: {
+			type: "user_managed" as const,
+			name: config.name,
+			authorizationEndpoint: config.authorizationEndpoint,
+			tokenEndpoint: config.tokenEndpoint,
+			scope: config.scope,
+			clientId: config.clientId,
+			clientSecret: config.clientSecret,
+			authorizationParams: config.authorizationParams,
+			callbackUrl: config.callbackUrl,
+			accessTokenExpireMs: config.accessTokenExpireMs,
+		},
+	};
+}
+
+function oauthNameToEnvKey(identifier: string): string {
+	const encoded = Buffer.from(identifier).toString("hex").toUpperCase();
+
+	return `OAUTH_${encoded}_ACCESS_TOKEN`;
+}
+
+function readRequiredEnvVar(key: string, context: { name: string }): string {
+	const value = process.env[key];
+	if (value) {
+		return value;
+	}
+
+	throw new Error(
+		`Missing OAuth access token env var "${key}" (name: "${context.name}"). ` +
+			`Make sure you've completed OAuth for this capability and are running inside the worker runtime.`,
+	);
+}

package/src/capabilities/sync.ts

@@ -1,10 +1,17 @@
-import { ExecutionError } from "../error.js";
+import { ExecutionError, unreachable } from "../error.js";
 import type {
 	PropertyConfiguration,
 	PropertySchema,
 	Schema,
 } from "../schema.js";
-import type { Icon, PeopleValue, TextValue } from "../types.js";
+import type {
+	Icon,
+	PeopleValue,
+	Schedule,
+	SyncSchedule,
+	TextValue,
+	TimeUnit,
+} from "../types.js";
 
 /**
  * Maps a property configuration to its corresponding value type.
@@ -92,6 +99,18 @@ export type SyncConfiguration<
 	 */
 	deleteUnreturnedPages?: boolean;
 
+	/**
+	 * How often the sync should run.
+	 * - "continuous": Run as frequently as the system allows (default)
+	 * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
+	 *
+	 * Minimum interval: 1 minute ("1m")
+	 * Maximum interval: 7 days ("7d")
+	 *
+	 * @default "continuous"
+	 */
+	schedule?: Schedule;
+
 	/**
 	 * A function that fetches the data to sync from the third-party service.
 	 *
@@ -135,6 +154,7 @@ export function sync<
 			primaryKeyProperty: syncConfiguration.primaryKeyProperty,
 			schema: syncConfiguration.schema,
 			deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages,
+			schedule: parseSchedule(syncConfiguration.schedule),
 		},
 		async handler(context?: Context) {
 			const executionResult = await syncConfiguration
@@ -155,3 +175,57 @@ export function sync<
 		},
 	};
 }
+
+const MS_PER_MINUTE = 60 * 1000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+
+const MIN_INTERVAL_MS = MS_PER_MINUTE; // 1m
+const MAX_INTERVAL_MS = 7 * MS_PER_DAY; // 7d
+
+/**
+ * Parses a user-friendly schedule string into the normalized backend format.
+ */
+function parseSchedule(schedule: Schedule | undefined): SyncSchedule {
+	if (!schedule || schedule === "continuous") {
+		return { type: "continuous" };
+	}
+
+	const match = schedule.match(/^(\d+)(m|h|d)$/);
+	if (!match || !match[1] || !match[2]) {
+		throw new Error(
+			`Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`,
+		);
+	}
+
+	const value = parseInt(match[1], 10);
+	const unit = match[2] as TimeUnit;
+
+	let intervalMs: number;
+	switch (unit) {
+		case "m":
+			intervalMs = value * MS_PER_MINUTE;
+			break;
+		case "h":
+			intervalMs = value * MS_PER_HOUR;
+			break;
+		case "d":
+			intervalMs = value * MS_PER_DAY;
+			break;
+		default:
+			unreachable(unit);
+	}
+
+	if (intervalMs < MIN_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at least 1 minute. Got: "${schedule}"`,
+		);
+	}
+	if (intervalMs > MAX_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at most 7 days. Got: "${schedule}"`,
+		);
+	}
+
+	return { type: "interval", intervalMs };
+}

package/src/error.ts

@@ -10,3 +10,10 @@ export class ExecutionError extends Error {
 		this.cause = cause;
 	}
 }
+
+/**
+ * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
+ */
+export function unreachable(value: never): never {
+	throw new Error(`Unreachable: ${value}`);
+}

package/src/index.ts

@@ -5,6 +5,12 @@ export type {
 	PageObjectResponse,
 } from "./capabilities/automation.js";
 export { automation } from "./capabilities/automation.js";
+export type {
+	NotionManagedOAuthConfiguration,
+	OAuthConfiguration,
+	UserManagedOAuthConfiguration,
+} from "./capabilities/oauth.js";
+export { oauth } from "./capabilities/oauth.js";
 export type {
 	SyncConfiguration,
 	SyncExecutionResult,
@@ -12,4 +18,10 @@ export type {
 } from "./capabilities/sync.js";
 export { sync } from "./capabilities/sync.js";
 export { tool } from "./capabilities/tool.js";
-export type { Icon, ImageIcon, NoticonColor, NoticonName } from "./types.js";
+export type {
+	Icon,
+	ImageIcon,
+	NoticonColor,
+	NoticonName,
+	Schedule,
+} from "./types.js";

package/src/types.ts

@@ -187,3 +187,30 @@ export interface PersonReference {
 export type PeopleValue = PersonReference[];
 
 export type { NoticonName } from "./icon-names.js";
+
+/**
+ * Time units for schedule intervals.
+ * - "m": minutes
+ * - "h": hours
+ * - "d": days
+ */
+export type TimeUnit = "m" | "h" | "d";
+
+/**
+ * A string representing an interval, e.g. "30m", "1h", "7d".
+ */
+export type IntervalString = `${number}${TimeUnit}`;
+
+/**
+ * Schedule configuration for sync capabilities.
+ * - "continuous": Run as frequently as the system allows
+ * - IntervalString: Run at specified intervals, e.g. "30m", "1h", "1d"
+ */
+export type Schedule = "continuous" | IntervalString;
+
+/**
+ * Normalized schedule representation stored in the backend.
+ */
+export type SyncSchedule =
+	| { type: "continuous" }
+	| { type: "interval"; intervalMs: number };