computesdk 1.9.4 → 1.9.5

package/dist/index.d.mts

@@ -259,17 +259,89 @@ interface TypedComputeAPI<TProvider extends Provider> extends Omit<ComputeAPI, '
         destroy(sandboxId: string): Promise<void>;
     };
 }
+/**
+ * E2B provider configuration for explicit compute mode
+ */
+interface E2BProviderConfig {
+    /** E2B API key */
+    apiKey?: string;
+    /** E2B project ID */
+    projectId?: string;
+    /** E2B environment/template ID */
+    templateId?: string;
+}
+/**
+ * Modal provider configuration for explicit compute mode
+ */
+interface ModalProviderConfig {
+    /** Modal token ID */
+    tokenId?: string;
+    /** Modal token secret */
+    tokenSecret?: string;
+}
+/**
+ * Railway provider configuration for explicit compute mode
+ */
+interface RailwayProviderConfig {
+    /** Railway API token */
+    apiToken?: string;
+}
+/**
+ * Supported provider names for explicit compute mode
+ */
+type ExplicitProviderName = 'e2b' | 'modal' | 'railway';
+/**
+ * Explicit compute configuration for callable compute()
+ *
+ * Used when calling compute as a function: compute({ provider: 'e2b', ... })
+ * Always uses gateway mode.
+ */
+interface ExplicitComputeConfig {
+    /** Provider name to use */
+    provider: ExplicitProviderName;
+    /** ComputeSDK API key (required for gateway mode) */
+    apiKey: string;
+    /** E2B provider configuration */
+    e2b?: E2BProviderConfig;
+    /** Modal provider configuration */
+    modal?: ModalProviderConfig;
+    /** Railway provider configuration */
+    railway?: RailwayProviderConfig;
+}
+/**
+ * Callable compute type - works as both singleton and factory function
+ */
+type CallableCompute = ComputeAPI & ((config: ExplicitComputeConfig) => ComputeAPI);
 
 /**
  * Compute Singleton - Main API Orchestrator
  *
- * Provides the unified compute.* API and delegates to specialized managers
+ * Provides the unified compute.* API and delegates to specialized managers.
+ * The `compute` export works as both a singleton and a callable function:
+ *
+ * - Singleton: `compute.sandbox.create()` (auto-detects from env vars)
+ * - Callable: `compute({ provider: 'e2b', ... }).sandbox.create()` (explicit config, uses gateway)
  */
 
 /**
- * Singleton instance - the main API (untyped)
+ * Callable compute - works as both singleton and factory function
+ *
+ * @example
+ * ```typescript
+ * import { compute } from 'computesdk';
+ *
+ * // Singleton mode (auto-detects from env vars)
+ * const sandbox1 = await compute.sandbox.create();
+ *
+ * // Callable mode (explicit config, uses gateway)
+ * const sandbox2 = await compute({
+ *   provider: 'e2b',
+ *   apiKey: 'computesdk_xxx',
+ *   e2b: { apiKey: 'e2b_xxx' }
+ * }).sandbox.create();
+ * ```
  */
