@sylphx/sdk 0.3.4 → 0.3.5

package/dist/index.d.cts

@@ -8,6 +8,33 @@ import * as openapi_fetch from 'openapi-fetch';
  *
  * Uses appId or secretKey for authentication via x-app-secret header.
  */
+/**
+ * Parsed representation of a Sylphx API key (ADR-021 format).
+ */
+interface ParsedKey {
+    /** Key type: 'pk' (publishable) or 'sk' (secret) */
+    type: 'pk' | 'sk';
+    /** Environment short code: 'prod', 'dev', or 'stg' */
+    env: 'prod' | 'dev' | 'stg';
+    /** 12-char project ref (base36) */
+    ref: string;
+    /** Random secret portion of the key */
+    token: string;
+    /** Whether this is a client-safe publishable key */
+    isPublic: boolean;
+    /** Pre-computed base URL for this project */
+    baseUrl: string;
+}
+/**
+ * Parse an ADR-021 API key into its component parts.
+ *
+ * Supports:
+ *   pk_{env}_{ref}_{32hex}   — publishable key (ADR-021)
+ *   sk_{env}_{ref}_{64hex}   — secret key (ADR-021)
+ *
+ * @throws SylphxError if key format is invalid or uses old app_* format
+ */
+declare function parseKey(key: string): ParsedKey;
 /**
  * SDK Configuration for Pure Functions
  *
@@ -31,61 +58,79 @@ import * as openapi_fetch from 'openapi-fetch';
  */
 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 */
     readonly accessToken?: string;
 }
 /**
- * Configuration input (some fields are optional)
+ * Configuration input — ADR-021 key-first API.
+ *
+ * Provide either publicKey or secretKey (or both).
+ * The project ref is extracted automatically from the key.
  */
 interface SylphxConfigInput {
+    /**
+     * Publishable key (pk_*) — client-safe.
+     * Format: pk_{env}_{ref}_{32hex}
+     * env var: NEXT_PUBLIC_SYLPHX_KEY
+     */
+    publicKey?: string;
+    /**
+     * Secret key (sk_*) — server-side only.
+     * Format: sk_{env}_{ref}_{64hex}
+     * env var: SYLPHX_SECRET_KEY
+     */
     secretKey?: string;
     /**
-     * Project ref — short 12-char lowercase alphanumeric string.
-     *
-     * The SDK automatically targets: https://{ref}.api.sylphx.com/v1
-     *
-     * Get this from Platform Console → Projects → Your Project → Overview.
+     * @deprecated Use publicKey or secretKey — ref is now embedded in keys (ADR-021).
+     * Still accepted for backward compatibility; overridden by key-embedded ref.
      */
-    ref: string;
+    ref?: string;
     accessToken?: string;
 }
 /**
- * Create a Sylphx configuration object
+ * Create a Sylphx configuration object (ADR-021 key-first API).
+ *
+ * The project ref is extracted from the key automatically — no need to configure
+ * NEXT_PUBLIC_SYLPHX_APP_ID separately.
  *
- * Validates the secretKey (if provided) using the SSOT key-validation module.
- * Validates the ref format (if provided) — must be a 12-char lowercase alphanumeric string.
- * Sanitizes keys with common issues (whitespace, newlines) and logs warnings.
+ * Validates key format, extracts ref, builds base URL.
  * Throws if key format is invalid.
  *
- * @example
+ * @example Server-side (secret key)
  * ```typescript
  * const config = createConfig({
  *   secretKey: process.env.SYLPHX_SECRET_KEY!,
  * })
  * ```
+ *
+ * @example Client-side (publishable key)
+ * ```typescript
+ * const config = createConfig({
+ *   publicKey: process.env.NEXT_PUBLIC_SYLPHX_KEY!,
+ * })
+ * ```
  */
 declare function createConfig(input: SylphxConfigInput): SylphxConfig;
 /**
@@ -25725,4 +25770,4 @@ declare const WorkersClient: {
     }): Promise<WorkerResult>;
 };
 
-export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CriteriaOperator, type CronInput, type CronSchedule, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type ExceptionFrame, type ExceptionValue, type ExecOptions, type FacetsResponse, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListUsersOptions, type ListUsersResult, type ListWorkersOptions, type ListWorkersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type Plan, type PortalRequest, type PortalResponse, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type RollbackDeployRequest, type RunWorkerOptions, SandboxClient, type SandboxFile, type SandboxOptions, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type TriggerDeployRequest, type TwoFactorVerifyRequest, type UpdateOrgInput, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, WorkerHandle, type WorkerLogsResult, type WorkerResourceSpec, type WorkerResult, type WorkerRun, type WorkerStatus, type WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createConfig, createCron, createDynamicRestClient, createOrganization, createPortalSession, createRestClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasConsent, hasError, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };
+export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CriteriaOperator, type CronInput, type CronSchedule, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type ExceptionFrame, type ExceptionValue, type ExecOptions, type FacetsResponse, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListUsersOptions, type ListUsersResult, type ListWorkersOptions, type ListWorkersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type ParsedKey, type Plan, type PortalRequest, type PortalResponse, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type RollbackDeployRequest, type RunWorkerOptions, SandboxClient, type SandboxFile, type SandboxOptions, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type TriggerDeployRequest, type TwoFactorVerifyRequest, type UpdateOrgInput, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, WorkerHandle, type WorkerLogsResult, type WorkerResourceSpec, type WorkerResult, type WorkerRun, type WorkerStatus, type WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createConfig, createCron, createDynamicRestClient, createOrganization, createPortalSession, createRestClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasConsent, hasError, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, parseKey, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };

package/dist/index.d.ts

@@ -8,6 +8,33 @@ import * as openapi_fetch from 'openapi-fetch';
  *
  * Uses appId or secretKey for authentication via x-app-secret header.
  */
