@sylphx/sdk 0.3.7 → 0.5.0

package/dist/index.js

@@ -35,20 +35,28 @@ __export(index_exports, {
   AuthorizationError: () => AuthorizationError,
   CircuitBreakerOpenError: () => CircuitBreakerOpenError,
   ERROR_CODE_STATUS: () => ERROR_CODE_STATUS,
+  InvalidConnectionUrlError: () => InvalidConnectionUrlError,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
   RETRYABLE_CODES: () => RETRYABLE_CODES,
   RateLimitError: () => RateLimitError,
+  RunHandle: () => RunHandle,
+  RunsClient: () => RunsClient,
   SandboxClient: () => SandboxClient,
+  SandboxFiles: () => SandboxFiles,
+  SandboxProcesses: () => SandboxProcesses,
+  SandboxWatch: () => SandboxWatch,
   StepCompleteSignal: () => StepCompleteSignal,
   StepSleepSignal: () => StepSleepSignal,
   SylphxError: () => SylphxError,
   TimeoutError: () => TimeoutError,
+  TriggersClient: () => TriggersClient,
   ValidationError: () => ValidationError,
-  WorkerHandle: () => WorkerHandle,
+  WorkerHandle: () => RunHandle,
   WorkersClient: () => WorkersClient,
   acceptAllConsents: () => acceptAllConsents,
   acceptOrganizationInvitation: () => acceptOrganizationInvitation,
+  assignMemberRole: () => assignMemberRole,
   batchIndex: () => batchIndex,
   canDeleteOrganization: () => canDeleteOrganization,
   canManageMembers: () => canManageMembers,
@@ -63,12 +71,16 @@ __export(index_exports, {
   checkFlag: () => checkFlag,
   complete: () => complete,
   createCheckout: () => createCheckout,
+  createClient: () => createClient,
   createConfig: () => createConfig,
   createCron: () => createCron,
   createDynamicRestClient: () => createDynamicRestClient,
   createOrganization: () => createOrganization,
+  createPermission: () => createPermission,
   createPortalSession: () => createPortalSession,
   createRestClient: () => createRestClient,
+  createRole: () => createRole,
+  createServerClient: () => createServerClient,
   createServiceWorkerScript: () => createServiceWorkerScript,
   createStepContext: () => createStepContext,
   createTasksHandler: () => createTasksHandler,
@@ -83,6 +95,8 @@ __export(index_exports, {
   deleteEnvVar: () => deleteEnvVar,
   deleteFile: () => deleteFile,
   deleteOrganization: () => deleteOrganization,
+  deletePermission: () => deletePermission,
+  deleteRole: () => deleteRole,
   deleteUser: () => deleteUser,
   disableDebug: () => disableDebug,
   embed: () => embed,
@@ -116,6 +130,7 @@ __export(index_exports, {
   getFlagPayload: () => getFlagPayload,
   getFlags: () => getFlags,
   getLeaderboard: () => getLeaderboard,
+  getMemberPermissions: () => getMemberPermissions,
   getMyReferralCode: () => getMyReferralCode,
   getOrganization: () => getOrganization,
   getOrganizationInvitations: () => getOrganizationInvitations,
@@ -127,6 +142,7 @@ __export(index_exports, {
   getReferralLeaderboard: () => getReferralLeaderboard,
   getReferralStats: () => getReferralStats,
   getRestErrorMessage: () => getRestErrorMessage,
+  getRole: () => getRole,
   getScheduledEmail: () => getScheduledEmail,
   getScheduledEmailStats: () => getScheduledEmailStats,
   getSearchStats: () => getSearchStats,
@@ -146,8 +162,11 @@ __export(index_exports, {
   getWebhookDeliveries: () => getWebhookDeliveries,
   getWebhookDelivery: () => getWebhookDelivery,
   getWebhookStats: () => getWebhookStats,
+  hasAllPermissions: () => hasAllPermissions,
+  hasAnyPermission: () => hasAnyPermission,
   hasConsent: () => hasConsent,
   hasError: () => hasError,
+  hasPermission: () => hasPermission,
   hasRole: () => hasRole,
   hasSecret: () => hasSecret,
   identify: () => identify,
@@ -184,12 +203,13 @@ __export(index_exports, {
   leaveOrganization: () => leaveOrganization,
   linkAnonymousConsents: () => linkAnonymousConsents,
   listEnvVars: () => listEnvVars,
+  listPermissions: () => listPermissions,
+  listRoles: () => listRoles,
   listScheduledEmails: () => listScheduledEmails,
   listSecretKeys: () => listSecretKeys,
   listTasks: () => listTasks,
   listUsers: () => listUsers,
   page: () => page,
-  parseKey: () => parseKey,
   pauseCron: () => pauseCron,
   realtimeEmit: () => realtimeEmit,
   recordStreakActivity: () => recordStreakActivity,
@@ -236,6 +256,7 @@ __export(index_exports, {
   updateOrganization: () => updateOrganization,
   updateOrganizationMemberRole: () => updateOrganizationMemberRole,
   updatePushPreferences: () => updatePushPreferences,
+  updateRole: () => updateRole,
   updateUser: () => updateUser,
   updateUserMetadata: () => updateUserMetadata,
   updateWebhookConfig: () => updateWebhookConfig,
@@ -249,10 +270,104 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// 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;
@@ -354,6 +469,13 @@ var SylphxError = class _SylphxError extends Error {
   static isRateLimited(err) {
     return err instanceof _SylphxError && err.code === "TOO_MANY_REQUESTS";
   }
+  /**
+   * Check if error is an account lockout error (too many failed login attempts).
+   * When true, `error.data?.lockoutUntil` contains the ISO 8601 timestamp when the lockout expires.
+   */
+  static isAccountLocked(err) {
+    return err instanceof _SylphxError && err.code === "TOO_MANY_REQUESTS" && err.data?.code === "ACCOUNT_LOCKED";
+  }
   /**
    * Check if error is a quota exceeded error (plan limit reached)
    */
@@ -580,195 +702,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:
@@ -801,79 +881,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}`;
@@ -892,7 +905,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) {
@@ -914,6 +928,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,
@@ -990,7 +1009,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
     });
   }
 }
@@ -1100,6 +1118,111 @@ function installGlobalDebugHelpers() {
 
 // src/rest-client.ts
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
+
+// 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 }) {
@@ -2319,6 +2442,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
 var import_node_crypto = require("crypto");
 var StepCompleteSignal = class {
@@ -2335,6 +2525,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 {
     /**
@@ -2361,6 +2559,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);
     }
   };
 }
@@ -2440,9 +2664,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 {
@@ -2465,6 +2689,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(
@@ -2936,6 +3170,86 @@ function canDeleteOrganization(membership) {
   return hasRole(membership, "super_admin");
 }
 
+// src/permissions.ts
+async function listPermissions(config) {
+  return callApi(config, "/permissions");
+}
+async function createPermission(config, input) {
+  return callApi(config, "/permissions", {
+    method: "POST",
+    body: input
+  });
+}
+async function deletePermission(config, permissionKey) {
+  return callApi(config, `/permissions/${permissionKey}`, {
+    method: "DELETE"
+  });
+}
+async function getMemberPermissions(config, orgIdOrSlug, memberId) {
+  return callApi(
+    config,
+    `/orgs/${orgIdOrSlug}/members/${memberId}/permissions`
+  );
+}
+function hasPermission(permissions, required) {
+  return permissions.includes(required);
+}
+function hasAnyPermission(permissions, required) {
+  return required.some((perm) => permissions.includes(perm));
+}
+function hasAllPermissions(permissions, required) {
+  return required.every((perm) => permissions.includes(perm));
+}
+
+// src/roles.ts
+async function listRoles(config) {
+  return callApi(config, "/roles");
+}
+async function getRole(config, roleKey) {
+  return callApi(config, `/roles/${roleKey}`);
+}
+async function createRole(config, input) {
+  const body = {
+    key: input.key,
+    name: input.name
+  };
+  if (input.description !== void 0) body.description = input.description;
+  if (input.permissions !== void 0) body.permissionKeys = input.permissions;
+  if (input.isDefault !== void 0) body.isDefault = input.isDefault;
+  if (input.sortOrder !== void 0) body.sortOrder = input.sortOrder;
+  return callApi(config, "/roles", {
+    method: "POST",
+    body
+  });
+}
+async function updateRole(config, roleKey, input) {
+  const body = {};
+  if (input.name !== void 0) body.name = input.name;
+  if (input.description !== void 0) body.description = input.description;
+  if (input.permissions !== void 0) body.permissionKeys = input.permissions;
+  if (input.isDefault !== void 0) body.isDefault = input.isDefault;
+  if (input.sortOrder !== void 0) body.sortOrder = input.sortOrder;
+  return callApi(config, `/roles/${roleKey}`, {
+    method: "PUT",
+    body
+  });
+}
+async function deleteRole(config, roleKey) {
+  return callApi(config, `/roles/${roleKey}`, {
+    method: "DELETE"
+  });
+}
+async function assignMemberRole(config, orgIdOrSlug, memberId, roleKey) {
+  return callApi(
+    config,
+    `/orgs/${orgIdOrSlug}/members/${memberId}/assign-role`,
+    {
+      method: "PUT",
+      body: { roleKey }
+    }
+  );
+}
+
 // src/secrets.ts
 async function getSecret(config, input) {
   return callApi(config, "/secrets/get", {
@@ -3394,6 +3708,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;
@@ -3403,12 +3854,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
@@ -3428,7 +3885,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);
@@ -3456,10 +3914,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
@@ -3471,13 +3940,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()}`);
@@ -3530,6 +3999,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)
   // ---------------------------------------------------------------------------
   /**
@@ -3575,7 +4096,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) {
@@ -3599,7 +4120,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
@@ -3667,7 +4188,7 @@ var WorkerHandle = class {
     await callApi(this.config, `/workers/${this.id}`, { method: "DELETE" });
   }
 };
-var WorkersClient = {
+var RunsClient = {
   // --------------------------------------------------------------------------
   // Run
   // --------------------------------------------------------------------------
@@ -3679,7 +4200,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' } },
@@ -3689,7 +4210,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,
@@ -3700,25 +4221,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
@@ -3728,12 +4249,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
     });
@@ -3744,11 +4265,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'],
    * })
@@ -3756,13 +4277,14 @@ 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;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACHIEVEMENT_TIER_CONFIG,
@@ -3770,20 +4292,28 @@ function sleep2(ms) {
   AuthorizationError,
   CircuitBreakerOpenError,
   ERROR_CODE_STATUS,
+  InvalidConnectionUrlError,
   NetworkError,
   NotFoundError,
   RETRYABLE_CODES,
   RateLimitError,
+  RunHandle,
+  RunsClient,
   SandboxClient,
+  SandboxFiles,
+  SandboxProcesses,
+  SandboxWatch,
   StepCompleteSignal,
   StepSleepSignal,
   SylphxError,
   TimeoutError,
+  TriggersClient,
   ValidationError,
   WorkerHandle,
   WorkersClient,
   acceptAllConsents,
   acceptOrganizationInvitation,
+  assignMemberRole,
   batchIndex,
   canDeleteOrganization,
   canManageMembers,
@@ -3798,12 +4328,16 @@ function sleep2(ms) {
   checkFlag,
   complete,
   createCheckout,
+  createClient,
   createConfig,
   createCron,
   createDynamicRestClient,
   createOrganization,
+  createPermission,
   createPortalSession,
   createRestClient,
+  createRole,
+  createServerClient,
   createServiceWorkerScript,
   createStepContext,
   createTasksHandler,
@@ -3818,6 +4352,8 @@ function sleep2(ms) {
   deleteEnvVar,
   deleteFile,
   deleteOrganization,
+  deletePermission,
+  deleteRole,
   deleteUser,
   disableDebug,
   embed,
@@ -3851,6 +4387,7 @@ function sleep2(ms) {
   getFlagPayload,
   getFlags,
   getLeaderboard,
+  getMemberPermissions,
   getMyReferralCode,
   getOrganization,
   getOrganizationInvitations,
@@ -3862,6 +4399,7 @@ function sleep2(ms) {
   getReferralLeaderboard,
   getReferralStats,
   getRestErrorMessage,
+  getRole,
   getScheduledEmail,
   getScheduledEmailStats,
   getSearchStats,
@@ -3881,8 +4419,11 @@ function sleep2(ms) {
   getWebhookDeliveries,
   getWebhookDelivery,
   getWebhookStats,
+  hasAllPermissions,
+  hasAnyPermission,
   hasConsent,
   hasError,
+  hasPermission,
   hasRole,
   hasSecret,
   identify,
@@ -3919,12 +4460,13 @@ function sleep2(ms) {
   leaveOrganization,
   linkAnonymousConsents,
   listEnvVars,
+  listPermissions,
+  listRoles,
   listScheduledEmails,
   listSecretKeys,
   listTasks,
   listUsers,
   page,
-  parseKey,
   pauseCron,
   realtimeEmit,
   recordStreakActivity,
@@ -3971,6 +4513,7 @@ function sleep2(ms) {
   updateOrganization,
   updateOrganizationMemberRole,
   updatePushPreferences,
+  updateRole,
   updateUser,
   updateUserMetadata,
   updateWebhookConfig,