@sylphx/sdk 0.10.0 → 0.10.1

package/dist/server/index.d.ts

@@ -15,7 +15,7 @@ import { SdkBillingPlan, SdkConsentType } from '@sylphx/contract';
  * import { createRestClient } from '@sylphx/sdk'
  *
  * const client = createRestClient({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *   secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey!,
  * })
  *
  * const { data: user, error } = await client.GET('/auth/me')
@@ -130,6 +130,10 @@ interface Middleware {
     onRequest?: (ctx: {
         request: Request;
     }) => Promise<Request | undefined> | Request | undefined;
+    onFetch?: (ctx: {
+        request: Request;
+        next: (request: Request) => Promise<Response>;
+    }) => Promise<Response | undefined> | Response | undefined;
     onResponse?: (ctx: {
         request: Request;
         response: Response;
@@ -192,7 +196,7 @@ declare class InvalidConnectionUrlError extends Error {
  * import { createClient } from '@sylphx/sdk'
  *
  * const sylphx = createClient(process.env.SYLPHX_URL!)
- * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.api.sylphx.com
+ * // Parses: sylphx://pk_prod_{ref?}_{hex}@bold-river-a1b2c3.api.sylphx.com
  * ```
  */
 
@@ -264,7 +268,7 @@ interface SylphxClientInput {
  * @example Connection URL (recommended)
  * ```typescript
  * const sylphx = createClient(process.env.NEXT_PUBLIC_SYLPHX_URL!)
- * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.api.sylphx.com
+ * // Parses: sylphx://pk_prod_{ref?}_{hex}@bold-river-a1b2c3.api.sylphx.com
  * ```
  *
  * @example Explicit components
@@ -285,7 +289,7 @@ declare function createClient(input: string | SylphxClientInput): SylphxConfig;
  * @example Connection URL (recommended)
  * ```typescript
  * const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
- * // Parses: sylphx://sk_prod_{hex}@bold-river-a1b2c3.api.sylphx.com
+ * // Parses: sylphx://sk_prod_{ref?}_{hex}@bold-river-a1b2c3.api.sylphx.com
  * ```
  *
  * @example Explicit components
@@ -469,17 +473,17 @@ interface AccessTokenPayload {
  * 5. Single Source of Truth - All key logic in one place
  *
  * Key Formats (ADR-021):
- * - Publishable key: pk_(dev|stg|prod)_{ref}_{32hex} — client-safe (new)
- * - Secret Key:      sk_(dev|stg|prod)_{ref}_{64hex} — server-side only
+ * - Publishable key: pk_(dev|stg|prod|prev)_{ref}_{32hex} — client-safe (new)
+ * - Secret Key:      sk_(dev|stg|prod|prev)_{ref}_{64hex} — server-side only
  *
  * Legacy Key Formats (backward-compat):
- * - App ID (old):    app_(dev|stg|prod)_[identifier] — Public identifier
+ * - App ID (old):    app_(dev|stg|prod|prev)_[identifier] — Public identifier
  *
  * Special Internal Formats (NOT rotated):
  * - Console bootstrap: app_prod_platform_{slug} / sk_prod_platform_{slug}
  */
 /** Environment type derived from key prefix */
-type EnvironmentType = 'development' | 'staging' | 'production';
+type EnvironmentType = 'development' | 'staging' | 'production' | 'preview';
 /** Key type - publicKey (pk_*), appId (legacy app_*), or secret (sk_*) */
 type KeyType = 'publicKey' | 'appId' | 'secret';
 /** Validation result with clear error information */
@@ -529,7 +533,7 @@ declare function validateAndSanitizeAppId(key: string | undefined | null): strin
  *
  * @example
  * ```typescript
- * const result = validateSecretKey(process.env.SYLPHX_SECRET_KEY)
+ * const result = validateSecretKey('sk_prod_...')
  * if (!result.valid) {
  *   throw new Error(result.error)
  * }
@@ -601,7 +605,7 @@ declare function isSecretKey(key: string): boolean;
  *
  * @example
  * ```typescript
- * const result = validateKey(process.env.SYLPHX_SECRET_KEY)
+ * const result = validateKey('sk_prod_...')
  * if (!result.valid) {
  *   throw new Error(result.error)
  * }
@@ -671,17 +675,11 @@ type OAuthProvider = OAuthProviderId | (string & {});
  * }
  * ```
  *
- * ```bash
- * # Deploy via CLI
- * sylphx functions deploy hello-world
- * # → https://my-project.sylphx.app/functions/hello-world
- * ```
- *
  * ```typescript
- * // Or deploy programmatically via SDK
+ * // Deploy programmatically from trusted server-side tooling
  * import { createConfig, FunctionsClient } from '@sylphx/sdk'
  *
- * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
+ * const config = createConfig({ secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey! })
  *
  * await FunctionsClient.deploy(config, {
  *   name: 'hello-world',
@@ -723,7 +721,8 @@ interface FunctionDeployOptions {
      * Must export a default handler function:
      *   export default async function(req: Request): Promise<Response> { ... }
      *
-     * For functions > 100KB, use the CLI: sylphx functions deploy
+     * For larger bundles, use a production-backed deployment workflow that
+     * uploads source as an artifact instead of embedding it in JSON.
      */
     code: string;
     /** Human-readable display name */
@@ -942,7 +941,9 @@ declare function decodeUserId(prefixedId: string): string | null;
  * ```
  */
 interface AIClientOptions {
-    /** Secret key for authentication (default: SYLPHX_SECRET_KEY env var) */
+    /** Server connection URL. Defaults to SYLPHX_SECRET_URL. */
+    secretUrl?: string;
+    /** @deprecated Use secretUrl. */
     secretKey?: string;
     /** Platform URL (default: https://api.sylphx.com) */
     platformUrl?: string;
@@ -1047,7 +1048,7 @@ interface AIClient {
  *
  * Uses environment variables by default:
  *
- * - SYLPHX_SECRET_KEY: Your app's secret key (sk_dev_xxx, sk_stg_xxx, sk_prod_xxx)
+ * - SYLPHX_SECRET_URL: Your app's server connection URL
  */
 declare function createAI(options?: AIClientOptions): AIClient;
 /**
@@ -1126,7 +1127,9 @@ interface KvZMember {
  */
 
 interface KvClientOptions {
-    /** Secret key for authentication (default: SYLPHX_SECRET_KEY env var) */
+    /** Server connection URL. Defaults to SYLPHX_SECRET_URL. */
+    secretUrl?: string;
+    /** @deprecated Use secretUrl. */
     secretKey?: string;
     /** Platform URL (default: https://api.sylphx.com) */
     platformUrl?: string;
@@ -1292,7 +1295,7 @@ interface KvClient {
  * Create a server-side KV client
  *
  * Uses environment variables by default:
- * - SYLPHX_SECRET_KEY: Your app's secret key (sk_dev_xxx, sk_stg_xxx, sk_prod_xxx)
+ * - SYLPHX_SECRET_URL: Your app's server connection URL
  */
 declare function createKv(options?: KvClientOptions): KvClient;
 /**
@@ -1351,7 +1354,9 @@ interface StreamMessage<T = unknown> {
  */
 
 interface StreamsClientOptions {
-    /** Secret key for authentication (default: SYLPHX_SECRET_KEY env var) */
+    /** Server connection URL. Defaults to SYLPHX_SECRET_URL. */
+    secretUrl?: string;
+    /** @deprecated Use secretUrl. */
     secretKey?: string;
     /** Platform URL (default: https://api.sylphx.com) */
     platformUrl?: string;
@@ -1403,7 +1408,7 @@ interface StreamsClient {
  *
  * Uses environment variables by default:
  *
- * - SYLPHX_SECRET_KEY: Your app's secret key (sk_dev_xxx, sk_stg_xxx, sk_prod_xxx)
+ * - SYLPHX_SECRET_URL: Your app's server connection URL
  */
 declare function createStreams(options?: StreamsClientOptions): StreamsClient;
 /**
@@ -1422,8 +1427,10 @@ declare function getStreams(): StreamsClient;
  * ```typescript
  * import { createServerClient, verifyWebhook } from '@sylphx/sdk/server'
  *
+ * const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
  * const client = createServerRestClient({
- *   secretKey: process.env.SYLPHX_SECRET_URL!,
+ *   secretKey: sylphx.secretKey!,
+ *   platformUrl: sylphx.baseUrl.replace(/\/v1$/, ''),
  * })
  *
  * // REST API calls
@@ -1525,7 +1532,7 @@ interface WebhookVerifyOptions {
  *   const result = await verifyWebhook({
  *     payload: body,
  *     signatureHeader: request.headers.get('x-webhook-signature'),
- *     secret: process.env.SYLPHX_SECRET_KEY!,
+ *     secret: process.env.SYLPHX_WEBHOOK_SECRET!,
  *   })
  *
  *   if (!result.valid) {
@@ -1555,7 +1562,7 @@ declare function verifyWebhook(options: {
  * import { createWebhookHandler } from '@sylphx/sdk/server'
  *
  * const handler = createWebhookHandler({
- *   secret: process.env.SYLPHX_SECRET_KEY!,
+ *   secret: process.env.SYLPHX_WEBHOOK_SECRET!,
  *   handlers: {
  *     'user.created': async (data) => {
  *       console.log('New user:', data)
@@ -1656,7 +1663,7 @@ interface FeatureFlagDefinition {
  * import { getFeatureFlags } from '@sylphx/sdk/server'
  *
  * export default async function RootLayout({ children }) {
- *   const sylphx = createServerClient(process.env.SYLPHX_URL!)
+ *   const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
  *   const flags = await getFeatureFlags({
  *     secretKey: sylphx.secretKey!,
  *     platformUrl: sylphx.baseUrl.replace(/\/v[0-9]+$/, ''),
@@ -1713,7 +1720,7 @@ interface GetAppConfigOptions {
  * import { getAppConfig } from '@sylphx/sdk/server'
  *
  * export default async function RootLayout({ children }) {
- *   const sylphx = createServerClient(process.env.SYLPHX_URL!)
+ *   const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
  *   const config = await getAppConfig({
  *     secretKey: sylphx.secretKey!,
  *     appId: process.env.NEXT_PUBLIC_SYLPHX_APP_ID!,
@@ -1761,7 +1768,7 @@ interface ReferralLeaderboardResult {
  *
  * export default async function ReferralsPage() {
  *   const leaderboard = await getReferralLeaderboard({
- *     secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *     secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey!,
  *     limit: 10,
  *     period: 'month',
  *   })
@@ -1798,7 +1805,7 @@ interface EngagementLeaderboardResult {
  *
  * export default async function LeaderboardPage() {
  *   const leaderboard = await getEngagementLeaderboard({
- *     secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *     secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey!,
  *     leaderboardId: 'high-scores',
  *   })
  *   return <Leaderboard initialData={leaderboard} />
@@ -1838,7 +1845,7 @@ interface DatabaseStatusInfo {
  *
  * // In your database initialization
  * const dbInfo = await getDatabaseConnection({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *   secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey!,
  * })
  *
  * if (dbInfo) {
@@ -1857,7 +1864,7 @@ declare function getDatabaseConnection(options: AuthenticatedFetchOptions): Prom
  * import { getDatabaseStatus } from '@sylphx/sdk/server'
  *
  * const status = await getDatabaseStatus({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *   secretKey: createServerClient(process.env.SYLPHX_SECRET_URL!).secretKey!,
  * })
  *
  * if (status?.status === 'ready') {

package/dist/server/index.mjs

@@ -1360,13 +1360,14 @@ function exponentialBackoff(attempt, baseDelay = BASE_RETRY_DELAY_MS, maxDelay =
 }
 
 // src/key-validation.ts
-var PUBLIC_KEY_PATTERN = /^pk_(dev|stg|prod)_[a-z0-9]{12}_[a-f0-9]{32}$/;
+var PUBLIC_KEY_PATTERN = /^pk_(dev|stg|prod|prev)(?:_[a-z0-9]{12})?_[a-f0-9]{32}$/;
 var APP_ID_PATTERN = /^(app|pk)_(dev|stg|prod|prev)_[a-z0-9_-]+$/;
-var SECRET_KEY_PATTERN = /^sk_(dev|stg|prod)_[a-z0-9_-]+$/;
+var SECRET_KEY_PATTERN = /^sk_(dev|stg|prod|prev)_[a-z0-9_-]+$/;
 var ENV_PREFIX_MAP = {
   dev: "development",
   stg: "staging",
-  prod: "production"
+  prod: "production",
+  prev: "preview"
 };
 function detectKeyIssues(key) {
   const issues = [];
@@ -1391,7 +1392,7 @@ The SDK will automatically sanitize the key, but fixing the source is recommende
 }
 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 formatHint = keyType === "appId" ? "pk_(dev|stg|prod|prev)_{ref}_{hex} or app_(dev|stg|prod|prev)_[id]" : "sk_(dev|stg|prod|prev)_{ref}_{hex}";
   const keyTypeName = keyType === "appId" ? "App ID" : "Secret Key";
   return `[Sylphx] Invalid ${keyTypeName} format.
 
@@ -1404,7 +1405,7 @@ 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 has invalid environment (must be dev, stg, prod, or prev)
 \u2022 Key was copied with extra whitespace`;
 }
 function extractEnvironment(key) {
@@ -1451,7 +1452,7 @@ function validateKeyForType(key, keyType, pattern, envVarName) {
   };
 }
 function validatePublicKey(key) {
-  return validateKeyForType(key, "publicKey", PUBLIC_KEY_PATTERN, "NEXT_PUBLIC_SYLPHX_KEY");
+  return validateKeyForType(key, "publicKey", PUBLIC_KEY_PATTERN, "publishable credential");
 }
 function validateAppId(key) {
   return validateKeyForType(key, "appId", APP_ID_PATTERN, "NEXT_PUBLIC_SYLPHX_APP_ID");
@@ -1467,7 +1468,7 @@ function validateAndSanitizeAppId(key) {
   return result.sanitizedKey;
 }
 function validateSecretKey(key) {
-  return validateKeyForType(key, "secret", SECRET_KEY_PATTERN, "SYLPHX_SECRET_KEY");
+  return validateKeyForType(key, "secret", SECRET_KEY_PATTERN, "secret credential");
 }
 function validateAndSanitizeSecretKey(key) {
   const result = validateSecretKey(key);
@@ -1508,7 +1509,7 @@ function isProductionKey(key) {
 }
 function getCookieNamespace(secretKey) {
   const env = detectEnvironment(secretKey);
-  const shortEnv = env === "development" ? "dev" : env === "staging" ? "stg" : "prod";
+  const shortEnv = env === "development" ? "dev" : env === "staging" ? "stg" : env === "preview" ? "prev" : "prod";
   return `sylphx_${shortEnv}`;
 }
 function detectKeyType(key) {
@@ -1538,7 +1539,7 @@ function validateKey(key) {
   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.",
+    error: key ? `Invalid key format. Keys must start with 'pk_' (publishable), 'app_' (legacy), or 'sk_' (secret), followed by environment (dev/stg/prod/prev). Got: ${key.slice(0, 20)}...` : "API key is required but was not provided.",
     issues: key ? ["invalid_format"] : ["missing"]
   };
 }
@@ -1571,7 +1572,14 @@ async function runPipeline(middlewares, initial) {
       if (next) request = next;
     }
   }
-  let response = await fetch(request);
+  const fetchWithMiddleware = middlewares.reduceRight(
+    (next, mw) => mw.onFetch ? async (request2) => {
+      const response2 = await mw.onFetch?.({ request: request2, next });
+      return response2 ?? next(request2);
+    } : next,
+    (request2) => fetch(request2)
+  );
+  let response = await fetchWithMiddleware(request);
   for (const mw of middlewares) {
     if (mw.onResponse) {
       const next = await mw.onResponse({ request, response });
@@ -1590,6 +1598,11 @@ function buildUrl(baseUrl, path, params) {
   ).toString();
   return `${url}?${search}`;
 }
+function cloneRequestWithHeaders(request, updateHeaders) {
+  const headers = new Headers(request.headers);
+  updateHeaders(headers);
+  return new Request(request, { headers });
+}
 function interpolatePath(path, pathParams) {
   if (!pathParams) return path;
   return path.replace(/\{(\w+)\}/g, (_match, key) => {
@@ -1652,66 +1665,51 @@ function buildClient(baseUrl, baseHeaders) {
 function createAuthMiddleware(config) {
   return {
     async onRequest({ request }) {
-      request.headers.set("X-SDK-Version", SDK_VERSION);
-      request.headers.set("X-SDK-Platform", SDK_PLATFORM);
-      if (config.secretKey) {
-        request.headers.set("x-app-secret", config.secretKey);
-      }
-      const token = config.getAccessToken?.();
-      if (token) {
-        request.headers.set("Authorization", `Bearer ${token}`);
-      }
-      return request;
+      return cloneRequestWithHeaders(request, (headers) => {
+        headers.set("X-SDK-Version", SDK_VERSION);
+        headers.set("X-SDK-Platform", SDK_PLATFORM);
+        if (config.secretKey) {
+          headers.set("x-app-secret", config.secretKey);
+        }
+        const token = config.getAccessToken?.();
+        if (token) {
+          headers.set("Authorization", `Bearer ${token}`);
+        }
+      });
     }
   };
 }
 function isRetryableStatus(status) {
   return status >= 500 || status === 429;
 }
-var inFlightRequests = /* @__PURE__ */ new Map();
 async function getRequestKey(request) {
   const body = request.body ? await request.clone().text() : "";
   return `${request.method}:${request.url}:${body}`;
 }
 function createDeduplicationMiddleware(config = {}) {
   const { enabled = true, methods = ["GET"] } = config;
-  if (!enabled) {
-    return {
-      async onRequest({ request }) {
-        return request;
-      }
-    };
-  }
+  if (!enabled) return {};
+  const inFlightRequests = /* @__PURE__ */ new Map();
   return {
-    async onRequest({ request }) {
-      if (!methods.includes(request.method)) {
-        return request;
+    async onFetch({ request, next }) {
+      const method = request.method.toUpperCase();
+      if (!methods.includes(method)) {
+        return next(request);
       }
       const key = await getRequestKey(request);
       const existing = inFlightRequests.get(key);
       if (existing) {
-        const deduped = request.clone();
-        deduped._dedupKey = key;
-        return deduped;
-      }
-      ;
-      request._dedupKey = key;
-      return request;
-    },
-    async onResponse({ request, response }) {
-      const key = request._dedupKey;
-      if (!key) return response;
-      const existing = inFlightRequests.get(key);
-      if (existing && inFlightRequests.get(key) !== void 0) {
         const cachedResponse = await existing;
         return cachedResponse.clone();
       }
-      const responsePromise = Promise.resolve(response.clone());
+      const responsePromise = next(request).then((response) => response.clone());
       inFlightRequests.set(key, responsePromise);
-      responsePromise.finally(() => {
-        setTimeout(() => inFlightRequests.delete(key), 100);
-      });
-      return response;
+      try {
+        const response = await responsePromise;
+        return response.clone();
+      } finally {
+        inFlightRequests.delete(key);
+      }
     }
   };
 }
@@ -1861,7 +1859,9 @@ function createETagMiddleware(config) {
         if (Date.now() - cached.timestamp > ttlMs) {
           etagCache.delete(cacheKey);
         } else {
-          request.headers.set("If-None-Match", cached.etag);
+          return cloneRequestWithHeaders(request, (headers) => {
+            headers.set("If-None-Match", cached.etag);
+          });
         }
       }
       return request;
@@ -2018,7 +2018,7 @@ function createDynamicRestClient(config) {
 // 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 CREDENTIAL_REGEX = /^(pk|sk)_(dev|stg|prod|prev)(?:_[a-z0-9]{12})?_[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 {
@@ -2035,7 +2035,7 @@ function fail(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}"`);
+    fail(`credential must match (pk|sk)_(dev|stg|prod|prev)(_{ref})?_{hex}, got "${raw}"`);
   }
   return {
     credentialType: match[1],
@@ -2112,7 +2112,7 @@ function parseConnectionUrl(url) {
 // 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.api.sylphx.com\n\nGenerate new credentials from the Sylphx Console \u2192 Your App \u2192 Environments.\nSee https://docs.sylphx.com/migration for details.";
+var MIGRATION_MESSAGE = "API key format has changed. Use a sylphx:// connection URL instead.\n\nNew format: sylphx://pk_prod_{ref?}_{hex}@your-slug.api.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)) {
@@ -2245,7 +2245,7 @@ function createConfigFromComponents(input) {
     });
   }
   throw new SylphxError(
-    `[Sylphx] Invalid credential format. Expected (pk|sk)_(dev|stg|prod|prev)_[a-f0-9]{32,64}. Got: "${trimmedCred.slice(0, 30)}..."`,
+    `[Sylphx] Invalid credential format. Expected (pk|sk)_(dev|stg|prod|prev)(_{ref})?_{hex}. Got: "${trimmedCred.slice(0, 30)}..."`,
     { code: "BAD_REQUEST" }
   );
 }
@@ -2571,14 +2571,32 @@ function decodeUserId(prefixedId) {
   return null;
 }
 
+// src/server/secret-url.ts
+function resolveServerConnection(options = {}) {
+  const configuredSecret = resolveSecretUrl(options.secretUrl ?? options.secretKey);
+  if (!configuredSecret) {
+    throw new Error("SYLPHX_SECRET_URL is required for server-side SDK calls");
+  }
+  if (configuredSecret.trim().startsWith("sylphx://")) {
+    const config = createServerClient(configuredSecret);
+    return {
+      secretKey: config.credential,
+      baseUrl: options.platformUrl?.trim() || config.baseUrl.replace(/\/v1\/?$/, "")
+    };
+  }
+  return {
+    secretKey: validateAndSanitizeSecretKey(configuredSecret),
+    baseUrl: options.platformUrl?.trim() || `https://${DEFAULT_SDK_API_HOST}`
+  };
+}
+
 // src/server/ai.ts
 function createAI(options = {}) {
   const baseURL = (options.platformUrl || `https://${DEFAULT_SDK_API_HOST}`).trim();
-  const rawApiKey = options.secretKey || process.env.SYLPHX_SECRET_KEY;
-  const apiKey = validateAndSanitizeSecretKey(rawApiKey);
+  const { secretKey } = resolveServerConnection(options);
   const headers = {
     "Content-Type": "application/json",
-    Authorization: `Bearer ${apiKey}`
+    Authorization: `Bearer ${secretKey}`
   };
   async function chat(opts) {
     const response = await fetch(`${baseURL}/api/v1/chat/completions`, {
@@ -2666,8 +2684,7 @@ function getAI() {
 
 // src/server/kv.ts
 function createKv(options = {}) {
-  const platformUrl = (options.platformUrl || `https://${DEFAULT_SDK_API_HOST}`).trim();
-  const secretKey = validateAndSanitizeSecretKey(resolveSecretUrl(options.secretKey));
+  const { baseUrl, secretKey } = resolveServerConnection(options);
   const headers = {
     "Content-Type": "application/json",
     "x-app-secret": secretKey,
@@ -2678,7 +2695,7 @@ function createKv(options = {}) {
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       try {
-        const response = await fetch(`${platformUrl}${SDK_API_PATH}/kv${path}`, {
+        const response = await fetch(`${baseUrl}${SDK_API_PATH}/kv${path}`, {
           method,
           headers,
           body: body ? JSON.stringify(body) : void 0
@@ -2855,15 +2872,13 @@ function getKv() {
 
 // src/server/streams.ts
 function createStreams(options = {}) {
-  const baseURL = (options.platformUrl || `https://${DEFAULT_SDK_API_HOST}`).trim();
-  const rawApiKey = options.secretKey || process.env.SYLPHX_SECRET_KEY;
-  const apiKey = validateAndSanitizeSecretKey(rawApiKey);
+  const { baseUrl, secretKey } = resolveServerConnection(options);
   const headers = {
     "Content-Type": "application/json",
-    "x-app-secret": apiKey
+    "x-app-secret": secretKey
   };
   async function emit(channel, event, data) {
-    const response = await fetch(`${baseURL}${SDK_API_PATH}/realtime/emit`, {
+    const response = await fetch(`${baseUrl}${SDK_API_PATH}/realtime/emit`, {
       method: "POST",
       headers,
       body: JSON.stringify({ channel, event, data })
@@ -2876,7 +2891,7 @@ function createStreams(options = {}) {
     return result.id;
   }
   async function history(channel, options2) {
-    const response = await fetch(`${baseURL}${SDK_API_PATH}/realtime/history`, {
+    const response = await fetch(`${baseUrl}${SDK_API_PATH}/realtime/history`, {
       method: "POST",
       headers,
       body: JSON.stringify({