@sylphx/sdk 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -1,7 +1,101 @@
+// src/connection-url.ts
+var SYLPHX_PROTOCOL = "sylphx:";
+var DEFAULT_VERSION = "v1";
+var CREDENTIAL_REGEX = /^(pk|sk)_(dev|stg|prod|prev)_[a-f0-9]{32,64}$/;
+var VERSION_REGEX = /^v[0-9]+$/;
+var SLUG_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+var InvalidConnectionUrlError = class _InvalidConnectionUrlError extends Error {
+  code = "INVALID_CONNECTION_URL";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidConnectionUrlError";
+    Object.setPrototypeOf(this, _InvalidConnectionUrlError.prototype);
+  }
+};
+function fail(reason) {
+  throw new InvalidConnectionUrlError(`Invalid Sylphx connection URL: ${reason}`);
+}
+function parseCredential(raw) {
+  const match = CREDENTIAL_REGEX.exec(raw);
+  if (!match) {
+    fail(`credential must match (pk|sk)_(dev|stg|prod|prev)_[a-f0-9]{32,64}, got "${raw}"`);
+  }
+  return {
+    credentialType: match[1],
+    env: match[2]
+  };
+}
+function validateSlug(candidate) {
+  if (!candidate || candidate.length > 63 || !SLUG_REGEX.test(candidate)) {
+    fail(`slug "${candidate}" is not a valid DNS label (lowercase alnum + hyphens, 1-63 chars)`);
+  }
+  return candidate;
+}
+function parseConnectionUrl(url) {
+  if (typeof url !== "string" || url.length === 0) {
+    fail("url must be a non-empty string");
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    fail(`not a valid URL: "${url}"`);
+  }
+  if (parsed.protocol !== SYLPHX_PROTOCOL) {
+    fail(`protocol must be "sylphx:", got "${parsed.protocol}"`);
+  }
+  const credential = decodeURIComponent(parsed.username);
+  if (!credential) {
+    fail("missing credential (expected `sylphx://<credential>@<host>`)");
+  }
+  if (parsed.password) {
+    fail("connection URL must not contain a password component");
+  }
+  const { credentialType, env } = parseCredential(credential);
+  const host = parsed.host;
+  if (!host) {
+    fail("missing host");
+  }
+  const hostname = parsed.hostname;
+  const firstDot = hostname.indexOf(".");
+  if (firstDot <= 0) {
+    fail(`host "${hostname}" must contain at least one dot (slug.domain)`);
+  }
+  const slugCandidate = hostname.slice(0, firstDot);
+  const domainSuffix = hostname.slice(firstDot + 1);
+  if (!domainSuffix) {
+    fail(`host "${hostname}" has empty domain suffix`);
+  }
+  const slug = validateSlug(slugCandidate);
+  const rawPath = parsed.pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+  let version = DEFAULT_VERSION;
+  if (rawPath !== "") {
+    if (!VERSION_REGEX.test(rawPath)) {
+      fail(`path "${parsed.pathname}" must be empty or match /v{N}`);
+    }
+    version = rawPath;
+  }
+  if (parsed.search) {
+    fail("connection URL must not contain a query string");
+  }
+  if (parsed.hash) {
+    fail("connection URL must not contain a fragment");
+  }
+  const apiBaseUrl = `https://${host}/${version}`;
+  return {
+    credential,
+    credentialType,
+    env,
+    slug,
+    host,
+    apiBaseUrl
+  };
+}
+
 // src/constants.ts
 var SDK_API_PATH = `/v1`;
 var DEFAULT_SDK_API_HOST = "api.sylphx.com";
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.5.0";
 var SDK_PLATFORM = typeof window !== "undefined" ? "browser" : typeof process !== "undefined" && process.versions?.node ? "node" : "unknown";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var SESSION_TOKEN_LIFETIME_SECONDS = 5 * 60;
@@ -336,195 +430,153 @@ function exponentialBackoff(attempt, baseDelay = BASE_RETRY_DELAY_MS, maxDelay =
   return Math.round(cappedDelay + jitter);
 }
 
