@sylphx/sdk 0.3.3 → 0.3.5

package/dist/server/index.d.cts

@@ -18405,7 +18405,7 @@ interface components {
 		OrgInvitation: {
 			/**
 			 * @description Invitation ID
-			 * @example ivt_3Zb83qVQxkHMJPZ8VrJfQ2
+			 * @example inv_3Zb83qVQxkHMJPZ8VrJfQ2
 			 */
 			id: string
 			/**
@@ -18475,7 +18475,7 @@ interface components {
 			/**
 			 * Format: uuid
 			 * @description Invitation token (ID)
-			 * @example ivt_3Zb83qVQxkHMJPZ8VrJfQ2
+			 * @example inv_3Zb83qVQxkHMJPZ8VrJfQ2
 			 */
 			token: string
 		}
@@ -19782,18 +19782,20 @@ interface AccessTokenPayload {
  * 4. No silent fixes - Transparency over convenience (but warn + continue)
  * 5. Single Source of Truth - All key logic in one place
  *
- * Key Formats (OAuth 2.0 Standard):
- * - App ID: app_(dev|stg|prod)_[identifier] — Public identifier (like OAuth client_id)
- * - Secret Key: sk_(dev|stg|prod)_[identifier] — Server-side only (like OAuth client_secret)
+ * 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
  *
- * Identifier Types:
- * - Customer apps: 32 hex chars
- * - Platform apps: platform_{app-slug} (e.g., platform_sylphx-console)
+ * Legacy Key Formats (backward-compat):
+ * - App ID (old):    app_(dev|stg|prod)_[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';
-/** Key type - appId (public) or secret (server) */
-type KeyType = 'appId' | 'secret';
+/** Key type - publicKey (pk_*), appId (legacy app_*), or secret (sk_*) */
+type KeyType = 'publicKey' | 'appId' | 'secret';
 /** Validation result with clear error information */
 interface KeyValidationResult {
     /** Whether the key is valid (possibly after sanitization) */
@@ -19812,7 +19814,9 @@ interface KeyValidationResult {
     issues?: string[];
 }
 /**
- * Validate an App ID and return detailed results
+ * Validate a legacy App ID (app_*) and return detailed results.
+ *
+ * @deprecated Use validatePublicKey() for new pk_* keys (ADR-021).
  *
  * @example
  * ```typescript
@@ -19827,8 +19831,9 @@ interface KeyValidationResult {
  */
 declare function validateAppId(key: string | undefined | null): KeyValidationResult;
 /**
- * Validate and sanitize App ID, logging warnings
+ * Validate and sanitize App ID, logging warnings.
  *
+ * @deprecated Use validateAndSanitizePublicKey() for new pk_* keys (ADR-021).
  * @throws Error if the key is invalid and cannot be sanitized
  * @returns The sanitized App ID
  */
@@ -19887,17 +19892,19 @@ declare function isProductionKey(key: string): boolean;
  */
 declare function getCookieNamespace(secretKey: string): string;
 /**
- * Detect the type of key (App ID or Secret Key)
+ * Detect the type of key.
  *
- * @returns 'appId', 'secret', or null if unknown
+ * @returns 'publicKey' (pk_*), 'appId' (legacy app_*), 'secret' (sk_*), or null if unknown
  */
 declare function detectKeyType(key: string): KeyType | null;
 /**
- * Check if a key is an App ID
+ * Check if a key is an App ID (legacy app_* format)
+ *
+ * @deprecated Use isPublishableKey() to also accept new pk_* keys
  */
 declare function isAppId(key: string): boolean;
 /**
- * Check if a key is a secret key
+ * Check if a key is a secret key (sk_*)
  */
 declare function isSecretKey(key: string): boolean;
 /**
@@ -19931,33 +19938,36 @@ declare function isDevelopmentRuntime(): boolean;
  * Platform ID utilities for the Sylphx SDK
  *
  * Converts between raw UUIDs (used internally / in JWT sub claims) and
- * prefixed base58 IDs (used in all API responses and JWT pid claims).
+ * prefixed TypeID strings (used in all API responses and JWT pid claims).
+ *
+ * Uses TypeID spec v0.3.0 (Crockford base32, case-insensitive).
+ * Also accepts legacy base58 format for backward compatibility.
  *
- * Same alphabet and encoding logic as the platform server.
- * No external dependencies — pure TypeScript.
+ * No external dependencies — pure TypeScript implementation of Crockford base32.
  *
  * @example
  * ```ts
  * import { encodeUserId, decodeUserId } from '@sylphx/sdk/nextjs'
  *
  * const prefixed = encodeUserId('018f4a3b-1c2d-7000-9abc-def012345678')
- * // => 'user_3Zb83qVQxkHMJPZ8VrJfQ2'
+ * // => 'user_01h2xcejqtf2nbrexx3vqjhp41'
  *
- * const uuid = decodeUserId('user_3Zb83qVQxkHMJPZ8VrJfQ2')
+ * const uuid = decodeUserId('user_01h2xcejqtf2nbrexx3vqjhp41')
  * // => '018f4a3b-1c2d-7000-9abc-def012345678'
  * ```
  */
 /**
- * Encode a raw UUID as a prefixed base58 user ID.
+ * Encode a raw UUID as a prefixed TypeID user ID.
  *
  * @param uuid - Raw UUID string (with or without dashes)
- * @returns Prefixed platform ID: `user_<base58>`
+ * @returns Prefixed TypeID: `user_<crockford_base32>`
  */
 declare function encodeUserId(uuid: string): string;
 /**
- * Decode a prefixed base58 user ID back to a raw UUID.
+ * Decode a prefixed user ID back to a raw UUID.
+ * Accepts both TypeID (current) and base58 (legacy) formats.
  *
- * @param prefixedId - Prefixed platform ID: `user_<base58>`
+ * @param prefixedId - Prefixed user ID: `user_<encoded>`
  * @returns Raw UUID string, or null if invalid
  */
 declare function decodeUserId(prefixedId: string): string | null;

package/dist/server/index.d.ts

@@ -18405,7 +18405,7 @@ interface components {
 		OrgInvitation: {
 			/**
 			 * @description Invitation ID
-			 * @example ivt_3Zb83qVQxkHMJPZ8VrJfQ2
+			 * @example inv_3Zb83qVQxkHMJPZ8VrJfQ2
 			 */
 			id: string
 			/**
@@ -18475,7 +18475,7 @@ interface components {
 			/**
 			 * Format: uuid
 			 * @description Invitation token (ID)
-			 * @example ivt_3Zb83qVQxkHMJPZ8VrJfQ2
+			 * @example inv_3Zb83qVQxkHMJPZ8VrJfQ2
 			 */
 			token: string
 		}
@@ -19782,18 +19782,20 @@ interface AccessTokenPayload {
  * 4. No silent fixes - Transparency over convenience (but warn + continue)
  * 5. Single Source of Truth - All key logic in one place
  *
- * Key Formats (OAuth 2.0 Standard):
- * - App ID: app_(dev|stg|prod)_[identifier] — Public identifier (like OAuth client_id)
- * - Secret Key: sk_(dev|stg|prod)_[identifier] — Server-side only (like OAuth client_secret)
+ * 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
  *
- * Identifier Types:
- * - Customer apps: 32 hex chars
- * - Platform apps: platform_{app-slug} (e.g., platform_sylphx-console)
+ * Legacy Key Formats (backward-compat):
+ * - App ID (old):    app_(dev|stg|prod)_[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';
-/** Key type - appId (public) or secret (server) */
-type KeyType = 'appId' | 'secret';
+/** Key type - publicKey (pk_*), appId (legacy app_*), or secret (sk_*) */
+type KeyType = 'publicKey' | 'appId' | 'secret';
 /** Validation result with clear error information */
 interface KeyValidationResult {
     /** Whether the key is valid (possibly after sanitization) */
@@ -19812,7 +19814,9 @@ interface KeyValidationResult {
     issues?: string[];
 }
 /**
- * Validate an App ID and return detailed results
+ * Validate a legacy App ID (app_*) and return detailed results.
+ *
+ * @deprecated Use validatePublicKey() for new pk_* keys (ADR-021).
  *
  * @example
  * ```typescript
@@ -19827,8 +19831,9 @@ interface KeyValidationResult {
  */
 declare function validateAppId(key: string | undefined | null): KeyValidationResult;
 /**
- * Validate and sanitize App ID, logging warnings
+ * Validate and sanitize App ID, logging warnings.
  *
+ * @deprecated Use validateAndSanitizePublicKey() for new pk_* keys (ADR-021).
  * @throws Error if the key is invalid and cannot be sanitized
  * @returns The sanitized App ID
  */
@@ -19887,17 +19892,19 @@ declare function isProductionKey(key: string): boolean;
  */
 declare function getCookieNamespace(secretKey: string): string;
 /**
- * Detect the type of key (App ID or Secret Key)
+ * Detect the type of key.
  *
- * @returns 'appId', 'secret', or null if unknown
+ * @returns 'publicKey' (pk_*), 'appId' (legacy app_*), 'secret' (sk_*), or null if unknown
  */
 declare function detectKeyType(key: string): KeyType | null;
 /**
- * Check if a key is an App ID
+ * Check if a key is an App ID (legacy app_* format)
+ *
+ * @deprecated Use isPublishableKey() to also accept new pk_* keys
  */
 declare function isAppId(key: string): boolean;
 /**
- * Check if a key is a secret key
+ * Check if a key is a secret key (sk_*)
  */
 declare function isSecretKey(key: string): boolean;
 /**
@@ -19931,33 +19938,36 @@ declare function isDevelopmentRuntime(): boolean;
  * Platform ID utilities for the Sylphx SDK
  *
  * Converts between raw UUIDs (used internally / in JWT sub claims) and
- * prefixed base58 IDs (used in all API responses and JWT pid claims).
+ * prefixed TypeID strings (used in all API responses and JWT pid claims).
+ *
+ * Uses TypeID spec v0.3.0 (Crockford base32, case-insensitive).
+ * Also accepts legacy base58 format for backward compatibility.
  *
- * Same alphabet and encoding logic as the platform server.
- * No external dependencies — pure TypeScript.
+ * No external dependencies — pure TypeScript implementation of Crockford base32.
  *
  * @example
  * ```ts
  * import { encodeUserId, decodeUserId } from '@sylphx/sdk/nextjs'
  *
  * const prefixed = encodeUserId('018f4a3b-1c2d-7000-9abc-def012345678')
- * // => 'user_3Zb83qVQxkHMJPZ8VrJfQ2'
+ * // => 'user_01h2xcejqtf2nbrexx3vqjhp41'
  *
- * const uuid = decodeUserId('user_3Zb83qVQxkHMJPZ8VrJfQ2')
+ * const uuid = decodeUserId('user_01h2xcejqtf2nbrexx3vqjhp41')
  * // => '018f4a3b-1c2d-7000-9abc-def012345678'
  * ```
  */
 /**
- * Encode a raw UUID as a prefixed base58 user ID.
+ * Encode a raw UUID as a prefixed TypeID user ID.
  *
  * @param uuid - Raw UUID string (with or without dashes)
- * @returns Prefixed platform ID: `user_<base58>`
+ * @returns Prefixed TypeID: `user_<crockford_base32>`
  */
 declare function encodeUserId(uuid: string): string;
 /**
- * Decode a prefixed base58 user ID back to a raw UUID.
+ * Decode a prefixed user ID back to a raw UUID.
+ * Accepts both TypeID (current) and base58 (legacy) formats.
  *
- * @param prefixedId - Prefixed platform ID: `user_<base58>`
+ * @param prefixedId - Prefixed user ID: `user_<encoded>`
  * @returns Raw UUID string, or null if invalid
  */
 declare function decodeUserId(prefixedId: string): string | null;

package/dist/server/index.js

@@ -1413,6 +1413,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 SECRET_KEY_PATTERN = /^sk_(dev|stg|prod)_[a-z0-9_-]+$/;
 var ENV_PREFIX_MAP = {
@@ -1503,6 +1504,9 @@ function validateKeyForType(key, keyType, pattern, 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");
 }
@@ -1531,22 +1535,23 @@ function validateAndSanitizeSecretKey(key) {
 }
 function detectEnvironment(key) {
   const sanitized = key.trim().toLowerCase();
+  if (sanitized.startsWith("pk_")) {
+    const result = validatePublicKey(sanitized);
+    if (!result.valid) throw new Error(result.error);
+    return result.environment;
+  }
   if (sanitized.startsWith("sk_")) {
     const result = validateSecretKey(sanitized);
-    if (!result.valid) {
-      throw new Error(result.error);
-    }
+    if (!result.valid) throw new Error(result.error);
     return result.environment;
   }
   if (sanitized.startsWith("app_")) {
     const result = validateAppId(sanitized);
-    if (!result.valid) {
-      throw new Error(result.error);
-    }
+    if (!result.valid) throw new Error(result.error);
     return result.environment;
   }
   throw new Error(
-    `[Sylphx] Invalid key format. Key must start with 'sk_' (secret) or 'app_' (App ID).`
+    `[Sylphx] Invalid key format. Key must start with 'pk_' (publishable), 'sk_' (secret), or 'app_' (legacy App ID).`
   );
 }
 function isDevelopmentKey(key) {
@@ -1562,6 +1567,7 @@ function getCookieNamespace(secretKey) {
 }
 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;
@@ -1574,6 +1580,9 @@ function isSecretKey(key) {
 }
 function validateKey(key) {
   const keyType = key ? detectKeyType(key) : null;
+  if (keyType === "publicKey") {
+    return validatePublicKey(key);
+  }
   if (keyType === "appId") {
     return validateAppId(key);
   }
@@ -1583,7 +1592,7 @@ function validateKey(key) {
   return {
     valid: false,
     sanitizedKey: "",
-    error: key ? `Invalid key format. Keys must start with 'app_' (App ID) or 'sk_' (Secret Key), followed by environment (dev/stg/prod) and identifier. 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). Got: ${key.slice(0, 20)}...` : "API key is required but was not provided.",
     issues: key ? ["invalid_format"] : ["missing"]
   };
 }
@@ -1981,31 +1990,41 @@ function createDynamicRestClient(config) {
 }
 
 // src/lib/ids.ts
+var CB32 = "0123456789abcdefghjkmnpqrstvwxyz";
+var CB32_MAP = Object.fromEntries([...CB32].map((c, i) => [c, i]));
 var B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 var B58_MAP = Object.fromEntries([...B58].map((c, i) => [c, i]));
-function encodeUserId(uuid) {
-  const hex = uuid.replace(/-/g, "");
-  if (hex.length !== 32)
-    throw new Error("Invalid UUID: expected 32 hex chars after stripping dashes");
-  let n = BigInt("0x" + hex);
-  let r = "";
-  while (n > 0n) {
-    r = B58[Number(n % 58n)] + r;
-    n /= 58n;
+function cb32Encode(hex) {
+  const num = BigInt(`0x${hex}`);
+  const chars = [];
+  let n = num;
+  for (let i = 0; i < 26; i++) {
+    chars.unshift(CB32[Number(n & 0x1fn)]);
+    n >>= 5n;
+  }
+  return chars.join("");
+}
+function cb32Decode(str) {
+  if (str.length !== 26) return null;
+  let n = 0n;
+  for (const c of str.toLowerCase()) {
+    const idx = CB32_MAP[c];
+    if (idx === void 0) return null;
+    n = n << 5n | BigInt(idx);
   }
-  return `user_${r}`;
+  return n.toString(16).padStart(32, "0");
 }
-function decodeUserId(prefixedId) {
-  if (!prefixedId.startsWith("user_")) return null;
-  const enc = prefixedId.slice(5);
-  if (!enc) return null;
+function b58Decode(str) {
   let n = 0n;
-  for (const c of enc) {
+  for (const c of str) {
     const i = B58_MAP[c] ?? -1;
     if (i === -1) return null;
     n = n * 58n + BigInt(i);
   }
   const hex = n.toString(16).padStart(32, "0");
+  return hex.length === 32 ? hex : null;
+}
+function hexToUuid(hex) {
   return [
     hex.slice(0, 8),
     hex.slice(8, 12),
@@ -2014,6 +2033,24 @@ function decodeUserId(prefixedId) {
     hex.slice(20)
   ].join("-");
 }
+function encodeUserId(uuid) {
+  const hex = uuid.replace(/-/g, "");
+  if (hex.length !== 32)
+    throw new Error("Invalid UUID: expected 32 hex chars after stripping dashes");
+  return `user_${cb32Encode(hex)}`;
+}
+function decodeUserId(prefixedId) {
+  if (!prefixedId.startsWith("user_")) return null;
+  const enc = prefixedId.slice(5);
+  if (!enc) return null;
+  if (enc.length === 26) {
+    const hex2 = cb32Decode(enc);
+    if (hex2) return hexToUuid(hex2);
+  }
+  const hex = b58Decode(enc);
+  if (hex) return hexToUuid(hex);
+  return null;
+}
 
 // src/server/ai.ts
 function createAI(options = {}) {