-declare const compute: ComputeAPI;
+declare const compute: CallableCompute;
 /**
  * Create a compute instance with proper typing
  *
@@ -294,6 +366,21 @@ declare const compute: ComputeAPI;
 declare function createCompute(): ComputeAPI;
 declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider>): TypedComputeAPI<TProvider>;
 
+/**
+ * Explicit Config
+ *
+ * Converts explicit compute configuration to a gateway provider.
+ * Used when compute() is called as a function with configuration.
+ */
+
+/**
+ * Create a gateway provider from explicit configuration
+ *
+ * @param config - Explicit compute configuration
+ * @returns A configured gateway provider
+ */
+declare function createProviderFromConfig(config: ExplicitComputeConfig): Provider;
+
 /**
  * Provider Factory - Creates providers from method definitions
  *
@@ -583,4 +670,4 @@ interface HandleComputeRequestParams {
     provider: Provider;
 }
 
-export { type BaseProviderConfig, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type ExtractProviderSandboxType, GATEWAY_URL, type GatewayConfig, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, PROVIDER_ENV_VARS, PROVIDER_PRIORITY, type Provider, type ProviderConfig, type ProviderMode, type ProviderName, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type SandboxInfo, type SandboxMethods, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, autoConfigureCompute, calculateBackoff, compute, createCompute, createProvider, detectProvider, gateway, getProviderHeaders, handleComputeRequest, isGatewayModeEnabled };
+export { type BaseProviderConfig, type CallableCompute, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type E2BProviderConfig, type ExplicitComputeConfig, type ExplicitProviderName, type ExtractProviderSandboxType, GATEWAY_URL, type GatewayConfig, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, type ModalProviderConfig, PROVIDER_ENV_VARS, PROVIDER_PRIORITY, type Provider, type ProviderConfig, type ProviderMode, type ProviderName, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type RailwayProviderConfig, type SandboxInfo, type SandboxMethods, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, autoConfigureCompute, calculateBackoff, compute, createCompute, createProvider, createProviderFromConfig, detectProvider, gateway, getProviderHeaders, handleComputeRequest, isGatewayModeEnabled };

package/dist/index.d.ts

@@ -259,17 +259,89 @@ interface TypedComputeAPI<TProvider extends Provider> extends Omit<ComputeAPI, '
         destroy(sandboxId: string): Promise<void>;
     };
 }
+/**
+ * E2B provider configuration for explicit compute mode
+ */
+interface E2BProviderConfig {
+    /** E2B API key */
+    apiKey?: string;
+    /** E2B project ID */
+    projectId?: string;
+    /** E2B environment/template ID */
+    templateId?: string;
+}
+/**
+ * Modal provider configuration for explicit compute mode
+ */
+interface ModalProviderConfig {
+    /** Modal token ID */
+    tokenId?: string;
+    /** Modal token secret */
+    tokenSecret?: string;
+}
+/**
+ * Railway provider configuration for explicit compute mode
+ */
+interface RailwayProviderConfig {
+    /** Railway API token */
+    apiToken?: string;
+}
+/**
+ * Supported provider names for explicit compute mode
+ */
+type ExplicitProviderName = 'e2b' | 'modal' | 'railway';
+/**
+ * Explicit compute configuration for callable compute()
+ *
+ * Used when calling compute as a function: compute({ provider: 'e2b', ... })
+ * Always uses gateway mode.
+ */
+interface ExplicitComputeConfig {
+    /** Provider name to use */
+    provider: ExplicitProviderName;
+    /** ComputeSDK API key (required for gateway mode) */
+    apiKey: string;
+    /** E2B provider configuration */
+    e2b?: E2BProviderConfig;
+    /** Modal provider configuration */
+    modal?: ModalProviderConfig;
+    /** Railway provider configuration */
+    railway?: RailwayProviderConfig;
+}
+/**
+ * Callable compute type - works as both singleton and factory function
+ */
+type CallableCompute = ComputeAPI & ((config: ExplicitComputeConfig) => ComputeAPI);
 
 /**
  * Compute Singleton - Main API Orchestrator
  *
- * Provides the unified compute.* API and delegates to specialized managers
+ * Provides the unified compute.* API and delegates to specialized managers.
+ * The `compute` export works as both a singleton and a callable function:
+ *
+ * - Singleton: `compute.sandbox.create()` (auto-detects from env vars)
+ * - Callable: `compute({ provider: 'e2b', ... }).sandbox.create()` (explicit config, uses gateway)
  */
 
 /**
- * Singleton instance - the main API (untyped)
+ * Callable compute - works as both singleton and factory function
+ *
+ * @example
+ * ```typescript
+ * import { compute } from 'computesdk';
+ *
+ * // Singleton mode (auto-detects from env vars)
+ * const sandbox1 = await compute.sandbox.create();
+ *
+ * // Callable mode (explicit config, uses gateway)
+ * const sandbox2 = await compute({
+ *   provider: 'e2b',
+ *   apiKey: 'computesdk_xxx',
+ *   e2b: { apiKey: 'e2b_xxx' }
+ * }).sandbox.create();
+ * ```
  */
