@sylphx/sdk 0.8.0-rc.2 → 0.9.0

package/dist/nextjs/index.d.ts

@@ -76,18 +76,27 @@ interface SylphxMiddlewareConfig {
     debug?: boolean;
     /**
      * Secret key for authentication.
-     * Override to use a programmatic key instead of SYLPHX_SECRET_KEY env var.
+     * Override to use a programmatic key instead of SYLPHX_SECRET_URL env var.
      *
      * Use case: Platform Console uses dynamically generated keys.
      *
-     * @default process.env.SYLPHX_SECRET_KEY
+     * @default credential parsed from process.env.SYLPHX_SECRET_URL, falling back
+     * to process.env.SYLPHX_SECRET_KEY for legacy apps
      */
     secretKey?: string;
+    /**
+     * Server connection URL for authentication.
+     *
+     * Format: sylphx://sk_<env>_<hex>@<tenant>.api.sylphx.com
+     *
+     * @default process.env.SYLPHX_SECRET_URL
+     */
+    secretUrl?: string;
     /**
      * Platform URL for API calls.
      * Override for self-hosted or same-origin deployments.
      *
-     * @default https://api.sylphx.com
+     * @default resolved from SYLPHX_URL, then legacy 4-part key routing
      */
     platformUrl?: string;
     /**
@@ -216,7 +225,8 @@ interface UserCookieData {
  * Configure the SDK for server-side usage
  *
  * NOTE: This is optional! The SDK auto-configures from environment variables:
- * - SYLPHX_SECRET_KEY (required)
+ * - SYLPHX_SECRET_URL (recommended)
+ * - SYLPHX_SECRET_KEY (legacy fallback)
  *
  * Use this only if you need to override the default configuration.
  *
@@ -226,12 +236,13 @@ interface UserCookieData {
  * import { configureServer } from '@sylphx/sdk/nextjs'
  *
  * configureServer({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *   secretUrl: process.env.SYLPHX_SECRET_URL!,
  * })
  * ```
  */
 declare function configureServer(config: {
-    secretKey: string;
+    secretKey?: string;
+    secretUrl?: string;
     platformUrl?: string;
 }): void;
 /**

package/dist/nextjs/index.mjs

@@ -2,6 +2,9 @@
 import { NextResponse } from "next/server";
 
 // src/constants.ts
+var ENV_URL = "SYLPHX_URL";
+var ENV_SECRET_URL = "SYLPHX_SECRET_URL";
+var ENV_SECRET_KEY = "SYLPHX_SECRET_KEY";
 var DEFAULT_SDK_API_HOST = "api.sylphx.com";
 var SDK_PLATFORM = typeof window !== "undefined" ? "browser" : typeof process !== "undefined" && process.versions?.node ? "node" : "unknown";
 var TOKEN_EXPIRY_BUFFER_MS = 3e4;
@@ -296,6 +299,154 @@ function parseUserCookie(value) {
   }
 }
 
+// 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(message2) {
+    super(message2);
+    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/nextjs/runtime-config.ts
+var SylphxRoutingConfigurationError = class extends Error {
+  name = "SylphxRoutingConfigurationError";
+};
+function normalizePlatformUrl(url) {
+  const trimmed = url.trim().replace(/\/+$/, "");
+  return trimmed.endsWith("/v1") ? trimmed.slice(0, -3) : trimmed;
+}
+function parseConnection(value) {
+  if (!value) return null;
+  return parseConnectionUrl(value.trim());
+}
+function platformUrlFromConnectionUrl(value) {
+  const parsed = parseConnection(value);
+  return parsed ? `https://${parsed.host}` : null;
+}
+function secretKeyFromConnectionUrl(value) {
+  const parsed = parseConnection(value);
+  if (!parsed || parsed.credentialType !== "sk") return null;
+  return parsed.credential;
+}
+function platformUrlFromLegacyKey(secretKey) {
+  if (!secretKey) return null;
+  const parts = secretKey.trim().toLowerCase().split("_");
+  const embeddedRef = parts.length === 4 ? parts[2] : null;
+  return embeddedRef ? `https://${embeddedRef}.${DEFAULT_SDK_API_HOST}` : null;
+}
+function resolveNextjsPlatformUrl(options) {
+  if (options.explicitPlatformUrl) return normalizePlatformUrl(options.explicitPlatformUrl);
+  const fromExplicitSecretUrl = platformUrlFromConnectionUrl(options.secretUrl);
+  if (fromExplicitSecretUrl) return fromExplicitSecretUrl;
+  const fromSecretUrl = platformUrlFromConnectionUrl(process.env[ENV_SECRET_URL]);
+  if (fromSecretUrl) return fromSecretUrl;
+  const fromConnectionUrl = platformUrlFromConnectionUrl(process.env[ENV_URL]);
+  if (fromConnectionUrl) return fromConnectionUrl;
+  const fromBaasOverride = process.env.SYLPHX_BAAS_URL ?? process.env.SYLPHX_RUNTIME_URL;
+  if (fromBaasOverride) return normalizePlatformUrl(fromBaasOverride);
+  const fromLegacyKey = platformUrlFromLegacyKey(options.secretKey);
+  if (fromLegacyKey) return fromLegacyKey;
+  throw new SylphxRoutingConfigurationError(
+    '[Sylphx] BaaS routing target is required for @sylphx/sdk/nextjs. Set SYLPHX_SECRET_URL="sylphx://sk_<env>_<hex>@<tenant>.api.sylphx.com" or SYLPHX_URL="sylphx://<credential>@<tenant>.api.sylphx.com" or pass platformUrl explicitly. New-format sk_* credentials do not carry routing material.'
+  );
+}
+function resolveNextjsSecretKey(options) {
+  if (options.explicitSecretKey?.trim()) return options.explicitSecretKey.trim();
+  const fromExplicitSecretUrl = secretKeyFromConnectionUrl(options.explicitSecretUrl);
+  if (fromExplicitSecretUrl) return fromExplicitSecretUrl;
+  const fromSecretUrl = secretKeyFromConnectionUrl(process.env[ENV_SECRET_URL]);
+  if (fromSecretUrl) return fromSecretUrl;
+  const fromGenericUrl = secretKeyFromConnectionUrl(process.env[ENV_URL]);
+  if (fromGenericUrl) return fromGenericUrl;
+  return process.env[ENV_SECRET_KEY]?.trim() || null;
+}
+
 // src/nextjs/middleware.ts
 function isTokenResponse(data) {
   return typeof data === "object" && data !== null && "accessToken" in data && "refreshToken" in data && "user" in data && typeof data.accessToken === "string" && typeof data.refreshToken === "string";
@@ -452,10 +603,13 @@ function createSylphxMiddleware(userConfig = {}) {
   let secretKey = null;
   function resolveSecretKey() {
     if (secretKey) return secretKey;
-    const rawSecretKey = userConfig.secretKey || process.env.SYLPHX_SECRET_KEY;
+    const rawSecretKey = resolveNextjsSecretKey({
+      explicitSecretKey: userConfig.secretKey,
+      explicitSecretUrl: userConfig.secretUrl
+    });
     if (!rawSecretKey) {
       throw new Error(
-        "[Sylphx] Secret key is required.\nEither pass secretKey in config or set SYLPHX_SECRET_KEY env var.\nGet your key from Sylphx Console \u2192 API Keys."
+        "[Sylphx] Server connection URL is required.\nEither pass secretUrl in config or set SYLPHX_SECRET_URL env var.\nLegacy apps may pass secretKey or set SYLPHX_SECRET_KEY during migration."
       );
     }
     secretKey = validateAndSanitizeSecretKey(rawSecretKey);
@@ -466,12 +620,11 @@ function createSylphxMiddleware(userConfig = {}) {
   let cookieNames;
   function resolveConfig() {
     const key = resolveSecretKey();
-    platformUrl = (() => {
-      if (userConfig.platformUrl) return userConfig.platformUrl.trim();
-      const parts = key.split("_");
-      const ref = parts.length === 4 ? parts[2] : null;
-      return ref ? `https://${ref}.${DEFAULT_SDK_API_HOST}` : `https://${DEFAULT_SDK_API_HOST}`;
-    })();
+    platformUrl = resolveNextjsPlatformUrl({
+      explicitPlatformUrl: userConfig.platformUrl,
+      secretKey: key,
+      secretUrl: userConfig.secretUrl
+    });
     namespace = getCookieNamespace(key);
     cookieNames = getCookieNames(namespace);
   }
@@ -1835,27 +1988,40 @@ function isTokenResponse2(data) {
 }
 var serverConfig = null;
 function configureServer(config) {
-  const secretKey = validateAndSanitizeSecretKey(config.secretKey);
+  const rawSecretKey = resolveNextjsSecretKey({
+    explicitSecretKey: config.secretKey,
+    explicitSecretUrl: config.secretUrl
+  });
+  if (!rawSecretKey) {
+    throw new Error(
+      "[Sylphx] Server credential is required. Set SYLPHX_SECRET_URL or pass secretUrl/secretKey to configureServer()."
+    );
+  }
+  const secretKey = validateAndSanitizeSecretKey(rawSecretKey);
   serverConfig = {
     secretKey,
-    platformUrl: config.platformUrl?.trim() || `https://${DEFAULT_SDK_API_HOST}`.trim()
+    platformUrl: resolveNextjsPlatformUrl({
+      explicitPlatformUrl: config.platformUrl,
+      secretKey,
+      secretUrl: config.secretUrl
+    })
   };
 }
 function getConfig() {
   if (serverConfig) {
     return serverConfig;
   }
-  const rawSecretKey = process.env.SYLPHX_SECRET_KEY;
+  const rawSecretKey = resolveNextjsSecretKey({});
   if (!rawSecretKey) {
     return null;
   }
   try {
     const secretKey = validateAndSanitizeSecretKey(rawSecretKey);
-    const platformUrl = `https://${DEFAULT_SDK_API_HOST}`.trim();
+    const platformUrl = resolveNextjsPlatformUrl({ secretKey });
     serverConfig = { secretKey, platformUrl };
     return serverConfig;
   } catch (error) {
-    console.warn("[Sylphx] Invalid SYLPHX_SECRET_KEY format:", error);
+    console.warn("[Sylphx] Invalid @sylphx/sdk/nextjs server configuration:", error);
     return null;
   }
 }
@@ -1915,7 +2081,7 @@ async function currentUserId() {
 async function handleCallback2(code) {
   const config = getConfig();
   if (!config) {
-    throw new Error("Sylphx SDK not configured. Set SYLPHX_SECRET_KEY environment variable.");
+    throw new Error("Sylphx SDK not configured. Set SYLPHX_SECRET_URL environment variable.");
   }
   const response = await fetch(`${config.platformUrl}/v1/auth/token`, {
     method: "POST",
@@ -1968,7 +2134,7 @@ async function syncAuthToCookies(tokens) {
 function getAuthorizationUrl(options) {
   const config = getConfig();
   if (!config) {
-    throw new Error("Sylphx SDK not configured. Set SYLPHX_SECRET_KEY environment variable.");
+    throw new Error("Sylphx SDK not configured. Set SYLPHX_SECRET_URL environment variable.");
   }
   const rawClientId = options?.appId || process.env.NEXT_PUBLIC_SYLPHX_APP_ID;
   if (!rawClientId) {