-// src/key-validation.ts
-var PUBLIC_KEY_PATTERN = /^pk_(dev|stg|prod)_[a-z0-9]{12}_[a-f0-9]{32}$/;
-var APP_ID_PATTERN = /^app_(dev|stg|prod)_[a-z0-9_-]+$/;
-var SECRET_KEY_PATTERN = /^sk_(dev|stg|prod)_[a-z0-9_-]+$/;
-var ENV_PREFIX_MAP = {
-  dev: "development",
-  stg: "staging",
-  prod: "production"
-};
-function detectKeyIssues(key) {
-  const issues = [];
-  if (key !== key.trim()) issues.push("whitespace");
-  if (key.includes("\n")) issues.push("newline");
-  if (key.includes("\r")) issues.push("carriage-return");
-  if (key.includes(" ")) issues.push("space");
-  if (key !== key.toLowerCase()) issues.push("uppercase-chars");
-  return issues;
-}
-function createSanitizationWarning(keyType, issues, envVarName) {
-  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
-  return `[Sylphx] ${keyTypeName} contains ${issues.join(", ")}. This is commonly caused by Vercel CLI's 'env pull' command.
-
-To fix permanently:
-1. Go to Vercel Dashboard \u2192 Your Project \u2192 Settings \u2192 Environment Variables
-2. Edit ${envVarName}
-3. Remove any trailing whitespace or newline characters
-4. Redeploy your application
-
-The SDK will automatically sanitize the key, but fixing the source is recommended.`;
-}
-function createInvalidKeyError(keyType, key, envVarName) {
-  const prefix = keyType === "appId" ? "app" : "sk";
-  const maskedKey = key.length > 20 ? `${key.slice(0, 20)}...` : key;
-  const formatHint = `${prefix}_(dev|stg|prod)_[identifier]`;
-  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
-  return `[Sylphx] Invalid ${keyTypeName} format.
-
-Expected format: ${formatHint}
-Received: "${maskedKey}"
-
-Please check your ${envVarName} environment variable.
-You can find your keys in the Sylphx Console \u2192 API Keys.
-
-Common issues:
-\u2022 Key has uppercase characters (must be lowercase)
-\u2022 Key has wrong prefix (App ID: app_, Secret Key: sk_)
-\u2022 Key has invalid environment (must be dev, stg, or prod)
-\u2022 Key was copied with extra whitespace`;
-}
-function extractEnvironment(key) {
-  const match = key.match(/^(?:app|sk)_(dev|stg|prod)_/);
-  if (!match) return void 0;
-  return ENV_PREFIX_MAP[match[1]];
-}
-function validateKeyForType(key, keyType, pattern, envVarName) {
-  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
-  if (!key) {
-    return {
-      valid: false,
-      sanitizedKey: "",
-      error: `[Sylphx] ${keyTypeName} is required. Set ${envVarName} in your environment variables.`,
-      issues: ["missing"]
-    };
-  }
-  const issues = detectKeyIssues(key);
-  if (pattern.test(key)) {
-    return {
-      valid: true,
-      sanitizedKey: key,
-      keyType,
-      environment: extractEnvironment(key),
-      issues: []
-    };
-  }
-  const sanitized = key.trim().toLowerCase();
-  if (pattern.test(sanitized)) {
-    return {
-      valid: true,
-      sanitizedKey: sanitized,
-      keyType,
-      environment: extractEnvironment(sanitized),
-      warning: createSanitizationWarning(keyType, issues, envVarName),
-      issues
-    };
-  }
-  return {
-    valid: false,
-    sanitizedKey: "",
-    error: createInvalidKeyError(keyType, key, envVarName),
-    issues: [...issues, "invalid-format"]
-  };
-}
-function validatePublicKey(key) {
-  return validateKeyForType(key, "publicKey", PUBLIC_KEY_PATTERN, "NEXT_PUBLIC_SYLPHX_KEY");
-}
-function validateAppId(key) {
-  return validateKeyForType(key, "appId", APP_ID_PATTERN, "NEXT_PUBLIC_SYLPHX_APP_ID");
-}
-function validateSecretKey(key) {
-  return validateKeyForType(key, "secret", SECRET_KEY_PATTERN, "SYLPHX_SECRET_KEY");
-}
-function validateAndSanitizeSecretKey(key) {
-  const result = validateSecretKey(key);
-  if (!result.valid) {
-    throw new Error(result.error);
-  }
-  if (result.warning) {
-    console.warn(result.warning);
-  }
-  return result.sanitizedKey;
-}
-function detectKeyType(key) {
-  const sanitized = key.trim().toLowerCase();
-  if (sanitized.startsWith("pk_")) return "publicKey";
-  if (sanitized.startsWith("app_")) return "appId";
-  if (sanitized.startsWith("sk_")) return "secret";
-  return null;
-}
-function validateKey(key) {
-  const keyType = key ? detectKeyType(key) : null;
-  if (keyType === "publicKey") {
-    return validatePublicKey(key);
-  }
-  if (keyType === "appId") {
-    return validateAppId(key);
+// src/config.ts
+var LEGACY_EMBEDDED_REF_PATTERN = /^(pk|sk)_(dev|stg|prod|prev)_[a-z0-9]{12}_[a-f0-9]+$/;
+var LEGACY_APP_KEY_PATTERN = /^app_(dev|stg|prod|prev)_/;
+var MIGRATION_MESSAGE = "API key format has changed. Use a sylphx:// connection URL instead.\n\nNew format: sylphx://pk_prod_{hex}@your-slug.sylphx.com\n\nGenerate new credentials from the Sylphx Console \u2192 Your App \u2192 Environments.\nSee https://docs.sylphx.com/migration for details.";
+function rejectLegacyKeyFormat(input) {
+  const trimmed = input.trim().toLowerCase();
+  if (LEGACY_APP_KEY_PATTERN.test(trimmed)) {
+    throw new SylphxError(`[Sylphx] ${MIGRATION_MESSAGE}`, { code: "BAD_REQUEST" });
   }
-  if (keyType === "secret") {
-    return validateSecretKey(key);
+  if (LEGACY_EMBEDDED_REF_PATTERN.test(trimmed)) {
+    throw new SylphxError(`[Sylphx] ${MIGRATION_MESSAGE}`, { code: "BAD_REQUEST" });
   }
-  return {
-    valid: false,
-    sanitizedKey: "",
-    error: key ? `Invalid key format. Keys must start with 'pk_' (publishable), 'app_' (legacy), or 'sk_' (secret), followed by environment (dev/stg/prod). Got: ${key.slice(0, 20)}...` : "API key is required but was not provided.",
-    issues: key ? ["invalid_format"] : ["missing"]
-  };
 }
-
-// src/config.ts
-function parseKey(key) {
-  const sanitized = key.trim().toLowerCase();
-  if (sanitized.startsWith("app_")) {
+function freezeConfig(opts) {
+  return Object.freeze({
+    credential: opts.credential,
+    credentialType: opts.credentialType,
+    env: opts.env,
+    slug: opts.slug,
+    baseUrl: opts.baseUrl,
+    accessToken: opts.accessToken,
+    // Backward-compat aliases
+    secretKey: opts.credentialType === "sk" ? opts.credential : void 0,
+    publicKey: opts.credentialType === "pk" ? opts.credential : void 0,
+    ref: opts.slug
+  });
+}
+function createClient(input) {
+  if (typeof input === "string") {
+    return createConfigFromUrl(input);
+  }
+  return createConfigFromComponents(input);
+}
+function createServerClient(input) {
+  const config = createClient(input);
+  if (config.credentialType !== "sk") {
     throw new SylphxError(
-      "[Sylphx] API key format has changed (ADR-021). Keys now embed the project ref.\n\nOld format: app_prod_xxx\nNew format: pk_prod_{ref}_xxx\n\nPlease regenerate your API keys from the Sylphx Console \u2192 Your App \u2192 Environments.\nOr contact support@sylphx.com for assistance.",
+      "[Sylphx] createServerClient() requires a secret key (sk_*). Use a SYLPHX_SECRET_URL with an sk_ credential, or pass { secretKey } in the components object.",
       { code: "BAD_REQUEST" }
     );
   }
-  const prefix = sanitized.startsWith("pk_") ? "pk" : sanitized.startsWith("sk_") ? "sk" : null;
-  if (!prefix) {
+  return config;
+}
+function createConfigFromUrl(url) {
+  if (!url || typeof url !== "string") {
     throw new SylphxError(
-      `[Sylphx] Invalid key format. Keys must start with 'pk_' (publishable) or 'sk_' (secret). Got: "${sanitized.slice(0, 15)}..."`,
+      "[Sylphx] Connection URL is required. Set SYLPHX_URL or NEXT_PUBLIC_SYLPHX_URL environment variable.\n\nFormat: sylphx://pk_prod_{hex}@your-slug.sylphx.com",
       { code: "BAD_REQUEST" }
     );
   }
-  const parts = sanitized.split("_");
-  if (parts.length !== 4) {
+  const trimmed = url.trim();
+  rejectLegacyKeyFormat(trimmed);
+  if (!trimmed.startsWith("sylphx://")) {
+    if (CREDENTIAL_REGEX.test(trimmed)) {
+      throw new SylphxError(
+        "[Sylphx] Received a bare credential instead of a connection URL.\n\nWrap it in a connection URL: sylphx://<credential>@<slug>.sylphx.com\nOr use createClient({ slug, publicKey }) for explicit components.",
+        { code: "BAD_REQUEST" }
+      );
+    }
     throw new SylphxError(
-      `[Sylphx] Invalid key structure. Expected format: ${prefix}_{env}_{ref}_{token} (4 segments separated by '_'). Got ${parts.length} segment(s).`,
+      `[Sylphx] Invalid connection URL \u2014 must start with "sylphx://". Got: "${trimmed.slice(0, 30)}..."`,
       { code: "BAD_REQUEST" }
     );
   }
-  const [, env, ref, token] = parts;
-  if (env !== "prod" && env !== "dev" && env !== "stg" && env !== "prev") {
-    throw new SylphxError(
-      `[Sylphx] Invalid key environment "${env}". Must be 'prod', 'dev', 'stg', or 'prev'.`,
-      { code: "BAD_REQUEST" }
-    );
+  let parsed;
+  try {
+    parsed = parseConnectionUrl(trimmed);
+  } catch (err) {
+    if (err instanceof InvalidConnectionUrlError) {
+      throw new SylphxError(err.message, { code: "BAD_REQUEST", cause: err });
+    }
+    throw err;
   }
-  if (!/^[a-z0-9]{12}$/.test(ref)) {
-    throw new SylphxError(
-      `[Sylphx] Invalid project ref in key: "${ref}". Must be a 12-character lowercase alphanumeric string.`,
-      { code: "BAD_REQUEST" }
-    );
+  return freezeConfig({
+    credential: parsed.credential,
+    credentialType: parsed.credentialType,
+    env: parsed.env,
+    slug: parsed.slug,
+    baseUrl: parsed.apiBaseUrl
+  });
+}
+function createConfigFromComponents(input) {
+  const credential = input.secretKey || input.publicKey;
+  if (!credential) {
+    throw new SylphxError("[Sylphx] Either publicKey or secretKey must be provided.", {
+      code: "BAD_REQUEST"
+    });
   }
-  const expectedTokenLen = prefix === "pk" ? 32 : 64;
-  if (token.length !== expectedTokenLen || !/^[a-f0-9]+$/.test(token)) {
-    throw new SylphxError(
-      `[Sylphx] Invalid key token. ${prefix === "pk" ? "Publishable" : "Secret"} keys must have a ${expectedTokenLen}-char hex token.`,
-      { code: "BAD_REQUEST" }
-    );
+  const resolvedSlug = input.slug || input.ref;
+  if (!resolvedSlug) {
+    throw new SylphxError("[Sylphx] slug is required when using explicit components.", {
+      code: "BAD_REQUEST"
+    });
   }
-  return {
-    type: prefix,
-    env,
-    ref,
-    token,
-    isPublic: prefix === "pk",
-    baseUrl: `https://${ref}.${DEFAULT_SDK_API_HOST}${SDK_API_PATH}`
-  };
+  const trimmedCred = credential.trim().toLowerCase();
+  if (CREDENTIAL_REGEX.test(trimmedCred)) {
+    const match = CREDENTIAL_REGEX.exec(trimmedCred);
+    const credentialType = match[1];
+    const env = match[2];
+    const slug = resolvedSlug.trim().toLowerCase();
+    const domain = input.domain?.trim() || "sylphx.com";
+    const baseUrl = `https://${slug}.${domain}/v1`;
+    return freezeConfig({
+      credential: trimmedCred,
+      credentialType,
+      env,
+      slug,
+      baseUrl,
+      accessToken: input.accessToken
+    });
+  }
+  const parts = trimmedCred.split("_");
+  const prefix = parts[0];
+  if ((prefix === "pk" || prefix === "sk") && parts.length >= 3) {
+    const envSegment = parts[1];
+    const validEnvs = ["dev", "stg", "prod", "prev"];
+    const env = validEnvs.includes(envSegment) ? envSegment : "prod";
+    const slug = resolvedSlug.trim().toLowerCase();
+    let baseUrl;
+    if (input.platformUrl) {
+      const platform = input.platformUrl.trim().replace(/\/$/, "");
+      baseUrl = platform.includes("/v1") ? platform : `${platform}/v1`;
+    } else {
+      const domain = input.domain?.trim() || "api.sylphx.com";
+      baseUrl = `https://${slug}.${domain}/v1`;
+    }
+    return freezeConfig({
+      credential: trimmedCred,
+      credentialType: prefix,
+      env,
+      slug,
+      baseUrl,
+      accessToken: input.accessToken
+    });
+  }
+  throw new SylphxError(
+    `[Sylphx] Invalid credential format. Expected (pk|sk)_(dev|stg|prod|prev)_[a-f0-9]{32,64}. Got: "${trimmedCred.slice(0, 30)}..."`,
+    { code: "BAD_REQUEST" }
+  );
+}
+function withToken(config, accessToken) {
+  return Object.freeze({
+    ...config,
+    accessToken
+  });
 }
+var createConfig = createClient;
 function httpStatusToErrorCode(status) {
   switch (status) {
     case 400:
@@ -557,79 +609,12 @@ function httpStatusToErrorCode(status) {
       return status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST";
   }
 }
-var REF_PATTERN = /^[a-z0-9]{12}$/;
-function createConfig(input) {
-  const keyForParsing = input.secretKey || input.publicKey;
-  if (!keyForParsing) {
-    if (input.ref) {
-      const trimmedRef = input.ref.trim();
-      if (!REF_PATTERN.test(trimmedRef)) {
-        throw new SylphxError(
-          `[Sylphx] Invalid project ref format: "${input.ref}". Expected a 12-character lowercase alphanumeric string (e.g. "abc123def456"). Get your ref from Platform Console \u2192 Projects \u2192 Your Project \u2192 Overview.`,
-          { code: "BAD_REQUEST" }
-        );
-      }
-      const baseUrl2 = `https://${trimmedRef}.${DEFAULT_SDK_API_HOST}${SDK_API_PATH}`;
-      console.warn(
-        "[Sylphx] Providing only ref without a key is deprecated. Provide secretKey or publicKey \u2014 the ref is now embedded in keys (ADR-021)."
-      );
-      return Object.freeze({ ref: trimmedRef, baseUrl: baseUrl2, accessToken: input.accessToken });
-    }
-    throw new SylphxError(
-      "[Sylphx] Either publicKey or secretKey must be provided to createConfig().",
-      { code: "BAD_REQUEST" }
-    );
-  }
-  const parsed = parseKey(keyForParsing);
-  const ref = parsed.ref;
-  const baseUrl = parsed.baseUrl;
-  let secretKey;
-  if (input.secretKey) {
-    const result = validateKey(input.secretKey);
-    if (!result.valid) {
-      throw new SylphxError(result.error || "Invalid secret key", {
-        code: "BAD_REQUEST",
-        data: { issues: result.issues }
-      });
-    }
-    if (result.warning) console.warn(`[Sylphx] ${result.warning}`);
-    secretKey = result.sanitizedKey;
-  }
-  let publicKey;
-  if (input.publicKey) {
-    const result = validateKey(input.publicKey);
-    if (!result.valid) {
-      throw new SylphxError(result.error || "Invalid public key", {
-        code: "BAD_REQUEST",
-        data: { issues: result.issues }
-      });
-    }
-    if (result.warning) console.warn(`[Sylphx] ${result.warning}`);
-    publicKey = result.sanitizedKey;
-  }
-  return Object.freeze({
-    secretKey,
-    publicKey,
-    ref,
-    baseUrl,
-    accessToken: input.accessToken
-  });
-}
-function withToken(config, accessToken) {
-  return Object.freeze({
-    ...config,
-    accessToken
-    // Preserve baseUrl and ref from original config
-  });
-}
 function buildHeaders(config) {
   const headers = {
     "Content-Type": "application/json"
   };
-  if (config.secretKey) {
-    headers["x-app-secret"] = config.secretKey;
-  } else if (config.publicKey) {
-    headers["x-app-secret"] = config.publicKey;
+  if (config.credential) {
+    headers["x-app-secret"] = config.credential;
   }
   if (config.accessToken) {
     headers.Authorization = `Bearer ${config.accessToken}`;
@@ -648,7 +633,8 @@ async function callApi(config, path, options = {}) {
     query,
     timeout = DEFAULT_TIMEOUT_MS,
     signal,
-    idempotencyKey
+    idempotencyKey,
+    headers: extraHeaders
   } = options;
   let url = buildApiUrl(config, path);
   if (query) {
@@ -670,6 +656,11 @@ async function callApi(config, path, options = {}) {
   if (idempotencyKey) {
     headers["Idempotency-Key"] = idempotencyKey;
   }
+  if (extraHeaders) {
+    for (const [k, v] of Object.entries(extraHeaders)) {
+      headers[k] = v;
+    }
+  }
   const fetchOptions = {
     method,
     headers,
@@ -746,7 +737,6 @@ async function callApi(config, path, options = {}) {
       code: "PARSE_ERROR",
       cause: error instanceof Error ? error : void 0,
       data: { body: text.slice(0, 200) }
-      // Include snippet for debugging
     });
   }
 }
@@ -855,7 +845,112 @@ function installGlobalDebugHelpers() {
 }
 
 // src/rest-client.ts
-import createClient from "openapi-fetch";
+import createClient2 from "openapi-fetch";
+
+// src/key-validation.ts
+var SECRET_KEY_PATTERN = /^sk_(dev|stg|prod)_[a-z0-9_-]+$/;
+var ENV_PREFIX_MAP = {
+  dev: "development",
+  stg: "staging",
+  prod: "production"
+};
+function detectKeyIssues(key) {
+  const issues = [];
+  if (key !== key.trim()) issues.push("whitespace");
+  if (key.includes("\n")) issues.push("newline");
+  if (key.includes("\r")) issues.push("carriage-return");
+  if (key.includes(" ")) issues.push("space");
+  if (key !== key.toLowerCase()) issues.push("uppercase-chars");
+  return issues;
+}
+function createSanitizationWarning(keyType, issues, envVarName) {
+  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
+  return `[Sylphx] ${keyTypeName} contains ${issues.join(", ")}. This is commonly caused by Vercel CLI's 'env pull' command.
+
+To fix permanently:
+1. Go to Vercel Dashboard \u2192 Your Project \u2192 Settings \u2192 Environment Variables
+2. Edit ${envVarName}
+3. Remove any trailing whitespace or newline characters
+4. Redeploy your application
+
+The SDK will automatically sanitize the key, but fixing the source is recommended.`;
+}
+function createInvalidKeyError(keyType, key, envVarName) {
+  const maskedKey = key.length > 20 ? `${key.slice(0, 20)}...` : key;
+  const formatHint = keyType === "appId" ? "pk_(dev|stg|prod)_{ref}_{hex} or app_(dev|stg|prod)_[id]" : "sk_(dev|stg|prod)_{ref}_{hex}";
+  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
+  return `[Sylphx] Invalid ${keyTypeName} format.
+
+Expected format: ${formatHint}
+Received: "${maskedKey}"
+
+Please check your ${envVarName} environment variable.
+You can find your keys in the Sylphx Console \u2192 API Keys.
+
+Common issues:
+\u2022 Key has uppercase characters (must be lowercase)
+\u2022 Key has wrong prefix (App ID: pk_ or app_, Secret Key: sk_)
+\u2022 Key has invalid environment (must be dev, stg, or prod)
+\u2022 Key was copied with extra whitespace`;
+}
+function extractEnvironment(key) {
+  const match = key.match(/^(?:app|pk|sk)_(dev|stg|prod|prev)_/);
+  if (!match) return void 0;
+  return ENV_PREFIX_MAP[match[1]];
+}
+function validateKeyForType(key, keyType, pattern, envVarName) {
+  const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
+  if (!key) {
+    return {
+      valid: false,
+      sanitizedKey: "",
+      error: `[Sylphx] ${keyTypeName} is required. Set ${envVarName} in your environment variables.`,
+      issues: ["missing"]
+    };
+  }
+  const issues = detectKeyIssues(key);
+  if (pattern.test(key)) {
+    return {
+      valid: true,
+      sanitizedKey: key,
+      keyType,
+      environment: extractEnvironment(key),
+      issues: []
+    };
+  }
+  const sanitized = key.trim().toLowerCase();
+  if (pattern.test(sanitized)) {
+    return {
+      valid: true,
+      sanitizedKey: sanitized,
+      keyType,
+      environment: extractEnvironment(sanitized),
+      warning: createSanitizationWarning(keyType, issues, envVarName),
+      issues
+    };
+  }
+  return {
+    valid: false,
+    sanitizedKey: "",
+    error: createInvalidKeyError(keyType, key, envVarName),
+    issues: [...issues, "invalid-format"]
+  };
+}
+function validateSecretKey(key) {
+  return validateKeyForType(key, "secret", SECRET_KEY_PATTERN, "SYLPHX_SECRET_KEY");
+}
+function validateAndSanitizeSecretKey(key) {
+  const result = validateSecretKey(key);
+  if (!result.valid) {
+    throw new Error(result.error);
+  }
+  if (result.warning) {
+    console.warn(result.warning);
+  }
+  return result.sanitizedKey;
+}
+
+// src/rest-client.ts
 function createAuthMiddleware(config) {
   return {
     async onRequest({ request }) {
@@ -1198,7 +1293,7 @@ function validateClientConfig(config) {
 }
 function createRestClient(config) {
   const { secretKey, baseUrl } = validateClientConfig(config);
-  const client = createClient({
+  const client = createClient2({
     baseUrl: `${baseUrl}${SDK_API_PATH}`,
     headers: {
       "Content-Type": "application/json",
@@ -1224,7 +1319,7 @@ function createDynamicRestClient(config) {
     secretKey,
     platformUrl: baseUrl
   };
-  const client = createClient({
+  const client = createClient2({
     baseUrl: `${baseUrl}${SDK_API_PATH}`,
     headers: {
       "Content-Type": "application/json"
@@ -2075,6 +2170,73 @@ async function updatePushPreferences(config, preferences) {
   });
 }
 
+// src/lib/triggers/index.ts
+var TriggersClient = class {
+  /** Create a new trigger (cron or event source, task/run/http target) */
+  static async create(config, options) {
+    return callApi(config, "/triggers", {
+      method: "POST",
+      body: options
+    });
+  }
+  /** List all triggers for the project */
+  static async list(config) {
+    return callApi(config, "/triggers");
+  }
+  /** Get a trigger by ID */
+  static async get(config, triggerId) {
+    return callApi(config, `/triggers/${triggerId}`);
+  }
+  /** Update a trigger */
+  static async update(config, triggerId, options) {
+    return callApi(config, `/triggers/${triggerId}`, {
+      method: "PATCH",
+      body: options
+    });
+  }
+  /** Delete a trigger */
+  static async delete(config, triggerId) {
+    return callApi(config, `/triggers/${triggerId}`, { method: "DELETE" });
+  }
+  /** Pause a trigger */
+  static async pause(config, triggerId) {
+    return callApi(config, `/triggers/${triggerId}/pause`, { method: "POST" });
+  }
+  /** Resume a paused trigger */
+  static async resume(config, triggerId) {
+    return callApi(config, `/triggers/${triggerId}/resume`, { method: "POST" });
+  }
+  /** Fire a trigger immediately (one-shot, regardless of schedule) */
+  static async fire(config, triggerId) {
+    return callApi(config, `/triggers/${triggerId}/fire`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Publish an event — dispatches all active event triggers matching the event name.
+   *
+   * @example
+   * ```typescript
+   * await TriggersClient.publishEvent(config, 'user.signup', { userId: '123', plan: 'pro' })
+   * ```
+   */
+  /**
+   * Publish an event — dispatches all active event triggers matching the event name.
+   * Endpoint: POST /triggers/events
+   *
+   * @example
+   * ```typescript
+   * await TriggersClient.publishEvent(config, 'user.signup', { userId: '123', plan: 'pro' })
+   * ```
+   */
+  static async publishEvent(config, eventName, payload) {
+    return callApi(config, "/triggers/events", {
+      method: "POST",
+      body: { eventName, payload: payload ?? {} }
+    });
+  }
+};
+
 // src/lib/tasks/handler.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var StepCompleteSignal = class {
@@ -2091,6 +2253,14 @@ var StepSleepSignal = class {
   }
   _isStepSleepSignal = true;
 };
+var StepWaitEventSignal = class {
+  constructor(stepName, eventName, options = {}) {
+    this.stepName = stepName;
+    this.eventName = eventName;
+    this.options = options;
+  }
+  _isStepWaitEventSignal = true;
+};
 function createStepContext(completedSteps, resolvedWaits) {
   return {
     /**
@@ -2117,6 +2287,32 @@ function createStepContext(completedSteps, resolvedWaits) {
         return;
       }
       throw new StepSleepSignal(name, duration);
+    },
+    /**
+     * Pause execution until a named event is published via TriggersClient.publishEvent().
+     *
+     * - If event already arrived (platform re-dispatched with result): return event payload.
+     * - If not yet arrived: throw StepWaitEventSignal to pause execution.
+     *
+     * @param name      Step identifier (unique within handler).
+     * @param eventName The event name to listen for (e.g. 'user.approved').
+     * @param options   Optional timeout ('24h', '7d') and payload filter.
+     *
+     * @example Human-in-the-loop approval
+     * ```typescript
+     * const approval = await step.waitForEvent('wait-approval', 'order.approved', {
+     *   timeout: '48h',
+     *   filter: { orderId: payload.orderId },
+     * })
+     * if (!approval) throw new Error('Approval timed out')
+     * await sendConfirmation(approval.approvedBy)
+     * ```
+     */
+    async waitForEvent(name, eventName, options = {}) {
+      if (resolvedWaits.has(name)) {
+        return resolvedWaits.get(name) ?? null;
+      }
+      throw new StepWaitEventSignal(name, eventName, options);
     }
   };
 }
@@ -2196,9 +2392,9 @@ function createTasksHandler(taskDefs, options = {}) {
     for (const step of context?.steps ?? []) {
       completedSteps.set(step.name, step.result);
     }
-    const resolvedWaits = /* @__PURE__ */ new Set();
+    const resolvedWaits = /* @__PURE__ */ new Map();
     for (const wait of context?.waits ?? []) {
-      resolvedWaits.add(wait.name);
+      resolvedWaits.set(wait.name, wait.result ?? void 0);
     }
     const stepCtx = createStepContext(completedSteps, resolvedWaits);
     try {
@@ -2221,6 +2417,16 @@ function createTasksHandler(taskDefs, options = {}) {
           duration: signal.duration
         });
       }
+      if (err instanceof StepWaitEventSignal || err?._isStepWaitEventSignal) {
+        const signal = err;
+        return Response.json({
+          status: "step_wait_event",
+          stepName: signal.stepName,
+          eventName: signal.eventName,
+          timeout: signal.options.timeout ?? null,
+          filter: signal.options.filter ?? null
+        });
+      }
       const message = err instanceof Error ? err.message : String(err);
       console.error(`[sylphx/tasks] Task "${taskName}" threw an error:`, err);
       return Response.json(
@@ -3230,6 +3436,143 @@ var SandboxFiles = class {
     return data.files;
   }
 };
+var SandboxProcesses = class {
+  constructor(endpoint, token) {
+    this.endpoint = endpoint;
+    this.token = token;
+  }
+  authHeader() {
+    return { Authorization: `Bearer ${this.token}` };
+  }
+  /** Spawn a new tracked process. Returns processId + pid immediately. */
+  async start(opts) {
+    const res = await fetch(`${this.endpoint}/process/start`, {
+      method: "POST",
+      headers: { ...this.authHeader(), "Content-Type": "application/json" },
+      body: JSON.stringify(opts)
+    });
+    if (!res.ok) throw new Error(`process.start failed: ${await res.text()}`);
+    return await res.json();
+  }
+  /** List all tracked processes. */
+  async list() {
+    const res = await fetch(`${this.endpoint}/process/list`, {
+      headers: this.authHeader()
+    });
+    if (!res.ok) throw new Error(`process.list failed: ${await res.text()}`);
+    return await res.json();
+  }
+  /** Get full process info including buffered output. */
+  async get(processId) {
+    const res = await fetch(`${this.endpoint}/process/${processId}`, {
+      headers: this.authHeader()
+    });
+    if (!res.ok) throw new Error(`process.get failed: ${await res.text()}`);
+    return await res.json();
+  }
+  /** Send a signal to a process. */
+  async kill(processId, signal = "SIGTERM") {
+    const res = await fetch(`${this.endpoint}/process/${processId}/kill`, {
+      method: "POST",
+      headers: { ...this.authHeader(), "Content-Type": "application/json" },
+      body: JSON.stringify({ signal })
+    });
+    if (!res.ok) throw new Error(`process.kill failed: ${await res.text()}`);
+  }
+  /** Write to process stdin. */
+  async writeStdin(processId, data) {
+    const res = await fetch(`${this.endpoint}/process/${processId}/input`, {
+      method: "POST",
+      headers: { ...this.authHeader(), "Content-Type": "application/json" },
+      body: JSON.stringify({ data })
+    });
+    if (!res.ok) throw new Error(`process.writeStdin failed: ${await res.text()}`);
+  }
+  /**
+   * Wait for a process to complete and return its final info.
+   * Polls every 500ms until status is no longer 'running'.
+   *
+   * For real-time output, use stream() instead.
+   */
+  async wait(processId, timeoutMs = 3e5) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const info = await this.get(processId);
+      if (info.status !== "running") return info;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    throw new Error(`Timed out waiting for process ${processId} to complete (${timeoutMs}ms)`);
+  }
+  /** Stream process output as async iterable SSE events. */
+  async *stream(processId) {
+    const res = await fetch(
+      `${this.endpoint}/process/${processId}/stream`,
+      { headers: this.authHeader() }
+    );
+    if (!res.ok) throw new Error(`process.stream failed: ${await res.text()}`);
+    if (!res.body) throw new Error("process.stream: no response body");
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            try {
+              const event = JSON.parse(line.slice(6));
+              yield event;
+              if (event.type === "exit") return;
+            } catch {
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+var SandboxWatch = class {
+  constructor(endpoint, token) {
+    this.endpoint = endpoint;
+    this.token = token;
+  }
+  authHeader() {
+    return { Authorization: `Bearer ${this.token}` };
+  }
+  /** Start watching a path. Events delivered via sandbox.events() SSE stream. */
+  async add(opts) {
+    const res = await fetch(`${this.endpoint}/watch`, {
+      method: "POST",
+      headers: { ...this.authHeader(), "Content-Type": "application/json" },
+      body: JSON.stringify(opts)
+    });
+    if (!res.ok) throw new Error(`watch.add failed: ${await res.text()}`);
+    return await res.json();
+  }
+  /** List active watches. */
+  async list() {
+    const res = await fetch(`${this.endpoint}/watch`, {
+      headers: this.authHeader()
+    });
+    if (!res.ok) throw new Error(`watch.list failed: ${await res.text()}`);
+    const data = await res.json();
+    return data.watches;
+  }
+  /** Stop watching a path. */
+  async remove(path) {
+    const res = await fetch(`${this.endpoint}/watch?path=${encodeURIComponent(path)}`, {
+      method: "DELETE",
+      headers: this.authHeader()
+    });
+    if (!res.ok) throw new Error(`watch.remove failed: ${await res.text()}`);
+  }
+};
 var SandboxClient = class _SandboxClient {
   id;
   config;
@@ -3239,12 +3582,18 @@ var SandboxClient = class _SandboxClient {
   token;
   /** File operations (direct to exec-server) */
   files;
+  /** Concurrent process management (direct to exec-server) */
+  processes;
+  /** Filesystem watch management (direct to exec-server) */
+  watch;
   constructor(id, config, endpoint, token) {
     this.id = id;
     this.config = config;
     this.endpoint = endpoint;
     this.token = token;
     this.files = endpoint && token ? new SandboxFiles(endpoint, token) : null;
+    this.processes = endpoint && token ? new SandboxProcesses(endpoint, token) : null;
+    this.watch = endpoint && token ? new SandboxWatch(endpoint, token) : null;
   }
   // ---------------------------------------------------------------------------
   // Factory
@@ -3264,7 +3613,8 @@ var SandboxClient = class _SandboxClient {
         idleTimeoutMs: options?.idleTimeoutMs ?? 3e5,
         resources: options?.resources,
         env: options?.env,
-        storage: options?.storageGi !== void 0 ? { enabled: true, sizeGi: options.storageGi } : void 0
+        storage: options?.storageGi !== void 0 ? { enabled: true, sizeGi: options.storageGi } : void 0,
+        volumeMounts: options?.volumeMounts
       }
     });
     return new _SandboxClient(record.id, config, record.endpoint, record.token);
@@ -3292,10 +3642,21 @@ var SandboxClient = class _SandboxClient {
   // Exec — SSE streaming (primary)
   // ---------------------------------------------------------------------------
   /**
-   * Execute a command and stream output as async iterable events.
+   * Execute a command and stream output as async iterable SSE events.
+   *
+   * **Stateless mode**: each exec() call runs in an isolated bash invocation.
+   * Shell state (CWD changes, exported env vars, functions) is NOT preserved
+   * between calls.
    *
-   * Uses Server-Sent Events (SSE) for real-time stdout/stderr streaming.
-   * Communicates DIRECTLY with exec-server (Platform not in data path).
+   * For state-preserving execution (CWD, env), use `run()` which runs in the
+   * persistent active shell and returns the result once complete.
+   *
+   * For streaming + state-preserving (advanced), combine `sandbox.events()` with `run()`:
+   * ```typescript
+   * const eventStream = sandbox.events({ type: 'stdout' })
+   * sandbox.run(['npm', 'install']) // don't await yet
+   * for await (const ev of eventStream) { ... }
+   * ```
    *
    * @example
    * ```typescript
@@ -3307,13 +3668,13 @@ var SandboxClient = class _SandboxClient {
    */
   async *exec(command, options) {
     this.assertDirect();
-    const res = await fetch(`${this.endpoint}/exec/stream`, {
+    const res = await fetch(`${this.endpoint}/exec`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${this.token}`,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ command, ...options })
+      body: JSON.stringify({ command, ...options, stateless: true, stream: true })
     });
     if (!res.ok) {
       throw new Error(`exec failed (${res.status}): ${await res.text()}`);
@@ -3366,6 +3727,58 @@ var SandboxClient = class _SandboxClient {
     return { stdout, stderr, exitCode, durationMs };
   }
   // ---------------------------------------------------------------------------
+  // Events — Unified SSE stream
+  // ---------------------------------------------------------------------------
+  /**
+   * Subscribe to the unified event stream (SSE).
+   *
+   * Receives all sandbox events: stdout, stderr, exit, port, file, shell, resource.
+   * Filter by type/pid/shellId using query params.
+   *
+   * @example
+   * ```typescript
+   * for await (const event of sandbox.events({ type: 'file' })) {
+   *   console.log('File changed:', event.path, event.event)
+   * }
+   * ```
+   */
+  async *events(filter) {
+    this.assertDirect();
+    const params = new URLSearchParams();
+    if (filter?.type) params.set("type", filter.type);
+    if (filter?.pid !== void 0) params.set("pid", String(filter.pid));
+    if (filter?.shellId) params.set("shellId", filter.shellId);
+    const qs = params.toString();
+    const url = `${this.endpoint}/events${qs ? `?${qs}` : ""}`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.token}` }
+    });
+    if (!res.ok) throw new Error(`events failed (${res.status}): ${await res.text()}`);
+    if (!res.body) throw new Error("events: no response body");
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            try {
+              yield JSON.parse(line.slice(6));
+            } catch {
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  // ---------------------------------------------------------------------------
   // PTY — Interactive terminal (WebSocket)
   // ---------------------------------------------------------------------------
   /**
@@ -3411,7 +3824,7 @@ var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 ]);
 var DEFAULT_POLL_INTERVAL_MS = 3e3;
 var DEFAULT_WAIT_TIMEOUT_MS = 72e5;
-var WorkerHandle = class {
+var RunHandle = class {
   id;
   config;
   constructor(id, config) {
@@ -3435,7 +3848,7 @@ var WorkerHandle = class {
    *
    * @param options.pollIntervalMs - How often to poll in ms (default: 3000)
    * @param options.timeoutMs - Max time to wait before throwing (default: 7_200_000 = 2h)
-   * @returns WorkerResult with exit code, status, stdout/stderr
+   * @returns RunResult with exit code, status, stdout/stderr
    * @throws Error if waitTimeout is exceeded
    *
    * @example
@@ -3503,7 +3916,7 @@ var WorkerHandle = class {
     await callApi(this.config, `/workers/${this.id}`, { method: "DELETE" });
   }
 };
-var WorkersClient = {
+var RunsClient = {
   // --------------------------------------------------------------------------
   // Run
   // --------------------------------------------------------------------------
@@ -3515,7 +3928,7 @@ var WorkersClient = {
    *
    * @example
    * ```typescript
-   * const worker = await WorkersClient.run(config, {
+   * const run = await RunsClient.create(config, {
    *   image: 'registry.sylphx.com/sylphx/trainer:abc123',
    *   command: ['python', 'train.py', '--fold', '3'],
    *   resources: { requests: { cpu: '4', memory: '16Gi' } },
@@ -3525,7 +3938,7 @@ var WorkersClient = {
    * ```
    */
   async run(config, options) {
-    const run = await callApi(config, "/workers", {
+    const run = await callApi(config, "/runs", {
       method: "POST",
       body: {
         image: options.image,
@@ -3536,25 +3949,25 @@ var WorkersClient = {
         volumeMounts: options.volumeMounts
       }
     });
-    return new WorkerHandle(run.id, config);
+    return new RunHandle(run.id, config);
   },
   // --------------------------------------------------------------------------
   // Get
   // --------------------------------------------------------------------------
   /**
-   * Get a WorkerHandle for an existing run by ID.
+   * Get a RunHandle for an existing run by ID.
    *
    * Useful for resuming monitoring across requests.
    *
    * @example
    * ```typescript
    * // Store the worker ID, retrieve later
-   * const handle = WorkersClient.fromId(config, storedWorkerId)
+   * const handle = RunsClient.fromId(config, storedWorkerId)
    * const result = await handle.wait()
    * ```
    */
   fromId(config, workerId) {
-    return new WorkerHandle(workerId, config);
+    return new RunHandle(workerId, config);
   },
   // --------------------------------------------------------------------------
   // List
@@ -3564,12 +3977,12 @@ var WorkersClient = {
    *
    * @example
    * ```typescript
-   * const { workers } = await WorkersClient.list(config, { status: 'running' })
+   * const { workers } = await RunsClient.list(config, { status: 'running' })
    * console.log(`${workers.length} workers currently running`)
    * ```
    */
   async list(config, options) {
-    return callApi(config, "/workers", {
+    return callApi(config, "/runs", {
       method: "GET",
       query: options?.status ? { status: options.status } : void 0
     });
@@ -3580,11 +3993,11 @@ var WorkersClient = {
   /**
    * Spawn a worker and wait for it to complete in one call.
    *
-   * Equivalent to `(await WorkersClient.run(config, options)).wait(waitOptions)`.
+   * Equivalent to `(await RunsClient.create(config, options)).wait(waitOptions)`.
    *
    * @example
    * ```typescript
-   * const result = await WorkersClient.runAndWait(config, {
+   * const result = await RunsClient.runAndWait(config, {
    *   image: 'registry.sylphx.com/sylphx/process:abc',
    *   command: ['node', 'dist/process.js'],
    * })
@@ -3592,30 +4005,38 @@ var WorkersClient = {
    * ```
    */
   async runAndWait(config, options, waitOptions) {
-    const handle = await WorkersClient.run(config, options);
+    const handle = await RunsClient.run(config, options);
     return handle.wait(waitOptions);
   }
 };
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var WorkersClient = RunsClient;
 export {
   ACHIEVEMENT_TIER_CONFIG,
   AuthenticationError,
   AuthorizationError,
   CircuitBreakerOpenError,
   ERROR_CODE_STATUS,
+  InvalidConnectionUrlError,
   NetworkError,
   NotFoundError,
   RETRYABLE_CODES,
   RateLimitError,
+  RunHandle,
+  RunsClient,
   SandboxClient,
+  SandboxFiles,
+  SandboxProcesses,
+  SandboxWatch,
   StepCompleteSignal,
   StepSleepSignal,
   SylphxError,
   TimeoutError,
+  TriggersClient,
   ValidationError,
-  WorkerHandle,
+  RunHandle as WorkerHandle,
   WorkersClient,
   acceptAllConsents,
   acceptOrganizationInvitation,
@@ -3634,6 +4055,7 @@ export {
   checkFlag,
   complete,
   createCheckout,
+  createClient,
   createConfig,
   createCron,
   createDynamicRestClient,
@@ -3642,6 +4064,7 @@ export {
   createPortalSession,
   createRestClient,
   createRole,
+  createServerClient,
   createServiceWorkerScript,
   createStepContext,
   createTasksHandler,
@@ -3771,7 +4194,6 @@ export {
   listTasks,
   listUsers,
   page,
-  parseKey,
   pauseCron,
   realtimeEmit,
   recordStreakActivity,