+/**
+ * Parsed representation of a Sylphx API key (ADR-021 format).
+ */
+interface ParsedKey {
+    /** Key type: 'pk' (publishable) or 'sk' (secret) */
+    type: 'pk' | 'sk';
+    /** Environment short code: 'prod', 'dev', or 'stg' */
+    env: 'prod' | 'dev' | 'stg';
+    /** 12-char project ref (base36) */
+    ref: string;
+    /** Random secret portion of the key */
+    token: string;
+    /** Whether this is a client-safe publishable key */
+    isPublic: boolean;
+    /** Pre-computed base URL for this project */
+    baseUrl: string;
+}
+/**
+ * Parse an ADR-021 API key into its component parts.
+ *
+ * Supports:
+ *   pk_{env}_{ref}_{32hex}   — publishable key (ADR-021)
+ *   sk_{env}_{ref}_{64hex}   — secret key (ADR-021)
+ *
+ * @throws SylphxError if key format is invalid or uses old app_* format
+ */
+declare function parseKey(key: string): ParsedKey;
 /**
  * SDK Configuration for Pure Functions
  *
@@ -31,61 +58,79 @@ import * as openapi_fetch from 'openapi-fetch';
  */
 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 */
     readonly accessToken?: string;
 }
 /**
- * Configuration input (some fields are optional)
+ * Configuration input — ADR-021 key-first API.
+ *
+ * Provide either publicKey or secretKey (or both).
+ * The project ref is extracted automatically from the key.
  */
 interface SylphxConfigInput {
+    /**
+     * Publishable key (pk_*) — client-safe.
+     * Format: pk_{env}_{ref}_{32hex}
+     * env var: NEXT_PUBLIC_SYLPHX_KEY
+     */
+    publicKey?: string;
+    /**
+     * Secret key (sk_*) — server-side only.
+     * Format: sk_{env}_{ref}_{64hex}
+     * env var: SYLPHX_SECRET_KEY
+     */
     secretKey?: string;
     /**
-     * Project ref — short 12-char lowercase alphanumeric string.
-     *
-     * The SDK automatically targets: https://{ref}.api.sylphx.com/v1
-     *
-     * Get this from Platform Console → Projects → Your Project → Overview.
+     * @deprecated Use publicKey or secretKey — ref is now embedded in keys (ADR-021).
+     * Still accepted for backward compatibility; overridden by key-embedded ref.
      */
-    ref: string;
+    ref?: string;
     accessToken?: string;
 }
 /**
- * Create a Sylphx configuration object
+ * Create a Sylphx configuration object (ADR-021 key-first API).
+ *
+ * The project ref is extracted from the key automatically — no need to configure
+ * NEXT_PUBLIC_SYLPHX_APP_ID separately.
  *
- * Validates the secretKey (if provided) using the SSOT key-validation module.
- * Validates the ref format (if provided) — must be a 12-char lowercase alphanumeric string.
- * Sanitizes keys with common issues (whitespace, newlines) and logs warnings.
+ * Validates key format, extracts ref, builds base URL.
  * Throws if key format is invalid.
  *
- * @example
+ * @example Server-side (secret key)
  * ```typescript
  * const config = createConfig({
  *   secretKey: process.env.SYLPHX_SECRET_KEY!,
  * })
  * ```
+ *
+ * @example Client-side (publishable key)
+ * ```typescript
+ * const config = createConfig({
+ *   publicKey: process.env.NEXT_PUBLIC_SYLPHX_KEY!,
+ * })
+ * ```
  */
 declare function createConfig(input: SylphxConfigInput): SylphxConfig;
 /**
@@ -25725,4 +25770,4 @@ declare const WorkersClient: {
     }): Promise<WorkerResult>;
 };
 
-export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CriteriaOperator, type CronInput, type CronSchedule, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type ExceptionFrame, type ExceptionValue, type ExecOptions, type FacetsResponse, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListUsersOptions, type ListUsersResult, type ListWorkersOptions, type ListWorkersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type Plan, type PortalRequest, type PortalResponse, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type RollbackDeployRequest, type RunWorkerOptions, SandboxClient, type SandboxFile, type SandboxOptions, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type TriggerDeployRequest, type TwoFactorVerifyRequest, type UpdateOrgInput, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, WorkerHandle, type WorkerLogsResult, type WorkerResourceSpec, type WorkerResult, type WorkerRun, type WorkerStatus, type WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createConfig, createCron, createDynamicRestClient, createOrganization, createPortalSession, createRestClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasConsent, hasError, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };
+export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CriteriaOperator, type CronInput, type CronSchedule, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type ExceptionFrame, type ExceptionValue, type ExecOptions, type FacetsResponse, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListUsersOptions, type ListUsersResult, type ListWorkersOptions, type ListWorkersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type ParsedKey, type Plan, type PortalRequest, type PortalResponse, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type RollbackDeployRequest, type RunWorkerOptions, SandboxClient, type SandboxFile, type SandboxOptions, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type TriggerDeployRequest, type TwoFactorVerifyRequest, type UpdateOrgInput, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, WorkerHandle, type WorkerLogsResult, type WorkerResourceSpec, type WorkerResult, type WorkerRun, type WorkerStatus, type WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createConfig, createCron, createDynamicRestClient, createOrganization, createPortalSession, createRestClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasConsent, hasError, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, parseKey, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };

package/dist/index.js

@@ -189,6 +189,7 @@ __export(index_exports, {
   listTasks: () => listTasks,
   listUsers: () => listUsers,
   page: () => page,
+  parseKey: () => parseKey,
   pauseCron: () => pauseCron,
   realtimeEmit: () => realtimeEmit,
   recordStreakActivity: () => recordStreakActivity,
@@ -579,6 +580,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 = {
@@ -669,6 +671,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");
 }
@@ -687,12 +692,16 @@ function validateAndSanitizeSecretKey(key) {
 }
 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;
 }
 function validateKey(key) {
   const keyType = key ? detectKeyType(key) : null;
+  if (keyType === "publicKey") {
+    return validatePublicKey(key);
+  }
   if (keyType === "appId") {
     return validateAppId(key);
   }
@@ -702,12 +711,63 @@ 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"]
   };
 }
 
 // src/config.ts
+function parseKey(key) {
+  const sanitized = key.trim().toLowerCase();
+  if (sanitized.startsWith("app_")) {
+    throw new SylphxError(
+      "[Sylphx] API key format has changed (ADR-021). Keys now embed the project ref.\n\nOld format: app_prod_xxx\nNew format: pk_prod_{ref}_xxx\n\nPlease regenerate your API keys from the Sylphx Console \u2192 Your App \u2192 Environments.\nOr contact support@sylphx.com for assistance.",
+      { code: "BAD_REQUEST" }
+    );
+  }
+  const prefix = sanitized.startsWith("pk_") ? "pk" : sanitized.startsWith("sk_") ? "sk" : null;
+  if (!prefix) {
+    throw new SylphxError(
+      `[Sylphx] Invalid key format. Keys must start with 'pk_' (publishable) or 'sk_' (secret). Got: "${sanitized.slice(0, 15)}..."`,
+      { code: "BAD_REQUEST" }
+    );
+  }
+  const parts = sanitized.split("_");
+  if (parts.length !== 4) {
+    throw new SylphxError(
+      `[Sylphx] Invalid key structure. Expected format: ${prefix}_{env}_{ref}_{token} (4 segments separated by '_'). Got ${parts.length} segment(s).`,
+      { code: "BAD_REQUEST" }
+    );
+  }
+  const [, env, ref, token] = parts;
+  if (env !== "prod" && env !== "dev" && env !== "stg") {
+    throw new SylphxError(
+      `[Sylphx] Invalid key environment "${env}". Must be 'prod', 'dev', or 'stg'.`,
+      { code: "BAD_REQUEST" }
+    );
+  }
+  if (!/^[a-z0-9]{12}$/.test(ref)) {
+    throw new SylphxError(
+      `[Sylphx] Invalid project ref in key: "${ref}". Must be a 12-character lowercase alphanumeric string.`,
+      { code: "BAD_REQUEST" }
+    );
+  }
+  const expectedTokenLen = prefix === "pk" ? 32 : 64;
+  if (token.length !== expectedTokenLen || !/^[a-f0-9]+$/.test(token)) {
+    throw new SylphxError(
+      `[Sylphx] Invalid key token. ${prefix === "pk" ? "Publishable" : "Secret"} keys must have a ${expectedTokenLen}-char hex token.`,
+      { code: "BAD_REQUEST" }
+    );
+  }
+  return {
+    type: prefix,
+    env,
+    ref,
+    token,
+    isPublic: prefix === "pk",
+    baseUrl: `https://${ref}.${DEFAULT_SDK_API_HOST}${SDK_API_PATH}`
+  };
+}
 function httpStatusToErrorCode(status) {
   switch (status) {
     case 400:
@@ -742,31 +802,58 @@ function httpStatusToErrorCode(status) {
 }
 var REF_PATTERN = /^[a-z0-9]{12}$/;
 function createConfig(input) {
+  const keyForParsing = input.secretKey || input.publicKey;
+  if (!keyForParsing) {
+    if (input.ref) {
+      const trimmedRef = input.ref.trim();
+      if (!REF_PATTERN.test(trimmedRef)) {
+        throw new SylphxError(
+          `[Sylphx] Invalid project ref format: "${input.ref}". Expected a 12-character lowercase alphanumeric string (e.g. "abc123def456"). Get your ref from Platform Console \u2192 Projects \u2192 Your Project \u2192 Overview.`,
+          { code: "BAD_REQUEST" }
+        );
+      }
+      const baseUrl2 = `https://${trimmedRef}.${DEFAULT_SDK_API_HOST}${SDK_API_PATH}`;
+      console.warn(
+        "[Sylphx] Providing only ref without a key is deprecated. Provide secretKey or publicKey \u2014 the ref is now embedded in keys (ADR-021)."
+      );
+      return Object.freeze({ ref: trimmedRef, baseUrl: baseUrl2, accessToken: input.accessToken });
+    }
+    throw new SylphxError(
+      "[Sylphx] Either publicKey or secretKey must be provided to createConfig().",
+      { code: "BAD_REQUEST" }
+    );
+  }
+  const parsed = parseKey(keyForParsing);
+  const ref = parsed.ref;
+  const baseUrl = parsed.baseUrl;
   let secretKey;
   if (input.secretKey) {
     const result = validateKey(input.secretKey);
     if (!result.valid) {
-      throw new SylphxError(result.error || "Invalid API key", {
+      throw new SylphxError(result.error || "Invalid secret key", {
         code: "BAD_REQUEST",
         data: { issues: result.issues }
       });
     }
-    if (result.warning) {
-      console.warn(`[Sylphx] ${result.warning}`);
-    }
+    if (result.warning) console.warn(`[Sylphx] ${result.warning}`);
     secretKey = result.sanitizedKey;
   }
-  const trimmedRef = input.ref.trim();
-  if (!REF_PATTERN.test(trimmedRef)) {
-    throw new SylphxError(
-      `[Sylphx] Invalid project ref format: "${input.ref}". Expected a 12-character lowercase alphanumeric string (e.g. "abc123def456"). Get your ref from Platform Console \u2192 Projects \u2192 Your Project \u2192 Overview.`,
-      { code: "BAD_REQUEST" }
-    );
+  let publicKey;
+  if (input.publicKey) {
+    const result = validateKey(input.publicKey);
+    if (!result.valid) {
+      throw new SylphxError(result.error || "Invalid public key", {
+        code: "BAD_REQUEST",
+        data: { issues: result.issues }
+      });
+    }
+    if (result.warning) console.warn(`[Sylphx] ${result.warning}`);
+    publicKey = result.sanitizedKey;
   }
-  const baseUrl = `https://${trimmedRef}.${DEFAULT_SDK_API_HOST}${SDK_API_PATH}`;
   return Object.freeze({
     secretKey,
-    ref: trimmedRef,
+    publicKey,
+    ref,
     baseUrl,
     accessToken: input.accessToken
   });
@@ -784,6 +871,8 @@ function buildHeaders(config) {
   };
   if (config.secretKey) {
     headers["x-app-secret"] = config.secretKey;
+  } else if (config.publicKey) {
+    headers["x-app-secret"] = config.publicKey;
   }
   if (config.accessToken) {
     headers.Authorization = `Bearer ${config.accessToken}`;
@@ -3825,6 +3914,7 @@ function sleep2(ms) {
   listTasks,
   listUsers,
   page,
+  parseKey,
   pauseCron,
   realtimeEmit,
   recordStreakActivity,