substarte 120240617.1.9

package/src/Platform.ts

@@ -0,0 +1,187 @@
+/**
+ * @private
+ *
+ * Returns properties of the current environment.
+ */
+
+declare const Deno: any;
+declare const EdgeRuntime: any;
+
+type Arch = "x32" | "x64" | "arm" | "arm64" | `other:${string}` | "unknown";
+
+type PlatformName =
+  | "MacOS"
+  | "Linux"
+  | "Windows"
+  | "FreeBSD"
+  | "OpenBSD"
+  | "iOS"
+  | "Android"
+  | `Other:${string}`
+  | "Unknown";
+
+type Browser = "ie" | "edge" | "chrome" | "firefox" | "safari";
+
+type PlatformProperties = {
+  os: PlatformName;
+  arch: Arch;
+  runtime:
+    | "node"
+    | "deno"
+    | "edge"
+    | "workerd"
+    | `browser:${Browser}`
+    | "unknown";
+  runtimeVersion: string;
+};
+
+export const getPlatformProperties = (): PlatformProperties => {
+  if (typeof Deno !== "undefined" && Deno.build != null) {
+    return {
+      os: normalizePlatform(Deno.build.os),
+      arch: normalizeArch(Deno.build.arch),
+      runtime: "deno",
+      runtimeVersion:
+        typeof Deno.version === "string"
+          ? Deno.version
+          : (Deno.version?.deno ?? "unknown"),
+    };
+  }
+  if (typeof EdgeRuntime !== "undefined") {
+    return {
+      os: "Unknown",
+      arch: `other:${EdgeRuntime}`,
+      runtime: "edge",
+      runtimeVersion: process.version,
+    };
+  }
+  // Check if Node.js
+  if (
+    Object.prototype.toString.call(
+      typeof process !== "undefined" ? process : 0,
+    ) === "[object process]"
+  ) {
+    return {
+      os: normalizePlatform(process.platform),
+      arch: normalizeArch(process.arch),
+      runtime: "node",
+      runtimeVersion: process.version,
+    };
+  }
+
+  // https://developers.cloudflare.com/workers/runtime-apis/web-standards/#navigatoruseragent
+  if (
+    typeof navigator !== undefined &&
+    navigator.userAgent === "Cloudflare-Workers"
+  ) {
+    return {
+      os: "Unknown",
+      arch: "unknown",
+      runtime: "workerd",
+      runtimeVersion: "unknown",
+    };
+  }
+
+  const browserInfo = getBrowserInfo();
+  if (browserInfo) {
+    return {
+      os: "Unknown",
+      arch: "unknown",
+      runtime: `browser:${browserInfo.browser}`,
+      runtimeVersion: browserInfo.version,
+    };
+  }
+
+  return {
+    os: "Unknown",
+    arch: "unknown",
+    runtime: "unknown",
+    runtimeVersion: "unknown",
+  };
+};
+
+type BrowserInfo = {
+  browser: Browser;
+  version: string;
+};
+
+// Note: modified from https://github.com/JS-DevTools/host-environment/blob/b1ab79ecde37db5d6e163c050e54fe7d287d7c92/src/isomorphic.browser.ts
+function getBrowserInfo(): BrowserInfo | null {
+  if (typeof navigator === "undefined" || !navigator) {
+    return null;
+  }
+
+  // NOTE: The order matters here!
+  const browserPatterns = [
+    { key: "edge" as const, pattern: /Edge(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: "ie" as const, pattern: /MSIE(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    {
+      key: "ie" as const,
+      pattern: /Trident(?:.*rv\:(\d+)\.(\d+)(?:\.(\d+))?)?/,
+    },
+    {
+      key: "chrome" as const,
+      pattern: /Chrome(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/,
+    },
+    {
+      key: "firefox" as const,
+      pattern: /Firefox(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/,
+    },
+    {
+      key: "safari" as const,
+      pattern:
+        /(?:Version\W+(\d+)\.(\d+)(?:\.(\d+))?)?(?:\W+Mobile\S*)?\W+Safari/,
+    },
+  ];
+
+  // Find the FIRST matching browser
+  for (const { key, pattern } of browserPatterns) {
+    const match = pattern.exec(navigator.userAgent);
+    if (match) {
+      const major = match[1] || 0;
+      const minor = match[2] || 0;
+      const patch = match[3] || 0;
+
+      return { browser: key, version: `${major}.${minor}.${patch}` };
+    }
+  }
+
+  return null;
+}
+
+const normalizeArch = (arch: string): Arch => {
+  // Node docs:
+  // - https://nodejs.org/api/process.html#processarch
+  // Deno docs:
+  // - https://doc.deno.land/deno/stable/~/Deno.build
+  if (arch === "x32") return "x32";
+  if (arch === "x86_64" || arch === "x64") return "x64";
+  if (arch === "arm") return "arm";
+  if (arch === "aarch64" || arch === "arm64") return "arm64";
+  if (arch) return `other:${arch}`;
+  return "unknown";
+};
+
+const normalizePlatform = (platform: string): PlatformName => {
+  // Node platforms:
+  // - https://nodejs.org/api/process.html#processplatform
+  // Deno platforms:
+  // - https://doc.deno.land/deno/stable/~/Deno.build
+  // - https://github.com/denoland/deno/issues/14799
+
+  platform = platform.toLowerCase();
+
+  // NOTE: this iOS check is untested and may not work
+  // Node does not work natively on IOS, there is a fork at
+  // https://github.com/nodejs-mobile/nodejs-mobile
+  // however it is unknown at the time of writing how to detect if it is running
+  if (platform.includes("ios")) return "iOS";
+  if (platform === "android") return "Android";
+  if (platform === "darwin") return "MacOS";
+  if (platform === "win32") return "Windows";
+  if (platform === "freebsd") return "FreeBSD";
+  if (platform === "openbsd") return "OpenBSD";
+  if (platform === "linux") return "Linux";
+  if (platform) return `Other:${platform}`;
+  return "Unknown";
+};

package/src/Streaming.ts

@@ -0,0 +1,55 @@
+/** Represents an array item within a `Node` output chunk, specifies the field is an array containing this `item` at the `index`. **/
+type ChunkArrayItem<T = Object> = {
+  object: "array.item";
+  index: number;
+  item: T;
+};
+
+/** Helper types for producing the "Chunk" types used in the `NodeDelta` messages */
+type ChunkizeObject<T> = T extends object
+  ? { [P in keyof T]: ChunkizeAny<T[P]> }
+  : T;
+
+type ChunkizeArray<T> = T extends (infer U)[]
+  ? ChunkArrayItem<ChunkizeAny<U>>
+  : ChunkArrayItem<T>;
+
+type ChunkizeAny<T> = T extends (infer U)[]
+  ? ChunkizeArray<U>
+  : T extends object
+    ? ChunkizeObject<T>
+    : T;
+
+/** Stream message that contains the completed `Node` output */
+type NodeResult<T = Object> = {
+  object: "node.result";
+  nodeId: string;
+  data: T;
+};
+
+/** Stream message that contains a chunk of the `Node` output */
+type NodeDelta<T = Object> = {
+  object: "node.delta";
+  nodeId: string;
+  data: ChunkizeAny<T>;
+};
+
+/** Stream message when an error happened during a `Node` run. */
+export type NodeError = {
+  object: "node.error";
+  nodeId: string;
+  data: {
+    type: string;
+    message: string;
+  };
+};
+
+/** Stream message that contains the completed "Graph" output */
+export type GraphResult<T = Object> = {
+  object: "graph.result";
+  data: T;
+};
+
+export type NodeMessage<T = Object> = NodeResult<T> | NodeDelta<T> | NodeError;
+
+export type SSEMessage<T = Object> = NodeMessage | GraphResult<T>;

package/src/Substrate.ts

@@ -0,0 +1,314 @@
+import { SubstrateError, RequestTimeoutError } from "substrate/Error";
+import { VERSION } from "substrate/version";
+import OpenAPIjson from "substrate/openapi.json";
+import { SubstrateResponse } from "substrate/SubstrateResponse";
+import { SubstrateStreamingResponse } from "substrate/SubstrateStreamingResponse";
+import { Node } from "substrate/Node";
+import { Future } from "substrate/Future";
+import { getPlatformProperties } from "substrate/Platform";
+import { deflate } from "pako";
+import { randomString } from "substrate/idGenerator";
+
+type Configuration = {
+  /**
+   * [docs/authentication](https://docs.substrate.run/#authentication)
+   */
+  apiKey: string | undefined;
+
+  /**
+   * [docs/versioning](https://docs.substrate.run/versioning)
+   */
+  apiVersion?: string | undefined;
+
+  baseUrl?: string;
+
+  /**
+   * Request timeout in milliseconds. Default: 5m
+   */
+  timeout?: number;
+
+  /**
+   * Secrets for third party services.
+   */
+  secrets?: Secrets;
+
+  /**
+   * Add additional headers to each request. These may override headers set by the Substrate client.
+   */
+  additionalHeaders?: Record<string, string>;
+};
+
+export type Secrets = {
+  openai?: string;
+  anthropic?: string;
+};
+
+/**
+ * [docs/introduction](https://docs.substrate.run)
+ */
+export class Substrate {
+  apiKey: Configuration["apiKey"];
+  baseUrl: NonNullable<Configuration["baseUrl"]>;
+  apiVersion: NonNullable<Configuration["apiVersion"]>;
+  timeout: NonNullable<Configuration["timeout"]>;
+  additionalHeaders: NonNullable<Configuration["additionalHeaders"]>;
+
+  /**
+   * Initialize the Substrate SDK.
+   */
+  constructor({
+    apiKey,
+    baseUrl,
+    apiVersion,
+    timeout,
+    secrets,
+    additionalHeaders,
+  }: Configuration) {
+    if (!apiKey) {
+      console.warn(
+        "[Substrate] An API Key is required. Specify it when constructing the client: `new Substrate({ apiKey: 'API_KEY' })`",
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl ?? "https://api.substrate.run";
+    this.apiVersion = apiVersion ?? OpenAPIjson["info"]["version"];
+    this.timeout = timeout ?? 300_000;
+    this.additionalHeaders = additionalHeaders ?? {};
+    if (secrets) {
+      if (secrets.openai) {
+        this.additionalHeaders["x-substrate-openai-api-key"] = secrets.openai;
+      }
+      if (secrets.anthropic) {
+        this.additionalHeaders["x-substrate-anthropic-api-key"] =
+          secrets.anthropic;
+      }
+    }
+  }
+
+  /**
+   *  Run the given nodes.
+   *
+   *  @throws {SubstrateError} when the server response is an error.
+   *  @throws {RequestTimeoutError} when the client has timed out (Configured by `Substrate.timeout`).
+   *  @throws {Error} when the client encounters an error making the request.
+   */
+  async run(...nodes: Node[]): Promise<SubstrateResponse> {
+    return this.runSerialized(nodes);
+  }
+
+  /**
+   *  Stream the given nodes.
+   */
+  async stream(...nodes: Node[]): Promise<SubstrateStreamingResponse> {
+    const serialized = Substrate.serialize(...nodes);
+    return this.streamSerialized(serialized);
+  }
+
+  /**
+   *  Run the given nodes, serialized using `Substrate.serialize`.
+   *
+   *  @throws {SubstrateError} when the server response is an error.
+   *  @throws {RequestTimeoutError} when the client has timed out (Configured by `Substrate.timeout`).
+   *  @throws {Error} when the client encounters an error making the request.
+   */
+  async runSerialized(
+    nodes: Node[],
+    endpoint: string = "/compose",
+  ): Promise<SubstrateResponse> {
+    const serialized = Substrate.serialize(...nodes);
+    const url = this.baseUrl + endpoint;
+    const req = { dag: serialized };
+    // NOTE: we're creating the signal this way instead of AbortController.timeout because it is only very
+    // recently available on some environments, so this is a bit more supported.
+    const abortController = new AbortController();
+    const { signal } = abortController;
+    const timeout = setTimeout(() => abortController.abort(), this.timeout);
+
+    const request = new Request(url, this.requestOptions(req, signal));
+    const requestId = request.headers.get("x-substrate-request-id");
+    try {
+      const apiResponse = await fetch(request);
+
+      if (apiResponse.ok) {
+        const json = await apiResponse.json();
+        const res = new SubstrateResponse(request, apiResponse, json);
+        /** TODO stop setting output on node */
+
+        // @ts-expect-error (accessing protected)
+        for (let node of Substrate.findAllNodes(nodes)) node.response = res;
+
+        return res;
+      } else {
+        throw new SubstrateError(
+          `[Request failed] status=${apiResponse.status} statusText=${apiResponse.statusText} requestId=${requestId}`,
+        );
+      }
+    } catch (err: unknown) {
+      if (err instanceof Error) {
+        if (err.name === "AbortError") {
+          throw new RequestTimeoutError(
+            `Request timed out after ${this.timeout}ms requestId=${requestId}`,
+          );
+          // TODO: We could propagate timeout errors to nodes too, but I'm
+          // not sure yet what might be easier for the user to manage.
+        }
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /**
+   *  Stream the given nodes, serialized using `Substrate.serialize`.
+   */
+  async streamSerialized(serialized: any, endpoint: string = "/compose") {
+    const url = this.baseUrl + endpoint;
+    const req = { dag: serialized };
+    const abortController = new AbortController();
+    const { signal } = abortController;
+    const timeout = setTimeout(() => abortController.abort(), this.timeout);
+    const requestOptions = this.requestOptions(req, signal);
+
+    // Add Streaming Headers
+    requestOptions.headers.set("Accept", "text/event-stream");
+    requestOptions.headers.set("X-Substrate-Streaming", "1");
+
+    const request = new Request(url, requestOptions);
+    const requestId = request.headers.get("x-substrate-request-id");
+    try {
+      const response = await fetch(request);
+      return await SubstrateStreamingResponse.fromRequestReponse(
+        request,
+        response,
+      );
+    } catch (err: unknown) {
+      if (err instanceof Error) {
+        if (err.name === "AbortError") {
+          throw new RequestTimeoutError(
+            `Request timed out after ${this.timeout}ms requestId=${requestId}`,
+          );
+          // TODO: We could propagate timeout errors to nodes too, but I'm
+          // not sure yet what might be easier for the user to manage.
+        }
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /**
+   *  Return a set of all nodes and their dependent nodes.
+   */
+  static findAllNodes(fromNodes: Node[]): Set<Node> {
+    const allNodes = new Set<Node>();
+    for (let node of fromNodes) {
+      // @ts-ignore: .references() is protected
+      const refs = node.references();
+      for (let n of refs.nodes) {
+        allNodes.add(n);
+      }
+    }
+    return allNodes;
+  }
+
+  /**
+   *  Return a set of all futures and their dependent futures.
+   */
+  static findAllFutures(fromNodes: Node[]): Set<Future<any>> {
+    const allFutures = new Set<Future<any>>();
+    for (let node of fromNodes) {
+      // @ts-ignore: .references() is protected
+      const refs = node.references();
+      for (let f of refs.futures) {
+        allFutures.add(f);
+      }
+    }
+    return allFutures;
+  }
+
+  /**
+   *  Transform an array of nodes into JSON for the Substrate API
+   */
+  static serialize(...nodes: Node[]): any {
+    const allFutures = this.findAllFutures(nodes);
+    const allNodes = this.findAllNodes(nodes);
+    const allEdges: Record<string, Set<string>> = {};
+    for (let n of allNodes) {
+      allEdges[n.id] = new Set<string>();
+      for (let d of n.depends) {
+        allEdges[n.id]!.add(d.id);
+      }
+    }
+    return {
+      nodes: Array.from(allNodes).map((node) => node.toJSON()),
+      futures: Array.from(allFutures).map((future) => future.toJSON()),
+      edges: Object.keys(allEdges).flatMap((toId: string) => {
+        let fromIds: string[] = Array.from(allEdges[toId] as Set<string>);
+        return fromIds.map((fromId: string) => [fromId, toId, {}]);
+      }),
+      initial_args: {}, // @deprecated
+    };
+  }
+
+  /**
+   *  Returns a url to visualize the given nodes.
+   */
+  static visualize(...nodes: Node[]): string {
+    const serialized = this.serialize(...nodes);
+    const compressed = deflate(JSON.stringify(serialized), {
+      level: 9,
+    });
+    const numArray = Array.from(compressed);
+    const base64 = btoa(String.fromCharCode.apply(null, numArray));
+    const urlEncoded = base64
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    const baseURL = "https://explore.substrate.run/s/";
+    return baseURL + urlEncoded;
+  }
+
+  protected requestOptions(body: any, signal: AbortSignal) {
+    return {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+      signal,
+    };
+  }
+
+  protected headers() {
+    const headers = new Headers();
+
+    // API
+    headers.append("Accept", "application/json");
+    headers.append("Content-Type", "application/json");
+    headers.append("User-Agent", `APIClient/JS ${VERSION}`);
+    headers.append("X-Substrate-Version", this.apiVersion);
+    headers.append("X-Substrate-Request-Id", randomString(32));
+    headers.append("X-Substrate-Backend", "v1");
+
+    // Auth
+    headers.append("Authorization", `Bearer ${this.apiKey}`);
+
+    // SDK
+    headers.append("X-Substrate-Lang", "js");
+    headers.append("X-Substrate-Package-Version", VERSION);
+
+    // Platform, Runtime
+    const props = getPlatformProperties();
+    headers.append("X-Substrate-OS", props.os);
+    headers.append("X-Substrate-Arch", props.arch);
+    headers.append("X-Substrate-Runtime", props.runtime);
+    headers.append("X-Substrate-Runtime-Version", props.runtimeVersion);
+
+    // User-Provided
+    for (const [name, value] of Object.entries(this.additionalHeaders)) {
+      headers.set(name, value);
+    }
+
+    return headers;
+  }
+}

package/src/SubstrateResponse.ts

@@ -0,0 +1,41 @@
+import { AnyNode, NodeOutput } from "substrate/Nodes";
+import { NodeError } from "substrate/Error";
+
+/**
+ * Response to a run request.
+ */
+export class SubstrateResponse {
+  public apiRequest: Request;
+  public apiResponse: Response;
+  public json: any;
+
+  constructor(request: Request, response: Response, json: any = null) {
+    this.apiRequest = request;
+    this.apiResponse = response;
+    this.json = json;
+  }
+
+  get requestId() {
+    return this.apiRequest.headers.get("x-substrate-request-id");
+  }
+
+  /**
+   * Returns an error from the `Node` if there was one.
+   */
+  getError<T extends AnyNode>(node: T): NodeError | undefined {
+    // @ts-expect-error
+    return node.output() instanceof NodeError ? node.output() : undefined;
+  }
+
+  /**
+   * Returns the result for given `Node`.
+   *
+   *  @throws {NodeError} when there was an error running the node.
+   */
+  get<T extends AnyNode>(node: T): NodeOutput<T> {
+    const err = this.getError(node);
+    if (err) throw err;
+    // @ts-expect-error
+    return node.output() as NodeOutput<T>;
+  }
+}