-declare const compute: ComputeAPI;
+declare const compute: CallableCompute;
 /**
  * Create a compute instance with proper typing
  *
@@ -294,6 +366,21 @@ declare const compute: ComputeAPI;
 declare function createCompute(): ComputeAPI;
 declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider>): TypedComputeAPI<TProvider>;
 
+/**
+ * Explicit Config
+ *
+ * Converts explicit compute configuration to a gateway provider.
+ * Used when compute() is called as a function with configuration.
+ */
+
+/**
+ * Create a gateway provider from explicit configuration
+ *
+ * @param config - Explicit compute configuration
+ * @returns A configured gateway provider
+ */
+declare function createProviderFromConfig(config: ExplicitComputeConfig): Provider;
+
 /**
  * Provider Factory - Creates providers from method definitions
  *
@@ -583,4 +670,4 @@ interface HandleComputeRequestParams {
     provider: Provider;
 }
 
-export { type BaseProviderConfig, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type ExtractProviderSandboxType, GATEWAY_URL, type GatewayConfig, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, PROVIDER_ENV_VARS, PROVIDER_PRIORITY, type Provider, type ProviderConfig, type ProviderMode, type ProviderName, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type SandboxInfo, type SandboxMethods, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, autoConfigureCompute, calculateBackoff, compute, createCompute, createProvider, detectProvider, gateway, getProviderHeaders, handleComputeRequest, isGatewayModeEnabled };
+export { type BaseProviderConfig, type CallableCompute, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type E2BProviderConfig, type ExplicitComputeConfig, type ExplicitProviderName, type ExtractProviderSandboxType, GATEWAY_URL, type GatewayConfig, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, type ModalProviderConfig, PROVIDER_ENV_VARS, PROVIDER_PRIORITY, type Provider, type ProviderConfig, type ProviderMode, type ProviderName, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type RailwayProviderConfig, type SandboxInfo, type SandboxMethods, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, autoConfigureCompute, calculateBackoff, compute, createCompute, createProvider, createProviderFromConfig, detectProvider, gateway, getProviderHeaders, handleComputeRequest, isGatewayModeEnabled };

package/dist/index.js

@@ -30,6 +30,7 @@ __export(index_exports, {
   compute: () => compute,
   createCompute: () => createCompute,
   createProvider: () => createProvider,
+  createProviderFromConfig: () => createProviderFromConfig,
   detectProvider: () => detectProvider,
   gateway: () => gateway,
   getProviderHeaders: () => getProviderHeaders,
@@ -487,7 +488,7 @@ var gateway = createProvider({
     sandbox: {
       create: async (config, options) => {
         const gatewayUrl = config.gatewayUrl || DEFAULT_GATEWAY_URL;
-        const result = await gatewayFetch(`${gatewayUrl}/sandbox`, config, {
+        const result = await gatewayFetch(`${gatewayUrl}/v1/sandbox`, config, {
           method: "POST",
           body: JSON.stringify(options || {})
         });
@@ -524,7 +525,7 @@ var gateway = createProvider({
       },
       getById: async (config, sandboxId) => {
         const gatewayUrl = config.gatewayUrl || DEFAULT_GATEWAY_URL;
-        const result = await gatewayFetch(`${gatewayUrl}/sandbox/${sandboxId}`, config);
+        const result = await gatewayFetch(`${gatewayUrl}/v1/sandbox/${sandboxId}`, config);
         if (!result.success || !result.data) {
           return null;
         }
@@ -554,7 +555,7 @@ var gateway = createProvider({
       },
       destroy: async (config, sandboxId) => {
         const gatewayUrl = config.gatewayUrl || DEFAULT_GATEWAY_URL;
-        await gatewayFetch(`${gatewayUrl}/sandbox/${sandboxId}`, config, {
+        await gatewayFetch(`${gatewayUrl}/v1/sandbox/${sandboxId}`, config, {
           method: "DELETE"
         });
       },
@@ -772,6 +773,91 @@ Check your COMPUTESDK_GATEWAY_URL environment variable.`
   });
 }
 
+// src/explicit-config.ts
+function buildProviderHeaders(config) {
+  const headers = {};
+  switch (config.provider) {
+    case "e2b":
+      if (config.e2b?.apiKey) {
+        headers["X-E2B-API-Key"] = config.e2b.apiKey;
+      }
+      break;
+    case "modal":
+      if (config.modal?.tokenId) {
+        headers["X-Modal-Token-Id"] = config.modal.tokenId;
+      }
+      if (config.modal?.tokenSecret) {
+        headers["X-Modal-Token-Secret"] = config.modal.tokenSecret;
+      }
+      break;
+    case "railway":
+      if (config.railway?.apiToken) {
+        headers["X-Railway-API-Token"] = config.railway.apiToken;
+      }
+      break;
+    default: {
+      const exhaustiveCheck = config.provider;
+      throw new Error(`Unknown provider: ${exhaustiveCheck}`);
+    }
+  }
+  return headers;
+}
+function validateProviderConfig(config) {
+  const providerName = config.provider;
+  switch (providerName) {
+    case "e2b":
+      if (!config.e2b?.apiKey) {
+        throw new Error(
+          `Missing E2B configuration. When using provider: 'e2b', you must provide:
+  e2b: { apiKey: 'your-e2b-api-key' }
+
+Get your API key at: https://e2b.dev/dashboard`
+        );
+      }
+      break;
+    case "modal":
+      if (!config.modal?.tokenId || !config.modal?.tokenSecret) {
+        throw new Error(
+          `Missing Modal configuration. When using provider: 'modal', you must provide:
+  modal: { tokenId: '...', tokenSecret: '...' }
+
+Get your tokens at: https://modal.com/settings`
+        );
+      }
+      break;
+    case "railway":
+      if (!config.railway?.apiToken) {
+        throw new Error(
+          `Missing Railway configuration. When using provider: 'railway', you must provide:
+  railway: { apiToken: 'your-railway-token' }
+
+Get your token at: https://railway.app/account/tokens`
+        );
+      }
+      break;
+    default: {
+      const exhaustiveCheck = providerName;
+      throw new Error(`Unknown provider: ${exhaustiveCheck}`);
+    }
+  }
+}
+function createProviderFromConfig(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      `Missing ComputeSDK API key. The 'apiKey' field is required.
+
+Get your API key at: https://computesdk.com/dashboard`
+    );
+  }
+  validateProviderConfig(config);
+  const providerHeaders = buildProviderHeaders(config);
+  return gateway({
+    apiKey: config.apiKey,
+    provider: config.provider,
+    providerHeaders
+  });
+}
+
 // src/compute.ts
 var ComputeManager = class {
   constructor() {
@@ -895,7 +981,27 @@ var ComputeManager = class {
     return provider;
   }
 };
-var compute = new ComputeManager();
+var singletonInstance = new ComputeManager();
+function computeFactory(config) {
+  const provider = createProviderFromConfig(config);
+  return createCompute({ provider });
+}
+var compute = new Proxy(
+  computeFactory,
+  {
+    get(_target, prop, _receiver) {
+      const singleton = singletonInstance;
+      const value = singleton[prop];
+      if (typeof value === "function") {
+        return value.bind(singletonInstance);
+      }
+      return value;
+    },
+    apply(_target, _thisArg, args) {
+      return computeFactory(args[0]);
+    }
+  }
+);
 function createCompute(config) {
   const manager = new ComputeManager();
   if (!config) {
@@ -1143,6 +1249,7 @@ async function handleComputeRequest(paramsOrRequestOrBody, provider) {
   compute,
   createCompute,
   createProvider,
+  createProviderFromConfig,
   detectProvider,
   gateway,
   getProviderHeaders,