@project-ajax/sdk 0.0.66 → 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/index.d.ts

@@ -1,6 +1,8 @@
 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";

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,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,GACR,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.66",
+	"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/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,