@sylphx/sdk 0.3.4 → 0.3.6

package/dist/react/index.d.cts

@@ -694,14 +694,6 @@ interface TaskRunStatus {
     updatedAt: string;
 }
 
-/**
- * SDK Configuration
- *
- * Create a config object that can be passed to SDK functions.
- * This is the foundation for the function-based API.
- *
- * Uses appId or secretKey for authentication via x-app-secret header.
- */
 /**
  * SDK Configuration for Pure Functions
  *
@@ -725,27 +717,26 @@ interface TaskRunStatus {
  */
 interface SylphxConfig {
     /**
-     * Your app key — identifies the app and environment.
-     *
-     * Accepts either:
-     * - Secret key (sk_dev_, sk_stg_, sk_prod_) — full access, server-side only
-     * - Publishable key (app_dev_, app_stg_, app_prod_) — limited access, safe for client
-     *
-     * Get this from Platform Console → Apps → Your App → Environments
+     * Secret key (sk_*) — full access, server-side only.
+     * Embed project ref, env, and routing info (ADR-021).
+     * Get from Platform Console → Apps → Your App → Environments.
      */
     readonly secretKey?: string;
     /**
-     * Project ref — short 12-char lowercase alphanumeric string (e.g. "abc123def456").
-     *
+     * Publishable key (pk_*) — client-safe, read-only access.
+     * Embeds project ref, env, and routing info (ADR-021).
+     * Get from Platform Console → Apps → Your App → Environments.
+     */
+    readonly publicKey?: string;
+    /**
+     * Project ref — 12-char lowercase alphanumeric string.
+     * Extracted from the key automatically (ADR-021).
      * The SDK targets: https://{ref}.api.sylphx.com/v1
-     *
-     * Get this from Platform Console → Projects → Your Project → Overview.
      */
     readonly ref: string;
     /**
      * Pre-computed base URL: https://{ref}.api.sylphx.com/v1
-     *
-     * Used by buildApiUrl and callApi internally.
+     * Derived from the embedded ref in the key.
      */
     readonly baseUrl: string;
     /** Optional: Current access token for authenticated requests */
@@ -15399,18 +15390,20 @@ declare function sanitizeUrl$1(url: string): string | null;
  * 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) */
@@ -15429,7 +15422,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
@@ -15444,8 +15439,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
  */
@@ -15504,17 +15500,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;
 /**

package/dist/react/index.d.ts

@@ -694,14 +694,6 @@ interface TaskRunStatus {
     updatedAt: string;
 }
 
-/**
- * SDK Configuration
- *
- * Create a config object that can be passed to SDK functions.
- * This is the foundation for the function-based API.
- *
- * Uses appId or secretKey for authentication via x-app-secret header.
- */
 /**
  * SDK Configuration for Pure Functions
  *
@@ -725,27 +717,26 @@ interface TaskRunStatus {
  */
 interface SylphxConfig {
     /**
-     * Your app key — identifies the app and environment.
-     *
-     * Accepts either:
-     * - Secret key (sk_dev_, sk_stg_, sk_prod_) — full access, server-side only
-     * - Publishable key (app_dev_, app_stg_, app_prod_) — limited access, safe for client
-     *
-     * Get this from Platform Console → Apps → Your App → Environments
+     * Secret key (sk_*) — full access, server-side only.
+     * Embed project ref, env, and routing info (ADR-021).
+     * Get from Platform Console → Apps → Your App → Environments.
      */
     readonly secretKey?: string;
     /**
-     * Project ref — short 12-char lowercase alphanumeric string (e.g. "abc123def456").
-     *
+     * Publishable key (pk_*) — client-safe, read-only access.
+     * Embeds project ref, env, and routing info (ADR-021).
+     * Get from Platform Console → Apps → Your App → Environments.
+     */
+    readonly publicKey?: string;
+    /**
+     * Project ref — 12-char lowercase alphanumeric string.
+     * Extracted from the key automatically (ADR-021).
      * The SDK targets: https://{ref}.api.sylphx.com/v1
-     *
-     * Get this from Platform Console → Projects → Your Project → Overview.
      */
     readonly ref: string;
     /**
      * Pre-computed base URL: https://{ref}.api.sylphx.com/v1
-     *
-     * Used by buildApiUrl and callApi internally.
+     * Derived from the embedded ref in the key.
      */
     readonly baseUrl: string;
     /** Optional: Current access token for authenticated requests */
@@ -15399,18 +15390,20 @@ declare function sanitizeUrl$1(url: string): string | null;
  * 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) */
@@ -15429,7 +15422,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
@@ -15444,8 +15439,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
  */
@@ -15504,17 +15500,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;
 /**