@sylphx/sdk 0.4.0 → 0.5.0

package/dist/server/index.js

@@ -30,10 +30,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/server/index.ts
 var server_exports = {};
 __export(server_exports, {
+  FunctionsClient: () => FunctionsClient,
+  InvalidConnectionUrlError: () => InvalidConnectionUrlError,
   createAI: () => createAI,
   createAuthenticatedServerClient: () => createAuthenticatedServerClient,
+  createClient: () => createClient2,
   createKv: () => createKv,
   createServerClient: () => createServerClient,
+  createServerRestClient: () => createServerRestClient,
   createStreams: () => createStreams,
   createWebhookHandler: () => createWebhookHandler,
   decodeUserId: () => decodeUserId,
@@ -1201,13 +1205,13 @@ async function jwtVerify(jwt, key, options) {
 }
 
 // src/constants.ts
-var ENV_SECRET_KEY = "SYLPHX_SECRET_KEY";
-function resolveSecretKey(explicit) {
-  return explicit || process.env[ENV_SECRET_KEY];
+var ENV_SECRET_URL = "SYLPHX_SECRET_URL";
+function resolveSecretUrl(explicit) {
+  return explicit || process.env[ENV_SECRET_URL];
 }
 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;
@@ -1378,6 +1382,24 @@ var SylphxError = class _SylphxError extends Error {
     };
   }
 };
+var NetworkError = class extends SylphxError {
+  constructor(message2 = "Network request failed", options) {
+    super(message2, { ...options, code: "NETWORK_ERROR" });
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends SylphxError {
+  /** Timeout duration in milliseconds */
+  timeout;
+  constructor(timeout, options) {
+    super(`Request timed out after ${timeout}ms`, {
+      ...options,
+      code: "TIMEOUT"
+    });
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+  }
+};
 var RateLimitError = class extends SylphxError {
   /** Maximum requests allowed in window */
   limit;
@@ -1421,7 +1443,7 @@ 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 APP_ID_PATTERN = /^app_(dev|stg|prod)_[a-z0-9_-]+$/;
+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 ENV_PREFIX_MAP = {
   dev: "development",
@@ -1450,9 +1472,8 @@ To fix permanently:
 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 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.
 
@@ -1464,12 +1485,12 @@ 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 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|sk)_(dev|stg|prod)_/);
+  const match = key.match(/^(?:app|pk|sk)_(dev|stg|prod|prev)_/);
   if (!match) return void 0;
   return ENV_PREFIX_MAP[match[1]];
 }
@@ -1996,6 +2017,499 @@ function createDynamicRestClient(config) {
   return client;
 }
 
+// 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/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 (LEGACY_EMBEDDED_REF_PATTERN.test(trimmed)) {
+    throw new SylphxError(`[Sylphx] ${MIGRATION_MESSAGE}`, { code: "BAD_REQUEST" });
+  }
+}
+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 createClient2(input) {
+  if (typeof input === "string") {
+    return createConfigFromUrl(input);
+  }
+  return createConfigFromComponents(input);
+}
+function createServerClient(input) {
+  const config = createClient2(input);
+  if (config.credentialType !== "sk") {
+    throw new SylphxError(
+      "[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" }
+    );
+  }
+  return config;
+}
+function createConfigFromUrl(url) {
+  if (!url || typeof url !== "string") {
+    throw new SylphxError(
+      "[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 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 connection URL \u2014 must start with "sylphx://". Got: "${trimmed.slice(0, 30)}..."`,
+      { 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;
+  }
+  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 resolvedSlug = input.slug || input.ref;
+  if (!resolvedSlug) {
+    throw new SylphxError("[Sylphx] slug is required when using explicit components.", {
+      code: "BAD_REQUEST"
+    });
+  }
+  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 httpStatusToErrorCode(status) {
+  switch (status) {
+    case 400:
+      return "BAD_REQUEST";
+    case 401:
+      return "UNAUTHORIZED";
+    case 403:
+      return "FORBIDDEN";
+    case 404:
+      return "NOT_FOUND";
+    case 409:
+      return "CONFLICT";
+    case 413:
+      return "PAYLOAD_TOO_LARGE";
+    case 422:
+      return "UNPROCESSABLE_ENTITY";
+    case 429:
+      return "TOO_MANY_REQUESTS";
+    case 500:
+      return "INTERNAL_SERVER_ERROR";
+    case 501:
+      return "NOT_IMPLEMENTED";
+    case 502:
+      return "BAD_GATEWAY";
+    case 503:
+      return "SERVICE_UNAVAILABLE";
+    case 504:
+      return "GATEWAY_TIMEOUT";
+    default:
+      return status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST";
+  }
+}
+function buildHeaders(config) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (config.credential) {
+    headers["x-app-secret"] = config.credential;
+  }
+  if (config.accessToken) {
+    headers.Authorization = `Bearer ${config.accessToken}`;
+  }
+  return headers;
+}
+function buildApiUrl(config, path) {
+  const base = config.baseUrl.replace(/\/$/, "");
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${cleanPath}`;
+}
+async function callApi(config, path, options = {}) {
+  const {
+    method = "GET",
+    body,
+    query,
+    timeout = DEFAULT_TIMEOUT_MS,
+    signal,
+    idempotencyKey,
+    headers: extraHeaders
+  } = options;
+  let url = buildApiUrl(config, path);
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        params.set(key, String(value));
+      }
+    }
+    const queryString = params.toString();
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const combinedSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  const headers = buildHeaders(config);
+  if (idempotencyKey) {
+    headers["Idempotency-Key"] = idempotencyKey;
+  }
+  if (extraHeaders) {
+    for (const [k, v] of Object.entries(extraHeaders)) {
+      headers[k] = v;
+    }
+  }
+  const fetchOptions = {
+    method,
+    headers,
+    signal: combinedSignal
+  };
+  if (body) {
+    fetchOptions.body = JSON.stringify(body);
+  }
+  let response;
+  try {
+    response = await fetch(url, fetchOptions);
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        if (controller.signal.aborted && !signal?.aborted) {
+          throw new TimeoutError(timeout);
+        }
+        throw new SylphxError("Request aborted", {
+          code: "ABORTED",
+          cause: error
+        });
+      }
+      throw new NetworkError(error.message, { cause: error });
+    }
+    throw new NetworkError("Network request failed");
+  } finally {
+    clearTimeout(timeoutId);
+  }
+  if (!response.ok) {
+    const errorBody = await response.text().catch(() => "");
+    let errorMessage = "Request failed";
+    let errorData;
+    if (errorBody) {
+      try {
+        const parsed = JSON.parse(errorBody);
+        errorMessage = parsed.error?.message ?? parsed.message ?? errorMessage;
+        errorData = parsed.error;
+      } catch {
+        errorMessage = response.statusText || errorMessage;
+      }
+    }
+    const errorCode = httpStatusToErrorCode(response.status);
+    const retryAfterHeader = response.headers.get("Retry-After");
+    const rateLimitLimit = response.headers.get("X-RateLimit-Limit");
+    const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    const retryAfter = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : void 0;
+    if (response.status === 429) {
+      throw new RateLimitError(errorMessage || "Too many requests", {
+        status: response.status,
+        data: errorData,
+        retryAfter,
+        limit: rateLimitLimit ? Number.parseInt(rateLimitLimit, 10) : void 0,
+        remaining: rateLimitRemaining ? Number.parseInt(rateLimitRemaining, 10) : void 0,
+        resetAt: rateLimitReset ? Number.parseInt(rateLimitReset, 10) : void 0
+      });
+    }
+    throw new SylphxError(errorMessage, {
+      code: errorCode,
+      status: response.status,
+      data: errorData,
+      retryAfter
+    });
+  }
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new SylphxError("Failed to parse response", {
+      code: "PARSE_ERROR",
+      cause: error instanceof Error ? error : void 0,
+      data: { body: text.slice(0, 200) }
+    });
+  }
+}
+
+// src/lib/functions/index.ts
+var FunctionsClient = {
+  /**
+   * Deploy (create or update) a function.
+   *
+   * If a function with the same name already exists, it is updated
+   * (version number incremented, code replaced atomically).
+   *
+   * @example
+   * ```typescript
+   * const fn = await FunctionsClient.deploy(config, {
+   *   name: 'send-webhook',
+   *   code: `
+   *     export default async (req: Request) => {
+   *       const body = await req.json()
+   *       await fetch(body.url, { method: 'POST', body: JSON.stringify(body.payload) })
+   *       return Response.json({ ok: true })
+   *     }
+   *   `,
+   *   timeoutSeconds: 10,
+   * })
+   * console.log('Deployed:', fn.url)
+   * ```
+   */
+  async deploy(config, options) {
+    return callApi(config, "/functions", {
+      method: "POST",
+      body: options
+    });
+  },
+  /**
+   * Get a function by name.
+   */
+  async get(config, name) {
+    return callApi(config, `/functions/${encodeURIComponent(name)}`, { method: "GET" });
+  },
+  /**
+   * List all functions for this project.
+   */
+  async list(config, options = {}) {
+    const params = new URLSearchParams();
+    if (options.status) params.set("status", options.status);
+    if (options.environment) params.set("environment", options.environment);
+    if (options.limit) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    return callApi(config, `/functions${qs ? `?${qs}` : ""}`, { method: "GET" });
+  },
+  /**
+   * Delete a function permanently.
+   */
+  async delete(config, name) {
+    return callApi(config, `/functions/${encodeURIComponent(name)}`, { method: "DELETE" });
+  },
+  /**
+   * Invoke a function from server-side code.
+   *
+   * For client-side invocations, call the function URL directly via fetch().
+   *
+   * @example
+   * ```typescript
+   * const result = await FunctionsClient.invoke(config, 'process-order', {
+   *   body: { orderId: '123', userId: 'user_abc' },
+   * })
+   * ```
+   */
+  async invoke(config, name, body, options = {}) {
+    return callApi(config, `/functions/${encodeURIComponent(name)}/invoke`, {
+      method: options.method ?? "POST",
+      body: body ?? null,
+      headers: options.headers
+    });
+  },
+  /**
+   * Retrieve recent invocation logs for a function.
+   *
+   * @example
+   * ```typescript
+   * const logs = await FunctionsClient.logs(config, 'send-webhook', { errorsOnly: true })
+   * for (const entry of logs) {
+   *   console.log(`${entry.status} ${entry.durationMs}ms`, entry.errorMessage)
+   * }
+   * ```
+   */
+  async logs(config, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.errorsOnly) params.set("errors_only", "1");
+    if (options.since) params.set("since", options.since);
+    const qs = params.toString();
+    return callApi(config, `/functions/${encodeURIComponent(name)}/logs${qs ? `?${qs}` : ""}`, {
+      method: "GET"
+    });
+  }
+};
+
 // src/lib/ids.ts
 var CB32 = "0123456789abcdefghjkmnpqrstvwxyz";
 var CB32_MAP = Object.fromEntries([...CB32].map((c, i) => [c, i]));
@@ -2155,7 +2669,7 @@ function getAI() {
 // src/server/kv.ts
 function createKv(options = {}) {
   const platformUrl = (options.platformUrl || `https://${DEFAULT_SDK_API_HOST}`).trim();
-  const secretKey = validateAndSanitizeSecretKey(resolveSecretKey(options.secretKey));
+  const secretKey = validateAndSanitizeSecretKey(resolveSecretUrl(options.secretKey));
   const headers = {
     "Content-Type": "application/json",
     "x-app-secret": secretKey,
@@ -2402,7 +2916,7 @@ function getStreams() {
 }
 
 // src/server/index.ts
-function createServerClient(config) {
+function createServerRestClient(config) {
   const secretKey = validateAndSanitizeSecretKey(config.secretKey);
   return createRestClient({
     secretKey,
@@ -2801,10 +3315,14 @@ async function getDatabaseStatus(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FunctionsClient,
+  InvalidConnectionUrlError,
   createAI,
   createAuthenticatedServerClient,
+  createClient,
   createKv,
   createServerClient,
+  createServerRestClient,
   createStreams,
   createWebhookHandler,
   decodeUserId,