TypeScript SDK for Exosphere

typescript-sdk/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+Dist
+dist

typescript-sdk/README.md

@@ -0,0 +1,76 @@
+# ExosphereHost TypeScript SDK
+
+This package provides a TypeScript interface to interact with the ExosphereHost state manager. It mirrors the functionality of the Python SDK, offering utilities to manage graphs and trigger executions.
+
+It also ships a lightweight runtime for executing `BaseNode` subclasses and utility signals for advanced control flow.
+
+## Installation
+
+```bash
+npm install exospherehost
+```
+
+## Usage
+
+```typescript
+import { StateManager, GraphNode, TriggerState } from 'exospherehost';
+
+const sm = new StateManager('my-namespace', {
+  stateManagerUri: 'https://state-manager.example.com',
+  key: 'api-key'
+});
+
+const nodes: GraphNode[] = [
+  {
+    node_name: 'Start',
+    identifier: 'start-node',
+    inputs: {},
+    next_nodes: ['end-node']
+  },
+  {
+    node_name: 'End',
+    identifier: 'end-node',
+    inputs: {},
+    next_nodes: []
+  }
+];
+
+await sm.upsertGraph('sample-graph', nodes, {});
+
+const trigger: TriggerState = {
+  identifier: 'demo',
+  inputs: { foo: 'bar' }
+};
+
+await sm.trigger('sample-graph', trigger);
+```
+
+### Defining Nodes and Running the Runtime
+
+```typescript
+import { BaseNode, Runtime } from 'exospherehost';
+import { z } from 'zod';
+
+class ExampleNode extends BaseNode<typeof ExampleNode.Inputs, typeof ExampleNode.Outputs> {
+  static Inputs = z.object({ message: z.string() });
+  static Outputs = z.object({ result: z.string() });
+  static Secrets = z.object({});
+
+  async execute() {
+    return { result: this.inputs.message.toUpperCase() };
+  }
+}
+
+const runtime = new Runtime('my-namespace', 'example-runtime', [ExampleNode], {
+  stateManagerUri: 'https://state-manager.example.com',
+  key: 'api-key'
+});
+
+await runtime.start();
+```
+
+Nodes can also throw `PruneSignal` to drop a state or `ReQueueAfterSignal` to requeue it after a delay.
+
+## License
+
+MIT

typescript-sdk/exospherehost/index.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './models.js';
+export * from './stateManager.js';
+export * from './node/index.js';
+export * from './runtime.js';
+export * from './signals.js';
+export * from './logger.js';
+export * from './utils.js';

typescript-sdk/exospherehost/logger.ts

@@ -0,0 +1,70 @@
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3
+}
+
+export class Logger {
+  private static instance: Logger;
+  private level: LogLevel;
+  private isDisabled: boolean;
+
+  private constructor() {
+    this.level = this.getLogLevelFromEnv();
+    this.isDisabled = process.env.EXOSPHERE_DISABLE_DEFAULT_LOGGING === 'true';
+  }
+
+  public static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger();
+    }
+    return Logger.instance;
+  }
+
+  private getLogLevelFromEnv(): LogLevel {
+    const levelName = (process.env.EXOSPHERE_LOG_LEVEL || 'INFO').toUpperCase();
+    switch (levelName) {
+      case 'DEBUG': return LogLevel.DEBUG;
+      case 'INFO': return LogLevel.INFO;
+      case 'WARN': return LogLevel.WARN;
+      case 'ERROR': return LogLevel.ERROR;
+      default: return LogLevel.INFO;
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return !this.isDisabled && level >= this.level;
+  }
+
+  private formatMessage(level: string, name: string, message: string): string {
+    const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
+    return `${timestamp} | ${level} | ${name} | ${message}`;
+  }
+
+  public debug(name: string, message: string): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      console.debug(this.formatMessage('DEBUG', name, message));
+    }
+  }
+
+  public info(name: string, message: string): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      console.info(this.formatMessage('INFO', name, message));
+    }
+  }
+
+  public warn(name: string, message: string): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      console.warn(this.formatMessage('WARN', name, message));
+    }
+  }
+
+  public error(name: string, message: string): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      console.error(this.formatMessage('ERROR', name, message));
+    }
+  }
+}
+
+export const logger = Logger.getInstance();

