@chainlink/cre-sdk 1.1.4 → 1.2.0-alpha.1

package/README.md

@@ -8,6 +8,7 @@ The Chainlink Runtime Environment (CRE) SDK for TypeScript enables developers to
 - [Examples](#examples)
 - [Simulate locally with CRE CLI](#simulate-locally-with-cre-cli)
 - [Installation](#installation)
+- [Runtime Compatibility Constraints](#runtime-compatibility-constraints)
 - [Core Concepts](#core-concepts)
   - [Workflows](#workflows)
   - [Runtime Modes](#runtime-modes)
@@ -47,10 +48,20 @@ This package must be used along with the [CRE CLI tool](https://github.com/smart
 
 ## Prerequisites
 
-1. the [bun runtime](https://bun.com/). The wasm compilation currently is only supported by the bun runtime which has near-complete NodeJS compatibility.
+1. the [bun runtime](https://bun.com/) for local tooling and workflow compilation.
 
 2. the [CRE CLI tool](https://github.com/smartcontractkit/cre-cli) installed.
 
+## Runtime Compatibility Constraints
+
+CRE workflows are compiled to WASM and executed through Javy (QuickJS). This is **not** a full Node.js runtime.
+
+- Node built-ins like `node:fs`, `node:crypto`, `node:http`, `node:net`, etc. are not supported in workflows.
+- Browser globals like `fetch`, `window`, and `setTimeout` are also not available in workflow runtime.
+- `cre compile:workflow` / `cre-compile` now validates workflow source and fails fast when unsupported APIs are used.
+
+Use CRE capabilities (for example, `cre.capabilities.HTTPClient`) instead of direct Node/browser APIs.
+
 ## Getting Started
 
 We recommend you consult the [getting started docs](https://docs.chain.link/cre/getting-started/cli-installation) and install the CRE CLI.

package/bin/cre-compile.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { main as compileWorkflow } from "../scripts/src/compile-workflow";
+import { WorkflowRuntimeCompatibilityError } from "../scripts/src/validate-workflow-runtime-compat";
 
 const main = async () => {
   const cliArgs = process.argv.slice(2);
@@ -26,6 +27,10 @@ const main = async () => {
 
 // CLI entry point
 main().catch((e) => {
-  console.error(e);
+  if (e instanceof WorkflowRuntimeCompatibilityError) {
+    console.error(`\n❌ ${e.message}`);
+  } else {
+    console.error(e);
+  }
   process.exit(1);
 });

package/dist/index.d.ts

@@ -1 +1,4 @@
+/// <reference types="./sdk/types/global" />
+/// <reference types="./sdk/types/restricted-apis" />
+/// <reference types="./sdk/types/restricted-node-modules" />
 export * from './sdk';

package/dist/sdk/types/global.d.ts

@@ -1,5 +1,8 @@
-// Global type declarations for the CRE SDK runtime
-// Those are the methods that the Host exposes to the Guest.
+// Global type declarations for the CRE SDK runtime.
+// These are the methods and globals exposed by the Host to the Guest.
+
+type ExistingGlobal<K extends PropertyKey, Fallback> =
+	typeof globalThis extends Record<K, infer T> ? T : Fallback
 
 /**
  * Host functions exposed by the CRE runtime to WASM guests
@@ -78,6 +81,147 @@ declare global {
 	 * @returns Unix timestamp in milliseconds
 	 */
 	function now(): number
+
+	/**
+	 * Console API available in the QuickJS runtime
+	 */
+	type CreConsole = {
+		log(...args: unknown[]): void
+		warn(...args: unknown[]): void
+		error(...args: unknown[]): void
+		info(...args: unknown[]): void
+		debug(...args: unknown[]): void
+	}
+	var console: ExistingGlobal<'console', CreConsole>
+
+	/**
+	 * TextEncoder/TextDecoder APIs available via Javy's text_encoding support
+	 */
+	interface CreTextEncoderEncodeIntoResult {
+		read: number
+		written: number
+	}
+
+	interface CreTextEncoder {
+		readonly encoding: string
+		encode(input?: string): Uint8Array
+		encodeInto(input: string, dest: Uint8Array): CreTextEncoderEncodeIntoResult
+	}
+	var TextEncoder: ExistingGlobal<
+		'TextEncoder',
+		{ prototype: CreTextEncoder; new (): CreTextEncoder }
+	>
+
+	interface CreTextDecoder {
+		readonly encoding: string
+		readonly fatal: boolean
+		readonly ignoreBOM: boolean
+		decode(input?: ArrayBuffer | ArrayBufferView, options?: { stream?: boolean }): string
+	}
+	var TextDecoder: ExistingGlobal<
+		'TextDecoder',
+		{
+			prototype: CreTextDecoder
+			new (label?: string, options?: { fatal?: boolean; ignoreBOM?: boolean }): CreTextDecoder
+		}
+	>
+
+	/**
+	 * Buffer and Base64 APIs exposed via prepareRuntime() from node:buffer.
+	 * Declared structurally so they work even when consumers opt out of @types/node.
+	 */
+	type CreBufferEncoding =
+		| 'ascii'
+		| 'base64'
+		| 'base64url'
+		| 'binary'
+		| 'hex'
+		| 'latin1'
+		| 'ucs-2'
+		| 'ucs2'
+		| 'utf-8'
+		| 'utf-16le'
+		| 'utf8'
+		| 'utf16le'
+
+	interface CreBuffer extends Uint8Array {
+		toString(encoding?: CreBufferEncoding, start?: number, end?: number): string
+		slice(start?: number, end?: number): CreBuffer
+		subarray(begin?: number, end?: number): CreBuffer
+	}
+
+	var Buffer: ExistingGlobal<
+		'Buffer',
+		{
+			prototype: CreBuffer
+			alloc(
+				size: number,
+				fill?: string | number | Uint8Array | ArrayBuffer | ArrayBufferView,
+				encoding?: CreBufferEncoding,
+			): CreBuffer
+			byteLength(
+				value: string | Uint8Array | ArrayBuffer | ArrayBufferView,
+				encoding?: CreBufferEncoding,
+			): number
+			concat(list: readonly Uint8Array[], totalLength?: number): CreBuffer
+			from(value: string, encoding?: CreBufferEncoding): CreBuffer
+			from(value: Uint8Array | ArrayBuffer | ArrayBufferView | ArrayLike<number>): CreBuffer
+			isBuffer(value: unknown): value is CreBuffer
+		}
+	>
+
+	function atob(encodedData: string): string
+	function btoa(stringToEncode: string): string
+
+	/**
+	 * URL and URLSearchParams — exposed via prepareRuntime() from node:url
+	 */
+	interface CreURLSearchParams {
+		append(name: string, value: string): void
+		delete(name: string): void
+		get(name: string): string | null
+		getAll(name: string): string[]
+		has(name: string): boolean
+		set(name: string, value: string): void
+		sort(): void
+		toString(): string
+		forEach(callback: (value: string, key: string, parent: CreURLSearchParams) => void): void
+		entries(): IterableIterator<[string, string]>
+		keys(): IterableIterator<string>
+		values(): IterableIterator<string>
+		[Symbol.iterator](): IterableIterator<[string, string]>
+		readonly size: number
+	}
+	var URLSearchParams: ExistingGlobal<
+		'URLSearchParams',
+		{
+			prototype: CreURLSearchParams
+			new (
+				init?: string | Record<string, string> | [string, string][] | CreURLSearchParams,
+			): CreURLSearchParams
+		}
+	>
+
+	interface CreURL {
+		hash: string
+		host: string
+		hostname: string
+		href: string
+		readonly origin: string
+		password: string
+		pathname: string
+		port: string
+		protocol: string
+		search: string
+		readonly searchParams: CreURLSearchParams
+		username: string
+		toString(): string
+		toJSON(): string
+	}
+	var URL: ExistingGlobal<
+		'URL',
+		{ prototype: CreURL; new (url: string, base?: string | CreURL): CreURL }
+	>
 }
 
 export {}

package/dist/sdk/types/restricted-apis.d.ts

@@ -1,27 +1,22 @@
 declare global {
-	/** @deprecated fetch is not available in CRE WASM workflows. Use cre.capabilities.HTTPClient instead. */
-	const fetch: never
-
-	/** @deprecated window is not available in CRE WASM workflows. */
-	const window: never
-
-	/** @deprecated document is not available in CRE WASM workflows. */
-	const document: never
-
-	/** @deprecated XMLHttpRequest is not available in CRE WASM workflows. Use cre.capabilities.HTTPClient instead. */
-	const XMLHttpRequest: never
-
-	/** @deprecated localStorage is not available in CRE WASM workflows. */
-	const localStorage: never
-
-	/** @deprecated sessionStorage is not available in CRE WASM workflows. */
-	const sessionStorage: never
-
-	/** @deprecated setTimeout is not available in CRE WASM workflows. Use cre.capabilities.CronCapability for scheduling. */
-	const setTimeout: never
-
-	/** @deprecated setInterval is not available in CRE WASM workflows. Use cre.capabilities.CronCapability for scheduling. */
-	const setInterval: never
+	/**
+	 * @deprecated fetch is not available in CRE WASM workflows.
+	 * Use cre.capabilities.HTTPClient instead.
+	 * @see https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+	 */
+	function fetch(_notAvailable: never): never
+
+	/**
+	 * @deprecated setTimeout is not available in CRE WASM workflows. Use cre.capabilities.CronCapability for scheduling.
+	 * @see https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+	 */
+	function setTimeout(_notAvailable: never, ..._args: never[]): never
+
+	/**
+	 * @deprecated setInterval is not available in CRE WASM workflows. Use cre.capabilities.CronCapability for scheduling.
+	 * @see https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+	 */
+	function setInterval(_notAvailable: never, ..._args: never[]): never
 }
 
 export {}