@sylphx/sdk 0.0.1 → 0.2.1

package/dist/index.js

@@ -39,6 +39,7 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   RETRYABLE_CODES: () => RETRYABLE_CODES,
   RateLimitError: () => RateLimitError,
+  SandboxClient: () => SandboxClient,
   SylphxError: () => SylphxError,
   TimeoutError: () => TimeoutError,
   ValidationError: () => ValidationError,
@@ -232,7 +233,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/constants.ts
 var DEFAULT_PLATFORM_URL = "https://sylphx.com";
-var SDK_API_PATH = `/api/app/v1`;
+var SDK_API_PATH = `/api/v1`;
 var SDK_API_PATH_NEW = `/v1`;
 var DEFAULT_SDK_API_HOST = "api.sylphx.com";
 var SDK_VERSION = "0.1.0";
@@ -683,6 +684,7 @@ function httpStatusToErrorCode(status) {
       return status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST";
   }
 }
+var REF_PATTERN = /^[a-z0-9]{16}$/;
 function createConfig(input) {
   let secretKey;
   if (input.secretKey) {
@@ -698,13 +700,22 @@ function createConfig(input) {
     }
     secretKey = result.sanitizedKey;
   }
+  if (input.ref !== void 0) {
+    const trimmedRef = input.ref.trim();
+    if (!REF_PATTERN.test(trimmedRef)) {
+      throw new SylphxError(
+        `[Sylphx] Invalid project ref format: "${input.ref}". Expected a 16-character lowercase alphanumeric string (e.g. "abc123def456ghij"). Get your ref from Platform Console \u2192 Projects \u2192 Your Project \u2192 Overview.`,
+        { code: "BAD_REQUEST" }
+      );
+    }
+  }
   let platformUrl;
   let apiBasePath;
   if (input.platformUrl) {
     platformUrl = input.platformUrl.trim();
     apiBasePath = SDK_API_PATH;
   } else if (input.ref) {
-    platformUrl = `https://${input.ref}.${DEFAULT_SDK_API_HOST}`;
+    platformUrl = `https://${input.ref.trim()}.${DEFAULT_SDK_API_HOST}`;
     apiBasePath = SDK_API_PATH_NEW;
   } else {
     platformUrl = DEFAULT_PLATFORM_URL;
@@ -1008,6 +1019,7 @@ function createDeduplicationMiddleware(config = {}) {
         deduped._dedupKey = key;
         return deduped;
       }
+      ;
       request._dedupKey = key;
       return request;
     },
@@ -1031,30 +1043,24 @@ function createDeduplicationMiddleware(config = {}) {
 var CircuitBreakerOpenError = class extends Error {
   remainingMs;
   constructor(remainingMs) {
-    super(
-      `Circuit breaker is open. Retry after ${Math.ceil(remainingMs / 1e3)}s`
-    );
+    super(`Circuit breaker is open. Retry after ${Math.ceil(remainingMs / 1e3)}s`);
     this.name = "CircuitBreakerOpenError";
     this.remainingMs = remainingMs;
   }
 };
-var circuitBreaker = null;
-function getCircuitBreaker(config = {}) {
-  if (!circuitBreaker) {
-    circuitBreaker = {
-      state: "CLOSED",
-      failures: [],
-      openedAt: null,
-      config: {
-        enabled: config.enabled ?? true,
-        failureThreshold: config.failureThreshold ?? CIRCUIT_BREAKER_FAILURE_THRESHOLD,
-        windowMs: config.windowMs ?? CIRCUIT_BREAKER_WINDOW_MS,
-        openDurationMs: config.openDurationMs ?? CIRCUIT_BREAKER_OPEN_DURATION_MS,
-        isFailure: config.isFailure ?? ((status) => status >= 500 || status === 429)
-      }
-    };
-  }
-  return circuitBreaker;
+function createCircuitBreakerInstance(config = {}) {
+  return {
+    state: "CLOSED",
+    failures: [],
+    openedAt: null,
+    config: {
+      enabled: config.enabled ?? true,
+      failureThreshold: config.failureThreshold ?? CIRCUIT_BREAKER_FAILURE_THRESHOLD,
+      windowMs: config.windowMs ?? CIRCUIT_BREAKER_WINDOW_MS,
+      openDurationMs: config.openDurationMs ?? CIRCUIT_BREAKER_OPEN_DURATION_MS,
+      isFailure: config.isFailure ?? ((status) => status >= 500 || status === 429)
+    }
+  };
 }
 function recordFailure(cb) {
   const now = Date.now();
@@ -1102,7 +1108,8 @@ function createCircuitBreakerMiddleware(config) {
       }
     };
   }
-  const cb = getCircuitBreaker(config ?? {});
+  const cb = createCircuitBreakerInstance(config ?? {});
+  _lastCircuitBreaker = cb;
   return {
     async onRequest({ request }) {
       if (!cb.config.enabled) {
@@ -1127,15 +1134,21 @@ function createCircuitBreakerMiddleware(config) {
     }
   };
 }
+var _lastCircuitBreaker = null;
 function resetCircuitBreaker() {
-  circuitBreaker = null;
+  if (_lastCircuitBreaker) {
+    _lastCircuitBreaker.state = "CLOSED";
+    _lastCircuitBreaker.failures = [];
+    _lastCircuitBreaker.openedAt = null;
+  }
+  _lastCircuitBreaker = null;
 }
 function getCircuitBreakerState() {
-  if (!circuitBreaker) return null;
+  if (!_lastCircuitBreaker) return null;
   return {
-    state: circuitBreaker.state,
-    failures: circuitBreaker.failures.length,
-    openedAt: circuitBreaker.openedAt
+    state: _lastCircuitBreaker.state,
+    failures: _lastCircuitBreaker.failures.length,
+    openedAt: _lastCircuitBreaker.openedAt
   };
 }
 var etagCache = /* @__PURE__ */ new Map();
@@ -1227,6 +1240,7 @@ function createETagMiddleware(config) {
     }
   };
 }
+var retryBodyMap = /* @__PURE__ */ new WeakMap();
 function createRetryMiddleware(retryConfig) {
   if (retryConfig === false) {
     return {
@@ -1242,27 +1256,22 @@ function createRetryMiddleware(retryConfig) {
     shouldRetry = isRetryableStatus,
     timeout = DEFAULT_TIMEOUT_MS
   } = retryConfig ?? {};
-  let originalBody = null;
   return {
     async onRequest({ request }) {
-      if (request.body) {
-        originalBody = await request.clone().text();
-      } else {
-        originalBody = null;
-      }
-      if (!request.signal) {
-        const controller = new AbortController();
-        setTimeout(() => controller.abort(), timeout);
-        return new Request(request.url, {
-          method: request.method,
-          headers: request.headers,
-          body: originalBody,
-          signal: controller.signal
-        });
-      }
-      return request;
+      const body = request.body ? await request.clone().text() : null;
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(), timeout);
+      const newRequest = new Request(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body,
+        signal: controller.signal
+      });
+      retryBodyMap.set(newRequest, body);
+      return newRequest;
     },
     async onResponse({ response, request }) {
+      const originalBody = retryBodyMap.get(request) ?? null;
       let attempt = 0;
       let currentResponse = response;
       while (attempt < maxRetries && shouldRetry(currentResponse.status, attempt)) {
@@ -1282,16 +1291,19 @@ function createRetryMiddleware(retryConfig) {
           const newResponse = await fetch(retryRequest);
           clearTimeout(timeoutId);
           if (newResponse.ok || !shouldRetry(newResponse.status, attempt)) {
+            retryBodyMap.delete(request);
             return newResponse;
           }
           currentResponse = newResponse;
         } catch (error) {
           clearTimeout(timeoutId);
           if (attempt >= maxRetries) {
+            retryBodyMap.delete(request);
             throw error;
           }
         }
       }
+      retryBodyMap.delete(request);
       return currentResponse;
     }
   };
@@ -1380,35 +1392,20 @@ async function signOut(config) {
   await callApi(config, "/auth/logout", { method: "POST" });
 }
 async function refreshToken(config, token) {
-  const response = await fetch(`${config.platformUrl}/api/v1/auth/token`, {
+  return callApi(config, "/auth/token", {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
+    body: {
       grant_type: "refresh_token",
       refresh_token: token,
       client_secret: config.secretKey
-    })
+    }
   });
-  if (!response.ok) {
-    const error = await response.json().catch(() => ({ message: "Token refresh failed" }));
-    throw new SylphxError(error.message ?? "Token refresh failed", {
-      code: "UNAUTHORIZED"
-    });
-  }
-  return response.json();
 }
 async function verifyEmail(config, token) {
-  const response = await fetch(`${config.platformUrl}/api/v1/auth/verify-email`, {
+  await callApi(config, "/auth/verify-email", {
     method: "POST",
-    headers: buildHeaders(config),
-    body: JSON.stringify({ token })
+    body: { token }
   });
-  if (!response.ok) {
-    const error = await response.json().catch(() => ({ message: "Email verification failed" }));
-    throw new SylphxError(error.message ?? "Email verification failed", {
-      code: "BAD_REQUEST"
-    });
-  }
 }
 async function forgotPassword(config, email) {
   await callApi(config, "/auth/forgot-password", {
@@ -3088,6 +3085,172 @@ async function captureMessage(config, message, options = {}) {
     body: request
   });
 }
+
+// src/sandbox.ts
+var DEFAULT_IMAGE = "registry.sylphx.com/library/exec-server:latest";
+var SandboxClient = class _SandboxClient {
+  id;
+  config;
+  constructor(id, config) {
+    this.id = id;
+    this.config = config;
+  }
+  // ---------------------------------------------------------------------------
+  // Factory
+  // ---------------------------------------------------------------------------
+  /**
+   * Create a new sandbox.
+   *
+   * The sandbox pod starts asynchronously — it will be in `starting` status
+   * after creation. File/run operations will block until the pod is ready.
+   *
+   * @param config - Sylphx config with a secret key (sk_*) and project ref
+   * @param options - Sandbox creation options
+   */
+  static async create(config, options) {
+    const record = await callApi(config, `/sandboxes`, {
+      method: "POST",
+      body: {
+        image: options?.image ?? DEFAULT_IMAGE,
+        idleTimeoutMs: options?.idleTimeoutMs ?? 3e5,
+        resources: options?.resources,
+        env: options?.env,
+        storage: options?.storageGi !== void 0 ? { enabled: true, sizeGi: options.storageGi } : void 0
+      }
+    });
+    return new _SandboxClient(record.id, config);
+  }
+  /**
+   * Reconnect to an existing sandbox by ID.
+   *
+   * Use this to resume operations on a sandbox created in a previous request.
+   */
+  static fromId(config, sandboxId) {
+    return new _SandboxClient(sandboxId, config);
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the current status of this sandbox.
+   */
+  async getStatus() {
+    return callApi(
+      this.config,
+      `/sandboxes/${this.id}`,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Terminate the sandbox immediately.
+   *
+   * Deletes the K8s Pod and Service. PVC (storage) is preserved for reuse.
+   * This operation is idempotent — safe to call multiple times.
+   */
+  async terminate() {
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}`,
+      { method: "DELETE" }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // File Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Write a file to the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox (e.g. '/workspace/file.py')
+   * @param content - File content as string or Buffer
+   * @param encoding - 'utf8' (default) or 'base64' for binary files
+   */
+  async writeFile(path, content, encoding = "utf8") {
+    const contentStr = Buffer.isBuffer(content) ? content.toString("base64") : content;
+    const effectiveEncoding = Buffer.isBuffer(content) ? "base64" : encoding;
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "POST",
+        body: { path, content: contentStr, encoding: effectiveEncoding }
+      }
+    );
+  }
+  /**
+   * Read a file from the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox
+   * @returns File content as a string
+   */
+  async readFile(path) {
+    const result = await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "GET",
+        query: { path }
+      }
+    );
+    return result.content;
+  }
+  /**
+   * Delete a file from the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox
+   */
+  async deleteFile(path) {
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "DELETE",
+        query: { path }
+      }
+    );
+  }
+  /**
+   * List files in a directory.
+   *
+   * @param path - Directory path inside the sandbox (default: '/')
+   * @returns Array of file/directory paths
+   */
+  async listFiles(path = "/") {
+    const result = await callApi(
+      this.config,
+      `/sandboxes/${this.id}/list`,
+      {
+        method: "GET",
+        query: { path }
+      }
+    );
+    return result.files;
+  }
+  // ---------------------------------------------------------------------------
+  // Command Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Run a command inside the sandbox.
+   *
+   * The command runs synchronously inside the exec pod and returns when complete.
+   *
+   * @param command - Full command + args as array (e.g. ['python3', 'script.py'])
+   * @param options - Optional cwd, env, timeout, stdin
+   * @returns { stdout, stderr, exitCode, durationMs }
+   *
+   * @example
+   * ```typescript
+   * const { stdout, exitCode } = await sandbox.run(['python3', '-c', 'print(1+1)'])
+   * console.log(stdout) // "2\n"
+   * console.log(exitCode) // 0
+   * ```
+   */
+  async run(command, options) {
+    return callApi(this.config, `/sandboxes/${this.id}/run`, {
+      method: "POST",
+      body: { command, ...options }
+    });
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACHIEVEMENT_TIER_CONFIG,
@@ -3099,6 +3262,7 @@ async function captureMessage(config, message, options = {}) {
   NotFoundError,
   RETRYABLE_CODES,
   RateLimitError,
+  SandboxClient,
   SylphxError,
   TimeoutError,
   ValidationError,