typescript-sdk/exospherehost/models.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+
+// Unites Strategy Enum
+export enum UnitesStrategyEnum {
+  ALL_SUCCESS = 'ALL_SUCCESS',
+  ALL_DONE = 'ALL_DONE'
+}
+
+// Unites Model
+export const UnitesModel = z.object({
+  identifier: z.string().describe('Identifier of the node'),
+  strategy: z.nativeEnum(UnitesStrategyEnum).default(UnitesStrategyEnum.ALL_SUCCESS).describe('Strategy of the unites')
+});
+
+export type UnitesModel = z.infer<typeof UnitesModel>;
+
+// Graph Node Model
+export const GraphNodeModel = z.object({
+  node_name: z.string()
+    .min(1, 'Node name cannot be empty')
+    .transform((val: string) => val.trim())
+    .refine((val: string) => val.length > 0, 'Node name cannot be empty')
+    .describe('Name of the node'),
+  namespace: z.string().describe('Namespace of the node'),
+  identifier: z.string()
+    .min(1, 'Node identifier cannot be empty')
+    .transform((val: string) => val.trim())
+    .refine((val: string) => val.length > 0, 'Node identifier cannot be empty')
+    .refine((val: string) => val !== 'store', 'Node identifier cannot be reserved word \'store\'')
+    .describe('Identifier of the node'),
+  inputs: z.record(z.unknown()).default({}).describe('Inputs of the node'),
+  next_nodes: z.array(z.string())
+    .transform((nodes: string[]) => nodes.map((node: string) => node.trim()))
+    .refine((nodes: string[]) => {
+      const errors: string[] = [];
+      const identifiers = new Set<string>();
+
+      for (const node of nodes) {
+        if (node === '') {
+          errors.push('Next node identifier cannot be empty');
+          continue;
+        }
+        if (identifiers.has(node)) {
+          errors.push(`Next node identifier ${node} is not unique`);
+          continue;
+        }
+        identifiers.add(node);
+      }
+
+      if (errors.length > 0) {
+        throw new Error(errors.join('\n'));
+      }
+      return nodes;
+    })
+    .optional()
+    .describe('Next nodes to execute'),
+  unites: UnitesModel
+    .transform((unites: z.infer<typeof UnitesModel>) => ({
+      identifier: unites.identifier.trim(),
+      strategy: unites.strategy
+    }))
+    .refine((unites: { identifier: string; strategy: UnitesStrategyEnum }) => unites.identifier.length > 0, 'Unites identifier cannot be empty')
+    .optional()
+    .describe('Unites of the node')
+});
+
+export type GraphNodeModel = z.infer<typeof GraphNodeModel>;
+
+// Retry Strategy Enum
+export enum RetryStrategyEnum {
+  EXPONENTIAL = 'EXPONENTIAL',
+  EXPONENTIAL_FULL_JITTER = 'EXPONENTIAL_FULL_JITTER',
+  EXPONENTIAL_EQUAL_JITTER = 'EXPONENTIAL_EQUAL_JITTER',
+  LINEAR = 'LINEAR',
+  LINEAR_FULL_JITTER = 'LINEAR_FULL_JITTER',
+  LINEAR_EQUAL_JITTER = 'LINEAR_EQUAL_JITTER',
+  FIXED = 'FIXED',
+  FIXED_FULL_JITTER = 'FIXED_FULL_JITTER',
+  FIXED_EQUAL_JITTER = 'FIXED_EQUAL_JITTER'
+}
+
+// Retry Policy Model
+export const RetryPolicyModel = z.object({
+  max_retries: z.number().int().min(0).default(3).describe('The maximum number of retries'),
+  strategy: z.nativeEnum(RetryStrategyEnum).default(RetryStrategyEnum.EXPONENTIAL).describe('The method of retry'),
+  backoff_factor: z.number().int().positive().default(2000).describe('The backoff factor in milliseconds (default: 2000 = 2 seconds)'),
+  exponent: z.number().int().positive().default(2).describe('The exponent for the exponential retry strategy'),
+  max_delay: z.number().int().positive().optional().describe('The maximum delay in milliseconds (no default limit when None)')
+});
+
+export type RetryPolicyModel = z.infer<typeof RetryPolicyModel>;
+
+// Store Config Model
+export const StoreConfigModel = z.object({
+  required_keys: z.array(z.string())
+    .transform((keys: string[]) => keys.map((key: string) => key.trim()))
+    .refine((keys: string[]) => {
+      const errors: string[] = [];
+      const keySet = new Set<string>();
+
+      for (const key of keys) {
+        if (key === '') {
+          errors.push('Key cannot be empty or contain only whitespace');
+          continue;
+        }
+        if (key.includes('.')) {
+          errors.push(`Key '${key}' cannot contain '.' character`);
+          continue;
+        }
+        if (keySet.has(key)) {
+          errors.push(`Key '${key}' is duplicated`);
+          continue;
+        }
+        keySet.add(key);
+      }
+
+      if (errors.length > 0) {
+        throw new Error(errors.join('\n'));
+      }
+      return keys;
+    })
+    .default([])
+    .describe('Required keys of the store'),
+  default_values: z.record(z.string())
+    .transform((values: Record<string, string>) => {
+      const errors: string[] = [];
+      const keySet = new Set<string>();
+      const normalizedDict: Record<string, string> = {};
+
+      for (const [key, value] of Object.entries(values)) {
+        const trimmedKey = key.trim();
+
+        if (trimmedKey === '') {
+          errors.push('Key cannot be empty or contain only whitespace');
+          continue;
+        }
+        if (trimmedKey.includes('.')) {
+          errors.push(`Key '${trimmedKey}' cannot contain '.' character`);
+          continue;
+        }
+        if (keySet.has(trimmedKey)) {
+          errors.push(`Key '${trimmedKey}' is duplicated`);
+          continue;
+        }
+
+        keySet.add(trimmedKey);
+        normalizedDict[trimmedKey] = String(value);
+      }
+
+      if (errors.length > 0) {
+        throw new Error(errors.join('\n'));
+      }
+      return normalizedDict;
+    })
+    .default({})
+    .describe('Default values of the store')
+});
+
+export type StoreConfigModel = z.infer<typeof StoreConfigModel>;

