@notionhq/workers 0.8.0 → 0.8.1

package/src/worker.test.ts

@@ -1,11 +1,26 @@
 import { describe, expect, it } from "vitest";
 
+import { CREDENTIAL_VALUE } from "./credential.js";
 import * as Schema from "./schema.js";
 import { Worker } from "./worker.js";
 
 describe("Worker", () => {
-	it("includes sdkVersion, databases, and capabilities in manifest", () => {
+	it("includes sdkVersion, credentials, databases, and capabilities in manifest", () => {
 		const worker = new Worker();
+		worker.credential("LINEAR_API_TOKEN", {
+			network: [
+				{
+					domain: "api.linear.com",
+					transform: [
+						{
+							headers: {
+								Authorization: `Bearer ${CREDENTIAL_VALUE}`,
+							},
+						},
+					],
+				},
+			],
+		});
 		const tasks = worker.database("tasks", {
 			type: "managed",
 			initialTitle: "Tasks",
@@ -26,6 +41,23 @@ describe("Worker", () => {
 		});
 
 		expect(worker.manifest.sdkVersion).toMatch(/^\d+\.\d+\.\d+/);
+		expect(worker.manifest.credentials).toEqual([
+			{
+				key: "LINEAR_API_TOKEN",
+				network: [
+					{
+						domain: "api.linear.com",
+						transform: [
+							{
+								headers: {
+									Authorization: "Bearer {{credential}}",
+								},
+							},
+						],
+					},
+				],
+			},
+		]);
 		expect(worker.manifest.databases).toEqual([
 			{
 				key: "tasks",
@@ -288,7 +320,7 @@ describe("Worker", () => {
 		);
 	});
 
-	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
+	it("rejects duplicate keys across credentials, databases, pacers, and capabilities", () => {
 		const worker = new Worker();
 		const db = worker.database("shared-key", {
 			type: "managed",
@@ -301,6 +333,23 @@ describe("Worker", () => {
 			},
 		});
 
+		expect(() =>
+			worker.credential("shared-key", {
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: CREDENTIAL_VALUE,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow('Worker item with key "shared-key" already registered');
+
 		expect(() =>
 			worker.sync("shared-key", {
 				database: db,
@@ -311,4 +360,106 @@ describe("Worker", () => {
 			}),
 		).toThrow('Worker item with key "shared-key" already registered');
 	});
+
+	it("does not reserve a key when registration fails", () => {
+		const worker = new Worker();
+
+		expect(() =>
+			worker.credential("REUSABLE_KEY", {
+				network: [],
+			}),
+		).toThrow("must declare at least one network rule");
+
+		expect(() =>
+			worker.pacer("REUSABLE_KEY", {
+				allowedRequests: 10,
+				intervalMs: 1_000,
+			}),
+		).not.toThrow();
+	});
+
+	it("rejects credentials that target the same domain and header", () => {
+		const worker = new Worker();
+		worker.credential("FIRST_TOKEN", {
+			network: [
+				{
+					domain: "api.example.com",
+					transform: [{ headers: { Authorization: `Bearer ${CREDENTIAL_VALUE}` } }],
+				},
+			],
+		});
+
+		expect(() =>
+			worker.credential("SECOND_TOKEN", {
+				network: [
+					{
+						domain: "API.EXAMPLE.COM",
+						transform: [{ headers: { authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			}),
+		).toThrow('conflicts with credential "FIRST_TOKEN"');
+	});
+
+	it("limits the number of credential declarations", () => {
+		const worker = new Worker();
+		for (let index = 0; index < 100; index += 1) {
+			worker.credential(`TOKEN_${index}`, {
+				network: [
+					{
+						domain: `api${index}.example.com`,
+						transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			});
+		}
+
+		expect(() =>
+			worker.credential("ONE_TOO_MANY", {
+				network: [
+					{
+						domain: "overflow.example.com",
+						transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			}),
+		).toThrow("cannot declare more than 100 credentials");
+	});
+
+	it("matches the service limit for the credential declaration payload", () => {
+		const worker = new Worker();
+		for (let index = 0; index < 32; index += 1) {
+			worker.credential(`TOKEN_${index}`, {
+				network: [
+					{
+						domain: `api${index}.example.com`,
+						transform: [
+							{
+								headers: {
+									Authorization: `${"x".repeat(8_000)}${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			});
+		}
+
+		expect(() =>
+			worker.credential("TOKEN_32", {
+				network: [
+					{
+						domain: "api32.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: `${"x".repeat(8_000)}${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow("credential declarations must be at most 262144 bytes");
+	});
 });

package/src/worker.ts

@@ -39,6 +39,17 @@ import type {
 	WorkflowEvent,
 } from "./capabilities/workflow.js";
 import { createWorkflowCapability } from "./capabilities/workflow.js";
+import type {
+	CredentialConfiguration,
+	CredentialDeclaration,
+	CredentialKey,
+} from "./credential.js";
+import {
+	createCredentialDeclaration,
+	MAX_CREDENTIAL_DECLARATIONS_BYTES,
+	MAX_CREDENTIALS,
+	validateCredentialDeclarationConflicts,
+} from "./credential.js";
 import type { PacerDeclaration } from "./pacer_internal.js";
 import { pacerWait } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
@@ -212,6 +223,7 @@ type CapabilityManifestEntry = Pick<Capability, "_tag" | "key" | "config">;
  */
 export type WorkerManifest = {
 	readonly sdkVersion: string;
+	readonly credentials: readonly CredentialDeclaration[];
 	readonly databases: readonly RegisteredDatabase[];
 	readonly pacers: readonly PacerDeclaration[];
 	readonly capabilities: readonly CapabilityManifestEntry[];
@@ -243,9 +255,33 @@ const SDK_VERSION = (() => {
 
 export class Worker {
 	#capabilities: Map<string, StoredCapability> = new Map();
+	#credentials: Map<string, CredentialDeclaration> = new Map();
 	#databases: Map<string, RegisteredDatabase> = new Map();
 	#pacers: Map<string, PacerDeclaration> = new Map();
 
+	/**
+	 * Declare a credential that is injected into matching outbound HTTPS
+	 * requests without exposing its value to Worker code.
+	 */
+	credential(key: CredentialKey, config: CredentialConfiguration): void {
+		this.#validateUniqueKey(key);
+		if (this.#credentials.size >= MAX_CREDENTIALS) {
+			throw new Error(`Worker cannot declare more than ${MAX_CREDENTIALS} credentials`);
+		}
+		const declaration = createCredentialDeclaration(key, config);
+		validateCredentialDeclarationConflicts(this.#credentials.values(), declaration);
+		const declarations = [...this.#credentials.values(), declaration];
+		if (
+			new TextEncoder().encode(JSON.stringify(declarations)).byteLength >
+			MAX_CREDENTIAL_DECLARATIONS_BYTES
+		) {
+			throw new Error(
+				`Worker credential declarations must be at most ${MAX_CREDENTIAL_DECLARATIONS_BYTES} bytes`,
+			);
+		}
+		this.#credentials.set(key, declaration);
+	}
+
 	database<PK extends string, S extends Schema<PK>>(
 		key: string,
 		config: DatabaseConfig<PK, S>,
@@ -675,6 +711,7 @@ export class Worker {
 	get manifest(): WorkerManifest {
 		return {
 			sdkVersion: SDK_VERSION,
+			credentials: Array.from(this.#credentials.values()),
 			databases: Array.from(this.#databases.values()),
 			pacers: Array.from(this.#pacers.values()),
 			capabilities: this.capabilities,
@@ -723,7 +760,12 @@ export class Worker {
 		if (!key || typeof key !== "string") {
 			throw new Error("Capability key must be a non-empty string");
 		}
-		if (this.#capabilities.has(key) || this.#databases.has(key) || this.#pacers.has(key)) {
+		if (
+			this.#capabilities.has(key) ||
+			this.#credentials.has(key) ||
+			this.#databases.has(key) ||
+			this.#pacers.has(key)
+		) {
 			throw new Error(`Worker item with key "${key}" already registered`);
 		}
 	}