@project-ajax/sdk 0.0.28

package/src/cli/api/client.ts

@@ -0,0 +1,588 @@
+/**
+ * API client for making authenticated requests to the Workers API
+ */
+
+import type { Writer } from "../writer.js";
+import { Result } from "./result.js";
+
+export type Environment = "local" | "staging" | "dev" | "prod";
+
+interface ApiClientConfig {
+	token: string;
+	environment: Environment;
+	baseUrl?: string | undefined;
+	cellId: string;
+	writer: Writer;
+}
+
+type Endpoint = `/${string}`;
+
+export interface ApiError {
+	status: number;
+	statusText: string;
+	message: string;
+	validationError?: {
+		errorId: string;
+		name: string;
+		debugMessage: string;
+		message: string;
+	};
+}
+
+/**
+ * Get the base URL for the given environment
+ */
+export function baseUrl({
+	environment,
+	override,
+}: {
+	environment: Environment;
+	override?: string | undefined;
+}): string {
+	if (override) {
+		return override;
+	}
+
+	switch (environment) {
+		case "local":
+			return "http://localhost:3000";
+		case "staging":
+			return "https://staging.notion.so";
+		case "dev":
+			return "https://dev.notion.so";
+		case "prod":
+			return "https://www.notion.so";
+	}
+}
+
+/**
+ * Get the base API URL for the given environment
+ */
+function baseApiUrl({
+	environment,
+	override,
+}: {
+	environment: Environment;
+	override?: string | undefined;
+}): string {
+	return `${baseUrl({ environment, override })}/api/v3`;
+}
+
+/**
+ * API client for making authenticated requests to Workers endpoints
+ */
+export class ApiClient {
+	readonly #token: string;
+	readonly #env: Environment;
+	readonly #baseUrl: string | undefined;
+	readonly #cellId: string;
+	readonly #writer: Writer;
+
+	constructor(config: ApiClientConfig) {
+		this.#token = config.token;
+		this.#env = config.environment;
+		this.#baseUrl = config.baseUrl;
+		this.#cellId = config.cellId;
+		this.#writer = config.writer;
+	}
+
+	private baseApiUrl() {
+		return baseApiUrl({ environment: this.#env, override: this.#baseUrl });
+	}
+
+	/**
+	 * Make an authenticated fetch request to the Workers API
+	 */
+	private async fetch(
+		endpoint: Endpoint,
+		requestOptions: Omit<RequestInit, "body"> & { body?: unknown },
+		options: { stream: true },
+	): Promise<Result<ReadableStream<Uint8Array<ArrayBufferLike>>, ApiError>>;
+	private async fetch<TResponse>(
+		endpoint: Endpoint,
+		requestOptions?: Omit<RequestInit, "body"> & { body?: unknown },
+	): Promise<Result<TResponse, ApiError>>;
+	private async fetch<TResponse>(
+		endpoint: Endpoint,
+		requestOptions: Omit<RequestInit, "body"> & { body?: unknown } = {},
+		options?: { stream: true },
+	): Promise<
+		Result<TResponse | ReadableStream<Uint8Array<ArrayBufferLike>>, ApiError>
+	> {
+		if (!endpoint.startsWith("/")) {
+			throw new Error("Endpoint must start with a slash (/)");
+		}
+
+		const url = `${this.baseApiUrl()}${endpoint}`;
+
+		this.#writer.debug(`Fetching ${url}`);
+		this.#writer.debug(
+			`Options: ${JSON.stringify(requestOptions, null, "\t")}`,
+		);
+
+		const headers = new Headers({
+			Authorization: `Bearer ${this.#token}`,
+			"Content-Type": "application/json",
+			"X-Notion-Cell": this.#cellId,
+		});
+
+		const addlHeaders = headersInitToEntries(requestOptions.headers);
+
+		for (const [key, value] of addlHeaders) {
+			headers.append(key, value);
+		}
+
+		const response = await fetch(url, {
+			method: requestOptions.method ?? "GET",
+			headers,
+			body: requestOptions.body ? JSON.stringify(requestOptions.body) : null,
+		});
+
+		this.#writer.debug(`Response: ${response.status} ${response.statusText}`);
+
+		if (!response.ok) {
+			const error = await parseApiError(response);
+			return Result.fail(error);
+		}
+
+		if (options?.stream) {
+			if (!response.body) {
+				return Result.fail({
+					status: response.status,
+					statusText: response.statusText,
+					message: "No body in response",
+				});
+			}
+
+			return Result.success(response.body);
+		} else {
+			const data = (await response.json()) as TResponse;
+			return Result.success(data);
+		}
+	}
+
+	/**
+	 * Create a new worker
+	 */
+	async createWorker(name: string): Promise<
+		Result<
+			{
+				worker: {
+					workerId: string;
+					name: string;
+					spaceId: string;
+					createdAt: string;
+					updatedAt: string;
+					state: unknown;
+				};
+				url: string;
+				fields: Record<string, string>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersCreateWorker", {
+			method: "POST",
+			body: {
+				name,
+			},
+		});
+	}
+
+	/**
+	 * Update an existing worker's bundle
+	 */
+	async updateWorkerBundle(workerId: string): Promise<
+		Result<
+			{
+				url: string;
+				fields: Record<string, string>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersUpdateWorker", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Get a worker by ID
+	 */
+	async getWorker(workerId: string): Promise<
+		Result<
+			{
+				worker: {
+					workerId: string;
+					name: string;
+					spaceId: string;
+					state: unknown;
+					tools: unknown[];
+					createdAt: string;
+					updatedAt: string;
+				};
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersGetWorker", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * List all workers in the space
+	 */
+	async listWorkers(): Promise<
+		Result<
+			{
+				workers: Array<{
+					workerId: string;
+					name: string;
+					spaceId: string;
+					state: unknown;
+					createdAt: string;
+					updatedAt: string;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersListWorkers", {
+			method: "POST",
+			body: {},
+		});
+	}
+
+	/**
+	 * Delete a worker
+	 */
+	async deleteWorker(
+		workerId: string,
+	): Promise<Result<Record<string, never>, ApiError>> {
+		return this.fetch("/workersDeleteWorker", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Fetch and save worker capabilities
+	 */
+	async fetchAndSaveCapabilities(workerId: string): Promise<
+		Result<
+			{
+				capabilities: ReadonlyArray<{
+					_tag: "sync" | "slashCommand";
+					spaceId: string;
+					workerId: string;
+					key: string;
+					config: unknown;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersFetchAndSaveCapabilities", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Upsert secrets (create or update multiple secrets)
+	 */
+	async upsertSecrets(
+		workerId: string,
+		secrets: Array<{ key: string; value: string }>,
+	): Promise<
+		Result<
+			{
+				secrets: Array<{
+					spaceId: string;
+					workerId: string;
+					key: string;
+					createdAt: string;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersUpsertSecrets", {
+			method: "POST",
+			body: {
+				workerId,
+				secrets,
+			},
+		});
+	}
+
+	/**
+	 * List all secrets for a worker (keys only, not values)
+	 */
+	async listSecrets(workerId: string): Promise<
+		Result<
+			{
+				secrets: Array<{
+					spaceId: string;
+					workerId: string;
+					key: string;
+					createdAt: string;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersListSecrets", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Delete a secret
+	 */
+	async deleteSecret(
+		workerId: string,
+		key: string,
+	): Promise<Result<Record<string, never>, ApiError>> {
+		return this.fetch("/workersDeleteSecret", {
+			method: "POST",
+			body: {
+				workerId,
+				key,
+			},
+		});
+	}
+
+	/**
+	 * List all capabilities for a worker
+	 */
+	async listCapabilities(workerId: string): Promise<
+		Result<
+			{
+				capabilities: Array<{
+					_tag: "sync" | "slashCommand";
+					key: string;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersListCapabilities", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Run a capability
+	 */
+	async runCapability(
+		workerId: string,
+		capabilityKey: string,
+		functionName: string | null,
+		args: Array<{ name: string; value: string }>,
+		stream: true,
+	): Promise<Result<ReadableStream<Uint8Array<ArrayBufferLike>>, ApiError>>;
+	async runCapability(
+		workerId: string,
+		capabilityKey: string,
+		functionName: string | null,
+		args: Array<{ name: string; value: string }>,
+		stream?: false | undefined,
+	): Promise<Result<{ result: unknown }, ApiError>>;
+	async runCapability(
+		workerId: string,
+		capabilityKey: string,
+		functionName: string | null,
+		args: Array<{ name: string; value: string }>,
+		stream?: boolean | undefined,
+	): Promise<
+		Result<
+			{ result: unknown } | ReadableStream<Uint8Array<ArrayBufferLike>>,
+			ApiError
+		>
+	> {
+		if (stream) {
+			return this.fetch(
+				"/workersRunCapability",
+				{
+					method: "POST",
+					body: {
+						workerId,
+						capabilityKey,
+						functionName,
+						args,
+						stream,
+					},
+				},
+				{ stream },
+			);
+		} else {
+			return this.fetch("/workersRunCapability", {
+				method: "POST",
+				body: {
+					workerId,
+					capabilityKey,
+					functionName,
+					args,
+					stream,
+				},
+			});
+		}
+	}
+
+	/**
+	 * Download the bundle for a worker
+	 */
+	async downloadWorkerBundle(
+		workerId: string,
+	): Promise<Result<ReadableStream<Uint8Array<ArrayBufferLike>>, ApiError>> {
+		return this.fetch(
+			"/workersGetBundle",
+			{
+				method: "POST",
+				body: {
+					workerId,
+				},
+			},
+			{ stream: true },
+		);
+	}
+
+	/**
+	 * List all runs for a worker
+	 */
+	async listRunsForWorker(workerId: string): Promise<
+		Result<
+			{
+				runs: Array<{
+					workerId: string;
+					spaceId: string;
+					runId: string;
+					name: string;
+					exitCode: number | null;
+					startedAt: string;
+					endedAt: string | null;
+				}>;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersListRunsForWorker", {
+			method: "POST",
+			body: {
+				workerId,
+			},
+		});
+	}
+
+	/**
+	 * Get logs for a specific run
+	 */
+	async getRunLogs(
+		workerId: string,
+		runId: string,
+	): Promise<
+		Result<
+			{
+				logs: string;
+			},
+			ApiError
+		>
+	> {
+		return this.fetch("/workersGetRunLogs", {
+			method: "POST",
+			body: {
+				workerId,
+				runId,
+			},
+		});
+	}
+}
+
+function headersInitToEntries(
+	headersInit: RequestInit["headers"],
+): [string, string][] {
+	if (headersInit instanceof Headers) {
+		return Array.from(headersInit.entries());
+	}
+
+	if (Array.isArray(headersInit)) {
+		return headersInit;
+	}
+
+	if (headersInit === undefined) {
+		return [];
+	}
+
+	const entries: [string, string][] = [];
+	for (const [key, value] of Object.entries(headersInit)) {
+		if (value === undefined) {
+			continue;
+		}
+		entries.push([key, value]);
+	}
+
+	return entries;
+}
+
+async function parseApiError(response: Response): Promise<ApiError> {
+	const errorText = await response.text();
+	const message = `[${response.status}] ${response.statusText}: ${errorText}`;
+	const error: ApiError = {
+		status: response.status,
+		statusText: response.statusText,
+		message,
+	};
+
+	if (response.status === 400) {
+		const validationError = parseValidationError(errorText);
+		if (validationError) {
+			error.validationError = validationError;
+		}
+	}
+
+	return error;
+}
+
+/**
+ * Try to parse a ValidationError from error response text
+ */
+function parseValidationError(
+	errorText: string,
+): ApiError["validationError"] | undefined {
+	try {
+		const errorJson = JSON.parse(errorText);
+		if (
+			errorJson.name === "ValidationError" &&
+			errorJson.debugMessage &&
+			errorJson.errorId
+		) {
+			return {
+				errorId: errorJson.errorId,
+				name: errorJson.name,
+				debugMessage: errorJson.debugMessage,
+				message: errorJson.message,
+			};
+		}
+	} catch {
+		// If parsing fails, return undefined
+	}
+	return undefined;
+}

package/src/cli/api/result.ts

@@ -0,0 +1,71 @@
+/**
+ * Represents the union of *either* the value returned
+ * from some function *or* an arbitrary error emitted during computation.
+ */
+
+/**
+ * The left side of the Result type, the value.
+ */
+export interface Success<T> {
+	_tag: "success";
+	value: T;
+}
+
+/**
+ * The right side of the Result type, the error.
+ */
+export interface Fail<E> {
+	_tag: "fail";
+	error: E;
+}
+
+export type Result<S, E> = Success<S> | Fail<E>;
+
+/**
+ * Type predicates and helpers for the Result type.
+ */
+export const Result = {
+	success<S>(value: S): Success<S> {
+		return { _tag: "success", value };
+	},
+
+	fail<E>(error: E): Fail<E> {
+		return { _tag: "fail", error };
+	},
+
+	/**
+	 * Success (left side) type predicate for the Result type.
+	 */
+	isSuccess<S, E>(result: Result<S, E>): result is Success<S> {
+		return result._tag === "success";
+	},
+
+	/**
+	 * Fail (right side) type predicate for the Result type.
+	 */
+	isFail<S, E>(result: Result<S, E>): result is Fail<E> {
+		return result._tag === "fail";
+	},
+
+	/**
+	 * Unwrap a Result value, throwing the error if it's set.
+	 */
+	unwrap<S, E>(result: Result<S, E>): S {
+		if (Result.isFail(result)) {
+			throw result.error;
+		} else {
+			return result.value;
+		}
+	},
+
+	/**
+	 * Unwrap a Result value, or return a default value if an error is set.
+	 */
+	unwrapOr<S, E>(result: Result<S, E>, defaultValue: S): S {
+		if (Result.isFail(result)) {
+			return defaultValue;
+		} else {
+			return result.value;
+		}
+	},
+};

package/src/cli/bin/cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "@stricli/core";
+import { buildContext } from "../context.js";
+import { app } from "../routes.js";
+
+// @ts-expect-error // stricli violates exactOptionalPropertyTypes
+await run(app, process.argv.slice(2), buildContext(process));