typescript-sdk/exospherehost/node/BaseNode.ts

@@ -0,0 +1,36 @@
+import { z, ZodTypeAny, ZodObject } from 'zod';
+
+export abstract class BaseNode<I extends ZodObject<any> = ZodObject<any>, O extends ZodObject<any> = ZodObject<any>, S extends ZodObject<any> = ZodObject<any>> {
+  static Inputs: ZodObject<any> = z.object({});
+  static Outputs: ZodObject<any> = z.object({});
+  static Secrets: ZodObject<any> = z.object({});
+
+  protected inputs!: z.infer<I>;
+  protected secrets!: z.infer<S>;
+
+  constructor() {
+    if (this.constructor === BaseNode) {
+      throw new Error('BaseNode is an abstract class and cannot be instantiated directly');
+    }
+  }
+
+  async _execute(inputsRaw: unknown, secretsRaw: unknown): Promise<z.infer<O> | z.infer<O>[]> {
+    const ctor = this.constructor as typeof BaseNode;
+    const inputs = (ctor.Inputs as I).parse(inputsRaw);
+    const secrets = (ctor.Secrets as S).parse(secretsRaw);
+    this.inputs = inputs;
+    this.secrets = secrets;
+    const result = await this.execute();
+    const outputsSchema = ctor.Outputs as O;
+    if (Array.isArray(result)) {
+      return result.map(r => outputsSchema.parse(r));
+    }
+    if (result === null) {
+      return null as any;
+    }
+    return outputsSchema.parse(result);
+  }
+
+  abstract execute(): Promise<z.infer<O> | z.infer<O>[]>;
+}
+

typescript-sdk/exospherehost/node/index.ts

@@ -0,0 +1 @@
+export { BaseNode } from './BaseNode.js';